Ansi Incits 371.3-2003

ANSI INCITS 371.
3-2003
American National Standard
for Information Technology –

Real Time Locating Systems (RTLS) –
Part 3: Application Programming Interface
ANSI INCITS 371.3-2003
Developed by
ANSI ®
INCITS 371.3-2003


Secretariat
Information Technology Industry Council (ITI)
Approved July 25, 2003

American National Standards Institute, Inc.
Abstract
This standard defines an Application Programming Interface for Real Time Locating Systems (RTLS) for
use in asset management. This standard is intended to allow for compatibility and to encourage interop-
erability of products for the growing RTLS market.
Approval of an American National Standard requires review by ANSI that the
American requirements for due process, consensus, and other criteria for approval have
National been met by the standards developer.
Standard Consensus is established when, in the judgement of the ANSI Board of

Standards Review, substantial agreement has been reached by directly and
materially affected interests. Substantial agreement means much more than
a simple majority, but not necessarily unanimity. Consensus requires that all
views and objections be considered, and that a concerted effort be made
towards their resolution.
The use of American National Standards is completely voluntary; their
existence does not in any respect preclude anyone, whether he has approved
the standards or not, from manufacturing, marketing, purchasing, or using
products, processes, or procedures not conforming to the standards.
The American National Standards Institute does not develop standards and
will in no circumstances give an interpretation of any American National
Standard. Moreover, no person shall have the right or authority to issue an
interpretation of an American National Standard in the name of the American
National Standards Institute. Requests for interpretations should be
addressed to the secretariat or sponsor whose name appears on the title
page of this standard.
CAUTION NOTICE: This American National Standard may be revised or
withdrawn at any time. The procedures of the American National Standards
Institute require that action be taken periodically to reaffirm, revise, or
withdraw this standard. Purchasers of American National Standards may
receive current information on all standards by calling or writing the American
National Standards Institute.
CAUTION: The developers of this standard have requested that holders of patents that may be re-
quired for the implementation of the standard disclose such patents to the publisher. However, nei-
ther the developers nor the publisher have undertaken a patent search in order to identify which, if
any, patents may apply to this standard. As of the date of publication of this standard, following
calls for the identification of patents that may be required for the implementation of the standard,
notice of one or more such claims has been received. By publication of this standard, no position
is taken with respect to the validity of this claim or of any rights in connection therewith. The known
patent holder(s) has (have), however, filed a statement of willingness to grant a license under
these rights on reasonable and nondiscriminatory terms and conditions to applicants desiring to ob-
tain such a license. Details may be obtained from the publisher. No further patent search is con-
ducted by the developer or publisher in respect to any standard it processes. No representation is
made or implied that this is the only license that may be required to avoid infringement in the use of
this standard.
Published by
American National Standards Institute, Inc.

25 West 43rd Street, New York, NY 10036
Copyright © 2003 by Information Technology Industry Council (ITI)

All rights reserved.
No part of this publication may be reproduced in any

form, in an electronic retrieval system or otherwise,
without prior written permission of ITI, 1250 Eye Street NW,
Washington, DC 20005.
Printed in the United States of America

Contents
Page
Foreword ................................................................................................................ii
Introduction ............................................................................................................v
1 Scope ........................................................................................................... 1
2 Normative References.................................................................................. 1
3 Terms and Definitions................................................................................... 1
4 Symbols (and Abbreviated Terms) ............................................................... 1
5 The Service .................................................................................................. 2
6 Application Programming Interface (API) ..................................................... 3
7 Subroutine Calls ........................................................................................... 4
8 Data Structures and Data Types ................................................................ 13
Figures
1 Architecture of SOAP-RPC Calls.................................................................. 3
Annex
A XML Schemas for Remote Procedure Calls............................................... 17
i
Foreword (This foreword is not part of American National Standard ANSI INCITS 371.3-2003.)
ANSI INCITS 371.3-2003 is one of a series of standards for Real Time Locating Sys-
tems (RTLS) that provides, in real-time, the physical location and the tracking of as-
sets, human resources, or any other category of mobile items. This series of
standards is intended to foster compatibility and interoperability of RTLS. There are
three standards in the series. Two airwave interface protocols are specified: one is
defined to provide a high-precision system operating at 2.4 GHz and a second to pro-
vide a lower-precision system operating at 433 MHz. A single Application Program-
ming Interface (API) is defined that provides a unifying interface for either of the two
airwave interface protocols.
Requests for interpretation, suggestions for improvement or addenda, or defect re-
ports are welcome. They should be sent to InterNational Committee for Information
Technology Standards (INCITS), ITI, 1250 Eye Street, NW, Suite 200, Washington,
DC 20005.
This standard was processed and approved for submittal to ANSI by INCITS. Com-
mittee approval of this standard does not necessarily imply that all committee mem-
bers voted for its approval. At the time it approved this standard, INCITS had the
following members:
Karen Higginbottom, Chair

Jennifer Garner, Secretary
Organization Represented Name of Representative

Apple Computer, Inc................................................................... David Michael
Wanda Cox (Alt.)
Farance, Inc. .............................................................................. Frank Farance
Richard Lutz (Alt.)
Hewlett-Packard Company......................................................... Karen Higginbottom
Scott Jameson (Alt.)
Steve Mills (Alt.)
EIA.............................................................................................. Edward Mikoski, Jr.
Judith Anderson (Alt.)
Suan Hoyler (Alt.)
IBM Corporation ......................................................................... Ronald F. Silletti
Institute for Certification of Computer Professionals .................. Kenneth M. Zemrowski
Thomas Kurihara (Alt.)
IEEE ........................................................................................... Judith Gorman
Richard Holleman (Alt.)
Robert Pritchard (Alt.)
Intel Corporation......................................................................... Gregory Kisor
Dave Thewlis (Alt.)
Microsoft Corporation ................................................................. Mike Ksar
Joseph Zajaczkowski (Alt.)
National Institute of Standards & Technology ............................ Michael Hogan
William LaPlant, Jr. (Alt.)
Network Appliance ..................................................................... James Davis
Oracle Corporation ..................................................................... Donald R. Deutsch
Jim Melton (Alt.)
Connie Myers (Alt.)
Open Strategies ......................................................................... John Neumann
Panasonic Technologies, Inc. .................................................... Terence Nelson
Rudolf Vitti (Alt.)
Purdue University ....................................................................... Stephen Elliott
Sony Electronics, Inc.................................................................. Ed Barrett
Jean Baronas (Alt.)
Sun Microsystems, Inc. .............................................................. Carman Mondello
John Hill (Alt.)
Douglas Johnson (Alt.)
Carl Cargill (Alt.)
ii
UCC ............................................................................................Stephen Brown
Frank Sharkey (Alt.)
INCITS T20 Technical Committee on Real Time Locating Systems, which contributed
to the development of this standard, had the following members:
Larry Graham, Chairman

Anthony Cataldo, Vice-Chairman
Marsha A. Harmon, Secretary

Associated Foods........................................................................Tim Vandemerwe
Kent Seegmiller (Alt.)
Automotive Industry Action Group (AIAG) ..................................Morris Brown
Baxter Healthcare Corporation....................................................Tuan Bui
James P. Martucci (Alt.)
Bruno Associates, Inc. ................................................................Thomas Bruno
Defense Logistics Agency ..........................................................Dan Kimball
Carl Gardner (Alt.)
Electronic Data Systems Corp (EDS) .........................................Ben Cameron
Tom Whall (Alt.)
Elpas ..........................................................................................Israel Radomsky
Mathiew Bais (Alt.)
FMC Technologies ......................................................................Mike Camut
Tom Nolasco (Alt.)
Ford Motor Company ..................................................................Anthony Cataldo
Henry Ubik (Alt.)
General Electric...........................................................................Tom Tomlinson
Ted Robinson (Alt.)
General Motors ...........................................................................Larry Graham
IITRI ............................................................................................Andrew O’Neill
Tom Lucas (Alt.)
InfoGlyph.....................................................................................Pat McGowan
InfoRay Technologies .................................................................Aaron Samuel
Luz Erez (Alt.)
Northrop Grumman .....................................................................Roger Seese
Jim Laurance (Alt.)
Oak Ridge National Laboratory...................................................Mark Buckner
QED Systems..............................................................................Marsha A. Harmon
Craig K. Harmon (Alt.)
RF Code......................................................................................Roc Lastinger
Armando Viteri (Alt.)
RF Technologies .........................................................................Larry Cinpinski
Eric Heinze (Alt.)
Savi Technology..........................................................................Phil Boyle
Fraser Jennings (Alt.)
Sovereign Tracking Systems ......................................................William Robinson
Bryan Schmidt (Alt.)
Spectrum Management...............................................................Dave Wood
Steve Miller & Associates............................................................Steve Miller
Symbol Technologies..................................................................Chris Zegelin
Michael Hadley (Alt.)
VerdaSee Solutions ....................................................................Fran Smith
Reuben Vasquez (Alt.)
WCCN Publishing, Inc.................................................................Thomas Polizzi
WhereNet ....................................................................................Tim Harrington
Sandeep Jain (Alt.)
iii
The following members served in the capacity of document coordinators:
Tim Harrington
Sandeep Jain
Chris Zegelin
The following members served in the capacity of ad hoc committee chairs:
Mark Buckner
Dan Kimball
Tom Polizzi
iv
Introduction
The INCITS 371 series of standards defines two Air Interface Protocols and a single
Application Programming Interface (API) for Real Time Locating Systems (RTLS) for
use in asset management. This series of standards is intended to allow for compati-
bility and to encourage interoperability of products for the growing RTLS market. The
series consists of the following standards, under the general title “Information Tech-
nology - Real Time Locating Systems.”
ANSI INCITS 371.1 - 2.4-GHz Air Interface Protocol
ANSI INCITS 371.2 - 433-MHz Air Interface Protocol
ANSI INCITS 371.3 - The common API between either 2.4-GHz or 433-MHz Band
RTLS and application programs
This document defines the Application Programming Interface. To be fully compliant
with this standard, Real Time Locating Systems (RTLS) must also comply either with
ANSI INCITS 371.1 or ANSI INCITS 371.2.
An API is a boundary across which application software uses facilities of program-
ming languages to invoke services. These facilities may include procedures or opera-
tions, shared data objects and resolution of identifiers. A wide range of services may
be required at an API to support applications. Different methods may be appropriate
for documenting API specifications for different types of services.
The information flow across the API boundary is defined by the syntax and semantics
of a particular programming language, such that the user of that language may ac-
cess the services provided by the application platform on the other side of the bound-
ary. This implies the specification of a mapping of the functions being made available
by the application platform into the syntax and semantics of the programming lan-
guage.
An API specification documents a service and/or service access method that is avail-
able at an interface between the application and an application platform.
The T20 RTLS API describes the RTLS service and its access methods, to enable
client applications to interface with the RTLS system. This RTLS service is the mini-
mum service that must be provided by a RTLS system to be T20 RTLS API compati-
ble. Other services may be provided in addition to this.
The version of the API standard is signified by x.y, such as 1.0. A major release of
the RTLS API standard would increment the x, such as 2.0. A minor release would
increment the y, such as 1.1.
Client applications using the RTLS API should ignore XML tags that may appear in
future enhancements to the RTLS API standard within a single major release. This
requirement is intended to ensure backward compatibility.
v
AMERICAN NATIONAL STANDARD ANSI INCITS 371.3-2003


1 Scope
This American National Standard defines an API specification that serves as a boundary across
which application software uses facilities of programming languages to invoke the services of the
RTLS Air Interface Protocol standard as defined by INCITS T20.
2 Normative References
2.1 Referenced Documents
The following standards contain provisions which, through reference in this text, constitute provi-
sions of this American National Standard. At the time of publication, the editions indicated were
valid. All standards are subject to revision, and parties to agreements based on this American
National Standard are encouraged to investigate the possibility of applying the most recent edi-
tions of the standards indicated below.
ISO/IEC 9075:1992(E), Information Technology – Database Language – SQL
EXtensible Markup Language 1.0, as defined at the site: http://www.w3.org/tr/rec-xml
Simple Object Access Protocol, Version 1.1, as defined at the site: http://www.w3.org/tr/soap
2.2 Informative References
ANSI INCITS 371.1-2003, Information technology - Real Time Locating Systems (RTLS) - Part 1:
2.4-GHz Air Interface Protocol
ANSI INCITS 371.2-2003, Information technology - Real Time Locating Systems (RTLS) - Part 2:
433-MHz Air Interface Protocol
3 Terms and Definitions

In addition to the terms and definitions listed below, the terms and definitions given in ANSI
INCITS 371.1 and ANSI INCITS 371.2 also apply to this document.
3.1 RTLS tag: The radio frequency device that the RTLS system tracks and locates.
3.2 tag blink: A single RTLS blink of a radio frequency device. Within the API, a tag blink is
uniquely defined by a Tag ID, and usually consists of numerous other fields. A field of a Tag Blink
is equivalent to the property of a Tag Blink. Within the API, it is represented by a XML Tag.
3.3 XML tag: The marker that qualifies content in a XML document.
4 Symbols (and abbreviated terms)

In addition to the abbreviations listed below, the symbols and abbreviated terms given in ANSI
INCITS 371.1 and ANSI INCITS 371.2 also apply to this document.
RTLS Real-time Locating System
RPC Remote Procedure Call
1
SOAP Simple Object Access Protocol

XML eXtensible Markup Language
HTTP HyperText Transfer Protocol
5 The Service
5.1 Purpose
The real-time locating service is typically a Web Service. It receives RTLS tag blinks from the
RTLS infrastructure, and delivers those blinks as the response to client requests, over standard
Internet protocols. In addition, it allows filtering and field selection on the contents of those blinks.
5.2 Description
– An RTLS service shall support message exchange using the SOAP 1.1 encoding.
– An RTLS service should listen and respond to client requests using the HTTP network
protocol. It should listen on port 80.
– An RTLS service may take advantage of the Persistent Connections feature, which is
available in HTTP 1.1, but not in HTTP 1.0. This would yield significant performance
benefits for repeated calls to the RTLS Service, as described in 7.4.
– An RTLS service shall maintain state of the last blink of all tags in the RTLS infrastruc-
ture, since it was started. It may maintain state, from before its start time, by using a re-
pository.
– An RTLS service shall support filtering and field selection, as described in 7.2.5 and
7.2.6. An RTLS Service should eliminate extraneous spaces in the content of query pa-
rameters, such as filters.
– An RTLS service shall be able to create a Session, on request from the API, as described
in 7.3.
– The session shall keep the state of the Query parameters.
– Requests to that session shall return all tag blinks that match the filter criteria, and which
occurred subsequent to the last request, as described in the 7.4.
– If no tag blinks match the criteria, an RTLS service may delay response to session-based
requests, until such tag blinks are received.
– An RTLS service should remove the session state, when the CloseSession request is re-
ceived, as described in 7.5.
– An RTLS service may close the session, when a Query request is not received after
some predetermined period.
– An RLTS Service shall limit the length of all string values to a 1000 characters.
5.3 Security
The API uses SOAP, which assumes standard Internetworking protocols (HTTP and TCP/IP).
Security can be handled using existing standards (e.g. HTTP/S) and technologies at the commu-
nication layer, and discussion on it is beyond the scope of this draft standard.
2
6 Application Programming Interface (API)

6.1 Purpose
The Application Programming Interface (API) provides a standard mechanism for accessing the
location-enriched, tag blinks from the RTLS Service.
6.2 Language Independence
This API specifies a language independent interface to the RTLS Service. It does so by using an
industry standard protocol, Simple Object Access Protocol 1.1 (SOAP 1.1), to communicate to the
RTLS service.
6.3 Architecture
SOAP-RPC calls
Query(...)
Client Application
struct BlinkResponse
RTLS Service
OpenSession Stateless Query
struct SessionResponse Session-based

Query
QuerySession(...)
struct BlinkResponse
CloseSession
Figure 1 – Architecture of SOAP-RPC calls
6.4 Nomenclature and Conventions

The API standard declares namespaces in the SOAP schemas. All fields fall under one of the
namespaces described in those schemas. See the annex for more information.
3
7 Subroutine Calls
7.1 Overview of SOAP-RPC calls
1) struct QueryResponse* Query(char* queryName, char* string filters, char* fields, char*
sortBy)
2) struct SessionResponse* OpenSession(char* queryName, char* filters, char* fields,
char* sortBy)
3) struct QueryResponse* QuerySession(char* SessionID)
4) void CloseSession(char* SessionID)
“SOAP-RPC” refers to the remote methods provided by the RTLS Service, to client applications.
The function signatures shown above are in the C language syntax, merely to describe them con-
cretely. The SOAP-RPC calls may be bound to any programming language, with corresponding
subroutines. The implementation of each subroutine shall create a well-formatted SOAP mes-
sage, and make an HTTP-POST request to the RTLS Service.
Responses to the request may be a SOAP fault structure, a QueryResponse structure, or a Ses-
sionResponse structure. These structures should be deserialized, only if no error occurred. If an
error occurs, the server should return a SOAP fault structure.
7.2 Remote Procedure Call : Query()
7.2.1 Purpose
This client request retrieves the last blink received by the RTLS Service for all tags that match the
criteria of the query. There is at most 1 blink per tag returned. This is a stateless query. No state
about the query is kept in the RTLS service.
7.2.2 Synopsis
The RPC function signature in C language would look like:
struct QueryResponse* Query(char* queryName, char* filters, char* fields, char* sortBy)
Input parameters:
– queryName
– filters
– fields
– sortBy
Output parameters:
– QueryResponse struct
An underlying requirement is that parameters follow the Query method SOAP schema, as de-
scribed in the annex.
7.2.3 Description
The client application should construct a SOAP request message, which will be deserialized at
the service to invoke the function above. The SOAP request schema for Query RPC is described
in the annex.
The client application is responsible for opening a connection (typically, using HTTP), and send-
ing the SOAP request message - Query, with its associated parameters. The response will con-
4
sist of either a QueryResponse structure or a SOAP fault structure. The client application, or a
library that implements client-side proxy functions, should parse the response accordingly.
All the parameters discussed below refer to fields of a Tag Blink. These fields are described in the
QueryResponse data structure, in 8.2, and in the XML schema as described in the annex.
7.2.4 Parameter: queryName
This is the simplest parameter. This parameter opens up the opportunity for creating other que-
ries to the RTLS system, in the future.
Requirements:
1) The RTLS Service shall accept “RTLS_Blinks” as the value for the query name.
Example:
<QueryName>RTLS_Blinks</QueryName>
7.2.5 Parameter: filters
This is the most complex parameter.
Requirements:
1) The service shall return only those tag blinks that match the filters criteria, in the Que-
ryResponse structure.
2) The filters shall be expressed as a sum-of-products Boolean expression, with Boolean
operators acting on relational expressions, which in turn contain tag blink fields and their
values.
3) The filters parameter shall use a subset of Boolean and relational operators, as standard-
ized in ISO/IEC 9075:1992(E) Information technology - Database languages - SQL.
4) The relational operators shall not be used for fields with no values, such as parent fields.
Examples of parent fields are <States/> and <TagBlink/>.
5) The service should ignore extraneous blank spaces in nonstring field values.
6) The right-hand side of all relational expressions, except those containing ‘=’ only, shall be
inside a CDATA section, e.g., <TagID><![CDATA[<> 600]]></TagID>.
Relational Operators Boolean Operator

>, <, >=, <=, =, <> OR
An example of a filter in XML:

<FilterBy>
<TagID><![CDATA[>50]]></TagID>
<TagID><![CDATA[<= 1001]]></TagID>
<OR/>
<BatteryLow>=true</BatteryLow>
<Blinking>=true</Blinking>
</FilterBy>
This filter is equivalent to “all blinks which have TagIDs greater than 50 AND less than or equal to
1001, OR any tag with a BatteryLow flag set to true AND has a Blinking flag set to true.” Note
that this is a sum of products Boolean expression. A sequence of relational expressions that are
not separated by an “</OR>” operator are assumed to be ANDed together.
If no filters are needed, the filter parameter will look like: <FilterBy/>.
5
7.2.6 Parameter: fields

A tag blink can potentially have a large number of fields, not all of which may be interesting to the
client application. By specifying a list of fields, the number of fields per blink returned can be re-
duced, thereby reducing unnecessary network traffic.
If a parent tag is specified, with no mention of any child tags, then any child elements for that tag
blink will be returned. If child tags are mentioned, then only those fields will be returned.
Requirements:
1) The list of fields shall be expressed as a space delimited sequence of fields.
2) A field shall be a TagBlink property or a parent XML tag containing TagBlink properties.
Example:
<Fields>
TagID BatteryLow
</Fields>
If all fields are desired, the fields parameter can be either:

1) <Fields/> or
2) <Fields>
TagBlink
</Fields>
Note that the second alternative works, because the <TagBlink/> tag is the parent of all tag blink
fields.
7.2.7 Parameter: sortBy
The order in which tag blinks appear in the QueryResponse structure can be controlled by speci-
fying the sort order in the query.
Requirements:
1) The sortBy parameter shall consist of a single TagBlink property, and its sort order.
2) The sort order shall be either “asc” for ascending, or “desc” for descending.
Example:
<SortBy>
<Field>TagID</Field>
<Order>asc</Order>
</SortBy>
7.2.8 Return value: QueryResponse struct
QueryResponse struct is described in 8.1 and 8.2. Its XML Schema is defined in the annex, in
clauses A.6 and A.7.
7.2.9 Faults
A general structure for faults is described in 8.4. The XML schema is defined in the annex, in
clause A.9. The RTLS standard specifies a minimal set of error codes and error messages for the
<detail> section of the SOAP fault message. An RLTS Service may provide more specific error
messages that describe the specific portion of the request that is invalid. Any such error mes-
sage shall have a unique error code that is greater than 10000.
6
Error Code Error Message

1000 The Query request is not compliant with the RTLS schema
standard.
1010 This Query request is not compliant with the SOAP schema
standard.
7.2.10 Examples
The examples below are SOAP request-response messages that follow the corresponding XML
schemas described in the annex.
7.2.10.1 Method Request
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body >
<m:Query xmlns:m="http://www.incits.org/RTLS/">
<FilterBy>
<TagID><![CDATA[= 1234]]></TagID>
<OR/>
</FilterBy>
<Fields>TagID Location BatteryLow</Fields>
<SortBy>
<Order>asc</Order>
</SortBy>
</m:Query>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
7.2.10.2 Method Response
<SOAP-ENV:Envelope
<SOAP-ENV:Body >
<m:QueryResponse xmlns:m="http://www.incits.org/RTLS/">
<QueryResult>
<NumItems>1</NumItems>
<TagBlinks>
<TagBlink>
<TagID>1234</TagID>
<Location>
<X>23</X>
<Y>34</Y>
<Z>45</Z>
</Location>
<States>
<BatteryLow>true</BatteryLow>
</States>
</TagBlink>
</TagBlinks>
</QueryResult>
</m:QueryResponse>
7
<SOAP-ENV:Body>
7.3 Remote Procedure Call – OpenSession

7.3.1 Purpose
This client request starts a session in the RTLS Service, and returns with an unique identifier for
that session. The session maintains the query parameters, so that repeated requests to that ses-
sion do not require the query parameters to be sent repeatedly.
Unlike the Query RPC, this request creates state in the Service, and QuerySession RPC uses
that state.
7.3.2 Synopsis
struct SessionResponse* OpenSession(char* queryName, char* filters, char* fields,
char* sortBy)
Input parameters:
– queryName
– filters
– fields
– sortBy
Output parameters:
– SessionResponse struct
An underlying requirement is that parameters follow the OpenSession method SOAP schema.
7.3.3 Description
the service to invoke the function above. The SOAP request shall contain sections for each input
parameter.
ing the SOAP request message. The response will consist of either a SOAP-encoded Session-
Response, or a SOAP fault structure. The client application or a library that implements client
side proxy functions should parse the response accordingly.
7.3.4 Input Parameters
The input parameters are exactly the same as those for the Query RPC.
– QueryName – See 7.2.4
– Filters – See 7.2.5
– Fields – See 7.2.6
– SortBy – See 7.2.7
7.3.5 Return parameter: SessionResponse
The SessionResponse struct is described in 8.3. Its XML schema is defined in the annex, in
clause A.8.
8
7.3.6 Faults
A general description and structure for faults is described in 8.4. The XML schema is defined in
the annex, in clause A.9.

1000 The Query request is not compliant with the
RTLS schema standard.
1010 This Query request is not compliant with the
SOAP schema standard.
2000 The RTLS service is unable to open addi-
tional sessions, until some sessions are
closed.
7.3.7 Examples
<SOAP-ENV:Envelope
<SOAP-ENV:Body >
<m:OpenSession xmlns:m="http://www.incits.org/RTLS/">
<FilterBy>
<TagID><![CDATA[< 5000]]></TagID>
<OR/>
</FilterBy>
<Fields />
<SortBy>
<Order>asc</Order>
</SortBy>
</m:OpenSession>
</SOAP-ENV:Body>
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<m:SessionResponse xmlns:m="http://www.incits.org/RTLS/">
<SessionID>ABJ12300KO</SessionID>
<MaxNumBlinks>5000</MaxNumBlinks>
<ExpirationSeconds>1800</ExpirationSeconds>
</m:SessionResponse>
</SOAP-ENV:Body>
9
7.4 Remote Procedure Call – QuerySession

7.4.1 Purpose
This client request retrieves all tag blinks that match the criteria of the session, and which were
received by the RTLS Service since the last QuerySession request. Unlike the Query request,
more than 1 blink per tag may be returned. By making repeated QuerySession requests, client
applications can obtain near real-time data from the RTLS Service.
7.4.2 Synopsis
struct QueryResponse* QuerySession(char* SessionID)
Input parameters:
– SessionID
Output parameters:
– QueryResponse struct
7.4.3 Description
the service to invoke the function above. The SOAP request schema for QuerySession RPC is
described in the annex.
ing the SOAP request message - QuerySession, with its associated parameters. The response
will consist of either a QueryResponse structure or a SOAP fault structure. The client application,
or a library that implements client side proxy functions, should parse the response accordingly.
7.4.4 Input Parameter: SessionID
Requirements:
1) The client application shall use the same SessionID in the QuerySession RPC, that it re-
ceived from OpenSession RPC.
2) For each session, there should be only one client.
3) The client application should send the SessionID to the same host/service, from which it
received the SessionID.
7.4.5 Return Parameter: QueryResponse
QueryResponse struct is described in 8.1 and 8.2. Its XML Schema is defined in the annex in
clauses A.6 and A.7.
10
7.4.6 Faults

3000 No session with this SessionID has been found.
7.4.7 Examples
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<m:QuerySession xmlns:m="http://www.incits.org/RTLS/">
<SessionID>
ADJ909123LOPQ
</SessionID>
</m:QuerySession>
</SOAP-ENV:Body>
The method response is exactly the same as described in the example, in 7.2.10.2.
7.5 Remote Procedure Call – CloseSession
7.5.1 Purpose
This client request’s sole purpose is to inform the RTLS Service that the Session and its associ-
ated state are no longer needed by the client application, and that all resources used by that Ses-
sion may be released.
7.5.2 Synopsis
void CloseSession(char* SessionID)
Input Parameter:
– SessionID
Output Parameter:
– None
11
7.5.3 Description
The client application is responsible for opening a network connection (typically, using HTTP),
and sending the SOAP request message. Unlike the other RPC calls, the response does not
have an output parameter, and therefore, it should always return a SOAP fault structure. A client
application may ignore the response.
7.5.4 Input Parameter : SessionID
Requirements:
1) The client application shall use the same SessionID that it received from OpenSession
RPC.
2) The client application should send the SessionID to the same host/service, from which it
received the SessionID.
7.5.5 Faults
NOTE - If this RPC call executes successfully, error code 4000 (as shown below) will be returned in the
fault structure.

3000 No session with this SessionID has been found.
4000 The session has been closed successfully.
4010 The session could not be closed in a timely
manner.
7.5.6 Examples
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" >
<SOAP-ENV:Body >
<m:CloseSession xmlns:m="http://www.incits.org/RTLS/">
<SessionID>
ADJ909123LOPQ
</SessionID>
</m:CloseSession>
</SOAP-ENV:Body>
Unlike the other RPC calls, the CloseSession RPC always returns a fault structure.
If this RPC call executes successfully, error code 4000 will be returned in the fault structure, as
described in 7.5.5.
12
8 Data Structures and Data Types

The XML schemas for all data structures described below are detailed in the annex.
8.1 Struct TagBlink
Fields are categorized into Required or Optional fields. Every RTLS service shall support the
Required fields for any Tag Blink. An RTLS Service may omit Boolean fields, when their value is
False. For example, instead of sending <BatteryLow>false</BatteryLow>, the service may
choose to omit that field in the TagBlink struct.
The unit of length measurement for X, Y, Z, and Distance fields shall be in meters.
The fields, RTLSBlinkTime and LocateTime, shall be in Coordinated Universal Time (UTC), and
contain difference of time with UTC.
Tag Blink Fields Required or Op- Description

tional
TagID Required Tag identifier. Type: string.
CoordRef Optional This provides an identifier for the coordinate refer-
ence of this tag. Type: string.
Location Required A parent XML tag which contains a subset of the
following location elements: NoLocate, X, Y, Z,
ZoneID, Bearing, and Distance.
NoLocate Optional* The RTLS System received a tag blink, but was
unable to calculate its location. Type: boolean
X Optional* Location along the X-axis as a float. It shall be
followed by a Y XML tag. Type: float.
Y Optional* Location along the Y-axis as a float. It shall be
preceded by X, and may be followed by a Z XML
tag. Type: float.
Z Optional* Location along the Z-axis. It shall be preceded by
the X and Y XML tags. Type: float.
ZoneID Optional* Zone identifier. Type: string.
Bearing Optional* Angle from the Reader. It shall be in degrees. It
shall be followed by a Distance XML tag. Type:
float.
Distance Optional* Distance from the Reader. Type: float.
RTLSBlinkTime Required The time when this RTLS Blink was formed. Type:
timestamp.
LocateTime Optional The last time this RTLS tag was located. Type:
timestamp.
TagModel Optional Model of the RTLS tag. Type: string.
ResourceType Optional The type of asset, the tag is associated with. Type:
string.
ReaderID Optional The Reader that located the tag blink. Type: string.
13
Tag Blink Fields Required or Op- Description

tional
States Optional A parent XML tag which contains various states of
the RTLS Tag.
General Optional A generic XML tag that contains any telemetry
data, from the RTLS tag. Type: string.
Buttons Optional A binary string such as 1011. This example repre-
sents 4 buttons, and their states. 1 stands for on,
and 0 stands for off. Type: binary string.
ExciterID Optional The identifier of a device that causes the RTLS tag
to blink, when the tag passes its vicinity. Type:
string.
Motion Optional If a tag is moving, this element may be set to true.
Type: Boolean.
BatteryLow Optional If a tag is running low on battery, this element may
be set to true. Type: Boolean.
Blinking Optional If the RTLS system determines that the tag is
blinking, this element may be set to true. Type:
Boolean.
Registered Optional If the RTLS system determines that the tag is pre-
registered with it, then this element may be set to
true. Type: Boolean.
VendorSection Optional A parent XML tag that can contain any vendor
specific elements. A client application may ignore
XML tags in this section.
* This field appears under the Location parent field. Even though it is shown as optional, the Lo-
cation parent field shall have at least one of the fields.
8.2 Struct QueryResponse

QueryResponse Fields Required Or Optional Description
VendorID Optional Identifies the vendor that is
delivering RTLS Blinks. Type:
string.
QueryResult Required A parent XML tag that con-
tains the NumItems and
TagBlinks array.
NumItems Required Number of tag blinks in the
response structure. Type: in-
teger.
TagBlinks Required It contains an array of tagblink
structs, as described in 8.1.
TagBlink Required A single TagBlink struct, as
described in 8.1.
14
8.3 Struct SessionResponse

Session Response Fields Required Or Description
Optional
SessionID Required This is an identifier that uniquely specifies the
session created by the QuerySession RPC, on
a host. Type: string.
MaxNumBlinks Optional The maximum number of blinks that this ses-
sion will store, before it starts dropping blinks.
Type: integer.
ExpirationSeconds Optional If a client does not make a request in this time,
the service may close the session. Type: inte-
ger.
VendorSection Optional A parent XML tag that can contain any vendor
specific elements. A client application may
ignore XML tags in this section.
8.4 Fault Structure
Fields Required or Optional Description

RTLSFaultDetail Required A parent XML tag that con-
tains the fault parameters be-
low.
ErrorCode Required This is a unique identifier of an
error condition. Type: integer.
ErrorMessage Required This is a textual description of
an error condition. Type:
string
A RTLS Service may provide more specific and descriptive error messages than those specified
in this standard. Any such error message shall have a unique error code that is greater than
10000.
8.4.1 Example
Below is an example of the fault structure returned when an error occurs. Note that the example
described a fictitious error code that is greater than 10000, to demonstrate the error reporting
flexibility.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>
Internal Application Error
</faultstring>
<detail>
<rtls:RTLSFaultDetails xmlns:rtls="http:// www.incits.org/RTLS/">
15
<ErrorCode>
12345
</ ErrorCode>
< ErrorMsg>
Invalid filter rule
</ ErrorMsg>
</rtls:RTLSFaultDetails>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
16
Annex A
(normative)
XML Schemas for Remote Procedure Calls
A.1 RTLS API Schema

<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.incits.org/RTLS/"
version="1.0">
<xsd:annotation>
<xsd:documentation>
This schema includes the schemas for the methods and their
responses. It also defines the RTLS namespace.
</xsd:documentation>
</xsd:annotation>
<xsd:include schemaLocation="Query.xsd"/>
<xsd:include schemaLocation="QueryResponse.xsd"/>
<xsd:include schemaLocation="OpenSession.xsd"/>
<xsd:include schemaLocation="SessionResponse.xsd"/>
<xsd:include schemaLocation="QuerySession.xsd"/>
<xsd:include schemaLocation="CloseSession.xsd"/>
<xsd:include schemaLocation="FaultDetails.xsd" />
</xsd:schema>
A.2 SOAP Request Schema: Query
<xsd:schema
xmlns:rtls="http://www.incits.org/RTLS/"
version="1.0">
<xsd:element name="Query">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="QueryName" type="xsd:string"/>
<xsd:element name="FilterBy" type="FilterType"/>
<xsd:element name="Fields" type="FieldsType" />
<xsd:element name="SortBy" type="SortType" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="FilterType">
<xsd:annotation>
<xsd:documentation>
XML Schema 1.0 does not allow the any particle to be
restricted to a certain type.
Therefore, the client application should validate this nested
boolean expression as follows:
17
(a) Each element names should either be name of a tag blink

field, or the element "OR". These include all the fields
specified for TagBlink structure in the RTLS namespace, as
well as, any optional fields in the VendorSection of the
TagBlink structure.
(b) Each element’s value shall be a string of type "relExp",

as defined in this schema. The actual field value in that
relational expression may be validated to the element’s schema
type, if the type is known.
(c) The nested boolean expression shall be parsed as a

sum-of-products expression. The element "OR" implies sum,
while, its absence implies product.
(d) Any spaces around the relational operator should be ignored.
</xsd:annotation>
<xsd:sequence minOccurs="0">
<xsd:any namespace="##any" maxOccurs="unbounded" processCon-
tents="skip" />
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="relExp">
<xsd:annotation>
<xsd:documentation>
This represents the type of relational expression in the
nested, boolean expression for the FilterBy field.
The relational operators are those defined for SQL ’92.

(ISO/IEC 9075:1992)
</xsd:annotation>
<xsd:restriction base="xsd:string">
<xsd:pattern value="(<|<=|>|>=|<>|=)(.)+"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="FieldsType">
<xsd:annotation>
<xsd:documentation>
The client application should validate the list of fields, as
follows:
(a) The list of fields should be a subset of the TagBlink
fields or parent XML tags of those fields.
(b) By definition, an XML list is just a string of space
delimited values.
</xsd:annotation>
<xsd:list itemType="xsd:string" />
</xsd:simpleType>
<xsd:complexType name="SortType">
<xsd:all>
18
<xsd:element name="Field" type="xsd:token" />

<xsd:element name="Order">
<xsd:simpleType>
<xsd:enumeration value="asc" />
<xsd:enumeration value="desc" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:all>
</xsd:complexType>
</xsd:schema>
A.3 SOAP Request Schema: OpenSession

<xsd:schema
version="1.0">
<xsd:include schemaLocation="Query.xsd" />
<xsd:element name="OpenSession">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="QueryName" type="xsd:string"/>
<xsd:element name="FilterBy" type="FilterType"/>
<xsd:element name="Fields" type="FieldsType" />
<xsd:element name="SortBy" type="SortType" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
A.4 SOAP Request Schema : QuerySession

<xsd:schema
version="1.0">
<xsd:element name="QuerySession">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="SessionID" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
19
A.5 SOAP Request Schema: CloseSession

<xsd:schema
version="1.0">
<xsd:element name="CloseSession">
<xsd:complexType>
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
A.6 SOAP Response Schema: TagBlinkType

<xsd:schema
version="1.0">
<xsd:complexType name="TagBlinkType">
<xsd:sequence>
<xsd:annotation>
<xsd:documentation>
The RTLS Service shall provide the fields TagID, Location,
and RTLSBlinkTime for any TagBlink. However, the fields are
optional in the message itself, since the client application
may have filtered out those fields in the query request.
</xsd:annotation>
<xsd:element name="TagID" type="xsd:string" minOccurs="0" />

<xsd:element name="CoordRef" type="xsd:string" minOccurs="0" />
<xsd:element name="Location" type="LocationType" minOccurs="0"/>
<xsd:element name="RTLSBlinkTime" type="dateTimeWithTimezone" minOccurs="0"/>
<xsd:element name="LocateTime" type="dateTimeWithTimezone" minOccurs="0"/>
<xsd:element name="TagModel" type="xsd:string" minOccurs="0"/>
<xsd:element name="ResourceType" type="xsd:string" minOccurs="0"/>
<xsd:element name="ReaderID" type="xsd:string" minOccurs="0"/>
<xsd:element name="States" minOccurs="0">

<xsd:complexType>
<xsd:all>
<xsd:element name="General" type="xsd:string" minOccurs="0" />
<xsd:element name="Buttons" type="binaryString" minOccurs="0" />
<xsd:element name="ExciterID" type="xsd:string" minOccurs="0" />
<xsd:element name="Motion" type="xsd:boolean" minOccurs="0" />
<xsd:element name="BatteryLow" type="xsd:boolean" minOccurs="0" />
<xsd:element name="Blinking" type="xsd:boolean" minOccurs="0" />
<xsd:element name="Registered" type="xsd:boolean" minOccurs="0" />
20
</xsd:all>
</xsd:complexType>
</xsd:element>
<xsd:element name="VendorSection" minOccurs="0">

<xsd:complexType>
<xsd:sequence>
<xsd:any namespace="##any" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="binaryString">
<xsd:pattern value="(0|1)*"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="dateTimeWithTimezone">
<xsd:restriction base="xsd:dateTime">
<xsd:pattern value=".+T.+(Z|[+-].+)" />
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="LocationType">
<xsd:annotation>
<xsd:documentation>
At least 1 location element shall be present.
</xsd:annotation>
<xsd:choice>
<xsd:element name="NoLocate" type="xsd:boolean" minOccurs="0" />
<xsd:sequence>
<xsd:group ref="Coords" minOccurs="0" />
<xsd:group ref="RadialCoords" minOccurs="0" />
<xsd:element name="ZoneID" type="xsd:string" minOccurs="0" />
</xsd:sequence>
</xsd:choice>
</xsd:complexType>
<xsd:group name="Coords">
<xsd:sequence>
<xsd:element name="X" type="xsd:float" />
<xsd:element name="Y" type="xsd:float" />
<xsd:element name="Z" type="xsd:float" minOccurs="0"/>
</xsd:sequence>
</xsd:group>
<xsd:group name="RadialCoords">
21
<xsd:sequence>
<xsd:element name="Bearing" type="degrees" />
<xsd:element name="Distance" type="xsd:nonNegativeInteger" />
</xsd:sequence>
</xsd:group>
<xsd:simpleType name="degrees">
<xsd:restriction base="xsd:float">
<xsd:minInclusive value="-360.0" />
<xsd:maxInclusive value="360.0" />
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
A.7 SOAP Response Schema: QueryResponse

<xsd:schema
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
version="1.0">
<xsd:include schemaLocation="TagBlinkType.xsd"/>
<xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"
schemaLocation="http://schemas.xmlsoap.org/soap/encoding/" />
<xsd:element name="QueryResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="VendorID" type="xsd:string" minOccurs="0" />
<xsd:element name="QueryResult">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="NumItems" type="xsd:nonNegativeInteger"/>
<xsd:element name="TagBlinks" type="TagBlinkArray" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="TagBlinkArray">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:sequence>
<xsd:element name="TagBlink" type="TagBlinkType"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
</xsd:schema>
22
A.8 SOAP Response Schema: SessionResponse

<xsd:schema
version="1.0">
<xsd:element name="SessionResponse">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="MaxNumBlinks" type="xsd:positiveInteger" minOccurs="0" />
<xsd:element name="ExpirationSeconds" type="xsd:positiveInteger" minOccurs="0"/>
<xsd:element name="VendorSection" minOccurs="0">

<xsd:complexType>
<xsd:sequence>
<xsd:any namespace="##any" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
A.9 SOAP Fault Schema: RTLSFaultDetails

<xsd:schema
version="1.0">
<xsd:element name="RTLSFaultDetails">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="ErrorCode" type="xsd:positiveInteger"/>
<xsd:element name="ErrorMessage" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
23

Ansi Incits 371.3-2003

Uploaded by

Copyright:

Available Formats

You might also like

Ansi Incits 371.3-2003

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Ansi Incits 371.3-2003

Uploaded by

Copyright:

Available Formats

ANSI INCITS 371.

American National Standard

for Information Technology –

American National Standard

Real Time Locating Systems (RTLS) –

Approved July 25, 2003

Standard Consensus is established when, in the judgement of the ANSI Board of

American National Standards Institute, Inc.

Copyright © 2003 by Information Technology Industry Council (ITI)

No part of this publication may be reproduced in any

Printed in the United States of America

Karen Higginbottom, Chair

Organization Represented Name of Representative

Larry Graham, Chairman

Organization Represented Name of Representative

The following members served in the capacity of ad hoc committee chairs:

American National Standard

Real Time Locating Systems (RTLS) –

3 Terms and Definitions

4 Symbols (and abbreviated terms)

SOAP Simple Object Access Protocol

6 Application Programming Interface (API)

struct SessionResponse Session-based

Figure 1 – Architecture of SOAP-RPC calls

6.4 Nomenclature and Conventions

Relational Operators Boolean Operator

An example of a filter in XML:

7.2.6 Parameter: fields

If all fields are desired, the fields parameter can be either:

Error Code Error Message

7.3 Remote Procedure Call – OpenSession

Error Code Error Message

7.4 Remote Procedure Call – QuerySession

Error Code Error Message

Error Code Error Message

8 Data Structures and Data Types

Tag Blink Fields Required or Op- Description

Tag Blink Fields Required or Op- Description

8.2 Struct QueryResponse

8.3 Struct SessionResponse

8.4 Fault Structure

Fields Required or Optional Description

XML Schemas for Remote Procedure Calls

A.1 RTLS API Schema

<xsd:include schemaLocation="FaultDetails.xsd" />

(a) Each element names should either be name of a tag blink

(b) Each element’s value shall be a string of type "relExp",

(c) The nested boolean expression shall be parsed as a

The relational operators are those defined for SQL ’92.

<xsd:element name="Field" type="xsd:token" />

A.3 SOAP Request Schema: OpenSession

<xsd:include schemaLocation="Query.xsd" />

A.4 SOAP Request Schema : QuerySession

A.5 SOAP Request Schema: CloseSession

A.6 SOAP Response Schema: TagBlinkType

<xsd:element name="TagID" type="xsd:string" minOccurs="0" />

<xsd:element name="States" minOccurs="0">

<xsd:element name="VendorSection" minOccurs="0">