English
资源说明：Personal LLRP Toolkit stagging area
############################################################################
# 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
**/
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
