
============================================

libember_slim
Copyright (C) 2012-2016
LAWO GmbH

=============================================

authors: marius.keuck@lawo.com, roman.nick@lawo.com, pbo@l-s-b.de
date:    2016-05-10


------------------------------- Change Log:
- 1.70
  - Added callbacks for "other package received", "first package received" and "last package received".
	onOtherPackageReceived is invoked whenever a non-ember plus packet has been detected. This is a kind of
	breaking change, since the original callback onPackageReceived is no longer invoked in that case.
	onPackageReceived is invoked whenever an ember plus packet has been decoded.
	onFirstPackageReceived is invoked whenever the "EmberFramingFlag_FirstPackage" flag is set.
	OnLastPackageReceived is invoked whenever the "EmberFramingFlag_LastPackage" flag is set.

- 1.62:
  - Implements Glow DTD 2.31 (mutliple schemas)

- 1.60:
  - changed code so that it compiles without warnings on warning level 4
    (introduced breaking changes in structs like GlowValue, GlowMinMax etc.)
  - Implements Glow DTD 2.30 (schema extensions)

- 1.40:
  - FIXED: glow tag for EmberPlus-Glow.MatrixContents.labels was wrong
  - adjusted version number to match scheme proposed by kimohoff

- 1.20:
  - Implements Glow DTD 2.20 (function extensions)
  - split files "emberglow.h" and "emberglow.c"
    into "glow.h", "glowtx.h", "glowrx.h", "glow.c",
    "glowtx.c" and "glowrx.c".

- 1.12:
  - FIXED: REAL bug that treated the mantissa as signed

- 1.11:
  - FIXED: REAL decoder bug that only took effect on very few numbers whose
    encoding yielded a "bit gap"

- 1.10:
  - Implements Glow DTD 2.10 (matrix extensions)
  - Added top header "emberplus.h"
  - Moved define EMBER_LIBRARY_VERSION from ember.h to emberplus.h
  - Moved prototype for ember_init to from ember.h to emberplus.h
    to enforce usage of new top header.
  - Validates identifiers when writing and after decoding.
  - The "onNode" callback type (used by GlowReader) has changed: it now
    receives the "fields" parameter as defined by the "onParameter" callback.
  - Added support for "isOnline" field of EmberPlus-Glow.NodeContents.
  - Removed reliance on fixed-size buffers. ember_init now has two
    additional parameters: allocMemory and freeMemory.
    The passed callbacks are used to allocate memory dynamically.
    Therefore, you no longer need to initialize a GlowReader with
    a dedicated value buffer.
    The following members have been changed from buffers to pointers:
    - GlowParameter.identifier -> pIdentifier
    - GlowParameter.description -> pDescription
    - GlowOctetsValue.octets -> pOctets
    - GlowNode.identifier -> pIdentifier
    - GlowNode.description -> pDescription
    - GlowValue.string -> pString
  - Added free() functions for each type that contains pointers:
    - glowParameter_free
    - glowNode_free
    - glowValue_free
    The application does not need to call these functions on the RX side
    (since the GlowReader calls them), only on the TX side.
  - Removed defines GLOW_MAX_VALUE_LENGTH, GLOW_MAX_IDENTIFIER_LENGTH and
    GLOW_MAX_DESCRIPTION_LENGTH.
  - FIXED: RELATIVE-OID encoding was limited to a length of 16 bytes.

- 1.5:
  - Put under LGPL
  - Implemented fragmented packages on TX side:
    see glowOutput_beginPackage and glowOutput_beginPackage.
    NOTE: This is a breaking change!
  - Replaced function glow_writeStreamEntries with glow_writeStreamEntry.
    NOTE: This is a breaking change!
  - FIXED: when the "type" field of a received parameter was present, the
    "isOnline" field was marked as present instead.
  - Removed some unused code
  - Renamed sample file "__sample_glowwalk.c" to "__sample_consumer.c".

- 1.4:
  - glow_writeQualifiedCommand now supports the "dirFieldMask" field.
  - ParameterContents.streamDescriptor field now supported on RX side.

- 1.3:
  - FIXED: After setting a parameter value using the QualifiedParameter type
    and then issuing a GetDirectory command on a parameter, the onParameter
    callback was called with a wrong "fields" mask.
  - FIXED: glow_writeQualifiedCommand did not work for a command at the root
    level.
  - FIXED: After receiving a nested parameter, pathLength was reported wrong
    for all following elements on the same level as the parameter.
  - FIXED: Problems with reading QualifiedNode objects.
  - Fixed some gcc specific warnings.
  - Included new consumer sample (__sample_glowwalk.c").

- 1.2:
  - Support for Glow DTD 2.5
  - glow_writeStreamEntries uses a GlowStreamCollection as root instead
    of a GlowRootElementCollection nesting a GlowStreamCollection.
  - glow_writeNodeWithPath etc. renamed to glow_writeQualifiedNode
    with subtle changes in interpretation of the "pPath" argument.
  - Always uses the new glow types "QualifiedParameter" and "QualifiedNode"
    on the TX side.
  - EmberEncoding v1.6:
    - Fixed RelativeOid encoding to comply to the standard:
      It now encodes an array of integers instead of an ulonglong value.
  - Renamed "RelativeObject..." to "RelativeOid..."
    (e.g. ber_encodeRelativeObject)
  - Streamlined naming of preprocessor defines:
    - _INCLUDE_BER_CUSTOM_H renamed to INCLUDE_BERCUSTOM_H
    - _SECURE_CRT renamed to SECURE_CRT
    - _EMBER_MAX_TREE_DEPTH renamed to EMBER_MAX_TREE_DEPTH
    - EMBER_EncodingVersion renamed to EMBER_ENCODING_VERSION
    - EMBER_LibraryVersion renamed to EMBER_LIBRARY_VERSION
    - GLOW_DtdVersion renamed to GLOW_SCHEMA_VERSION
  - Replaced defines for glow command numbers with enum GlowCommandType.
  - Streamlined enum naming:
    - Renamed GlowParameterFields to GlowFieldFlags
    - Renamed GlowParameterField entries to begin with GlowFieldFlag_
      instead of ParamField_.
  - Removed RX support for the Parameter.format field.
  - Added new callback to NonFramingGlowReader: onUnsupportedTltlv.
    If set, this callback is invoked whenever the reader encounters a
    TLTLV it does not support out-of-the-box. E.g. this callback is
    invoked for the Parameter fields "enumeration", "formula" and "format".
  - Added new callback to GlowReader: onPackageReceived.
    If set, this callback is invoked whenever a valid framing package
    has been unframed.
  - Added functions emberFraming_writeKeepAliveRequest and
    emberFraming_writeKeepAliveResponse.

- 1.1:
  - Support for ppm stream subscriptions
  - Removed inline variable declarations since some gcc
    implementations (e.g. avr-gcc) seem to have problems
    with those.
  - Added defines for glow command numbers to emberglow.h:
    GLOW_CommandDir, GLOW_CommandSubscribe etc.

- 1.0:
  - Top-level support for ppm streams
  - Compiles and runs on ARM7 cpu board with ethernut os.

- 0.10:
  - Support for Glow DTD 2.4

- 0.9:
  - beta release


------------------------------- Requirements:
- ANSI C runtime
- only for sample "__sample_program.c": Win32 Sockets API (Winsock2)


------------------------------- Description:
libember_slim is a light-weight library written in ANSI C, covering the
Ember+ standard.
The component version numbers are defined in the library's header files:

GLOW_SCHEMA_VERSION
   the version of the glow schema ("DTD") supported by the library

EMBER_ENCODING_VERSION
   the version of the ember encoding supported by the libary

EMBER_LIBRARY_VERSION
   the version of the library implementation

libember_slim differs from libember in the following ways:
-  programming language: libember_slim is written in plain ANSI C whereas
   libember is written in C++ 3.
-  object model: libember_slim does not define classes that make up
   a DOM (like libember::dom::node in libember). Instead of building
   an in-memory ember tree using the DOM classes and then encoding
   the tree for transport, libember_slim directly encodes information
   in memory for transport.
   therefore, libember_slim has a much smaller memory footprint than libember
   and exposes a procedural interface instead of an object-oriented one.
-  ember encoding: libember_slim uses the indefinite length form when encoding
   ember containers. This means that containers are not length-prefixed but
   suffixed with a container terminator.
   all implementations of the ember/glow standard are required to handle
   both length forms when decoding.


------------------------------- Known Issues:
-  Glow: Parameter.enumMap is not supported
-  Glow: Parameter.defaultValue is not supported
-  Glow: Parameter.enumeration is supported for TX only.
-  Glow: Parameter.formula is supported for TX only.
-  Glow: Parameter.format is supported for TX only.
-  Glow: Matrix.labels is not supported.


------------------------------- Using the Library:
-  copy all code files and header files (except the sample "__sample_program.c")
   to your project and include the C files in the makefile/project file.
-  supported preprocessor defines (to be set in makefile):
   -  _DEBUG
      if defined, debugging checks (ASSERTs) are enabled.
   -  SECURE_CRT
      if defined, secure versions of the C runtime calls from stdio.h
      and string.h are used (e.g. strcpy_s instead of strcpy).
      only define when building against a runtime that implements these
      calls (e.g. MSVCRT).
   -  INCLUDE_BERCUSTOM_H
      if defined, a header file called "bercustom.h" is included first
      in bertypes.h. In this header you can adjust standard typedefs to the
      target platform. The standard typedefs used by libember_slim can be
      found in bertypes.h.
   -  EMBER_MAX_TREE_DEPTH=<value>
      defines the maximum depth of a decodable ember tree.
      default is 65.
-  When using the library in a C++ environment, make sure you tell
   the compiler to compile the library as C++ - this forces use of
   the native C++ bool type instead of the typedef from "bertypes.h".
-  If the type bool is already defined in another location of your project,
   make sure you adjust the typedef used by libember_slim (using bercustom.h),
   so that both definitions of the bool type have the same sizeof.


------------------------------- Getting Started with the Code:

-  include "emberplus.h" in your implementation file.
-  call "ember_init(throwError_t, failAssertion_t)" in your entry-point
   function to configure error reporting.
-  NOTE: all functions and types are documented (doxygen-style) in the
   header files.
-  set up an instance of type GlowReader in the code where you receive
   ember data. Initialize the instance with a call to "glowReader_init(...)".
-  call "glowReader_readBytes(...)" to feed received bytes into the reader.
-  set up an instance of type GlowOutput in the code where you send ember
   data. Initialize the instance with a call to "glowOutput_init(...)".
-  call any of the "glow_write..." functions to write ember encoded glow
   data to the output. Afterwards, the encoded data will be contained ready
   to be sent in the buffer passed to the GlowOutput.
-  it is probably easiest to port the sample "__sample_program.c" to your application
   as a start.
