Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 9 - IrDA Communication Tool / Using the IrDA Tool

Making a Connection

Establishing a connection with an IrDA device is a multi-staged process. The first stage of the connection process is the discovery phase. In this stage, the Newton unit probes and accumulates a list of other IrDA devices within beaming range. Each device is loosely identified by a service hints field (PDA/Computer/Printer/etc) and a device nickname. The *kCMOIrDADiscoveryInformation option is used to specify which device to use and also how the Newton unit should appear to other devices that probe it (in a Listen operation).

The second stage of the connection process involves a name lookup of the service to use, or registry of the service provided (in a Listen operation). The *kCMOIrDAConnectInformation option is used to specify this information.

The final stage of the connection process is to make the connection. At this point, a negotiation phase takes place between the Newton unit and the other IrDA device. The negotiation parameters are baud rate, data size (receive buffer size), window size (number of receive buffers), and link disconnect time. The following options are used to define these negotiation parameters: kCMOSerialBitRate, *kCMOIrDAReceiveBuffers, and *kCMOIrDALinkDisconnectTimeout.

Note that the kCMOSerialBitRate option is not documented in this chapter because it's already covered in the "Built-in Communications Tools" chapter of Newton Programmer's Reference. It works slightly different when used with the IrDA tool; it specifies the maximum speed at which you want the Newton device to communicate. The value you specify can be negotiated downwards by the device at the other end of the connection. The default value for the IrDA tool is k115200bps, or 115200 bits per second.

For convenience and future compatibility, the known higher FIR speeds defined for IrDA of 576000, 1152000, and 4000000 bps are accepted but treated as k115200bps (the highest possible speed currently supported by the hardware).

Below is an example NewtonScript option array that specifies all the options that can be used with either a Connect or Listen request. Note that some fields of some options apply only to Connect while other fields apply only to Listen.

Typically, the only option that needs to be supplied is the *kCMOIrDAConnectInformation option, to either identify the Newton device or to identify the device that you are connecting to. And even this option may be omitted if two Newton devices are communicating peer to peer, since they both use the default connection names.

 fEndpointConnectOptions := [

{  label:  kCMOIrDADiscoveryInformation, // IrDA discovery information
   type:   'option,
   opCode: opSetRequired,
   data: {
      arglist: [
         8,
         kIrDASvcHintPDAPalmtop,
         kIrDASvcHintPrinter,
         0,
         1,
      ],
      typelist: [
         'struct,
         'uLong, // num probe slots, default is 8
         'uLong, // my service hint, default is PDA
         'uLong, // service hint mask
         'uLong, // returned devAddr of peer device
         'uLong, // use standard media busy check?
      ], 
   },
},
{  label: kCMOIrDAConnectInformation, // IrDA connect info
   type:   'option,
   opCode: opSetRequired,
   data: {
      arglist: [
         0,
         0,
         4, // e.g. strlen("Test")
         5, // e.g. strlen("IrLPT")
         "Test",
         "IrLPT",
      ],
      typelist: [
         'struct,
         'uLong, // my lsap id, default is 0
         'uLong, // peer lsap id, default is 0
         'uLong, // my name length, default is 1
         'uLong, // peer name length, default is 1
         ['array, 'char, 0], // my name, default is "X"
         ['array, 'char, 0], // peer name, default is "X"
      ], 
   },
},
{  label:  kCMOSerialBitRate, // serial bit rate
   type:   'option,
   opCode: opSetRequired,
   data: {
      arglist: [
         115200,
      ],
      typelist: [
         'struct,
         'uLong, // max negotiate speed, default is 115.2k
      ], 
   },
},
{  label:  kCMOIrDAReceiveBuffers, // IrDA recv buffers info
   type:   'option,
   opCode: opSetRequired,
   data: {
      arglist: [
         2048,
         1,
      ],
      typelist: [
         'struct,
         'uLong, // size of each receive buffer, default is 512
         'uLong, // number of receive buffers used, default is 1
      ], 
   },
},
{  label:  kCMOIrDALinkDisconnectTimeout, // link disconnect threshold
   type:   'option,
   opCode: opSetRequired,
   data: {
      arglist: [
         8,
      ],
      typelist: [
         'struct,
         uLong, // time before disconnect, default is 40 seconds
      ], 
   },
},
 ];

If the above example option is used to connect, the Newton limits discovered devices to printers, and connects to the IrDA device with the class name "IrLPT". The Newton will communicate (up to) 115.2 Kbps, and will receive data using one 2K buffer. If there is no activity from the peer device, then the Newton will disconnect after 8 seconds.

If the above example option is used to listen, the Newton advertises itself as a palmtop device with the class name "Test". The Newton will communicate (up to) 115.2 Kbps, and will receive data using one 2K buffer. If there is no activity from the peer device, then the Newton will disconnect after 8 seconds.