< 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 #####
--> con | Pointer to IrConnect structure representing connection to which credit is advanced.
#####
--> credit | Amount 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 #####
--> refnum | IR library refNum.
#####
<--> con | Pointer to IrConnect structure.
#####
--> callBack | Pointer 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 #####
--> refnum | IR 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 #####
--> refnum | IR library refNum.
#####
--> deviceAddr | 32-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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer 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.
#####
--> packet | Pointer 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.
#####
--> credit | Initial 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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer to IrConnect structure.
#####
--> packet | Pointer 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.
#####
--> credit | Initial 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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer to IrConnect structure that specifies the connection over which the packet should be sent.
#####
--> packet | Pointer 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 #####
--> refnum | IR 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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer 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 #####
--> refnum | IR 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 #####
--> refnum | IR 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 #####
--> refnum | IR 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 #####
--> refnum | IR 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 #####
--> refnum | IR library refNum.
#####
--> flag | Value (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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer 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 #####
--> refnum | IR library refNum. This value is returned from the function SysLibFind, which you must call first to load the IR library.
#####
--> options | Open 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 #####
--> con | Pointer 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 #####
--> con | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> info | Pointer to array of bytes.
#####
--> len | Number 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 #####
--> refnum | IR library refNum.
#####
--> devAddr | Address of device where TEST is sent. This address is not checked so it can be the broadcast address or 0.
#####
--> con | Pointer to IrConnect structure specifying the callback function to call to report the result.
#####
--> packet | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> con | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> obj | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> t | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> token | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> token | Pointer 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 #####
--> refnum | IR library refNum.
#####
--> name | Pointer 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.
#####
--> len | Total 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 #####
--> t | Pointer 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 #####
--> status | The 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. |