############################################################################
#   Copyright 2007,2008 Impinj, Inc.
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
#
############################################################################

/** @mainpage LLRP Toolkit for C PlusPlus (LTKCPP)
 ** @author Gordon Waidhofer
 ** 

OVERVIEW OF THE LLRP Tool Kit for C++
Last updated 28 Jan 2008




INTRODUCTION
============

This is a high level overview of and orientation to
the LLRP Tool Kit for C++ (LTKCPP) on Linux and Windows.

The most recent versions of and news about the
LLRP Tool Kit is available on SourceForge.net

    http://sourceforge.net/projects/llrp-toolkit/

This document is organized:
    WHAT IT IS -- a summary for an apps programmer
    HOW IT WORKS -- orientation to the internals
    LIST OF FILES -- small description of each source file
    TODO LIST -- what still needs to be done and known problems




WHAT IT IS
==========

From the application C++ programmer's view:
    - There is a C++ class definition for each LLRP
      message and parameter type
    - An application constructs messages as "element trees"
      of these structures.
    - Using a transaction layer, an element tree is encoded into
      a "binary frame" and sent to the LLRP compatible RFID reader.
    - Messages from the reader are decoded into element trees.
    - Applications traverse the element trees to retrieve
      results and tag data
    - Applications are responsible to be sure element trees
      are properly deallocated




HOW IT WORKS
============

The LTKCPP library code has two major parts.

The first part is the base types, classes, and subroutines.
These are written by hand.

The second part is generated code. The code generators
are written in XSLT and process ../Definitions/Core/llrp-1x0-def.xml.
For each LLRP message and parameter type, generated are:
    - A C++ class
    - A type descriptor -- name, type number, constructor
      function pointer, etc.
    - A set of member functions to encode/decode the classes.

The generated encode/decode functions act through
an abstract interface. For example, the generated
function that encodes an ROBoundarySpec does not
know whether the abstract encoder is being used to
generate a LLRP binary frame or XML text.

The model for decode is a little tricky to understand
at first:
    - Identify the message or parameter type.
    - Look in a type registry to find the type descriptor.
    - Call the generated decodeFields() function.
    - The remainder of the message or parameter is considered
      a sequence of subparameters. Each are decoded
      by the method described here.
    - As each subparameter is decoded it is appended to
      an all-list.
    - Once all subparameters have been decoded, a generated
      assimilateSubParameters() function is called to
      walk the all-list and update the individual
      struct members.

Errors during encode/decode are generally handled by
setting values in an error details structure and then
terminating. The error details include an error number,
a string, and sometimes a reference type descriptor and/or
field descriptor. With rare exception, this is enough
information for the application programmer to determine
what went wrong with the application program.




LIST OF FILES
=============

Documentation/
    Directory for LTKCPP-specific documentation.
    Empty at this time.

Examples/
    Directory of example applications.

Examples/example1.cpp
    Implements the "LLRP Hello World" program.
    It does a five second inventory five times.
    Requires a LLRP reader.
    Runs from the command line (not a GUI).

Examples/Example-Makefile
    The Makefile that is copied to the example directory
    of each binary distribution. The copy is named
    "Makefile" and gets include files and libraries
    from directory .. (dot-dot, the parent dir).

Examples/Makefile
    Makefile for the examples.

INSTALL.TXT
    Terse instructions for obtaining and building LTKCPP

Library/
    The principal directory of LTKCPP.

Library/gencode.bat
    A Windows command script for running the MSXML
    code generator on windows. This must be run by
    hand before using Visual Studio to build the
    library and programs. Requires MSXML.EXE
    which can be downloaded at no charge from
    Microsoft.com. There are instructions within
    this gencode.bat file.

Library/LLRP.org/
    Directory that contains the LLRP.org extension C++ files.
    It is combined with ../Definitions/LLRP.org/LLRPOrgExampleDef.xml
    These extensions don't really do anything, they are
    just used for testing and to demonstrate how the LTK
    implementations build extensions.

Library/LLRP.org/llrporg_ltkcpp_genout.cpp
Library/LLRP.org/llrporg_ltkcpp.h
    Wrappers that combine and condition the generated C++
    source and header files for LLRP.org extensions.

Library/LLRP.org/Makefile
    Makefile for LLRP.org extensions.

Library/ltkcpp_array.cpp
    Helper functions for array types, like utf8v "strings"

Library/ltkcpp_base.h
    Base classes of LTKCPP, hand coded. Base classes include:
        Elements -- common between messages and parameters
        Messages -- base class for LLRP messages
        Parameters -- base class for LLRP parameters
        TypeDescriptors -- info about element types, eg name, typenum
        FieldDescriptors -- info about fields within elements
        NamespaceDescriptors -- info about an XML namespace, eg prefix, URI
        VendorDescriptors -- info about a vendor, eg name, PEN
        Decoders -- abstract interface for decoders: external->elements
        Encoders -- abstract interface for decoders: elements->external
        TypeRegistry -- used to help look up the right TypeDescriptor
        ErrorDetails -- helps explain what went wrong

Library/ltkcpp_connection.cpp
Library/ltkcpp_connection.h
    Implements a simple transaction interface for conveying
    messages to/from a remote reader. It does not try to be
    all things to all people. Rather it is an important
    reference to aid developers of application-specific
    transaction layers.

Library/ltkcpp_element.cpp
    Subroutines for elements (parameters and messages)

Library/ltkcpp_encdec.cpp
    Subroutines for encoders and decoders

Library/ltkcpp_error.cpp
    Subroutines for ErrorDetails

Library/ltkcpp_framedecode.cpp
    Frame decoder, translates "LLRP Binary" into element trees.
    Conforms, of course, the Decoder abstract definition (see ltkcpp_base.h)

Library/ltkcpp_frameencode.cpp
    Frame encoder, translates  element trees into "LLRP Binary".
    Conforms, of course, the Encoder abstract definition (see ltkcpp_base.h)

Library/ltkcpp_frameextract.cpp
    Used to identify and extract a single "LLRP Binary" frame
    from a byte buffer. LLRP frames can be coallesced in a
    network socket. This does the first level interpretation
    of the bytes so that the frames can be individually processed.

Library/ltkcpp_frame.h
    Declarations for ltkcpp_frame*.cpp

Library/ltkcpp_gen_cpp.xslt
    XSLT code generator for C++ definitions.
    This is where the generated encode/decode/etc functions are.
    Used to process ../../Definition/Core/llrp-1x0-def.xml
    into a transient file named out_ltkcpp.inc.
    Similarly used to process extension definitions.
    Requires xsltproc(1) 

Library/ltkcpp_gen_h.xslt
    XSLT code generator for C++ declarations (class declarations).
    This is where the structs are defined for each message and parameter.
    Used to process ../../Definition/Core/llrp-1x0-def.xml
    into a transient file named out_ltkcpp.h.
    Similarly used to process extension definitions.
    Requires xsltproc(1) 

Library/ltkcpp_genout.cpp
    Wrapper that combines platform headers, LTKCPP base headers,
    and the generated out_ltkcpp.inc. After the code generation
    this file is ready to compile.

Library/ltkcpp.h
    API C header file. This is the one applications #include.
    It #includes out_ltkcpp.h along with platform and
    LTKCPP header files.

Library/ltkcpp_hdrfd.cpp
    Contains FieldDescriptors (see ltkcpp_base.h) for
    message and parameter header fields.

Library/ltkcpp_platform.h
    Header file that #includes the right files
    for the current platform. It uses #ifdef linux, etc.
    This is where basic typedefs, like llrp_u32_t, are done.

Library/ltkcpp_typeregistry.cpp
    A type registry is a collection of pointers to
    type descriptors. During decode, a decoder might
    ask a type registry to find the type descriptor
    for message type number 123.

Library/ltkc_xmltextencode.c
    XML text encoder, translates element trees into XML text.
    It is essentially a pretty-printer.
    Conforms, of course, the Encoder abstract definition (see ltkc_base.h)
    The output is a string saved to a caller supplied buffer.
    It is mostly a trouble-shooting aid.

Library/ltkc_xmltext.h
    Declarations for ltkc_xmltext*.c

Library/Makefile
    Makefile for the library.

Makefile
    Top-level makefile. Builds the library, tests, and examples.

README.TXT
    This file that you are reading.

Release/
    Directory where binary distributions are built

Release/Makefile
    Makefile to build binary distributions

Release/std/        generated
    This directory is created and populated with the
    standard LLRP library and headers.

Tests/
    Directory of test programs.

Tests/dx10?.cpp
    All dx10?.cpp (dx101, dx102, etc) are stand-alone tests
    of the library. No reader is required.

Tests/dx101.cpp
    Reads a file containing LLRP binary frames. For each frame:
        - Decode it into an element tree
        - Encode it into XML text
        - Encode it into an LLRP frame
        - Compare the original input frame to the one produced by the encoder
        - Destruct the element tree.
    It is used as a regression to make sure things work consistently
    and to verify there are no memory leaks.
    Runs from the command line (not a GUI).

Tests/dx20?.cpp
    All dx20?.cpp (dx201, dx202, etc) are tests of the library
    that require a reader to talk to.

Tests/dx201.cpp
    Does a simple inventory operation with some bells
    and whistles. It also does extra queries.
    Along with the basic library this exercises the
    ltkcpp_connection.[ch] transaction layer.
    Runs from the command line (not a GUI).

Tests/Makefile
    Makefile for the test programs.

Tests/RUN101
    A shell script that runs dx101 with certain
    inputs and validation tools. Reports PASS/FAIL.

Tests/RUN201
    A shell script that runs dx201 with certain
    validation and measurement tools. Used to
    characterize CPU and memory utilization.

VS_LTKCPP/
    Visual Studio directory. The projects here
    reference the source files above.
    General options for all projects:
    - Precompiled headers are turned off.
    - Code generation uses Multi-threaded DLL
      and Multi-threaded Debug DLL
    - For the three console applications,
      ..\..\Library added as include dir
    - For dx201 and example1, added Ws2_32.lib to linker input

VS_LTKCPP/dx101/
VS_LTKCPP/dx101/dx101.vcproj
    Builds dx101 (see above)

VS_LTKCPP/dx201/
VS_LTKCPP/dx201/dx201.vcproj
    Builds dx201 (see above)

VS_LTKCPP/example1/
VS_LTKCPP/example1/example1.vcproj
    Builds example1 (see above)

VS_LTKCPP/libltkcpp/
VS_LTKCPP/litltkcpp/libltkcpp.vcproj
    Builds libraries for base LTKCPP library including
    the core protocol support. The libraries are
    Debug/libltkcpp_d.lib and Release/libltkcpp_r.lib.
    Warning level reduced to 2 for ltkcpp_genout.cpp.

VS_LTKCPP/libltkcppllrporg
VS_LTKCPP/libltkcppllrporg/libltkcppllrporg.vcproj
    Builds libraries for the LLRP.org example extension.
    The libraries are Debug/libltkcppllrporg_d.lib and
    Release/libltkcppllrporg_r.lib.
    Warning level reduced to 2 for llrporg_ltkcpp_genout.cpp.
    This is an example and doesn't really do anything
    nor is it used by anything.

VS_LTKCPP/Makefile
    Makefile to support the top-level Makefile 'clean' target.
    Also has target 'fugazi' that create (touch(1)) the
    library files so that Release/Makefile can be tested.

VS_LTKCPP/VS_LTKCPP.ncb
VS_LTKCPP/VS_LTKCPP.sln
VS_LTKCPP/VS_LTKCPP.suo
    Visual studio config files. Probably only the .sln is important.




TODO LIST
=========

- Need to settle question of formatting whether u1 fields are
  implictly boolean or not
- Need to finish comments, especially ltkcpp_base.h
- Need a decoder for XML text (XML text -> element tree)
- MAYBE: Need encoder and decoder for XML DOM trees
- Need a test for accessors (dx102)
- Need a test for XML encode/decode (dx103) (needs XML encode/decode first)
- On Windows, need a way to compare the dx101 output to the golden file
- Windows prior to WinXP does not have getaddrinfo(). Probably
  should step back to gethostbyname()
- Need to test on more versions of Visual Studio

**/