path: root/fpcsrc/packages/palmunits/src/irlib.pp

{$MACRO ON}

(******************************************************************************
 *
 * Copyright (c) 1994-1999 Palm, Inc. or its subsidiaries.
 * All rights reserved.

 *
 * Portions of this file are:
 *  Copyright Counterpoint Systems Foundry, Inc. 1995, 1996
 *
 * File: IrLib.h
 *
 * Release: Palm OS SDK 4.0 (63220)
 *
 * Description:
 *   Include file for PalmOS IrDA Library.
 *
 * History:
 *    5/23/97 Created by Gavin Peacock
 *    2/13/98 Merged with counterpoint libraries
 *    6/24/98 Added disconnect timeout opt for IrOpen,
 *          remaining speeds.  Added parentheses to control defines.
 *
 *****************************************************************************)

unit irlib;

interface

uses palmos, libtraps, exgmgr, systemresources;

// The Ir library is used as an Exchange library. ExgLib.h defines all the
// primary entrypoints into the library. The rest of this include file defines the
// direct stack API for apps not using the Exchange interface. The Stack API
// comes after the Exchange library API in the library interface.

// name of Ir library
const
  irLibName = 'IrDA Library';

// Specific scheme for IR exg lib
const
  exgIrObexScheme = '_irobex';

// Feature Creators and numbers, for use with the FtrGet() call. This
//  feature can be obtained to get the current version of the Ir Library
const
  irFtrCreator    = sysFileCIrLib;
  irFtrNumVersion = 0; // get version of Net Library
                       // 0xMMmfsbbb, where MM is major version, m is minor version
                       // f is bug fix, s is stage: 3-release,2-beta,1-alpha,0-development,
                       // bbb is build number for non-releases
                       // V1.12b3   would be: 0x01122003
                       // V2.00a2   would be: 0x02001002
                       // V1.01     would be: 0x01013000

// Options values for IrOpen
// BDDDxxxx xxxxxxxx xxxxxxxx xxxSSSSS
// Where B=background mode, DDD=disconnect timeout, SSSSS=speed

  irOpenOptBackground   = $80000000; // Unsupported background task use
  irOpenOptDisconnect3  = $10000000; // sets amount of time in seconds
  irOpenOptDisconnect8  = $20000000; // after no activity from other
  irOpenOptDisconnect12 = $30000000; // device before disconnect is
  irOpenOptDisconnect16 = $40000000; // initiated.
  irOpenOptDisconnect20 = $50000000; // default is 40 secs
  irOpenOptDisconnect25 = $60000000;
  irOpenOptDisconnect30 = $70000000;
  irOpenOptDisconnect40 = $00000000;
  irOpenOptSpeed115200  = $0000003F; // sets max negotiated baud rate
  irOpenOptSpeed57600   = $0000001F; // default is 57600
  irOpenOptSpeed38400   = $0000000F;
  irOpenOptSpeed19200   = $00000007;
  irOpenOptSpeed9600    = $00000003;

// Option codes for ExgLibControl
// These options are all unique to the Ir transport

  irGetScanningMode  = exgLibCtlSpecificOp or 1; // returns scanning enabled
  irSetScanningMode  = exgLibCtlSpecificOp or 2; // en/disables ir scanning mode
  irGetStatistics    = exgLibCtlSpecificOp or 3; // returns performance stats
  irSetSerialMode    = exgLibCtlSpecificOp or 4; // sets driver to use direct serial
  irSetBaudMask      = exgLibCtlSpecificOp or 5; // set possible baud rates (irOpenOpts)
  irSetSupported     = exgLibCtlSpecificOp or 6; // disables the ir not supported dialog
  irSuppressScanning = exgLibCtlSpecificOp or 7; // temporarily disabled beam receive
  irRestoreScanning  = exgLibCtlSpecificOp or 8; // restore beam receive state

// structure returned by irGetStatistics
type
  IrStatsType = record
    recLineErrors: UInt16; // # of serial errors since library opend
    crcErrors: UInt16;     // # of crc errors ...
  end;

//-----------------------------------------------------------------------------
// Ir library call ID's.
//-----------------------------------------------------------------------------

// These start after the old exchange library interface. If we add any more exchange
// library traps, we'll have to separate the publicly accessible "IR Library" and the
// IrOBEX exchange library.

type
  IrLibTrapNumberEnum = Enum;

const
  irLibTrapBind = sysLibTrapCustom + 10; // these start after the ObxLib interface...
  irLibTrapUnBind = Succ(irLibTrapBind);
  irLibTrapDiscoverReq = Succ(irLibTrapUnBind);
  irLibTrapConnectIrLap = Succ(irLibTrapDiscoverReq);
  irLibTrapDisconnectIrLap = Succ(irLibTrapConnectIrLap);
  irLibTrapConnectReq = Succ(irLibTrapDisconnectIrLap);
  irLibTrapConnectRsp = Succ(irLibTrapConnectReq);
  irLibTrapDataReq = Succ(irLibTrapConnectRsp);
  irLibTrapLocalBusy = Succ(irLibTrapDataReq);
  irLibTrapMaxTxSize = Succ(irLibTrapLocalBusy);
  irLibTrapMaxRxSize = Succ(irLibTrapMaxTxSize);
  irLibTrapSetDeviceInfo = Succ(irLibTrapMaxRxSize);
  irLibTrapIsNoProgress = Succ(irLibTrapSetDeviceInfo);
  irLibTrapIsRemoteBusy = Succ(irLibTrapIsNoProgress);
  irLibTrapIsMediaBusy = Succ(irLibTrapIsRemoteBusy);
  irLibTrapIsIrLapConnected = Succ(irLibTrapIsMediaBusy);
  irLibTrapTestReq = Succ(irLibTrapIsIrLapConnected);
  irLibTrapIAS_Add = Succ(irLibTrapTestReq);
  irLibTrapIAS_Query = Succ(irLibTrapIAS_Add);
  irLibTrapIAS_SetDeviceName = Succ(irLibTrapIAS_Query);
  irLibTrapIAS_Next = Succ(irLibTrapIAS_SetDeviceName);
  irLibTrapIrOpen = Succ(irLibTrapIAS_Next);
  irLibTrapHandleEvent = Succ(irLibTrapIrOpen);
  irLibTrapWaitForEvent = Succ(irLibTrapHandleEvent);

  irLibTrapLast = Succ(irLibTrapWaitForEvent);

(****************************************************************************
 *
 * Types and Constants
 *
 ****************************************************************************)

// Maximum size of packet that can be sent at connect time (ConnectReq or
// ConnectRsp) for IrLMP and Tiny TP connections.

const
  IR_MAX_CON_PACKET     = 60;
  IR_MAX_TTP_CON_PACKET = 52;
  IR_MAX_TEST_PACKET    = 376;
  IR_MAX_DEVICE_INFO    = 23;

// Size of the device list used in discovery process

  IR_DEVICE_LIST_SIZE = 6;

(*---------------------------------------------------------------------------
 *
 * Maximum size of the XID info field used in a discovery frame. The XID
 * info field contains the device hints and nickname.
 *)

  IR_MAX_XID_LEN = 23;

// Maximum allowed LSAP in IrLMP

  IR_MAX_LSAP = $6f;

// The following are used to access the hint bits in the first byte
// of the Device Info field of an XID frame (IrDeviceInfo).

  IR_HINT_PNP      = $01;
  IR_HINT_PDA      = $02;
  IR_HINT_COMPUTER = $04;
  IR_HINT_PRINTER  = $08;
  IR_HINT_MODEM    = $10;
  IR_HINT_FAX      = $20;
  IR_HINT_LAN      = $40;
  IR_HINT_EXT      = $80;

(* The following are used to access the hint bits in the second byte
 * of the Device Info field of an XID frame (IrDeviceInfo). Note
 * that LM_HINT_EXT works for all hint bytes.
 *)

  IR_HINT_TELEPHONY = $01;
  IR_HINT_FILE      = $02;
  IR_HINT_IRCOMM    = $04;
  IR_HINT_MESSAGE   = $08;
  IR_HINT_HTTP      = $10;
  IR_HINT_OBEX      = $20;

(*---------------------------------------------------------------------------
 *
 * Status of a stack operation or of the stack.
 *)

type
  IrStatus = UInt8;

const
  IR_STATUS_SUCCESS        = 0; // Successful and complete
  IR_STATUS_FAILED         = 1; // Operation failed
  IR_STATUS_PENDING        = 2; // Successfully started but pending
  IR_STATUS_DISCONNECT     = 3; // Link disconnected
  IR_STATUS_NO_IRLAP       = 4; // No IrLAP Connection exists
  IR_STATUS_MEDIA_BUSY     = 5; // IR Media is busy
  IR_STATUS_MEDIA_NOT_BUSY = 6; // IR Media is not busy
  IR_STATUS_NO_PROGRESS    = 7; // IrLAP not making progress
  IR_STATUS_LINK_OK        = 8; // No progress condition cleared
  // IR_STATUS_RESERVED1 = 9;  // Reserved for future use
  // IR_STATUS_RESERVED2 = 10; // Reserved for future use

(*---------------------------------------------------------------------------
 *
 * Character set for user strings. These are definitions for the character
 * set in Nicknames and in IAS attributes of type User String.
 *)

type
  IrCharSet = UInt8;

const
  IR_CHAR_ASCII      = 0;
  IR_CHAR_ISO_8859_1 = 1;
  IR_CHAR_ISO_8859_2 = 2;
  IR_CHAR_ISO_8859_3 = 3;
  IR_CHAR_ISO_8859_4 = 4;
  IR_CHAR_ISO_8859_5 = 5;
  IR_CHAR_ISO_8859_6 = 6;
  IR_CHAR_ISO_8859_7 = 7;
  IR_CHAR_ISO_8859_8 = 8;
  IR_CHAR_ISO_8859_9 = 9;
  IR_CHAR_UNICODE    = $ff;

(*---------------------------------------------------------------------------
 *
 * All indication and confirmations are sent to the IrLMP/TTP connections
 * through one callback function. The types of the events passed are
 * defined below. Applications should ignore events listed as "reserved"
 * as well as events not listed at all, since we may add more events in
 * future versions of the IR library.
 *)


type
  IrEvent = UInt8;

const
  LEVENT_LM_CON_IND     = 0;
  LEVENT_LM_DISCON_IND  = 1;
  LEVENT_DATA_IND       = 2;
  LEVENT_PACKET_HANDLED = 3;
  LEVENT_LAP_CON_IND    = 4;
  LEVENT_LAP_DISCON_IND = 5;
  LEVENT_DISCOVERY_CNF  = 6;
  LEVENT_LAP_CON_CNF    = 7;
  LEVENT_LM_CON_CNF     = 8;
  LEVENT_STATUS_IND     = 9;
  LEVENT_TEST_IND       = 10;
  LEVENT_TEST_CNF       = 11;
  // LEVENT_RESERVED1 = 12; // reserved for future use
  LEVENT_LM_SEND_IND    = 13; // added in Palm OS 4.0

// LmConnect flags - used internally

  LCON_FLAGS_TTP = $02;

(****************************************************************************
 *
 * IAS Types and Constants
 *
 ****************************************************************************)

// Maximum size of a query that observes the IrDA Lite rules

  IR_MAX_QUERY_LEN = 61;

// Maximum values for IAS fields. IR_MAX_IAS_NAME is the maximum allowable
// size for IAS Object names and Attribute names.

  IR_MAX_IAS_NAME   = 60;
  IR_MAX_ATTRIBUTES = 255;

(* Maximum size of an IAS attribute that fits within the IrDA Lite rules.
 * Even though attribute values can be larger IrDA Lite highly recommends
 * that the total size of an attribute value fit within one 64 byte packet
 * thus, the allowable size is 56 bytes or less. This size is enforced by the
 * code.
 *)

  IR_MAX_IAS_ATTR_SIZE = 56;

// Type of the IAS entry. This is the value returned for type when parsing
// the results buffer after a successful IAS Query.

  IAS_ATTRIB_MISSING      = 0;
  IAS_ATTRIB_INTEGER      = 1;
  IAS_ATTRIB_OCTET_STRING = 2;
  IAS_ATTRIB_USER_STRING  = 3;
  IAS_ATTRIB_UNDEFINED    = $ff;

// Ias Return Codes. One of these values will be found in the IAS Query
// structure in the retCode field after a successful IAS Query.

  IAS_RET_SUCCESS        = 0;   // Query operation is successful
  IAS_RET_NO_SUCH_CLASS  = 1;   // Query failed no such class exists
  IAS_RET_NO_SUCH_ATTRIB = 2;   // Query failed no such attribute exists
  IAS_RET_UNSUPPORTED    = $ff; // Query failed operation is unsupported

// IAS Get Value By Class opcode number

  IAS_GET_VALUE_BY_CLASS = 4;

(****************************************************************************
 *
 * Data Structures
 *
 ****************************************************************************)

// stack functions use a diferent type for booleans
type
  BOOL = Int16;

(*---------------------------------------------------------------------------
 *
 * ListEntry is used internally by the stack
 *)

  _ListEntry = record
    Flink: ^ListEntry;
    Blink: ^ListEntry;
  end;

  ListEntry = _ListEntry;

// Forward declaration of the IrConnect structure

  IrConnectPtr = ^_hconnect;

(*---------------------------------------------------------------------------
 *
 * Packet Structure for sending IrDA packets.
 *)

  _IrPacket = record
    (* The node field must be the first field in the structure. It is used
     * internally by the stack
     *)
    node: ListEntry;

    (* The buff field is used to point to a buffer of data to send and len
     * field indicates the number of bytes in buff.
     *)
    buff: ^UInt8;
    len: UInt16;

    (*==================  For Internal Use Only =======================
     *
     * The following is used internally by the stack and should not be
     * modified by the upper layer.
     *
     *==================================================================*)

    origin: IrConnectPtr;             // Pointer to connection which owns packet
    headerLen: UInt8;               // Number of bytes in the header
    header: array [0..13] of UInt8; // Storage for the header
    reserved: UInt8;                // Explicitly account for 16-bit alignment padding
  end;

  IrPacket = _IrPacket;

(*---------------------------------------------------------------------------
 *
 * 32-bit Device Address
 *)

  IrDeviceAddr = record
    case Integer of
      0: (u8: array [0..3] of UInt8);
      1: (u16: array [0..1] of UInt16);
      2: (u32: UInt32);
  end;

(*---------------------------------------------------------------------------
 *
 * The information returned for each device discovered during discovery.
 * The maximum size of the xid field is 23. This holds the hints and
 * the nickname.
 *)

  IrDeviceInfo = record
    hDevice: IrDeviceAddr;                     // 32-bit address of device
    len: UInt8;                                // Length of xid
    xid: array [0..IR_MAX_XID_LEN-1] of UInt8; // XID information
  end;

(*---------------------------------------------------------------------------
 *
 * List of Device Discovery info elements.
 *)

  IrDeviceList = record
    nItems: UInt8;                                         // Number items in the list
    reserved: UInt8;                                       // Explicitly account for 16-bit alignment padding
    dev: array [0..IR_DEVICE_LIST_SIZE-1] of IrDeviceInfo; // Fixed size in IrDA Lite
  end;

(*---------------------------------------------------------------------------
 *
 * Callback Parameter 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.
 *)

  IrCallBackParms = record
    event: IrEvent;            // Event causing callback
    reserved1: UInt8;          // Explicitly account for 16-bit alignment padding
    rxBuff: ^UInt8;            // Receive buffer already advanced to app data
    rxLen: UInt16;             // Length of data in receive buffer
    packet: ^IrPacket;         // Pointer to packet being returned
    deviceList: ^IrDeviceList; // Pointer to discovery device list
    status: IrStatus;          // Status of stack
    reserved2: UInt8;          // Explicitly account for 16-bit alignment padding
  end;
  IrCallBackParmsPtr = ^IrCallBackParms;

(* The definitions for the callback function is given below. How the
 * callback function is used in conjuction with the stack functions is
 * given below in the Callback Reference.
 *)

  IrCallBack = procedure(p1: IrConnectPtr; p2: IrCallBackParmsPtr);

(*---------------------------------------------------------------------------
 *
 * Definition of IrConnect structure. This structure is used to manage an
 * IrLMP or Tiny TP connection.
 *)

  _hconnect = record
    lLsap: UInt8; // Local LSAP this connection will listen on
    rLsap: UInt8; // Remote Lsap

    (*==================  For Internal Use Only =======================
     *
     * The following is used internally by the stack and should not be
     * modified by the user.
     *
     *==================================================================*)

    flags: UInt8;         // Flags containing state, type, etc.
    reserved: UInt8;      // Explicitly account for 16-bit alignment padding
    callBack: IrCallBack; // Pointer to callback function

    (* Tiny TP fields *)
    packet: IrPacket;     // Packet for internal use
    packets: ListEntry;   // List of packets to send
    sendCredit: UInt16;   // Amount of credit from peer
    availCredit: UInt8;   // Amount of credit to give to peer
    dataOff: UInt8;       // Amount of data less than IrLAP size
  end;

  IrConnect = _hconnect;

(****************************************************************************
 *
 * IAS Data Strucutres
 *
 ****************************************************************************)

(*---------------------------------------------------------------------------
 *
 * The LmIasAttribute is a strucutre that holds one attribute of an IAS
 * object.
 *)

  _IrIasAttribute = record
    name: ^UInt8;     // Pointer to name of attribute
    len: UInt8;       // Length of attribute name
    reserved1: UInt8; // Explicitly account for 16-bit alignment padding
    value: ^UInt8;    // Hardcode value (see below)
    valLen: UInt8;    // Length of the value.
    reserved2: UInt8; // Explicitly account for 16-bit alignment padding
  end;

  IrIasAttribute = _IrIasAttribute;

(* The value field of the IrIasAttribute structure is a hard coded string
 * which represents the actual bytes sent over the IR for the attribute
 * value. The value field contains all the bytes which represent an
 * attribute value based on the transmission format described in section
 * 4.3 of the IrLMP specification. An example of a user string is given
 * below.
 *
 * User String:
 *   1 byte type,  1 byte Char set, 1 byte length, length byte string
 *
 * Example of an user string "Hello World" in ASCII
 *
 * U8 helloString[] = {
 *    IAS_ATTRIB_USER_STRING,IR_CHAR_ASCII,11,
 *    'H','e','l','l','o',' ','W','o','r','l','d'
 * };
 *)

(*---------------------------------------------------------------------------
 *
 * The LmIasObject is storage for an IAS object managed by the local
 * IAS server.
 *)

  _IrIasObject = record
    name: ^UInt8;             // Pointer to name of object
    len: UInt8;               // Length of object name

    nAttribs: UInt8;          // Number of attributes
    attribs: ^IrIasAttribute; // A pointer to an array of attributes
  end;

  IrIasObject = _IrIasObject;

(*---------------------------------------------------------------------------
 *
 * Forward declaration of a structure used for performing IAS Queries so
 * that a callback type can be defined for use in the structure.
 *)

type
  IrIasQueryCallBack = procedure(p: IrStatus);

(*---------------------------------------------------------------------------
 *
 * Actual definition of the IrIasQuery structure.
 *)

  _IrIasQuery = record

    (* Query fields. The query buffer contains the class name and class
     * attribute whose value is being queried it is as follows:
     *
     * 1 byte - Length of class name
     * "Length" bytes - class name
     * 1 byte - length of attribute name
     * "Length" bytes - attribute name
     *
     * queryLen - contains the total number of byte in the query
     *)
    queryLen: UInt8;       // Total length of the query
    reserved: UInt8;       // Explicitly account for 16-bit alignment padding
    queryBuf: ^UInt8;      // Points to buffer containing the query

    (* Fields for the query result *)
    resultBufSize: UInt16; // Size of the result buffer
    resultLen: UInt16;     // Actual number of bytes in the result buffer
    listLen: UInt16;       // Number of items in the result list.
    offset: UInt16;        // Offset into results buffer
    retCode: UInt8;        // Return code of operation
    overFlow: UInt8;       // Set TRUE if result exceeded result buffer size
    result: ^UInt8;        // Pointer to buffer containing result;

    (* Pointer to callback function *)
    callBack: IrIasQueryCallBack;
  end;

  IrIasQuery = _IrIasQuery;

(****************************************************************************
 *
 * Function Reference
 *
 ****************************************************************************)

(*---------------------------------------------------------------------------
 *
 * Prototype:     Err   IrOpen(UInt16 refnum, UInt32 options)
 *
 * Description:   Open the Ir library. This allocates the global memory
 *                for the ir stack and reserves and system resources it
 *                requires. This must be done before any other ir libary
 *                calls are made.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                options - open options flags
 *
 *
 * Return Values: zero if no error or exgErrStackInit
 *
 *)

function IrOpen(refnum: UInt16; options: UInt32): Err; syscall irLibTrapIrOpen;

(*---------------------------------------------------------------------------
 *
 * Prototype:     Err   IrClose(UInt16 refnum)
 *
 * Description:   Close 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.
 *
 * Parameters:    refNum - ir library refNum
 *
 * Return Values: zero if no error
 *
 *)

function IrClose(refnum: UInt16): Err; syscall sysLibTrapClose;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrBind(UInt16 refNum,IrConnect* con,
 *                                 IrCallback callBack)
 *
 * Description:   Obtain a local LSAP selector and register the connection
 *                with the protocol stack. This IrConnect structure will be
 *                initialized. Any values stored in the structure will be
 *                lost. The assigned LSAP will be in the lLsap field of con.
 *                The type of the connection will be set to IrLMP. The
 *                IrConnect must be bound to the stack before it can be used.
 *
 * 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.
 *
 * Return Values: IR_STATUS_SUCCESS - operation completed successfully.
 *                The assigned LSAP can be found in con->lLsap.
 *
 *                IR_STATUS_FAILED - the operation failed for one of the
 *                following reasons:
 *                    - con is already bound to the stack
 *                    - no room in the connection table
 *)

function IrBind(refNum: UInt16; var con: IrConnect; callBack: IrCallBack): IrStatus; syscall irLibTrapBind;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrUnbind(UInt16 refNum,IrConnect* con)
 *
 * Description:   Unbind the IrConnect structure from the protocol stack
 *                freeing it's LSAP selector.
 *
 * Parameters:     refNum - ir library refNum
 *
 *                  con - pointer to IrConnect structure to unbind
 *
 * Return Values: IR_STATUS_SUCCESS - operation competed succesfully
 *
 *                IR_STATUS_FAILED - operation failed
 *                either because the IrConnect structure was not bound
 *                or the lLsap field contained an invalid number.
 *)

function IrUnbind(refNum: UInt16; var con: IrConnect): IrStatus; syscall irLibTrapUnBind;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrDiscoverReq(UInt16 refNum,IrConnect* con)
 *
 * Description:   Start an IrLMP discovery process. The result will be
 *                signaled via the callBack function specified in the
 *                IrConnect structure with the event LEVENT_DISCOVERY_CNF.
 *                Only one discovery can be invoked at a time.
 *
 * Parameters:     refNum - ir library refNum
 *
 *                 con - pointer to a bound IrConnect structure.
 *
 * Return Values: IR_STATUS_PENDING - operation is started successfully
 *                result returned via callback.
 *
 *                IR_STATUS_MEDIA_BUSY - 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 - operation failed
 *                because the IrConnect structure is not bound to the stack.
 *)

function IrDiscoverReq(refNum: UInt16; var con: IrConnect): IrStatus; syscall irLibTrapDiscoverReq;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrConnectIrLap(UInt16 refNum,IrDeviceAddr deviceAddr)
 *
 * Description:   Start an IrLAP connection. The result is signaled to all
 *                bound IrConnect structures via the callback function. The
 *                callback event is LEVENT_LAP_CON_CNF if successful or
 *                LEVENT_LAP_DISCON_IND if unsuccessful.
 *
 * Parameters::   refNum - ir library refNum
 *
 *                deviceAddr - 32-bit address of device to which connection
 *                should be made.
 *
 * Return Values: IR_STATUS_PENDING - operation started successfully and
 *                callback will be called with result.
 *
 *                IR_STATUS_MEDIA_BUSY - operation failed to start because
 *                the IR 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
 *)

function IrConnectIrLap(refNum: UInt16; deviceAddr: IrDeviceAddr): IrStatus; syscall irLibTrapConnectIrLap;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrDisconnectIrLap(UInt16 refNum)
 *
 * Description:   Disconnect the IrLAP connection. When the IrLAP connection
 *                goes down the callback of all bound IrConnect structures
 *                is called with event LEVENT_LAP_DISCON_IND.
 *
 * Parameters:    refNum - ir library refNum
 *
 * Return Values: IR_STATUS_PENDING - operation started successfully and
 *                the all bound IrConnect structures will be called back
 *                when complete.
 *
 *                IR_STATUS_NO_IRLAP - operation failed because no IrLAP
 *                connection exists.
 *)

function IrDisconnectIrLap(refNum: UInt16): IrStatus; syscall irLibTrapDisconnectIrLap;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrConnectReq(UInt16 refNum,
 *                                       IrConnect* con,
 *                                       IrPacket* packet,
 *                                       UInt8 credit);
 *
 * Description:   Request an IrLMP or TinyTP connection. The result is
 *                is signaled via the callback specified in the IrConnect
 *                structure. The callback event is 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.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                con - pointer to IrConnect structure for handing the
 *                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 conneciton 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 will be returned
 *                via 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 will occur. This
 *                parameter is ignored if the Connection is an IrLMP connection.
 *
 * Return Values: IR_STATUS_PENDING - operation has been started successfully
 *                and the result will be returned via 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
 *                via the callback with the event LEVENT_PACKET_HANDLED.
 *
 *                IR_STATUS_FAILED - operation failed because of one of the
 *                reasons below. Note that the packet is
 *                available immediately:
 *                   - Connection is busy (already involved in a connection)
 *                   - IrConnect structure is not bound to the stack
 *                   - Packet size exceeds maximum allowed.
 *
 *                IR_STATUS_NO_IRLAP - operation failed because there is no
 *                IrLAP connection (the packet is available immediately).
 *)

function IrConnectReq(refNum: UInt16; var con: IrConnect; var packet: IrPacket; credit: UInt8): IrStatus; syscall irLibTrapConnectReq;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrConnectRsp(UInt16 refNum,
 *                                       IrConnect* con,
 *                                       IrPacket* packet,
 *                                       UInt8 credit);
 *
 * Description:   Accept an incoming connection that has been signaled via
 *                the callback with the event LEVENT_LM_CON_IND. IR_ConnectRsp
 *                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 LEVENT_LM_CON_IND event.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                con - pointer to IrConnect structure to managed 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 will be returned
 *                via 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 will occur. This
 *                parameter is ignored if the Connection is an IrLMP connection.
 *
 * Return Values: IR_STATUS_PENDING - response has been started successfully
 *                and the packet is returned via the callback with the event
 *                LEVENT_PACKET_HANDLED.
 *
 *                IR_STATUS_FAILED - operation failed because of one of the
 *                reasons below . Note that the packet is
 *                available immediately:
 *                   - Connection is not in the proper state to require a
 *                     response.
 *                   - IrConnect structure is not bound to the stack
 *                   - Packet size exceeds maximum allowed.
 *
 *                IR_STATUS_NO_IRLAP - operation failed because there is no
 *                IrLAP connection (Packet is available immediately).
 *)

function IrConnectRsp(refNum: UInt16; var con: IrConnect; var packet: IrPacket; credit: UInt8): IrStatus; syscall irLibTrapConnectRsp;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IR_DataReq(IrConnect* con,
 *                                    IrPacket* packet);
 *
 * Description:   Send a data packet. The packet is owned by the stack until
 *                it is returned via the callback with event
 *                LEVENT_PACKET_HANDLED. The largest packet that can be sent
 *                is found by calling IR_MaxTxSize().
 *
 * 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 packet that contains data to send.
 *                The packet should exceed the max size found with
 *                IR_MaxTxSize().
 *
 * Return Values: IR_STATUS_PENDING - packet has been queued by the stack.
 *                The packet will be returned via the callback with event
 *                LEVENT_PACKET_HANDLED.
 *
 *
 *                IR_STATUS_FAILED - operation failed and packet is available
 *                immediately. Operation failed for one of the following
 *                reasons:
 *                  - IrConnect structure is not bound to the stack (error
 *                    checking only)
 *                  - packet exceeds the maximum size (error checking only)
 *                  - IrConnect does not represent an active connection
 *)

function IrDataReq(refNum: UInt16; var con: IrConnect; var packet: IrPacket): IrStatus; syscall irLibTrapDataReq;

(*---------------------------------------------------------------------------
 *
 * Prototype:     void IrAdvanceCredit(IrConnect* con,
 *                                      UInt8 credit);
 *
 * Description:   Advance credit to the other side. The total amount of
 *                credit should not exceed 127. The credit passed by this
 *                function is added to existing available credit which is
 *                the number that must not exceed 127. This function
 *                only makes sense for a Tiny TP connection.
 *
 * Parameters:    con - pointer to IrConnect structure representing
 *                connection to which credit is advanced.
 *
 *                credit - number of credit to advance.
 *
 * Return Values: void
 *)

// IrAdvanceCredit(con, credit) {(con)->availCredit += (credit);}

(*---------------------------------------------------------------------------
 *
 * Prototype:     void IrLocalBusy(UInt16 refNum,BOOL flag);
 *
 * Description:   Set the IrLAP local busy flag. If local busy is set to true
 *                then the local IrLAP layer will send RNR 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.
 *                This function should not be used when using Tiny TP or when
 *                multiple connections exist. It takes affect the next time
 *                IrLAP sends an RR frame. If IrLAP has data to send the data
 *                will be sent first so it should be used carefully.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                flag - value (true or false) to set IrLAP's local busy flag.
 *
 * Return Values: void
 *)

procedure IrLocalBusy(refNum: UInt16; flag: BOOL); syscall irLibTrapLocalBusy;

(*---------------------------------------------------------------------------
 *
 * Prototype:     void IrSetConTypeTTP(IrConnect* con)
 *
 * Description:   Set the type of the connection to Tiny TP. This function
 *                must be called after the IrConnect structure is bound to
 *                the stack.
 *
 * Parameters:    con - pointer to IrConnect structure.
 *
 * Return Values: void
 *)

// IrSetConTypeTTP(con) { ((con)->flags |= LCON_FLAGS_TTP); }

(*---------------------------------------------------------------------------
 *
 * Prototype:     void IrSetConTypeLMP(IrConnect* con)
 *
 * Description:   Set the type of the connection to IrLMP. This function
 *                must be called after the IrConnect structure is bound to
 *                the stack.
 *
 * Parameters:    con - pointer to IrConnect structure.
 *
 * Return Values: void
 *)

// IrSetConTypeLMP(con) { ((con)->flags &= ~LCON_FLAGS_TTP); }

(*---------------------------------------------------------------------------
 *
 * Prototype:     UInt16 IrMaxTxSize(UInt16 refNum,IrConnect* con);
 *
 * Description:   Returns the maximum size allowed for a transmit packet.
 *                The value returned is only valid for active connections.
 *                The maximum size will vary for each connection and is based
 *                on the negotiated IrLAP parameters and the type of the
 *                connection.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                con - pointer to IrConnect structure which represents
 *                an active connection.
 *
 * Return Values: Maxmum number of bytes for a transmit packet.
 *)

function IrMaxTxSize(refNum: UInt16; var con: IrConnect): UInt16; syscall irLibTrapMaxTxSize;

(*---------------------------------------------------------------------------
 *
 * Prototype:    IrMaxRxSize(UInt16 refNum,IrConnect* con);
 *
 * Description:   Returns the maximum size buffer that can be sent by the
 *                the other device. The value returned is only valid for
 *                active connections. The maximum size will vary for
 *                each connection and is based on the negotiated IrLAP
 *                parameters and the type of the connection.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                con - pointer to IrConnect structure which represents
 *                an active connection.
 *
 * Return Values: Maxmum number of bytes that can be sent by the other
 *                device (maximum bytes that can be received).
 *)

function IrMaxRxSize(refNum: UInt16; var con: IrConnect): UInt16; syscall irLibTrapMaxRxSize;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrSetDeviceInfo(UInt16 refNum,UInt8 *info,UInt8 len);
 *
 * Description:   Set the XID info string used during discovery to the given
 *                string and length. The XID info string contains hints and
 *                the nickname of the device. The size cannot exceed
 *                IR_MAX_DEVICE_INFO bytes.
 *
 * Parameters:    refNum - ir library refNum
 *
 *                info - pointer to array of bytes
 *
 *                len - number of bytes pointed to by info
 *
 * Return Values: IR_STATUS_SUCCESS - operation is successful.
 *
 *                IR_STATUS_FAILED - operation failed because info is too
 *                big (Error Checking only).
 *)

function IrSetDeviceInfo(refNum: UInt16; var info: UInt8; len: UInt8): IrStatus; syscall irLibTrapSetDeviceInfo;

(*---------------------------------------------------------------------------
 *
 * Prototype:     BOOL IrIsNoProgress(UInt16 refNum);
 *
 * Description:   Return true if IrLAP is not making progress otherwise
 *                return false (this is an optional function).
 *
 * Parameters:    refNum - ir library refNum
 *
 * Return Values: true if IrLAP is not making progress, false otherwise.
 *)

function IrIsNoProgress(refNum: UInt16): BOOL; syscall irLibTrapIsNoProgress;

(*---------------------------------------------------------------------------
 *
 * Prototype:     Boolean IrIsRemoteBusy(UInt16 refNum)
 *
 * Description:   Return true if the other device's IrLAP is busy otherwise
 *                return false (this is an optional function).
 *
 * Parameters:    refNum - ir library refNum
 *
 * Return Values: true if the other device's IrLAP is busy, false otherwise.
 *)

function IrIsRemoteBusy(refNum: UInt16): BOOL; syscall irLibTrapIsRemoteBusy;

(*---------------------------------------------------------------------------
 *
 * Prototype:     BOOL IrIsMediaBusy(UInt16 refNum);
 *
 * Description:   Return true if the IR media is busy. Otherwise return false
 *                (this is an optional function).
 *
 * Parameters:    refNum - ir library refNum
 *
 * Return Values: true if IR media is busy, false otherwise.
 *)

function IrIsMediaBusy(refNum: UInt16): BOOL; syscall irLibTrapIsMediaBusy;

(*---------------------------------------------------------------------------
 *
 * Prototype:     BOOL IrIsIrLapConnected(UInt16 refNum);
 *
 * Description:   Return true if an IrLAP connection exists (this is an
 *                optional function). Only available if IR_IS_LAP_FUNCS is
 *                defined.
 *
 * Parameters:    refNum - ir library refNum
 *
 * Return Values: true if IrLAP is connected, false otherwise.
 *)

function IrIsIrLapConnected(refNum: UInt16): BOOL; syscall irLibTrapIsIrLapConnected;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IR_TestReq(IrDeviceAddr devAddr,
 *                                    IrConnect* con,
 *                                    IrPacket* packet)
 *
 * Description:   Request a TEST command frame be sent in the NDM state. The
 *                result is signaled via the callback specified in the
 *                IrConnect structure. The callback event is LEVENT_TEST_CNF
 *                and the status field indates 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.
 *
 *
 * Parameters:    refNum - ir library refNum
 *
 *                devAddr - device address of device where TEST will be
 *                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 a packet 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.
 *
 *
 * Return Values: IR_STATUS_PENDING - operation has been started successfully
 *                and the result will be returned via the callback function with
 *                the event LEVENT_TEST_CNF. This is also the indication
 *                returning the packet.
 *
 *                IR_STATUS_FAILED - operation failed because of one of the
 *                reasons below. Note that the packet is
 *                available immediately:
 *                   - IrConnect structure is not bound to the stack
 *                   - Packet size exceeds maximum allowed.
 *
 *                IR_STATUS_MEDIA_BUSY - operation failed because the media is
 *                busy or the stack is not in the NDM state (the packet is
 *                available immediately).
 *)

function IrTestReq(refNum: UInt16; devAddr: IrDeviceAddr; var con: IrConnect; var packet: IrPacket): IrStatus; syscall irLibTrapTestReq;

(****************************************************************************
 *
 * Callback Reference
 *
 ****************************************************************************)

(*---------------------------------------------------------------------------
 *
 * The stack calls the application via 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 are as follows:
 *
 * LEVENT_LM_CON_IND - Other device has initiated a connection. IR_ConnectRsp
 * should be called to accept the connection. Any data associated with the
 * connection request can be found using fields rxBuff and rxLen for the
 * 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 for the data pointer and length respectively.
 *
 * LEVENT_DATA_IND - Data has been received. The received data is accessed
 * using fields rxBuff and rxLen;
 *
 * LEVENT_PACKET_HANDLED - A packet is being returned. A pointer to the
 * packet exists in field packet.
 *
 * 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 will not be given. The callback function
 * of all bound IrConnect structures is called.
 *
 * 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_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_STATUS_IND - Indicates that a status event from the stack has
 * occured. The status field indicates the status generating the event.
 * Possible statuses are as follows. Note this event is optional:
 *    IR_STATUS_NO_PROGRESS - means that IrLAP has no progress for 3 seconds
 *    threshold time (e.g. beam is blocked).
 *
 *    IR_STATUS_LINK_OK - indicates that the no progress condition has
 *    cleared.
 *
 *    IR_STATUS_MEDIA_NOT_BUSY - indicates that the IR media has
 *    transitioned from busy to not busy.
 *
 * 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 will be sent in response to the test command is in the packet
 * field. The packet is currently setup to respond with the same data sent
 * in the command TEST frame. If different data is desired as a response
 * then modify the packet structure. This event is sent to the callback
 * function in all bound IrConnect structures. The IAS connections ignore
 * this event.
 *
 * LEVENT_TEST_CNF - Indicates that a TEST command has completed. The status
 * field indicates if the test was successful. IR_STATUS_SUCCESS indicates
 * that 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 will occur).
 *)
(* The following functions are used to extract U16 and U32 bit numbers
 * from an IAS result. Only IasGetU16 is used internal by the stack
 * but they are part of some of the IAS Query result macros. To enable
 * the function versions define IR_IAS_GET_AS_FUNC
 *)

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrIAS_Add(UInt16 refNum,IrIasObject* obj)
 *
 * Description:   Add an IAS Object to the IAS Database. The Object is
 *                is not copied so the memory for the object must exist
 *                for as long as the object is in the data base. The
 *                IAS database is designed to only allow objects with unique
 *                class names. The error checking version 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.
 *
 * Parameters:    refNum - ir library reference number
 *
 *                obj - pointer to an IrIasObject structure.
 *
 * Return Values: IR_STATUS_SUCCESS - operation is successful.
 *
 *                IR_STATUS_FAILED - operation failed for one of the
 *                following reasons:
 *                  - No space in the data base (see irconfig.h to
 *                    increase the size of the IAS database).
 *                  - An entry with the same class name already exists.
 *                    Error check only.
 *                  - 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).
 *                    Error check only.
 *                  - The class name exceeds IR_MAX_IAS_NAME. Error check
 *                    only
 *)

function IrIAS_Add(refNum: UInt16; var obj: IrIasObject): IrStatus; syscall irLibTrapIAS_Add;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrIAS_Query(UInt16 refNum,IrIasQuery* token)
 *
 * Description:   Make an IAS query of another devices IAS database. 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.
 *
 * Parameters:    refNum - ir library reference number
 *
 *                token - pointer to an IrIasQuery structure initialized
 *                as follows:
 *                   - pointer to a callback function in which the result will
 *                     signaled.
 *                   - result points to a buffer large enough to hold the
 *                     result of the query.
 *                   - resultBufSize is set to the size of the result buffer.
 *                   - queryBuf must point to a valid query.
 *                   - queryLen is set to the number of bytes in queryBuf.
 *                     The length must not exceed IR_MAX_QUERY_LEN.
 *
 * Return Values: IR_STATUS_PENDING - operation is started successfully and
 *                the result will be signaled via the calback function.
 *
 *                IR_STATUS_FAILED - operation failed for one of the
 *                following reasons (Error check only):
 *                   - The query exceeds IR_MAX_QUERY_LEN.
 *                   - The result field of token is 0.
 *                   - The resultBuffSize field of token is 0.
 *                   - The callback field of token is 0.
 *                   - A query is already in progress.
 *
 *                IR_STATUS_NO_IRLAP - operation failed because there is no
 *                IrLAP connection.
 *)

function IrIAS_Query(refNum: UInt16; var token: IrIasQuery): IrStatus; syscall irLibTrapIAS_Query;

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrStatus IrIAS_SetDeviceName(UInt16 refNum,UInt8 *name, UInt8 len)
 *
 * Description:   Set the value field of the device name attribute of the
 *                "Device" object in the IAS Database. This function is only
 *                available if IR_IAS_DEVICE_NAME is defined.
 *
 * Parameters:    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.
 *
 * Return Values: IR_STATUS_SUCCESS - operation is successful.
 *
 *                IR_STATUS_FAILED - len is too big or the value field is not
 *                a valid user string (Error Checking only).
 *)

function IrIAS_SetDeviceName(refNum: UInt16; var name: UInt8; len: UInt8): IrStatus; syscall irLibTrapIAS_SetDeviceName;

(*---------------------------------------------------------------------------
 *
 * Below are some functions and macros for parsing the results buffer
 * after a successfull IAS Query.
 *)

(*---------------------------------------------------------------------------
 *
 * Prototype:     void IrIAS_StartResult(IrIasQuery* token)
 *
 * Description:   Put the internal pointer to the start of the
 *                result buffer.
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: void
 *)

// IrIAS_StartResult(t) ((t)->offset = 0)

(*---------------------------------------------------------------------------
 *
 * Prototype:     U16 IRIAS_GetObjectID(IrIasQuery* token)
 *
 * Description:   Return the unique object ID of the current result item.
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: object ID
 *)

// IrIAS_GetObjectID(t) IasGetU16((t)->result + (t)->offset)

(*---------------------------------------------------------------------------
 *
 * Prototype:     U8 IrIAS_GetType(IrIasQuery* token)
 *
 * Description:   Return the type of the current result item
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Type of result item such as IAS_ATTRIB_INTEGER,
 *                IAS_ATTRIB_OCTET_STRING or IAS_ATTRIB_USER_STRING.
 *)

// IrIAS_GetType(t) ((t)->result[(t)->offset + 2])

(*---------------------------------------------------------------------------
 *
 * Prototype:     U32 IrIAS_GetInteger(IrIasQuery* token)
 *
 * Description:   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).
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Integer value.
 *)

// IrIAS_GetInteger(t) IasGetU32((t)->result + (t)->offset + 3)

(*---------------------------------------------------------------------------
 *
 * Prototype:     U8 IrIAS_GetIntLsap(IrIasQuery* token)
 *
 * Description:   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.
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Integer value.
 *)

// IrIAS_GetIntLsap(t) ((t)->result[(t)->offset + 6])

(*---------------------------------------------------------------------------
 *
 * Prototype:     U16 IrIAS_GetOctetStringLen(IrIasQuery* token)
 *
 * Description:   Get 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).
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Length of octet string
 *)

// IrIAS_GetOctetStringLen(t) IasGetU16((t)->result + (t)->offset + 3)

(*---------------------------------------------------------------------------
 *
 * Prototype:     U8* IrIAS_GetOctetString(IrIasQuery* token)
 *
 * Description:   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).
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: pointer to octet string
 *)

// IrIAS_GetOctetString(t) ((t)->result + (t)->offset + 5)

(*---------------------------------------------------------------------------
 *
 * Prototype:     U8 IrIAS_GetUserStringLen(IrIasQuery* token)
 *
 * Description:   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).
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Length of user string
 *)

// IrIAS_GetUserStringLen(t) ((t)->result[(t)->offset + 4])

(*---------------------------------------------------------------------------
 *
 * Prototype:     IrCharSet IrIAS_GetUserStringCharSet(IrIasQuery* token)
 *
 * Description:   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).
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Character set
 *)

// IrIAS_GetUserStringCharSet(t) ((t)->result[(t)->offset + 3])

(*---------------------------------------------------------------------------
 *
 * Prototype:     U8* IrIAS_GetUserString(IrIasQuery* token)
 *
 * Description:   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).
 *
 * Parameters:    token - pointer to an IrIasQuery structure
 *
 * Return Values: Pointer to result string
 *)

// IrIAS_GetUserString(t) ((t)->result + (t)->offset + 5)

 (*---------------------------------------------------------------------------
 *
 * Prototype:     UInt8 *IrIAS_Next(UInt16 refNum,IrIasQuery* token)
 *
 * Description:   Move the internal pointer to the next result item. This
 *                function returns a pointer to the start of the next result
 *                item. If the poiinter is 0 then there are no more result
 *                items. Only available if IR_IAS_NEXT is defined.
 *
 * Parameters:    refNum - library reference number
 *
 *               token - pointer to an IrIasQuery structure
 *
 * Return Values: Pointer to the next result item or 0 if no more items.
 *)

function IrIAS_Next(refNum: UInt16; var token: IrIasQuery): UInt8Ptr; syscall irLibTrapIAS_Next;

(****************************************************************************
 *
 * IAS Callback Reference
 *
 ****************************************************************************)

(*---------------------------------------------------------------------------
 *
 * The result of IAS query is signaled by calling the callback function
 * pointed to by the callBack field of IrIasQuery structure. The callback
 * has the following prototype:
 *
 *  void callBack(IrStatus);
 *
 * The callback is called with a status as follows:
 *
 *    IR_STATUS_SUCCESS - the query operation finished successfully and
 *    the results can be parsed
 *
 *    IR_STATUS_DISCONNECT - the link or IrLMP connection was disconnected
 *    during the query so the results are not valid.

=========================================================================== *)

// The following two functions are only for advances uses - do not use these.

 (*---------------------------------------------------------------------------
 *
 * Prototype:     IrHandleEvent(UInt16 refnum)
 *
 * Description:   MemHandle background task event (ony used for special cases)
 *                  Normally you will not use this function
 *
 * Parameters:    refNum - library reference number
 **
 * Return Values: Pointer to the next result item or 0 if no more items.
 *)

function IrHandleEvent(refnum: UInt16): Boolean; syscall irLibTrapHandleEvent;

 (*---------------------------------------------------------------------------
 *
 * Prototype:     IrWaitForEvent(UInt16 libRefnum,Int32 timeout)
 *
 * Description:   Wait for background task event (ony used for special cases)
 *                  Normally you will not use this function
 *
 * Parameters:    refNum - library reference number
 *
 *                timeout - number of ticks to wait
 *
 * Return Values: Pointer to the next result item or 0 if no more items.
 *)

function IrWaitForEvent(libRefnum: UInt16; timeout: Int32): Err; syscall irLibTrapWaitForEvent;

implementation

end.