Transport Layer Architecture and Software Design

7/30/2019 Transport Layer Architecture and Software Design

1/83

DRAFT - D ESIGN S PECIFICATION

Transport Interface Layer [TIL]Revision 59

December 16, 2008

.

Jeremy MartinBarry ReinholdDennis Tolstenko

Lamprey Networks, Inc.58 Dover RoadDurham, NH 03824

Copyright 2008 by Lamprey Networks, Inc. All rights reserved.

.

This document may be distributed under the Continua license agreement.


2/83

ii

Revision History

Author Revision Comments Date

Dennis Tolstenko 59updated the document to describe memorymanagement, updated calls and added a smallbluetooth description

December 16,2008

Barry Reinhold 58Signal_OXPStack needed to have VASCHANDLEhshim added to it in order to be able toproperly locate nexus

September 10,2008

Barry Reinhold 57Needed to fix sVirtualChannelInfo again as itdid not have the proper structure. Copiedactual text from shim.h into document.

September 5,2008

Barry Reinhold 56Corrected description of VirtualChannelInfostructure to represent move away from directmemory sharing of objects in SHIM and TIL

September 4,2008

Barry Reinhold 55Added in tables of supported API calls,removed LNI confidential statements

August 26, 2008

Barry Reinhold 54Fixed documentation for sNexus, and sEvents.Updated outdated structures based on currentshim.h and til.h files.

August 25, 2008

Barry Reinhold 53 Updates to reflect current headers August 18, 2008Dennis Tolstenko 50 Added TCI_Delete and TCI_ClearNexus August 6, 2008

Barry Reinhold (LNI) 49

Modified TCI_InitializeTIL such that it nolonger returned the list of interfaces.Modified TCI_GetFirstTransportInterface andTCI_GetNextTransportInterface to return theShim handle.

June 18, 2008

Barry Reinhold (LNI) 47Introduced consumption based oneResultCodes June 16, 2008

Barry Reinhold (LNI) 44Changed size_t* to size_t in TPI_SetAttribute,and added the corresponding TCI calls

June 14, 2008

Jeremy Martin (LNI)Barry Reinhold (LNI)

Initial Drafts May 1 st , 2008


3/83

iii

Table of Contents1 Reference Documents .................................................................................. 1

2 Definitions, Acronyms and Abbreviations ..................................................... 2 3 Overview ...................................................................................................... 3

3.1 Architecture for Future Transports ............................................................ 5 3.2 Cooperating Application Threads ............................................................... 5

3.2.1 Cooperation in Control Event Processing ................................................................ 5 3.2.2 Cooperation in Shim Control and Configuration ..................................................... 6

3.3 Major TIL Operations and Components ..................................................... 6 3.3.1 Initialization ............................................................................................................. 6 3.3.2 Virtual Channel Setup .............................................................................................. 7 3.3.3 Control Event Processing ......................................................................................... 8 3.3.4 APDU Transmission ................................................................................................. 8 3.3.5 APDU Reception....................................................................................................... 9

4 Transport Interface Layer Requirements .................................................... 11 4.1.1 External Interface Requirements ........................................................................... 11 4.1.2 Internal Interfaces (Supported APIs) ..................................................................... 11

4.1.2.1 Transport Provider Interface (TPI) ............................................................... 11 4.1.2.2 Transport Consumer Interface (TCI) ............................................................ 12 4.1.2.3 Transport Provider Shim .............................................................................. 12

4.1.3 Functional Requirements of TIL ............................................................................. 15 4.1.4 Performance Requirements ................................................................................... 15

5 TIL Components .......................................................................................... 16 5.1 Nexus ....................................................................................................... 16 5.2 Virtual Channel ........................................................................................ 17 5.3 Transport Endpoints ................................................................................. 17 5.4 Profiles ..................................................................................................... 18 5.5 Transport Shims ....................................................................................... 18

5.6 Transport Provider API ............................................................................. 18 5.7 Transport Consumer API .......................................................................... 18

6 Functional Behavior .................................................................................... 19 6.1 Initialization ............................................................................................. 19

6.1.1 Transport Shim initialization ................................................................................. 19


4/83

iv

6.2 Connection Management ........................................................................ 20 6.2.1 Application Initiated Passive Connection .............................................................. 23 6.2.2 Application Initiated Active Connection ................................................................ 23 6.2.3 Transport Initiated Connection ............................................................................. 24

6.2.4 Disconnection Events ............................................................................................. 24 6.3 Transmission of APDUs ............................................................................ 25 6.4 Reception of APDUs ................................................................................. 25

7 Software Design ......................................................................................... 27 7.1 Conventions ............................................................................................. 27

7.1.1 Transport Specific Structures of unknown types ................................................... 27 7.1.2 HANDLES ................................................................................................................ 27

7.2 Software Components ............................................................................. 27 7.2.1 API Routines ........................................................................................................... 27

7.2.1.1 Transport Consumer Interface Routines [TCI] ............................................. 27 7.2.1.2 Transport Provider Interface (shim) routines [TPI] ..................................... 46

7.2.2 Internal Modules ................................................................................................... 58 7.2.2.1 LoadTransportInterfaceModules ................................................................. 58

7.2.3 Control Events and Control Event Data Structures (TPI) ....................................... 59 7.2.3.1 Control Event Structure ............................................................................... 59 7.2.3.2 Discovery Event (sDiscoveryEventObject) ................................................... 59 7.2.3.3 Discovery Finished Event (sDiscoveryFinishedEventObject) ....................... 60 7.2.3.4 Connection Event (sConnectionEventObject) ............................................. 60

7.2.3.5 Disconnection Event .................................................................................... 60 7.2.3.6 Authentication Event ................................................................................... 61 7.2.3.7 Extended Event (sExtendedEventObject) .................................................... 61

7.2.4 Endpoints and EndPoint Data Structures (TPI) ...................................................... 61 7.2.4.1 StructureSignature ....................................................................................... 62 7.2.4.2 DeviceIdentifier Field ................................................................................... 62 7.2.4.3 TransportClassID Field ................................................................................. 62 7.2.4.4 pTransportSpecificDeviceInfo Field ............................................................. 62

7.2.5 Virtual Channels and Virtual Channel Representation (TPI) ................................. 62

7.2.5.1 Virtual Channel Structure ............................................................................ 62 7.2.6 Transport Interface Structures (TPI) ...................................................................... 63

7.2.6.1 Transport Interface Information Structure .................................................. 63 7.2.6.2 Transport Interface Extension Structure ..................................................... 64 7.2.6.3 Transport Interface Standard Entry Points .................................................. 65 7.2.6.4 The Nexus and the Nexus Data Structure (TIL) ............................................ 65


5/83

v

7.2.6.5 Profiles and Profile Data Structure(TPI) ....................................................... 67 7.2.6.6 QoS and QoS Related Data Structures ......................................................... 68

7.3 Transport Specific Information ................................................................. 69 7.3.1 USB ........................................................................................................................ 69

7.3.1.1 One peer per USB Device ............................................................................. 69 7.3.1.2 Two Shims .................................................................................................... 70 7.3.1.3 USB Device Information ............................................................................... 70 7.3.1.4 Device Specializations .................................................................................. 70 7.3.1.5 Discovery ...................................................................................................... 70 7.3.1.6 Virtual Channels ........................................................................................... 71 7.3.1.7 Sequence of Events on Device Connection ................................................. 71 7.3.1.8 Sequence of Events on disconnection ......................................................... 74 7.3.1.9 Shutdown ..................................................................................................... 76

7.3.2 Bluetooth ............................................................................................................... 76 7.3.2.1 Configuration and Roles ............................................................................... 77 7.3.2.2 Bluetooth Device Information ..................................................................... 77 7.3.2.3 Discovery ...................................................................................................... 78


6/83

1

1 Reference Documents

ISO/IEEE 11073-20601 Personal health device communication Application profile- Optimizedexchange protocol

LNI VASC Coding Standards

Continua Interoperability Guidelines
http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://fuji.lampreynetworks.com/twiki4.2.0/pub/ProjectManagement/VASCProjectDocuments/VASC_Coding_Standards.dochttp://fuji.lampreynetworks.com/twiki4.2.0/pub/ProjectManagement/VASCProjectDocuments/VASC_Coding_Standards.dochttp://fuji.lampreynetworks.com/twiki4.2.0/pub/ProjectManagement/VASCProjectDocuments/VASC_Coding_Standards.dochttp://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197http://ieeexplore.ieee.org/Xplore/login.jsp?url=/ielD/4459195/4459196/04459197.pdf?tp=&isnumber=4459196&arnumber=4459197


7/83

2

2 Definitions, Acronyms and Abbreviations

Call table A set of function pointers exported by the Shim to the TIL. The first of these functionpointers are well defined and expected to be present on all Shims.

TIL Transport Interface Layer

OXP ISO/IEEE 11073-20601 Optimized Exchange Protocol

VASC Vendor Assisted Source Code

QoS Quality of Service

API Application Programming Interface

Endpointidentifier

A general term that is designed to represent the transport layer entity that would beused to get to the peer OXP stack. In TCP/IP this would be the IP address and TCP port

number.

Nexus The Nexus is a structure that contains the information about the communication linksbetween a given local and remote OXP device pair (in practice a given Agent-Managerpair). The information consists of the virtual channel identifiers and their QoS valuesand the shim identifier (communication links between a given device pair using adifferent transport technology, though possible, is not supported). In this manner alocal OXP stack can give the TIL a Nexus ID and QoS value and the TIL can deliver theADPU to the proper destination on the proper channel and a received APDU can bedelivered to the right local OXP stack when the transport layer provides the virtualchannel and shim handle. The Nexus is created and loaded by the Application duringsetup, but it resides in the TIL. It is used to enable the TIL to support severalconcurrent operations between different instances of Manager and Agent pairs.

Shim An interface routine that is provided by a transport vendor. The shim maps transportspecific connection concepts into the Virtual Channels used by the TIL. The shimimplements the routines defined by the TIL Transport Provider API.

Shim handle A unique identifier that the Shim gives the TIL during initialization. (The handle iscreated as a pointer to a region in shared memory assuring a unique value betweenshims that have no knowledge of each other.)

APDU Application Protocol Data Unit

TransportClass A type of transport technology used, for example USB, Bluetooth, Ethernet, etc.


8/83

3

3 OverviewThe Transport Interface Layer (TIL) is glue between the ISO/IEEE 11073-20601 Optimized ExchangeProtocol (OXP) and transport-specific software Shims that connect to the transport layers on a hostsystem. The principal design goal of the Transport Interface Layer is to allow operation over theContinua version 1 transports of Bluetooth TM, TCP and USB, while being extensible to include future

transports that might be added later on. The TIL defines two APIs, one for the transport consumer, andone for the transport provider. The transport consumer is envisioned to be application specific controlcode, or the OXP stack itself. The Transport Consumer API provides control services that allow the VASCapplication to setup Virtual Channels in order to exchange APDUs with remote OXP stacks. TheTransport Provider API connects the transport specific Shims to the TIL. At startup, the TIL loads theShims by calling an initialization routine that links the Shims defined entry points.

The TIL is designed to support both simple agents running in embedded systems as well as complexmanagers in which there are multiple concurrent threads working with a set of different agents, possiblycommunicating over different transport technologies.

To the extent possible, a Shim identifies the endpoints to which it has connectivity. For Transport

initiators this information is maintained by the provider in a table. The initiator will use the endpointinformation to create a connection with an endpoint. For transport connection receivers an eventmechanism is used to indicate when a connection has been established from the initiator. TransportConnections are represented by the abstract Virtual Channel concept. QoS information is used by theapplication in establishing this Virtual Channel. Virtual Channels are created in the context of a Nexuswhich represents the end to end context between the OXP of two devices.

ISO/IEEE 11073-20601 describes exchanges between Mangers and Agents as possibly flowing overmultiple Virtual Channels, where the Virtual Channels may have different QoS characteristics. VirtualChannels, however, are not strictly defined within OXP. In VASC, the Virtual Channel is not used in theOXP stack, but it is used by the application to create or update Nexuses in response to connectionevents from the Shim. Each Virtual Channel is provided by a Shim and is represented in the TIL by ahandle.

When the APDU enters the TIL the QoS and Nexus ID are used to identify a Virtual Channel over whichthe packet can be transmitted. The TIL selects a Virtual Channel from the supplied Nexus that meets theQoS requirements and sends the APDU to the Shim owning that Virtual Channel. The Shim haspreviously mapped this handle to a communication link and the APDU is sent over this link.


9/83

4

Application Code

I S O / I E E E 1 1 0 7 3 - 2

0 6 0 1 s

t a c

k

I S O / I E E E 1 1 0 7 3 - 2

0 6 0 1 s

t a c

k

I S O / I E E E 1 1 0 7 3 - 2

0 6 0 1 s

t a c

k

T L I S e

t u p a n

d C o n

t r o

l

TLI Consumer API

TIL Provider API

Provider Bluetooth Shim

Provider Bluetooth Driver

Provider USB Shim

Provider USB Driver

Provider TCP/UDP Shim

Provider TCP/UDP Driver

Remote Device withBluetooth and ISO/IEEE

11073-20601 Stack

R e l i a b l e

B e s

t E f f o r t

R e l i a b l e

R e l i a b l e

B e s

t E f f o r t

B e s

t E f f o r t

TIL Interface ModuleTIL

Manager Module

Association Layer

Service Layer

Object Layer

Association Nexus

Context

D i r e c

t C a

l l s t o T r a n s p o r t

L a y e r

( e g s o c

k e

t c a

l l s )

V A S C c o r e c o

d e c o v e r a g e

APDUs delivered using Reliable Transport APDUs delivered using Best Effort TransportFlows (APDUs with QOS Context)Reliable Virtual Channel

APDUs delivered using Best Effort Transport

Transport connections

T r a n s p o r t

I n t e r f a c e

L a y e r

P r o v i

d e r

E x p o r t e

d A P I t o A p p

l i c a

t i o n

Figure 1 - TIL Overview


10/83

5

3.1 Architecture for Future TransportsContinua as an organization has just begun to mature the field of telehealth. The initial specificationsreleased by Continua target USB and Bluetooth as the transport layers for the OXP stack. Futuretransport technologies, however, are anticipated. In order to enable the VASC architecture to migratesmoothly to future transports the TIL abstracts the details of transport connections into Virtual Channels

that connect OXP stacks. The transport shim is responsible for the mapping of actual transportconnections into TIL Virtual Channels. The selection of which device to communicate with, and how toaddress that device is left up to the application and the shim to coordinate.

ISO/IEEE 11073-20601 operates in the context of an association which, conceptually, is the session layerin the ISO/OSI seven layer model. The OXP stack expects that all the APDUs it is sending, and all theAPDUs it is receiving are being exchanged with exactly one other OXP stack. The APDUs may travel overdifferent Virtual Channels with different QoS characteristics but there is only one logical peeringbetween OXPs stacks from the time an OXP association is established until that OXP association isterminated. In the TIL code it is the Nexus that represents the peering of the two OXP stacks. The Nexuscan be visualized as a bundle of cables. The bundle of cables starts at one OXP stack and ends at theother OXP stack. Each cable in the bundle represents a Virtual Channel. All the Virtual Channels connect

the same endpoints, although some of the cables may be copper and some may be fiber (representingdifferent QoS characteristics).

The TIL expects to see either control events or APDUs on virtual channels from the shim. The TIL deliversAPDUs to an OXP stack by identifying which Nexus contains the Virtual Channel that delivered the APDU.It requires that the application be able to process control events for the discovery of new devices and toeither allow or refuse connections to those devices.

Since the TIL requires that the application be able to identify the devices it wishes to establishconnections with it must provide extensible mechanisms that will allow different transports to providethe application layer with the information and control the application will need to carry out this task.These mechanisms take the form of two extensible interfaces.

The first extensible interface is a table of function pointers, identified as the call table, which allows theShim to export methods to the application that are beyond that normally required by the TIL. Thesecond is a set of attributes that may be used in get and set operations. These attributes allow the Shimto be configured by the application.

3.2 Cooperating Application ThreadsAs an API attempting to service both a simple and a more complex environment the TIL is able to beused for a single application thread, but it also can be used to service a threaded application. Whencompiled for a threaded application the TIL does not attempt to play the role of a modern concurrent OSin terms of protecting threads from each other and shielding access to devices, these requirements areleft up to the application which implies that VASC applications must be cooperative in nature. However,the TIL does provide a limited paradigm that allows distinct threads to cooperate. Threads mustcooperate in two key areas, first they must process control events in a well defined manner, and second,they must agree to control and configure a Shim consistently.

3.2.1 Cooperation in Control Event ProcessingThe TIL enables an application to register for the reception of control events. When an applicationregisters for control events it places a call back function pointer onto the head of a dispatch list. When a


11/83

6

control event is to be dispatched the TIL walks down the dispatch list delivering the control event to thenext call back on the list. If the called code deems that the event is uniquely for itself, it indicates to theTIL that it has consumed the event, meaning that the TIL should not dispatch the event to the remainingentries on the dispatch list. If the callback does not consume the event, the TIL continues to move downthe dispatch list until the event is consumed or it reaches the end of the list. If the TIL reaches the end of the list the event has been ignored by all the applications and the TIL passes the event back to the Shim.

Callbacks registered by threads can impact the operation of other threads, and hence threads must takecare to process control events properly. Proper event processing implies that the application passes onevents it does not understand, and only consumes events that it knows are its own. The applicationshould exercise care to make sure that the callback function does not block, as the event process isdesigned to synchronize a sequence of events, and if the application blocks the thread executing thecallback it may cause buffer overflows or failure of other applications. In particular the application mustnever wait for an event while processing an event as this may result in deadlock.

The order of the dispatch list determines who has priority in processing control events. The TIL allowsthe application to register an event callback, in which case it is placed at the top of the dispatch list.

Alternatively the application may manually insert itself into the list at a given position.3.2.2 Cooperation in Shim Control and ConfigurationWhen an application obtains a call table from a Shim that Shim may have provided capabilities that haveglobal impact to all applications, such as resetting the transport bus. The TIL may have no knowledge of a particular function. Hence an application may need to take into account the potential of otherapplications being active before invoking functions such as reset.

3.3 Major TIL Operations and Components

3.3.1 InitializationThe Initialization process involves the detection of shims, and the loading of the call tables associatedwith the shim. A VASC implementation may have one or more shims built in at compile time, or it mayallow for a number of different transports to be supported by discovery at run time. When discovery isused the TIL searches in a directory for shared libraries. These shared libraries all implement a methodthat exports a reference to the Shims interface structure. Thi s reference is the memory address of where the structure resides. The reference must be unique for all Shims, which implies that all Shimsmust reside in a common address space in conjunction with the TIL. The TIL stores the reference pointerto the interface structure in an internal table, called the transport table. Figure 2 documents theownership of the Transport Interface Structure by the Shim, and the use of the reference pointer byboth the TIL and the application to obtain the callable functions in the Shim.


12/83

7

Standard Methods

Shim Interface structure

SHIM sendfunction

Shim Handle

Extension Methods

SHIM get attributefunction

Attribute

Attribute

Shim Attributes

Shim Handle

Transport Shim

TIL

Application

Transport TableShim Handle

Figure 2

3.3.2 Virtual Channel SetupVirtual Channels are set up by the Application when it processes connection events. A connection eventcan be initiated by a remote device or by a local application. When a connection event is received the

Shim passes in a Virtual Channel handle to the TIL. The Shim also passes in a transport-specific structurethat allows the application to identify the device or endpoint that is generating the connection request.A Virtual Channel is always created in the context of a Nexus. A Virtual Channel can only be associatedwith one Nexus. A Nexus may contain one or more Virtual Channels. The Virtual Channel is stored in theNexus structure along with the QoS parameters that the Virtual Channel supports.


13/83

8

3.3.3 Control Event ProcessingThe TIL provides a flexible, yet simple, mechanism for the management of control events that comefrom the Shim. These events include connection establishment, device discovery, and connectiontermination. The TIL is the sole registrant of all control messages that come from the Shim. In otherwords the Shim provides a mechanism for registering one function callback to receive all controlmessages. The TIL allows application registrants to receive these control messages through aregistration process. The normal registration routine will add the provided delegate to the front of a listof delegates that receive the control messages.

3.3.4 APDU TransmissionTransmitting of an APDU starts when one of the layers in the OXP stack creates an APDU. Based onContinua Interoperability Guidelines, a QoS value is assigned to the APDU when it is created. The QoS iscarried with the APDU with a simple identifier. Once the APDU has been generated and assigned to aQoS the APDU passes through the remainder of the OXP stack until it arrives at the bottom of theAssociation Layer. At this point, a function is called to deliver the APDU to the TIL. Since the TIL cansupport multiple concurrent OXP stacks, the Nexus identifier has to be passed to the TIL along with theAPDU. In addition to the Nexus, the TIL needs to find the Virtual Channel within the shim on which to

send the APDU. This is derived from the QoS structure. The QoS information is used to map the APDU toa particular Virtual Channel. Thus, when the APDU is sent to the TIL from the Association Layer it arriveswith two additional pieces of information, the QoS, and the Nexus. The combination of the Nexus andQoS allows the TIL to identify which Shim fnSendAPDU() call to use, and which Virtual Channel to passinto the Shim.


14/83

9

[APDU, Nexus ID, QOS]

Nexus

VC Table Entry

QoS Supported

virtual channel handle

Shim handle

TIL Consumer API

Transport Table Entry

Transport Table inShim

SHIM sendfunction

To SHIM

QOS to VC mapping

Figure 3 - Data Structures used by TIL on APDU transmission

3.3.5 APDU ReceptionOn reception of an APDU from the shim the TIL has to identify the proper nexus in order to invoke thecallback that will deliver the APDU to the right OXP stack. This identification is achieved by using theVirtual Channel identifier in conjunction with the Shim handle generated during Shim initialization. TheShim handle, and the Virtual Channel identifier, which are passed in with the APDU event, allows theproper Nexus to be located through a search of the Virtual Channel lists in each Nexus. When the VirtualChannel is located, the APDU is delivered through the APDU callback in the Nexus to the proper OXPstack.

The TIL registers with the Shim to receive APDUs. For debugging and testing purposes the TIL supportstwo additional types of registrants, one which allows a test application to see and modify an APDUbefore it is delivered for normal TIL processing, and another that allows a test application to see, but notmodify the APDU.


15/83

10

The function pointer called TCI_RegisterTestAPDUHandler is an interception of the APDU before the TILstarts processing the APDU message. This function pointer allows a testing tool the ability to modify theAPDU before the TIL starts processing the message or takes over processing the APDU all together. If theTCI_RegisterTestAPDUHandler desires to take full control of processing the APDU it will consume theAPDU. The consumption will signal the TIL to stop processing the APDU itself. If theTCI_RegisterTestAPDUHandler does not consume the APDU then the TIL will continue to process theAPDU after the TCI_RegisterTestAPDUHandler returns. This feature allows theTCI_RegisterTestAPDUHandler to change the APDU and have the TIL continue processing the APDU withthe new changes.

For sniffing purposes of an APDU which does not require an interception or changes to an APDU theTIL provides a function pointer called TCI_RegisterSnifferAPDUHandler.

TIL provider API

TIL callback

APDU dispatch table

VC handle

Nexus VC Table

nexus

SHIM

[APDU, Shim Handle, VC handle]

TIL APDUreceivehandler

20601 stack APDUcallback

Shim Handle

VC handle

Figure 4 - Data Structures used by TIL on APDU reception


16/83

11

4 Transport Interface Layer RequirementsThe TILs requirements are broken into interface, functional, and performance requirements. Additionalrequirements governing the overall operation of the VASC code base shall apply to the TIL but are notspecified here.

4.1.1 External Interface RequirementsThe TIL shall have no physical interfaces that connect it to another component.

4.1.2 Internal Interfaces (Supported APIs)The TIL shall provide an interface and define mechanisms for providers of transports thataddress issues assigned to layer four in the ISO/OSI stack model. This interface shall be sufficientto support Shims that connect USB, Bluetooth, and TCP/IP transports to the OXP stack. The TPIshould be extensible to other technologies as well.

The TIL shall provide a consumer interface (TCI) that enables an application to control thetransport layer, and enables the delivery of APDUs and connection events to the ISO/IEEE11073-20601 stack.

4.1.2.1 Transport Provider Interface (TPI)The TPI shall define an interface that enables a provider of a transport to create a Shim that will enablethe transport to be used with the VASC code base. The TPI shall:

Support multiple shims

Support a mechanism by which the transport provider can present a table of entry pointsdirectly to the application.

Provide a callback function for the transport Shim (register a callback) in order to accept amessage representing an APDU from the transport.

Provide a callback function for the transport Shim (register a callback) in order to receive controlevent notifications.

Support an event indicating that a device has been discovered by the Shim.

Support an event indicating that a device has issued a connection request.

Support an event indicating that a connection is no longer operational

Provide a mechanism that allows the Shim to represent QoS information associated with avirtual channel in a manner that is consistent with the Continua Interoperability Guidelines .

Provide a mechanism to support concurrent operation of shims using different technologies,such as USB and Bluetooth.

Accept a shim instance pointer during shim interface creation, and be able to use the instancepointer to invoke methods in the shims call table.


17/83

12

4.1.2.2 Transport Consumer Interface (TCI)The ISO/IEEE 11073-20601 specification defines the Optimized Exchange Protocol above the transportprotocol. Since applications will need to set up and configure the transport layer, the TCI must providethe services that enable this setup to be accomplished. In particular the TCI shall:

Provide an interface that enables APDUs generated by the ISO/IEEE 11073-20601 stack to bedelivered using the interoperability characterization given in the Quality of Service Strategyclause of the Continua Interoperability Guidelines .

Provide control functions to the application that enable the application to setup and map virtualchannels to OXP stacks.

Provide an inbound event dispatching mechanism that enables the application to register forthese messages. This control event mechanism shall support the ability to pass opaquestructures to the application based off event types that the TCI may not understand.

Provide an interface that allows the application to initiate the discovery, connection, anddisconnection of a Virtual Channel.

The ability to provide unique function calls in the call table and/or vendor specific attributes thatallows a Shim interface to provide functions that extend the Shim beyond the set of servicesdefined in this document.

4.1.2.3 Transport Provider ShimThe transport provider Shim interfaces to the TIL through the TPI. The TPI requires that the Shimimplement a set of functions and provide instance pointers that will enable the TIL to call thesefunctions. The set of function pointers available via the instance pointer shall be designated as the calltable , and represents the Shims interface to the TIL. The call table shall provide function pointers thatimplement the methods called out in this document. The call table may include additional functionsparticular to the transport. The Shim shall:

Support a function to initialize the transport This function shall perform the initialization stepsrequired by the transport. The Shim shall be ready to receive connection requests when theinitialization call returns. The Shim shall allocate in heap storage memory which it shall populatewith an interface structure including the call table. The Shim shall return a pointer to thisstructure which the caller can use in conjunction with the proper C casting type to invokemethods in the Shims call table. The Shim is assumed to share a common virtual memoryaddress space with the caller of the provided interface methods.

Implement a registration function that accepts a callback for control events. The Shim uponreceiving a discovery event, a connection event, a disconnection event, or other event definedfor the transport, shall invoke the callback routine and provide the shim handle, event type, andinformation appropriate for the type of event. When the Shim indicates a connection event itshall pass a 4-byte Virtual Channel handle that the receiver of the indication can use forcomparison. The Shim must ensure that the provided Virtual Channel handles are unique for allactive Virtual Channels that the Shim presents. (Note: the Shim does not have to coordinatewith other entities to track global Virtual Channel uniqueness, it only needs to ensureuniqueness within the set of Virtual Channel identifiers that it generates.)


18/83

13

Implement a registration function that accepts a callback routine for APDU arrivals. Thisregistration function shall use the provided callback routine when an APDU is received by theShim from the underlying transport. The callback function shall be passed the shim handle thatwas provided to the TIL during initialization, the virtual channel handle, the APDU, and thenumber of bytes in the APDU. Ownership of the APDU buffer is passed to the callback functionwhen the callback is invoked. The Shim shall not alter or delete the buffer once the callback hasbeen called.

Implement a function that accepts an APDU from the OXP stack for delivery by the Shim to thetransport layer. The function will provide a Virtual Channel handle which shall be used by theShim to identify the transport connections to use when delivering the APDU to the transportlayer. If the Shim is unaware of the virtual channel handle it shall return an error to the caller.The Shim shall not take ownership of the APDU buffer, alter its contents or free memory and if itneeds to use the buffer it shall make a local copy.

Implement a disconnect function that shall cause the transport layer to disconnect all transportlayer connections that are used for the Virtual Channel. The disconnect function shall accept a

Virtual Channel handle as an argument to the call. The Shim shall return an error if the VirtualChannel handle does not identify a valid VC.

If a Disconnect is received on any transport connection that is part of a Virtual Channel withmultiple transport connections, then the Disconnect of a Virtual Channel must be signaled to theTIL and if logically consistent with the operation of a given transport, the transport connectionsare disconnected.

Implement a function that shall be used to set an attribute in a table of attributes that ismaintained by the Shim and has semantics defined by the Shim. The Shim shall not modify ordelete the buffer provided by the caller. It shall, in general, return to the caller when thesemantic implied in the set operation is complete, not just the setting of the value. The

implementer of the Shim may, however, explicitly define attributes where the call may returnbefore the semantic is complete. However, Shim documentation shall explicitly identify thisbehavior.

Implement a function that shall be used to get an attribute in a table of attributes that ismaintained by the Shim. The Shim shall not allocate a buffer for the purpose of getting anattributes value, a buffer of sufficient size shall be provided by the caller. The ownership of thebuffer is returned to the caller at the time the call returns. The caller of the get functionprovides an [IN, OUT] argument to the Shim that indicates the size of the provided buffer asinput, and contains the number of used octets in the buffer on return. If the provided buffer isof insufficient size the Shim shall return an error and indicate the required size as the OUT valueof the size argument.

Define an attribute table. This table shall be composed of a sequence of TLV (type, length, value)entries. The first entry shall be of type Shim_ATTRIB_LIST_SIZE and shall have a size of 4 bytesand a value that corresponds to the size of the Shims attribute list in bytes. This attribute shallalways be present in the table. If the Shim supports no additional attributes the value returnedby getting the Shim_ATTRIB_LIST_SIZE shall be four. If additional attributes are supported theShim shall support the Shim_ATTRIB_LIST attribute which shall return a list, the size of which is


19/83

14

known from the Shim_ATTRIB_LIST_SIZE attribute. When the get function is called with anattribute value of Shim_ATTRIBUT_LIST the call shall return list and size information for eachattribute that the Shim supports.

Implement a shutdown routine that will close all transport connections and release any datamessage within the Shim. The Shim s hall generate a disconnect on all VCs that it knows aboutto the extent supported by the transport technology, this disconnect shall result in disconnectevents being dispatched locally. The Shim shall do whatever transport layer operations areappropriate to indicate that it is no longer operational. No further events or APDUs will be sentto the TIL using that disconnected VC handle. The Shim shall remove itself from registeredservices it requested from the host OS, and release any memory it has allocated. To the extentpossible it shall place itself in the state it was before it was initialized such that a new call to theinitialization routine would result in the same behavior as the first call did. Shutdown shallterminate any other logical use of the Shim.

Provide additional functions as needed to control the transport. These functions may includeconnect, bind, listen, accept functions as appropriate for the transport. The functions should

extend the transport interface using the extension capabilities of that interface.If appropriate for the transport, support a discovery mechanism that will generate one or moreevents to indicate that a device is available.

The Shim shall maintain a table of endpoints that it is aware of. These endpoints will correspondto the best mapping of logical entities that would be named by an application when establishingconnections to OXP stacks in the given transport technology. There shall always be an entry foractive connections, and if the technology supports a discovery mechanism there shall be entriesfor discovered endpoints. The information in an entry shall be consistent with the informationthe shim receives on a request to establish a virtual channel, and on discovery and connectionevents that the Shim indicates.

For each entry in the table of endpoints the Shim shall assign a unique 32 bit identifier that shallbe part of the information describing the endpoint. The identifier shall allow upper level code toidentify and compare devices. The identifier shall always be included whenever the endpoint ispresented by the Shim to the upper layers.

Must identify APDU boundaries and segment the data stream delivered to the TIL such that eachmessage dispatched is a single and complete APDU.

Must terminate a reliable Virtual Channels if an APDU on that Virtual Channel is unable to beproperly processed in either the inbound or outbound direction. Termination involves, atminimum, causing the local OXP stack to see a disconnection event. It is highly desirable to

cause the remote end to also see a disconnect event, but not required.

Code should be written in portable C using POSIX calls.

If a virtual channel is composed of multiple transport connections and a disconnection is seenon more than one transport connections in the virtual channel the Shim shall indicate only once(by issuing an event) that the virtual channel is disconnected, release the virtual channels


20/83

15

resources, and disconnect the remaining transport connections as appropriate for thetechnology.

4.1.3 Functional Requirements of TILThe functional requirements of the TIL are summarized below. Detailed information can be found byreading the overview section and by review of the module descriptions in the section of SoftwareLayout.

The TIL shall be able to discover the set of transport Shims available to it.

The OXP protocol shall operate over a USB interface.

The OXP protocol shall operate over a Bluetooth interface.

The OXP protocol shall be able to operate over a TCP interface.

The TIL shall be able to support the operation of multiple concurrent OXP stacks

The TIL shall enable an application, within the abilities of the transport, to establish connectionsthat meet application specified QoS requirements.

The TIL shall be able to support OXP stacks which require multiple virtual channels.

The TIL shall support, within the abilities of the transport, reliable virtual channels fortransmitting APDUs.

The TIL shall support, within the abilities of the transport, best effort virtual channels fortransmitting APDUs.

4.1.4 Performance RequirementsThe TIL does not have any explicit performance requirements.


21/83

16

5 TIL ComponentsError! Reference source not found. This section presents an overview of the Transport Interface Layerof VASC as it operates in the context of an overall system. The figure also shows how the majorcomponents of the TIL relate to each other. A more detailed description of the major components ispresented in this clause.

5.1 NexusThe ISO/IEEE 11073-20601 protocol is written from the perspective of two peers communicating over afacility that is either connected or disconnected. The communication facility is composed of one or morevirtual channels that provide either reliable or best-effort services. In VASC this communication facility isrepresented by the nexus. The nexus is the pipe between an Agent and a Manager, over which all theAPDUs exchanged between the two are sent. A nexus always represents exactly two OXP stacks, and agiven OXP stack can never be involved in two nexuses at the same time. The nexus is created by theapplication. The structure representing the nexus is maintained by the TIL, and it exists from the point intime when the application creates it until the application explicitly removes it. The TIL does not removean association nexus for any reason except by request from the application.

Within the nexus is a table of virtual channels, representing pipes that can be used to deliver APDUs tothe remote peer. Each virtual channel provides a link to a transport connection. The informationcontained in the virtual channel includes the QoS parameter, device identifier and a handle to theVirtual Channel within the shim. Typically the application passes the Nexus the virtual channel providedby the shim in connection events when creating the Nexus and when adding additional connections.This is a copy of the virtual channel with a QoS and device identifier filled in as well as handle to theactual virtual channel structure within the shim.

In the nexus are two dispatch points, one for inbound APDUs and one for inbound events. The tables arenormally populated by callback routines that deliver the inbound information to the OXP stack. Themessages are freed by the shim if there are no callbacks which consume them and the TIL does notconsume it (in most instances the TIL will not consume the messages).

The Association Nexus, which may be composed of multiple VCs, must represent itself to the associationstate machine as a single connected or disconnected pipe. The TIL owns the Association Nexus. Itallocates the memory for it, and releases it as requested. It exports an opaque handle (the nexus id) tothe caller that creates or updates the nexus which the TIL expects to receive back on outbound APDUsfrom the OXP.

The nexus maintains an identification of the remote endpoint. The identifier shall be comparable as a 32bit unsigned integer. This remote endpoint identifier is used to ensure that a VC is never added to anexus that doesnt transport APDUs to the same OXP stack. If it is not possible to properly identify theremote peers OXP stack this value shall be set to zero. A VC can always be added to the nexus if it isassociated with a remote endpoint that has an id of zero.


22/83

17

OXP callback

NULL

NULL

Event Dispatch Table

APDU Dispatch Table

Shim handle

VC handle

QOS info

Virtual channel entry

VC handle

QOS info

Virtual channel entry

Virtual Channel Table

OXP callback

endpoint identifier

Figure 5 Association Nexus

5.2 Virtual ChannelThe primary purpose of the TIL is to manage transport resources and make them available to connectISO/IEEE 11073-20601 Agents and Managers. To do this task, the Shim represents the concept of one ormore transport level connections as a Virtual Channel. A Virtual Channel is an abstracted set of one or

more transport connections that provide a bidirectional path with consistent QoS parameters on bothdirections of transmission. (Some devices consider a connection one-way and thus a round trip wouldconsist of two connections; those two connections would map to a virtual channel.) APDUs which are tobe transmitted arrive at the TIL in the context of an Association Nexus and have a QoS requirement. TheTIL transmits the APDU using a Virtual Channel that is compatible with the QoS requirements of theAPDU. The Virtual Channel creation is controlled by the application, typically through a connectionevent. However, an application may manually populate the virtual channel table with a Virtual Channelobtained by other means, though the application must assure that the information structurerepresented by the virtual channel handle is correct and that the shim receiving that information alsounderstands it.

Virtual channel QoS information is based on the 12-box model defined by the Continua InteroperabilityGuidelines.

5.3 Transport EndpointsEach supported transport provides a facility to move an APDU from a source endpoint to a destinationendpoint. Although Endpoint may have specific meaning within a transport, as it is used here it refersto the final addressable point of the transport protocol where an OXP stack is expected to reside. Thestructure of information needed to identify and address an APDU to an endpoint, however, is different


23/83

18

for each transport technology. The TIL is opaque to transport endpoint addressing, requiring theapplication to be involved when knowledge of the addressing of an endpoint is required. When atransport Shim requires the application to identify a transport endpoint, it defines an endpoint handlewhich the application uses in communications with the Shim. The provider of a transport may maintain atable of transport endpoints that it is aware of. This table is called the Transport Endpoint Table (TET).The transport Shim may provide the application access to this table allowing the application to establishconnections to known endpoints.

Discovery is the process by which some transports identify the set of endpoints that are compatible witha given node. The Shim is expected to populate its TET during the discovery process with endpointswhich may be OXP peers for the application(s) running over the TIL. To execute discovery properly, itmay be necessary for the Shim to be provided with characteristics of the application environment. Thisexchange of information is done by populating the Shim with profiles of the characteristics that theapplication is expected to support.

5.4 ProfilesProfiles are provided by applications and allow an application to configure the Shim with information it

may need to present itself during discovery. A Shim normally supports one profile, but may supportmultiple profiles if it is possible to run concurrent Agents and Managers over the same Shim.

5.5 Transport ShimsThe transport Shim is the code that implements the functionality defined in the transport providers API.The TIL defines a mechanism by which the Shim can expose an extensible set of functions and attributesto the application. The TIL itself requires a defined set of services that the Shim must implement. Henceeach transport Shim contains a basic set of services that allows the TIL to send and receive APDUs, anddetect connection-oriented events. In addition, the Shim may contain a number of additional elementsthat extend the interface of the Shim. The application is expected to use these functions directly tocontrol the operation of the transport.

All specialized services required by the transport, such as metadata for connections, security keys, andinitialization parameters must be addressed by the Shim through exposing an interface that will allowthe application to provide the requested information or by defining additional attributes.

5.6 Transport Provider APIThe provider API defines the interface between the transport Shim and the TIL. The details of this APIare defined in section 7. The API allows a vendor to export a set of function calls, receive APDUs fortransmission, and provide APDUs and events to the TIL.

5.7 Transport Consumer APIThe consumer API provides the interface to move data APDUs from the TIL to the association layer of the OXP stack as well as the interface to discover and initialize the transport Shims. The application usesthis API in conjunction with the functions exported by the transport Shim to link the OXP stack to thetransport layer of choice.


24/83

19

6 Functional BehaviorThe functional behavior for major operations is described in this section in order to provide a systemlevel view of TIL operation.

6.1 InitializationThe initialization process involves steps taken by both the TIL and the application. Some elements of thisprocess are described in more detail in Section 6.2 Connection Management.

6.1.1 Transport Shim initialization

DynamicLoading

Search a directoryfor DLLs

Begin

yes

Register Interface

DLLs Found

END

no

yes

RegistrationSucceeded

No

Add Int erface toTransport Interface

Listyes

Load StaticInterface

Figure 6 Loading of Transport Shims


25/83

20

The TIL is initialized by a call to TCI_InitializeTIL, which causes the TIL to invoke a routine calledLoadTransportInterface . Load transport interface is responsible for finding Shims. This modulecan be compiled such that it will use a dynamic searching technique to find modules, as shown below, orreturn a static interface table. The static table is specifically designed to be used in environments wherethe dynamic loading process would result in significant resource issues and it is expected that theimplementer would modify the provided TIL source code to satisfy the particular needs. The TIL thencalls ConstructTransportInterface on each loaded shim which provides the TIL with a shim handle andtransport interface table.

The TIL uses the interface information to register callbacks with each shim. At the completion of the callthe TIL will have created the Transport Interface Table and populated it with an entry for each Shim thatwas loaded. It will not have yet made any calls into the Shims call table (except to register callbacks), orperformed any manipulation of the Shims attributes.

6.2 Connection Management The semantics of connection establishment and termination varies significantly between differenttransport technologies. Wired USB devices become active when plugged into the bus and do not, in

general, require intervention above the USB driver. By way of contrast a device that is using the TCPtransport will need to go through a number of steps that will involve application level support before thetransport is ready to exchange APDUs. In most situations connection setup involves the application, theTIL, and the transport Shim. Decision making, such as endpoint selection and mapping of connections toOXP stacks is performed by the application. The TIL and transport Shim provide the services required bythe application to handle connection setup.

The OXP understands only two indications related to the control of a transport, an indication that theunderlying transport is operational and ready to exchange APDUs, and an indication that it is no longerable to exchange APDUs. The TIL, in conjunction with the application, is responsible for working with theShim to perform all other control plane management. Within the VASC architecture, the TIL providesmostly mechanisms for connection management, with policy requiring application involvement.

The TIL provides three primary mechanisms to support connection management:

The loading of the transport providers call table, enabling the application to detect whichtransports are available and to make the necessary calls to manage the connection within thecontext of the transport.

The passing of connection related control events up to the application to allow the applicationto decide whether or not it wants to signal the association layer state machine with the TILsTCI_SignalOXPStack call.

The use of the attribute mechanism to define configuration information needed by the Shim.


26/83

21

Application TIL TransportSHIM20601 Stack

LoadTransportInterface

ListOfLoadedTransportInterfaces

Success/Fail

ReturnFronControlMessage

TCI_InitTransport(void* vpTransportInfo)

ControlMessage(EventType, void* sEventObject) In this case Discovery Event Type

Succeed/Fail

Succeed/Fail

Succeed/Fail

TCI_VirtualChannelRequest(Endpoint)

Succeed/Fail

ControlMessage(EventType, void* sEventObject)[ConnectionEvent] in this case TransportInterface, VirtualChannel*, QOS

TILControlMessage - Type Connection Event

ControlMessage - Type Discovery Event

Succeed/Fail

TCI_AddProfile

Success/Fail

CreateNexus

Success/Fail

callback completes

TCI_InitializeTIL

TCI_RegisterControlMessageHandler

TPI_AddProfile

Success/Fail

TPI_ConstructTransportInterface

TPI_RegisterControlMessageHandler

TPI_RegisterAPDUHandler

Success/Failure

Success/Failure

TPI_InitTransport(void* vpTransportInfo)

Succeed/Fail

TPI_VirtualChannelRequest(Endpoint)

TCI_AddVirtualChannel(nexus, shim, VC, QoS)

Succeed/Fail

Shim Handle (call table)

TCI_SignalStack

Success/Fail


27/83

22

Figure 7 Transport Sequence Diagram

The sequence of events that occur to get a connection established from a VASC application and aremote client is detailed in Figure 7 (Note: Figure 7 describes the minimum set of events needed toestablish a connection. Additional events might be required specific to each type of transport. See eachtransport section for more details).

The Application starts by initializing the TIL which in turns loads the transport interfaces that areeither statically or dynamically linked. Once the Transport Interfaces are loaded a call to the Transport Interfaces provider TPI_Cons tructTransportInterface is made to obtain the Shimhandle. The Shim handle is used by the TIL to register a ControlMessageHandler delegate andReceiveAPDU delegate. Finally, the TIL returns from the Initialization routine with a list of loaded Transport Interfaces. The list includes the Shim Handles for each loaded Shim.

The Application then registers a ControlMessageHandler with the TIL for Control Messages.

The Application then calls TCI_AddProfile method to set the Profile of the Device that theApplication wishes to act as. For example; Agent that is a Weight Scale, or a Manager.

The Application Calls TCI_InitTransport to initialize the Transport Shim. The application shouldbe ready to handle control events when this call is made. The Shim must be ready to handle allstandard interface methods when it allows this call to return (assuming the call succeeded). TheShim shall have started any discovery process that it supports.

The application waits for a Control Message of type DiscoveryEvent , DiscoveryFinished or Connection Established if discovery is part of the transport protocol, otherwise it skips the

discovery process and either initiates or waits for a connection.

If the application gets a Control Message (by the TIL) of type DiscoveryEvent then it will use theinformation provided with the event to determine if it wishes to establish a connection with thedevice that the Transport Interface (Shim) discovered. If the Application wishes to establish aVirtual Channel it will issue a TCI_RequestVirtualChannel call.

The Transport Shim gets a TPI_RequestVirtualChannel, and when it has established thetransport connection(s) to the remote host and created the Virtual Channel, it delivers the eventto the TIL. The TIL then dispatches the event to any entities that have registered for it. If none of the entities consume the event then the TIL passes control back to the Shim with an indicationthat the event has not been consumed. If the event is consumed when the callback returns to

the Shim, the Shim updates the endpoint in the endpoint table to include its usage of this virtualchannel. If the virtual channel connection event was not consumed then the Shim shall releaselocal resources for the virtual channel and the virtual channel handle provided in the connectionevent shall not be reused until the Shim has received a TPI_Shutdown call. The Shim shouldhandle the semantics of the transport connection in a manner that is consistent with thetransport technology, such that the remote peer is aware, to the extent possible, that a virtual


28/83

23

channel was not established and transport resources used to support that virtual channel arenot needed.

The Application upon receipt of a connection Event calls a method in the TIL to create a Nexuspassing in the shim handle and the Virtual Channel from the connection event. This calleffectively sets up the OXP stack in the nexus to receive APDUs.

The application then calls TCI_SignalStack to cause the OXP stack to see the connection event.(Note: In a single thread model care must be taken to ensure that the completion of theconnection event is seen by the Shim before the Shim sees an APDU on the virtual channel.)

Finally, the application returns from the function call that was invoked by the Transport Shim.

There are four envisioned use cases that may arise when establishing connections with differenttransports. These use cases are outlined in the sections that follow.

6.2.1 Application Initiated Passive ConnectionA socket-based implementation of TCP is an example of a transport technology that requires the

application to perform several calls in order to establish a connection. In the passive flavor, where theapplication awaits a connection from a remote peer, a listening port has to be established before aconnection can be accepted. The following steps are used to create the connection and pass theconnection indication onto the OXP.

Initialize the TIL

Register a callback function for the TCP transport control indications. This allows the applicationto see the TCP connection indication before it is passed to OXP.

The TCP transport providers call table can then be used to call the socket, bind, and listen entrypoints.

When the connection indication arrives on the callback, create a Nexus with the VC handle fromthe connection event which will map the VC to the TCP transport, theVCs QoS, and endpoint.The TCP transport will have provided a socket identifier on the connection indication which isrecorded with the VCs transport dependent structure.

Pass the connection indication on to the TIL, which will cause it to be passed to the OXP.

Call the TCP transports accept function to compete the connection establishment.

At this point the Nexus is populated with the VC and is ready to receive APDUs.

6.2.2 Application Initiated Active ConnectionAn application attempts to establish a TCP connection to a well known TCP port. This case is similar tothat of the Application Initiated Passive Connection, but not identical.

Initialize the TIL

Register a callback function for the TCP transport control indications. This allows the applicationto see the TCP connection indication before it is passed to OXP.


29/83

24

Use the TCP transport providers call table to call the socket, and bind calls.

Issue the TCP transport connect call providing an y addition information needed to completethe TCP connection.

When the TCP transport invokes the callback indicating that a connection has been established

create a nexus passing in the Virtual Channel handle from the connection event which maps theVirtua l Channel to the TCP transport, the VCs QoS, and endpoint. The TCP transport will haveprovided a socket identifier with the connection indication; this identifier is recorded with theVirtual Channels transport -dependent structure.

Pass the connection indication on to the TIL, which passes it to the OXP.

The connection is now in place and the OXP protocol will start.

6.2.3 Transport Initiated ConnectionIn transports such as USB a connection is established when the USB device is physically connected to thebus. In this case the application follows the steps outlined below:

Initialize the TIL

Register a callback function for the USB transport control indications. This allows the applicationto see the USB connect indication that is issued by the transport provider module when thetransport is ready to exchange APDUs.

Establish configuration information as needed and initiate a discovery process

When the USB Shim indicates that it has discovered a compatible device, request a connectionto that device.

When the US B Shim asserts the connection established event the callback is invoked and theQoS parameters and USB device information of the connection are passed in.

The callback validates the device based on local policy and if acceptable the application createsa nexus passing in theVC handle from the connection event.

Pass the connection indication on to the TIL, which passes it to the OXP.

The connection is now in place and the OXP protocol will start operation.

Note that the exact behavior of a transport-initiated connection will depend on the role the code isplaying. Managers may need to support multiple arriving connections from different devices, whileAgents should never see this condition.

6.2.4 Disconnection EventsWhen a disconnect event is received by the TIL on any connection, it processes the control event in thenormal manner. If the event comes back to the TIL from the registered entities then the TIL examinesthe event to see if it is a disconnection event. If it is a disconnection event it uses the virtual channelinformation to identify the nexus that owns the virtual channel. The disconnect event is then passed tothe OXP stack of that nexus. If the virtual channel cannot be found, the event is passed back to the Shim.


30/83

25

6.3 Transmission of APDUsOnce the application and TIL have set up the structures associated with the transport interface and theconnections, the movement of APDUs through the TIL is straightforward. The OXP generates an APDU toexchange with its remote peer in the context of a Nexus. The Nexus is established when the applicationassigned connections to the Nexus. In addition to being in a Nexus context, all APDUs are in the context

of a QoS. The QoS and Nexus information is passed from the OXP stack to the TIL using the send methodof the Transport Consumer Interface. The ownership of the buffer is passed to the TIL when the sendmethod is called. Once the send method is called the TIL performs the following steps:

The Nexus identifier is used to lookup the nexus entry in the nexus table. The send methodsearches the virtual channel table in the Nexus to determine if there is a virtual channel withacceptable QoS characteristics. If no acceptable VC is found the send call returns an error.

Once the virtual channel is known it is used in conjunction with the shim handle to locate thecall table of the transport Shim.

The shim handle is used to index into the TILs transport table from which the appropriate

transport-specific send method is called.The transport-specific send method accepts the buffer and length assuming it to be a completeAPDU and delivers it to the transport layer. The ownership of the buffer is passed to thetransport Shim when the transport specific send is called. The send method is also passed theVC identifier.

6.4 Reception of APDUsThe reception process moves data from the transport layer and delivers in to the OXP stack.

The transport layer delivers data to the transport Shim.

If additional protocols have been used to maintain APDU alignment, the Shim removes theseheaders. The Shim does any de-multiplexing operations required to obtain a single APDU.

The Shim looks up the single registered callback in the dispatch table for APDUs and invokes thecall passing the buffer, the buffer length, the connection identifier, and the shim handle. Whenthe callback is invoked the Shim releases ownership of the buffer. If the Shim cant releasebuffer ownership it must use copy semantics and pass a copy of a buffer that it can release.

The TIL uses the shim handle to look up the proper entry in the transport table. It then searchesthe VC list to find the VC identifier passed in with the APDU. This allows the TIL to obtain thenexus context.

The TIL then uses the nexus context to identify the dispatcher that delivers the message to theOXP stack. The dispatch process either consumes or passes the message on. If the message isconsumed the TIL is done. (Note that applications that insert callbacks into the dispatch tablemust make sure that they do not destroy the reliability of a transport connection.) If themessage is not consumed the TIL calls the next callback in the dispatch list until all callbackshave been invoked. If the TIL has not delivered the message and it is on a reliable channel theTIL returns the message to the Shim.


31/83

26

The Shim, if it is unable to dispatch the message and the message is on a reliable channeldisconnects the transport connection.


32/83

27

7 Software Design

7.1 ConventionsSoftware conventions used within the TIL.

7.1.1 Transport Specific Structures of unknown typesThe TIL must manage structures that will be specific to particular transports. These structures aredesigned so that they can be properly copied by software components that do not understand thestructures. The structures are identified using TLV (Type-Length-Value) notation, where the Lengthcomponent describes the size of the Value component in bytes.

7.1.2 HANDLESBoth the shim and the TIL allocate structures in memory that are used as handles. These handles can becompared by the application as they are guaranteed to be unique across the defined lifetimes that thestructures represent. The handles are returned as VASCHANDLES which is simply a void * pointer, assuch they can be cast to the corresponding data structures they represent. To maintain upwardcompatibility application code should treat VASCHANDLES as opaque objects. When the underlying data

structure of the VASCHANDLE is used, such as to get to vendor extended capabilities, the code becomesdependent on the current definition of the underlying structure.

7.2 Software ComponentsThe Transport Interface Layer is composed of the TCI, the TPI, and internal routines. The TPI isimplemented as part of shims that connect to specific transports. For the initial release of VASC thereare three defined shims for Bluetooth, USB and TCP.

7.2.1 API RoutinesAPI routines are broken into those related to the TCI and those related to the TPI.

7.2.1.1 Transport Consumer Interface Routines [TCI]

The Transport Consumer Module provides the Transport Consumer API to create, initialize and usedifferent transport mechanisms that are either statically or dynamically linked. The table belowidentifies the set of routines that make up the TCI.

TCI Routine NameExt/Sup

Description

TCI_AddProfile E/Y Adds a profile to a Shim

TCI_AddCallbacksToNexus I Adds callbacks to process connection events and APDUs. These callba

TCI_AddVirtualChannel E/Y Adds a virtual channel to a nexus

TCI_ClearProfileList E/N Removes all profiles on a ShimTCI_CreateNexus I Creates a nexus shell

TCI_DeleteNexus I Removes all references to a nexus from the TIL and releases its transp

TCI_ClearNexus I Removes all transport specific information from the Nexus (VC and s

TCI_DisconnectVirtualChannel E/Y Causes a Shim to disconnect a virtual channel

TCI_GetControlDispatchList I Allows application to get the list of function pointers used for dispatch


33/83

28

TCI_FreeRegisteredFunction E/N Removes the registered function from the list (test and sniffer list only

TCI_GetAttribute E/Y Wrapper function to TPI routine that returns an Attribute defined by t

TCI_GetFirstEndPoint E/Y Wrapper function to TPI routine to get first endpoint from Shim

TCI_GetNextEndPoint E/Y Wrapper function to TPI routine to get next endpoint from Shim

TCI_GetFirstProfile E/Y Get the first profile stored in a shimTCI_GetNextProfile E/Y Get the next profile stored in a shim

TCI_GetFirstTransportInterface E/Y Get the first Transport Interface for the TILs list of transport interface

TCI_GetNextTransportInterface E/Y Get the next transport interface from the list of transport interfaces m

TCI_GetFirstVirtualChannel E/Y Wrapper function to TPI routine to get next VirtualChannel from Shim

TCI_GetNextVirtualChannel E/Y Wrapper function to TPI routine to get next VirtualChannel from Shim

TCI_InitializeTIL E/Y Initializes the TIL, returning a list of transport shims handles.

TCI_InitializeTransport E/Y Causes the specified transport to start operation

TCI_RegisterControlMessageHandler E/Y Registers a callback with the TIL to which control events will be sent

TCI_RegisterTestAPDUHandler I Allows an APDU to be captured and changed

TCI_RegisterSnifferAPDUHandler I Allows an APDU to be seen, but not modified

TCI_RequestVirtualChannel E/Y Instructs a shim to establish a virtual channel, and to attempt a conne

TCI_SendAPDU E/Y Delivers an APDU to the TIL

TCI_SetAttribute E/N Wrapper routine to TPI_SetAttribute which returns an attribute from

TCI_SetControlDispatchList E/N Updates the dispatch list using the values provided by the application.

TCI_ShutdownTransport E/N Causes the transport to close connections and release resources.

TCI_SignalOXPStack E/Y Passes a control message to the input of the OXP stack identified by t

TCI_Free E/Y Frees the memory that was allocated on the ShimTCI_Delete E/Y Frees a structure and all sub-structures that were allocated on the shi

7.2.1.1.1 TCI_AddProfile

Synopsis:

eResultCode TCI_AddProfile(VASCHANDLE hTIL, VASCHANDLE hShim, sProfile Profile);

Description:

This method is a wrapper for the corresponding TPI call. Please see TPI documentation for additionalinformation on this method.

Parameters:

Input:VASCHANDLE hTIL - Handle returned by TCI_InitializeTIL()


34/83

29

VASCHANDLE hShim - Handle returned by TCI_GetFirst/NextTransportInterface()sProfile The profile to be added.

Output:None

Returns:eResultCode

Detected Error Conditions:

The TIL handle is NULL or invalid (INVALIDARG)The Shim handle is NULL or invalid (INVALIDARG)The Shim does not support profiles (NOTSUPPORTED)No additional profiles can be added (LIMITEXCEEDED)The profile requested is not supported (NOTSUPPORTED)

7.2.1.1.2 TCI_ClearProfileList

Synopsis:

eResultCode TCI_ClearProfileList(VASCHANDLE hTIL, VASCHANDLE hShim);

Description:

This method is a wrapper for the corresponding TPI call. Please see TPI documentation for additionalinformation on this method.

Parameters:

Input:VASCHANDLE hTIL TIL context handleVASCHANDLE hShim Shim context handle

Output:None

Returns:eResultCode

Defined Error Conditions:

The Shim handle is NULL or invalid (INVALIDARG)The Shim does not support profiles (NOTSUPPORTED)

7.2.1.1.3 TCI _GetFirstProfile, TCI_GetNextProfile

Synopsis:

eResultcode TCI_GetFirstProfile(VASCHANDLE hTIL, VASCHANDLE hShim, VASCHANDLE*hIterator, size_t bsize, sProfile* Profile);


35/83

30

eResultcode TCI_GetNextProfile(VASCHANDLE hTIL, VASCHANDLE hShim, VASCHANDLE*hIterator, size_t bsize, sProfile* Profile);

Description:

These methods are wrappers for the corresponding TPI calls. Please see TPI documentation foradditional information on this method.

Parameters:

Input:VASCHANDLE hTIL TIL context handleVASCHANDLE hShim Shim context handleVASCHANDLE *hIterator - pointer to a handle to be used as an iterator.Size_t bsize The size of the profile buffer in bytes

Output:sProfile* Profile The buffer for the profile structure

Returns:

eResultCode

Memory Management

The Shim shall check the size of the buffer and not write beyond the size provided. If the buffer isnot large enough to hold the profile it shall return an error.


The TIL handle is NULL or invalid (INVALIDARG)The Shim handle is NULL or invalid (INVALIDARG)hIterator is NULL or invalid (INVALIDARG) pointer to NULL is okay in the TCI_GetFirstProfile callThe Shim does not support profiles (NOTSUPPORTED)Requested entity does not exist There is no profile stored on the Shim, or the request is for a

profile beyond the end of the list. (LIMITEXCEEDED)

7.2.1.1.4 TCI_CreateNexus

Synopsis:

eResultCode = TCI_CreateNexus(VASCHANDLE hTIL, VASCHANDLE hShim, VASCHANDLEpsVirtualChannelInfo, void* pvOnReceivePDU, void* pvOnChangeLinkStatus, sNexus**psNexus, APPHANDLE hApp );

Description:

Create the Nexus. A Nexus provides the context that enables mapping between peer OXP stacks. Allof the virtual channels in a Nexus are required to map to the same OXP peer. When the Nexus iscreated it may be created in the context of a transport, and a device addressed through thattransport. If it is not, the Nexus is placed into the context of a transport the first time a virtualchannel is added to it. The Nexus forces all virtual channels connecting this OXP stack to the remotedevice to use one transport. The transport is identified by the Shim handle. The Shim handle


36/83

31

remains with the Nexus for the duration of the Nexus. It is not possible to establish one virtualchannel to a device via Bluetooth and another via USB as they would use different Shims.

Parameters:

Input:

VASCHANDLE hTIL - Handle to TILVASCHANDLE hShim - Handle to Shim (may be NULL)VASCHANDLE psChannelInfo - This is an instantiated virtual channel in a shim. The

VASCHANDLE is the virtual channel identifier based on the memory address of theallocated sVirtualChannelInfo structure. (may be NULL)

void* pvOnReceivePDU - callback for receiving PDUs (may be NULL)void* pvOnChangeLinkStatus -callback for link status change (may be NULL)APPHANDLE hApp - Application Context handle that is added to the Nexus. Each

Nexus is unique for an application. When an APDU isreceived, the App handle is needed to specify whichapplication should be notified.

Output: Nexus* pNexus pointer to the Nexus that is createdReturns:

eResultCode


The TIL handle is NULL or invalid (INVALIDARG)Unable to perform requested operation (FAIL)

7.2.1.1.5 TCI_DeleteNexus

Synopsis:

eResultCode TCI_DeleteNexus(VASCHANDLE hTIL, Nexus* pNexus);

Description:

This method deletes a Nexus that is stored in the TIL by passing a pointer to a Nexus that theapplication is using to send/receive messages on. When this method is invoked the TIL will force adisconnect event into the OXP stack associated with this Nexus, remove this nexus from the list of Nexuses known to the TIL, and call TPI_DisconnectVirtualChannel for all virtual channels that belongto this Nexus.

Parameters:

Input:VASCHANDLE hTIL - Handle to TILNexus* pNexus pointer to the Nexus to be deleted

Output:


37/83

32

Returns:eResultCode


The TIL handle is NULL or invalid (INVALIDARG)The Nexus is NULL or invalid (INVALIDARG)Unable to perform requested operation (FAIL)

7.2.1.1.6 TCI_ClearNexus

Synopsis:

eResultCode TCI_ClearNexus(VASCHANDLE hTIL, Nexus* pNexus);

Description:

This method removes all transport specific information from the Nexus (VCs and the SHIM handle).

TPI_DisconnectVirtualChannel is called for all virtual channels that belong to this Nexus. This is donein order to disconnect from a given device and transport. The Nexus remain intact and the callbacksremain registered. The Nexus is NOT removed from the list of Nexuses known to the TIL.

Parameters:

Input:VASCHANDLE hTIL - Handle to TILNexus* pNexus pointer to the Nexus to be cleared

Output:

Returns:eResultCode


The TIL handle is NULL or invalid (INVALIDARG)The Nexus is NULL or invalid (INVALIDARG)Unable to perform requested operation (FAIL)

7.2.1.1.7 TCI_AddVirtualChannel

Synopsis:

eResultCode TCI_AddVirtualChannel(VASCHANDLE hTIL, VASCHANDLE hShim, sNexus*psNexus, VASCHANDLE psChannelInfo, VASCBOOL bAllowDeviceEndPoint);

Description:

This method adds a virtual channel to a Nexus. All virtual channels added to a nexus must referencethe same peer OXP stack. If this nexus does not contain any virtual channels, the Shim associatedwith this call establishes the Shim context. All future calls to AddVirtualChannel must use to same


38/83

33

Shim. The peer OXP stack is not explicitly defined at a transport level and situations may arise whereit is necessary to override the normal behavior of identifying the endpoint via the Shim provideddevice identification. In this case the bAllowDeviceEndPoint flag shall be set. When this flag is setthe virtual channel may be added independent of the existing device identification in the nexus. TheTCI_CreateNexus call establishes the transport (shim handle) and device identifier that will be usedto detect the peer OXP stack. The device identifier is taken from the deviceID field of thesVirtualChannelInfo structure. If the virtual channel being added does not reference the samedeviceID and the same Shim handle, and bAllowDeviceEndPoint is not set, then an error is returnedto the caller and the virtual channel is not added. In normal operation the virtual channel that isadded is returned from the shim through the TCI_RequestVirtualChannel call or through theTCI_GetFirst/NetxtVirtualChannel methods. If psChannelInfo points to a virtual channel that has notbeen returned as a VASCHANDLE by a shim, the caller is responsible for ensuring that the handlerepresents an instantiated virtual channel within the shim.

Parameters:

Input:

VASCHANDLE hTIL - Handle to TILVASCHANDLE hShim Identifies the Shim on which the virtual channel was generated.sNexus* psNexus Nexus to which the virtual channel will be added.VASCHANDLE psChannelInfo This is an instantiated virtual channel in a shim. The

VASCHANDLE is the virtual channel identifier based on the memory address of theallocated sVirtualChannelInfo structure.

Output:

Returns:eResultCode


The TIL handle is NULL or invalid (INVALIDARG)The Shim handle is NULL or invalid (INVALIDARG)The Nexus handle is NULL