IR Library
 

 < Home   < Developers   < Development Support   < Documentation

60 IR Library


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part III: Communications

60 IR Library

IR Library Data Structures

IrConnect

IrPacket

IrIASObject

IrIasQuery

IrCallbackParms

IrStatsType

IR Library Constants

IR Control Constants

IR Stack Callback Events

LEVENT_DATA_IND

LEVENT_DISCOVERY_CNF

LEVENT_LAP_CON_CNF

LEVENT_LAP_CON_IND

LEVENT_LAP_DISCON_IND

LEVENT_LM_CON_CNF

LEVENT_LM_CON_IND

LEVENT_LM_DISCON_IND

LEVENT_PACKET_HANDLED

LEVENT_STATUS_IND

LEVENT_TEST_CNF

LEVENT_TEST_IND

IR Library Functions

IrAdvanceCredit

IrBind

IrClose

IrConnectIrLap

IrConnectReq

IrConnectRsp

IrDataReq

IrDisconnectIrLap

IrDiscoverReq

IrIsIrLapConnected

IrIsMediaBusy

IrIsNoProgress

IrIsRemoteBusy

IrLocalBusy

IrMaxRxSize

IrMaxTxSize

IrOpen

IrSetConTypeLMP

IrSetConTypeTTP

IrSetDeviceInfo

IrTestReq

IrUnbind

IAS Functions

IrIAS_Add

IrIAS_GetInteger

IrIAS_GetIntLsap

IrIAS_GetObjectID

IrIAS_GetOctetString

IrIAS_GetOctetStringLen

IrIAS_GetType

IrIAS_GetUserString

IrIAS_GetUserStringCharSet

IrIAS_GetUserStringLen

IrIAS_Next

IrIAS_Query

IrIAS_SetDeviceName

IrIAS_StartResult

Application-Defined Functions

IrIasQueryCallBack

       

The IR (InfraRed) library is a shared library that provides a direct interface to the IR communications capabilities of the Palm OS®. This chapter provides reference material for the IR library API:

IR Library Data Structures

IR Library Constants

IR Stack Callback Events

IR Library Functions

IAS Functions

Application-Defined Functions

The header file irlib.h declares the IR library API. For more information on the IR library, see the chapter "Beaming (Infrared Communication)" in the Palm OS Programmer's Companion, vol. II, Communications.

IR Library Data Structures

This section lists some of the more important data types used by the IR library functions.

IrConnect

The IrConnect structure is used to manage an IrLMP or Tiny TP connection.

typedef struct _hconnect { 
  UInt8 lLsap; 
  UInt8 rLsap; 
  UInt8 flags; 
  UInt8 reserved; 
  IrCallBack callBack; 
  IrPacket packet; 
  ListEntry packets; 
  UInt16 sendCredit; 
  UInt8 availCredit; 
  UInt8 dataOff; 
} _hconnect; 

Field Descriptions

lLsap
The local LSAP on which this connection listens.
rLsap
The LSAP assigned to the remote side.
flags
For system use only.
reserved
Reserved for future use.
callBack
Pointer to callback function. For system use only.
packet
For system use only.
packets
List of packets to send.
sendCredit
Amount of credit from peer.
availCredit
Amount of credit to give to peer.
dataOff
Amount of data less than IrLAP size.

IrPacket

The IrPacket structure is used for sending IrDA packets.

typedef struct _IrPacket { 
  ListEntry node; 
  UInt8 *buff; 
  UInt16 len; 
  IrConnect* origin; 
  UInt8 headerLen; 
  UInt8 header[14]; 
  UInt8 reserved; 
} IrPacket; 

Field Descriptions

node
For system use only.
buff
Pointer to the send data buffer.
len
Number of bytes in data buffer.
origin
Pointer to connection that owns the packet. For system use only.
headerLen
Number of bytes contained in the header. For system use only.
header
Storage for header. For system use only.
reserved
Reserved for future use.

IMPORTANT: The node field must be the first field in the structure. It is used internally by the stack.

IrIASObject

The IrIASObject structure is used as storage for an IAS object managed by the local IAS server. An object of this type is passed as the obj parameter to the IrIAS_Add function.

typedef struct _IrIasObject { 
  UInt8 *name; 
  UInt8 len; 
  UInt8 nAttribs; 
  IrIasAttribute* attribs; 
} IrIasObject; 

Field Descriptions

name
Pointer to name of object.
len
Length of object name.
nAttribs
Number of attributes.
attribs
Pointer to an array of attributes.

IrIasQuery

The IrIasQuery structure is used to perform IAS queries. The IrIasQuery object is passed as the token parameter to functions such as IrIAS_Query and IrIAS_Next.

typedef struct _IrIasQuery { 
  UInt8 queryLen; 
  UInt8 reserved; 
  UInt8 *queryBuf; 
  UInt16 resultBufSize; 
  UInt16 resultLen; 
  UInt16 listLen; 
  UInt16 offset; 
  UInt8 retCode; 
  UInt8 overFlow; 
  UInt8 *result; 
  IrIasQueryCallBack callBack; 
} _IrIasQuery; 

Field Descriptions

queryLen
Total length of the query.
reserved
Reserved for future use.
queryBuf
Pointer to buffer containing the query.
resultBufSize
Size of the result buffer.
resultLen
Actual number of bytes in the result buffer.
listLen
Number of items in the result list.
offset
Offset into the results buffer.
retCode
Return code of operation.
overFlow
Set to true if result exceeded result buffer size.
result
Pointer to buffer containing result.
callBack
Pointer to query callback function.

IrCallbackParms

The IrCallbackParms structure is used to pass information from the stack to the upper layer of the stack (application). Not all fields are valid at any given time. The type of event determines which fields are valid. The IrCallbackParms object is passed as the second parameter to the IrCallback function.

typedef struct { 
  IrEvent event; 
  UInt8 reserved1; 
  UInt8 *rxBuff; 
  UInt16 rxLen; 
  IrPacket* packet; 
  IrDeviceList* deviceList; 
  IrStatus status; 
  UInt8 reserved2; 
} IrCallBackParms; 

Field Descriptions

event
Event causing the callback.
reserved1
Reserved for future use.
rxBuff
Received data buffer.
rxLen
Length of data in received buffer.
packet
Pointer to packet being returned.
deviceList
Pointer to discovery device list.
status
Status of stack.
reserved2
Reserved for future use.

IrStatsType

The IrStatsType structure defines performance statistics for the IR Library. Use the ExgControl function with an irGetStatistics operation to retrieve these statistics. See IR Control Constants for more information.

typedef struct { 
  UInt16 recLineErrors; 
  UInt16 crcErrors; 
} IrStatsType; 

Field Descriptions

recLineErrors
The number of serial errors since the library opened.
crcErrors
The number of CRC errors since the library opened.

IR Library Constants

IR Control Constants

The IR control constants define operations that the IR Exchange Library can perform. You pass these constants as the operation parameter to ExgControl. The following table lists the operation constants, the data that should be passed as the valueP parameter to ExgControl, and what operation is performed in response.

Operation Constant
value Data Type
Description
irGetScanningMode
Boolean. Output only.
Returns true in *valueP if beaming is enabled or false if beaming is disabled.
irGetStatistics
IrStatsType. Output only.
Returns performance statistics.
irRestoreScanning
None
Re-enables beaming after an irSuppressScanning operation. This operation keeps track of the number of requests that beaming be disabled and re-enables beaming only when the count reaches 0.


This operation differs from irSetScanningMode in that it does not update the saved preferences.
irSetScanningMode
Boolean. Input only.
Enables or disables beaming.

This operation modifies the saved preferences database, which is back up during a HotSync® operation. Because of this, beaming may remain disabled after a reset if you use this operation to disable it. If you want to temporarily disable beaming use irSuppressScanning and irRestoreScanning instead.
irSetBaudMask
UInt16 containing a mask of the irOpenOptSpeed... constants defined in IrLib.h. Input only.
Sets the possible baud rates that the IR Library will use to those specified in *valueP. OR the irOpenOptSpeed... constants together to specify more than one. The default rate is 0, which causes the baud rate to be determined by the hardware.


This operation is sometimes useful for debugging connections. Generally, you should set all bits up to the fastest rate you want to allow. To reset, use this operation again and pass 0 in *valueP.


If you change the baud rate, your changes are until the device is reset or you perform this operation again.
irSetSerialMode
Boolean. Input only.
If the specified value is true, the IR Library uses the serial port instead of the infrared port until the device is reset. This option is useful for debugging. You can run your application in POSE and use the IR Library to communicate with a device connected in the cradle.
irSetSupported
Boolean. Input only.
If true, IR is supported on this device. If false, IR is not supported. You can use this constant to disable the unsupported dialog that normally displays when a beam is attempted and no IR support is available.
irSuppressScanning
None
Temporarily disables beam receive. This operation keeps track of the number of requests that beaming be disabled and re-enables beaming (through irRestoreScanning) only when the count reaches 0.


This operation differs from irSetScanningMode in that it does not update the saved preferences.

IR Stack Callback Events

The IR stack calls the application by way of a callback function stored in each IrConnect structure. The callback function is called with a pointer to the IrConnect structure and a pointer to a parameter structure. The parameter structure contains an event field, which indicates the reason the callback is called, and other parameters, which have meaning based on the event.

The meaning of the events is described in the following sections.

LEVENT_DATA_IND

Data has been received. The received data is accessed using fields rxBuff and rxLen.

LEVENT_DISCOVERY_CNF

Indicates the completion of a discovery operation. The field deviceList points to the discovery list.

LEVENT_LAP_CON_CNF

The requested IrLAP connection has been made successfully. The callback function of all bound IrConnect structures is called.

LEVENT_LAP_CON_IND

Indicates that the IrLAP connection has come up. The callback of all bound IrConnect structures is called.

LEVENT_LAP_DISCON_IND

Indicates that the IrLAP connection has gone down. This means that all IrLMP connections are also down. A callback with event LEVENT_LM_CON_IND is not given. The callback function of all bound IrConnect structures is called.

LEVENT_LM_CON_CNF

The requested IrLMP/Tiny TP connection has been made successfully. Connection data from the other side is found using fields rxBuff and rxLen.

LEVENT_LM_CON_IND

Other device has initiated a connection. IrConnectRsp should be called to accept the connection. Any data associated with the connection request can be found using fields rxBuff and rxLen, data pointer and length, respectively.

LEVENT_LM_DISCON_IND

The IrLMP/Tiny TP connection has been disconnected. Any data associated with the disconnect indication can be found using fields rxBuff and rxLen, data pointer and length, respectively.

LEVENT_PACKET_HANDLED

A packet is being returned. A pointer to the packet exists in field packet.

LEVENT_STATUS_IND

Indicates that a status event from the stack has occurred. The status field indicates the status generating the event. Possible status values are as follows:

IR_STATUS_NO_PROGRESS which means that IrLAP has no progress for 3 seconds threshold time (for example, the beam is blocked).

IR_STATUS_LINK_OK which indicates that the no progress condition has cleared.

IR_STATUS_MEDIA_NOT_BUSY which indicates that the IR media has transitioned from busy to not busy.

LEVENT_TEST_CNF

Indicates that a TEST command has completed. The status field indicates if the test was successful.

IR_STATUS_SUCCESS indicates that the operation was successful and the data in the test response can be found by using the rxBuff and rxLen fields.

IR_STATUS_FAILED indicates that no TEST response was received. The packet passed to perform the test command is passed back in the packet field and is now available (no separate packet handled event occurs).

LEVENT_TEST_IND

Indicates that a TEST command frame has been received. A pointer to the received data is in rxBuff and rxLen. A pointer to the packet that is sent in response to the test command is in the packet field. The packet is currently set up to respond with the same data sent in the command TEST frame. If different data is desired as a response, then you need to modify the packet structure. This event is sent to the callback function in all bound IrConnect structures. The IAS connections ignore this event.

IR Library Functions

IrAdvanceCredit

Purpose

Advances the credit to the other side of the connection.

Prototype

void IrAdvanceCredit (IrConnect* con, UInt8 credit)

Parameters

--> conPointer to IrConnect structure representing connection to which credit is advanced.
--> creditAmount of credit to advance.

Result

Returns nothing.

Comments

The credit passed by this function is added to the existing available credit, which must not exceed 127. This function only makes sense for a Tiny TP connection.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrBind

Purpose

Obtains a local LSAP selector and registers the connection with the protocol stack.

Prototype

IrStatus IrBind (UInt16 refNum, IrConnect* con, IrCallBack callBack)

Parameters

--> refnumIR library refNum.
<--> conPointer to IrConnect structure.
--> callBackPointer to a callBack function that handles the indications and confirmation from the protocol stack.

Result

IR_STATUS_SUCCESS means the operation completed successfully. The assigned LSAP can be found in con->lLsap.

IR_STATUS_FAILED means the operation failed for one of the following reasons:

con is already bound to the stack.

There is no room in the connection table.

Comments

The IrConnect structure is re-initialized. Any values stored in the structure are lost. The assigned LSAP is returned in the lLsap field of con. The type of the connection is set to IrLMP. The IrConnect must be bound to the stack before it can be used.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrClose

Purpose

Closes the IR library. This releases the global memory for the IR stack and any system resources it uses. This must be called when an application is done with the IR library.

Prototype

Err IrClose (UInt16 refnum)

Parameters

--> refnumIR library refNum.

Result

Returns 0 if successful.

Comments

Do not call this function unless the call to IrOpen was successful.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrConnectIrLap

Purpose

Starts an IrLAP connection.

Prototype

IrStatus IrConnectIrLap (UInt16 refNum, IrDeviceAddr deviceAddr)

Parameters

--> refnumIR library refNum.
--> deviceAddr32-bit address of device to which connection should be made.

Result

IR_STATUS_PENDING means the operation started successfully; the result is returned by way of a callback.

IR_STATUS_MEDIA_BUSY means the operation failed because the media is busy. Media busy is caused by one of the following reasons:

Other devices are using the IR medium.

An IrLAP connection already exists.

A discovery process is in progress.

Comments

The result is signaled to all bound IrConnect structures by way of the callback function. The callback event is LEVENT_LAP_CON_CNF if successful or LEVENT_LAP_DISCON_IND if unsuccessful.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrConnectReq

Purpose

Requests an IrLMP or Tiny TP connection.

Prototype

IrStatus IrConnectReq (UInt16 refNum, IrConnect* con, IrPacket* packet, UInt8 credit)

Parameters

--> refnumIR library refNum.
--> conPointer to IrConnect structure for handling the connection. The rLsap field must contain the LSAP selector for the peer on the other device. Also the type of the connection must be set. Use IR_SetConTypeLMP to set the type to an IrLMP connection or IR_SetConTypeTTP to set the type to a Tiny TP connection.
--> packetPointer to a packet that contains connection data. Even if no connection data is needed, the packet must point to a valid IrPacket structure. The packet is returned by way of the callback function with the LEVENT_PACKET_HANDLED event if no errors occur. The maximum size of the packet is IR_MAX_CON_PACKET for an IrLMP connection or IR_MAX_TTP_CON_PACKET for a Tiny TP connection.
--> creditInitial amount of credit advanced to the other side. Must be less than 127. It is ANDed with 0x7f, so if it is greater than 127, unexpected results occur. This parameter is ignored if the connection is an IrLMP connection.

Result

IR_STATUS_PENDING means the operation has been started successfully and the result is returned by way of the callback function with the event LEVENT_LM_CON_CNF if the connection is made or LEVENT_LM_DISCON_IND if connection fails. The packet is returned by way of the callback with the event LEVENT_PACKET_HANDLED.

IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.

The connection is busy (already involved in a connection).

The IrConnect structure is not bound to the stack.

The packet size exceeds maximum allowed.

IR_STATUS_NO_IRLAP means the operation failed because there is no IrLAP connection (the packet is available immediately).

Comments

The result is signaled by way of the callback specified in the IrConnect structure. The callback event LEVENT_LM_CON_CNF indicates that the connection is up and LEVENT_LM_DISCON_IND indicates that the connection failed. Before calling this function the fields in the con structure must be properly set.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrConnectRsp

Purpose

Accepts an incoming connection that has been signaled by way of the callback with the event LEVENT_LM_CON_IND.

Prototype

IrStatus IrConnectRsp (UInt16 refNum, IrConnect* con, IrPacket* packet, UInt8 credit)

Parameters

--> refnumIR library refNum.
--> conPointer to IrConnect structure.
--> packetPointer to a packet that contains connection data. Even if no connection data is needed, the packet must point to a valid IrPacket structure. The packet is returned by way of the callback with the LEVENT_PACKET_HANDLED event if no errors occur. The maximum size of the packet is IR_MAX_CON_PACKET for an IrLMP connection or IR_MAX_TTP_CON_PACKET for a Tiny TP connection.
--> creditInitial amount of credit advanced to the other side. Must be less than 127. It is ANDed with 0x7f, so if it is greater than 127, unexpected results occur. This parameter is ignored if the connection is an IrLMP connection.

Result

IR_STATUS_PENDING means the operation has been started successfully and the packet is returned by way of the callback function with the event LEVENT_PACKET_HANDLED.

IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.

The connection is not in the proper state to require a response.

The IrConnect structure is not bound to the stack.

The packet size exceeds the maximum allowed.

IR_STATUS_NO_IRLAP means the operation failed because there is no IrLAP connection (the packet is available immediately).

Comments

IrConnectRsp can be called during the callback or later to accept the connection. The type of the connection must already have been set to IrLMP or Tiny TP before the LEVENT_LM_CON_IND event.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrDataReq

Purpose

Sends a data packet.

Prototype

IrStatus IrDataReq (UInt16 refNum, IrConnect* con, IrPacket* packet)

Parameters

--> refnumIR library refNum.
--> conPointer to IrConnect structure that specifies the connection over which the packet should be sent.
--> packetPointer to a valid IrPacket structure that contains data to send. The packet should not exceed the maximum size found with IrMaxTxSize.

Result

IR_STATUS_PENDING means the packet has been queued by the stack. The packet is returned by way of the callback with event LEVENT_PACKET_HANDLED.

IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.

The IrConnect structure is not bound to the stack.

The packet size exceeds the maximum allowed.

The IrConnect structure does not represent an active connection.

Comments

The packet is owned by the stack until it is returned by way of the callback with event LEVENT_PACKET_HANDLED. The largest packet that can be sent is found by calling IrMaxTxSize.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrDisconnectIrLap

Purpose

Disconnects an IrLAP connection.

Prototype

IrStatus IrDisconnectIrLap (UInt16 refNum)

Parameters

--> refnumIR library refNum.

Result

IR_STATUS_PENDING means the operation started successfully and all bound IrConnect structures are called back when complete.

IR_STATUS_NO_IRLAP means the operation failed because no IrLAP connection exists.

Comments

When the IrLAP connection goes down, the callback of all bound IrConnect structures is called with event LEVENT_LAP_DISCON_IND.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrDiscoverReq

Purpose

Starts an IrLMP discovery process.

Prototype

IrStatus IrDiscoverReq (UInt16 refNum, IrConnect* con)

Parameters

--> refnumIR library refNum.
--> conPointer to a bound IrConnect structure.

Result

IR_STATUS_PENDING means the operation is started successfully; the result is returned by way of callback.

IR_STATUS_MEDIA_BUSY means the operation failed because the media is busy. Media busy is caused by one of the following reasons:

Other devices are using the IR medium.

A discovery process is already in progress.

An IrLAP connection exists.

IR_STATUS_FAILED means the operation failed because the IrConnect structure is not bound to the stack.

Comments

The result is signaled by way of the callback function specified in the IrConnect structure with the event LEVENT_DISCOVERY_CNF. Only one discovery can be invoked at a time.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIsIrLapConnected

Purpose

Determines if an IrLAP connection exists.

Prototype

BOOL IrIsIrLapConnected (UInt16 refNum)

Parameters

--> refnumIR library refNum.

Result

true if IrLAP is connected, false otherwise.

Comments

Only available if IR_IS_LAP_FUNCS is defined.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIsMediaBusy

Purpose

Determines if the IR media is busy.

Prototype

BOOL IrIsMediaBusy (UInt16 refNum)

Parameters

--> refnumIR library refNum.

Result

true if IR media is busy, false otherwise.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIsNoProgress

Purpose

Determines if IrLAP is not making progress.

Prototype

BOOL IrIsNoProgress (UInt16 refNum)

Parameters

--> refnumIR library refNum.

Result

ture if IrLAP is not making progress, false otherwise.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIsRemoteBusy

Purpose

Determines if IrLAP of the other device is busy.

Prototype

BOOL IrIsRemoteBusy (UInt16 refNum)

Parameters

--> refnumIR library refNum.

Result

ture if IrLAP of the other device is busy, false otherwise.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrLocalBusy

Purpose

Sets the IrLAP local busy flag.

Prototype

void IrLocalBusy (UInt16 refNum, BOOL flag)

Parameters

--> refnumIR library refNum.
--> flagValue (true or false) to set for local busy flag of IrLAP.

Result

Returns nothing.

Comments

If local busy is set to true, then the local IrLAP layer sends RNR (Receive Not Ready) frames to the other side indicating it cannot receive any more data. If the local busy is set to false, IrLAP is ready to receive frames.

The setting takes effect the next time IrLAP sends an RR (Receive Ready) frame. If IrLAP has data to send, the data is sent first, so it should be used carefully.

This function should not be used when using Tiny TP or when multiple connections exist.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrMaxRxSize

Purpose

Returns the maximum size buffer that can be sent by the other device.

Prototype

UInt16 IrMaxRxSize (UInt16 refNum, IrConnect* con)

Parameters

--> refnumIR library refNum.
--> conPointer to IrConnect structure that represents an active connection.

Result

Returns the maximum size buffer that can be sent by the other device (maximum bytes that can be received). The value returned is only valid for active connections. The maximum size varies for each connection and is based on the negotiated IrLAP parameters and the type of the connection.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrMaxTxSize

Purpose

Returns the maximum size allowed for a transmit packet.

Prototype

UInt16 IrMaxTxSize (UInt16 refNum, IrConnect* con)

Parameters

--> refnumIR library refNum.
--> conPointer to IrConnect structure that represents an active connection.

Result

Returns the maximum size allowed for a transmit packet. The value returned is only valid for active connections. The maximum size varies for each connection and is based on the negotiated IrLAP parameters and the type of the connection.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrOpen

Purpose

Opens the IR library. This allocates the global memory for the IR stack and reserves the system resources it requires. This must be done before any other IR library calls are made.

Prototype

Err IrOpen (UInt16 refnum, UInt32 options)

Parameters

--> refnumIR library refNum. This value is returned from the function SysLibFind, which you must call first to load the IR library.
--> optionsOpen options flags. See the Comments section for details.

Result

Returns 0 if successful.

Comments

The following flags can be specified for the options parameter to set the speed of the connection:

irOpenOptSpeed115200
Set to maximum negotiated baud rate.
irOpenOptSpeed57600
Set to 57600 bps (default if no flags given).
irOpenOptSpeed9600
Set to 9600 bps.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrSetConTypeLMP

Purpose

Sets the type of the connection to IrLMP. This function must be called after the IrConnect structure is bound to the stack.

Prototype

void IrSetConTypeLMP (IrConnect* con)

Parameters

--> conPointer to IrConnect structure.

Result

Returns nothing.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrSetConTypeTTP

Purpose

Sets the type of the connection to Tiny TP. This function must be called after the IrConnect structure is bound to the stack.

Prototype

void IrSetConTypeTTP (IrConnect* con)

Parameters

--> conPointer to IrConnect structure.

Result

Returns nothing.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrSetDeviceInfo

Purpose

Sets the XID info string used during discovery to the given string and length.

Prototype

IrStatus IrSetDeviceInfo (UInt16 refNum, UInt8 *info, UInt8 len)

Parameters

--> refnumIR library refNum.
--> infoPointer to array of bytes.
--> lenNumber of bytes pointed to by info.

Result

IR_STATUS_SUCCESS means the operation is successful.

IR_STATUS_FAILED means the operation failed because info is too big.

Comments

The XID info string contains hints and the nickname of the device. The size cannot exceed IR_MAX_DEVICE_INFO bytes.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrTestReq

Purpose

Requests a TEST command frame be sent in the NDM (Normal Disconnect Mode) state.

Prototype

IrStatus IrTestReq (UInt16 refNum, IrDeviceAddr devAddr, IrConnect* con, IrPacket* packet)

Parameters

--> refnumIR library refNum.
--> devAddrAddress of device where TEST is sent. This address is not checked so it can be the broadcast address or 0.
--> conPointer to IrConnect structure specifying the callback function to call to report the result.
--> packetPointer to an IrPacket structure that contains the data to send in the TEST command packet. The maximum size data that can be sent is IR_MAX_TEST_PACKET. Even if no data is to be sent, a valid packet must be passed.

Result

IR_STATUS_PENDING means the operation has been started successfully and the result is returned by way of the callback function with the event LEVENT_TEST_CNF. This is also the indication returning the packet.

IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.

The IrConnect structure is not bound to the stack.

The packet size exceeds the maximum allowed.

IR_STATUS_MEDIA_BUSY means the operation failed because the media is busy or the stack is not in the NDM state (the packet is available immediately).

Comments

The result is signaled by way of the callback specified in the IrConnect structure. The callback event is LEVENT_TEST_CNF and the status field indicates the result of the operation. IR_STATUS_SUCCESS indicates success and IR_STATUS_FAILED indicates no response was received. A packet must be passed containing the data to send in the TEST frame. The packet is returned when the LEVENT_TEST_CNF event is given.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrUnbind

Purpose

Unbinds the IrConnect structure from the protocol stack, freeing its LSAP selector.

Prototype

IrStatus IrUnbind (UInt16 refNum, IrConnect* con)

Parameters

--> refnumIR library refNum.
--> conPointer to IrConnect structure to unbind.

Result

IR_STATUS_SUCCESS means the operation completed successfully.

IR_STATUS_FAILED means the operation failed for one of the following reasons:

The IrConnect structure was not bound.

The lLsap field contained an invalid number.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IAS Functions

This section describes the following functions and macros related to IAS database:

IrIAS_Add

IrIAS_GetInteger

IrIAS_GetIntLsap

IrIAS_GetObjectID

IrIAS_GetOctetString

IrIAS_GetOctetStringLen

IrIAS_GetType

IrIAS_GetUserString

IrIAS_GetUserStringCharSet

IrIAS_GetUserStringLen

IrIAS_Next

IrIAS_Query

IrIAS_SetDeviceName

IrIAS_StartResult

IrIAS_Add

Purpose

Adds an IAS object to the IAS Database.

Prototype

IrStatus IrIAS_Add (UInt16 refNum, IrIasObject* obj)

Parameters

--> refnumIR library refNum.
--> objPointer to an IrIASObject structure.

Result

IR_STATUS_SUCCESS means the operation is successful.

IR_STATUS_FAILED means the operation failed for one of the following reasons:

There is no space in the database.

An entry with the same class name already exists.

The attributes of the object violate the IrDA Lite rules (attribute name exceeds IR_MAX_IAS_NAME, or attribute value exceeds IR_MAX_IAS_ATTR_SIZE).

The class name exceeds IR_MAX_IAS_NAME.

Comments

The object is not copied, so the memory for the object must exist for as long as the object is in the database. The IAS database is designed to allow only objects with unique class names, and it checks for this. Class names and attributes names must not exceed IR_MAX_IAS_NAME. Also, attribute values must not exceed IR_MAX_IAS_ATTR_SIZE.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetInteger

Purpose

Macro to return an integer value, assuming that the current result item is of type IAS_ATTRIB_INTEGER. (Call IrIAS_GetType to determine the type of the current result item.)

Prototype

IrIAS_GetInteger (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Integer value returned as a UInt32.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetIntLsap

Purpose

Macro to return an integer value that represents an LSAP, assuming that the current result item is of type IAS_ATTRIB_INTEGER. (Call IrIAS_GetType to determine the type of the current result item.) Usually integer values returned in a query are LSAP selectors.

Prototype

IrIAS_GetIntLsap (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Integer value returned as a UInt8.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetObjectID

Purpose

Macro to return the unique object ID of the current result item.

Prototype

IrIAS_GetObjectID (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Returns the object ID as a UInt16 type.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetOctetString

Purpose

Macro to return a pointer to an octet string, assuming that the current result item is of type IAS_ATTRIB_OCTET_STRING. (Call IrIAS_GetType to determine the type of the current result item.)

Prototype

IrIAS_GetOctetString (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Pointer to octet string of type UInt8.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetOctetStringLen

Purpose

Macro to return the length of an octet string, assuming that the current result item is of type IAS_ATTRIB_OCTET_STRING. (Call IrIAS_GetType to determine the type of the current result item.)

Prototype

IrIAS_GetOctetStringLen (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Length of octet string returned as a UInt16.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetType

Purpose

Macro to return the type of the current result item.

Prototype

IrIAS_GetType (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Type of result item, such as IAS_ATTRIB_INTEGER, IAS_ATTRIB_OCTET_STRING or IAS_ATTRIB_USER_STRING. The return value is of type UInt8.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetUserString

Purpose

Macro to return a pointer to a user string, assuming that the current result item is of type IAS_ATTRIB_USER_STRING. (Call IrIAS_GetType to determine the type of the current result item.)

Prototype

IrIAS_GetUserString (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Pointer to result string of type UInt8.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetUserStringCharSet

Purpose

Macro to return the character set of the user string, assuming that the current result item is of type IAS_ATTRIB_USER_STRING. (Call IrIAS_GetType to determine the type of the current result item.)

Prototype

IrIAS_GetUserStringCharSet (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Character set returned as an IrCharSet value.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_GetUserStringLen

Purpose

Macro to return the length of a user string, assuming that the current result item is of type IAS_ATTRIB_USER_STRING. (Call IrIAS_GetType to determine the type of the current result item.)

Prototype

IrIAS_GetUserStringLen (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Length of user string returned as a UInt8 value.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_Next

Purpose

Moves the internal pointer to the next result item.

Prototype

UInt8* IrIAS_Next (UInt16 refNum, IrIasQuery* token)

Parameters

--> refnumIR library refNum.
--> tokenPointer to an IrIasQuery structure.

Result

Pointer to the next result item, or 0 if there are no more items.

Comments

This function returns a pointer to the start of the next result item. If the pointer is 0, then there are no more result items.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_Query

Purpose

Makes an IAS query of the IAS database of another device.

Prototype

IrStatus IrIAS_Query (UInt16 refNum, IrIasQuery* token)

Parameters

--> refnumIR library refNum.
--> tokenPointer to an IrIasQuery structure initialized as described in the Comments section.

Result

IR_STATUS_SUCCESS means the operation is started successfully and the result is signaled by way of the callback function.

IR_STATUS_FAILED means the operation failed for one of the following reasons:

The query exceeds IR_MAX_QUERY_LEN.

The result field of token is 0.

The resultBufSize field of token is 0.

The callback field of token is 0.

A query is already in progress.

IR_STATUS_NO_IRLAP means the operation failed because there is no IrLAP connection.

Comments

An IrLAP connection must exist to the other device. The IAS query token must be initialized as described below. The result is signaled by calling the callback function whose pointer exists in the IrIasQuery structure. Only one query can be made at a time.

The IrIasQuery structure passed in the token parameter must be initialized as follows:

Assign a pointer to a callback function in which the result is signaled.

Set result to point to a buffer large enough to hold the result of the query.

Set resultBufSize to the size of the result buffer.

Set queryBuf to point to a valid query.

Set queryLen to the number of bytes in queryBuf. The length must not exceed IR_MAX_QUERY_LEN.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_SetDeviceName

Purpose

Sets the value field of the device name attribute of the "Device" object in the IAS database.

Prototype

IrStatus IrIAS_SetDeviceName (UInt16 refNum, UInt8 *name, UInt8 len)

Parameters

--> refnumIR library refNum.
--> namePointer to an IAS value field for the device name attribute of the device object. It includes the attribute type, character set and device name. This value field should be a constant and the pointer must remain valid until IrIAS_SetDeviceName is called with another pointer.
--> lenTotal length of the value field. Maximum size allowed is IR_MAX_IAS_ATTR_SIZE.

Result

IR_STATUS_SUCCESS means the operation is successful.

IR_STATUS_FAILED means len is too big, or the value field is not a valid user string.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIAS_StartResult

Purpose

Macro to put the internal pointer to the start of the result buffer.

Prototype

IrIAS_StartResult (t)

Parameters

--> tPointer to an IrIasQuery structure.

Result

Returns nothing.

Compatibility

Implemented only if 3.0 New Feature Set is present.

Application-Defined Functions

The functions in this section are supplied by the developer and can be named anything.

IrIasQueryCallBack

Purpose

Signals the result of IAS query. The result of IAS queries is signaled by calling this callback function which is pointed to by the callBack field of the IrIasQuery structure.

Prototype

void IrIasQueryCallBack (IrStatus status)

Parameters

--> statusThe status of the query operation. The following values can be passed:
IR_STATUS_SUCCESS means the query operation finished successfully and the results can be parsed.
IR_STATUS_DISCONNECT means the link or IrLMP connection was disconnected during the query, so the results are not valid.

Result

Returns nothing.