Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

72    Serial Link Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the serial link manager API. The header file SerialLinkMgr.h declares the serial link manager API. For more information on the serial link manager, see the chapter "Serial Communication" in the Palm OS Programmer's Companion, vol. II, Communications.

Serial Link Manager Functions ^TOP^

SlkClose Function ^TOP^

Purpose

Close down the serial link manager.

Declared In

SerialLinkMgr.h

Prototype

Err SlkClose (
   void
)

Parameters

None.

Returns

0
No error.
slkErrNotOpen
The serial link manager was not open.

Comments

When the open count reaches zero, this routine frees resources allocated by serial link manager.

SlkCloseSocket Function ^TOP^

Purpose

Closes a socket previously opened with SlkOpenSocket().

The caller is responsible for closing the communications library used by this socket, if necessary.

Declared In

SerialLinkMgr.h

Prototype

Err SlkCloseSocket (
   UInt16socket
)

Parameters

socket
The socket ID to close.

Returns

0
No error.
slkErrSocketNotOpen
The socket was not open.

Comments

SlkCloseSocket frees system resources the serial link manager allocated for the socket. It does not free resources allocated and passed by the client, such as the buffers passed to SlkSetSocketListener(); this is the client's responsibility. The caller is also responsible for closing the communications library used by this socket.

See Also

SlkOpenSocket()

SlkFlushSocket Function ^TOP^

Purpose

Flush the receive queue of the communications library associated with the given socket.

Declared In

SerialLinkMgr.h

Prototype

Err SlkFlushSocket (
   UInt16socket,
   Int32timeout
)

Parameters

socket
Socket ID.
timeout
Interbyte timeout in system ticks.

Returns

0
No error.
slkErrSocketNotOpen
The socket wasn't open.

SlkOpen Function ^TOP^

Purpose

Initialize the serial link manager.

Declared In

SerialLinkMgr.h

Prototype

Err SlkOpen (
   void
)

Parameters

None.

Returns

0
No error.
slkErrAlreadyOpen
No error.

Comments

Initializes the serial link manager, allocating necessary resources. Return codes of 0 (zero) and slkErrAlreadyOpen both indicate success. Any other return code indicates failure. The slkErrAlreadyOpen function informs the client that someone else is also using the serial link manager. If the serial link manager was successfully opened by the client, the client needs to call SlkClose() when it finishes using the serial link manager.

SlkOpenSocket Function ^TOP^

Purpose

Open a serial link socket and associate it with a communications library. The socket may be a known static socket or a dynamically assigned socket.

Declared In

SerialLinkMgr.h

Prototype

Err SlkOpenSocket (
   UInt16portID,
   UInt16*socketP,
   BooleanstaticSocket
)

Parameters

portID
Comm library reference number for socket.
socketP
Pointer to location for returning the socket ID.
staticSocket
If TRUE, *socketP contains the desired static socket number to open. If FALSE, any free socket number is assigned dynamically and opened.

Returns

0
No error.
slkErrOutOfSockets
No more sockets can be opened.

Comments

The communications library must already be initialized and opened (see SerOpen()). When finished using the socket, the caller must call SlkCloseSocket() to free system resources allocated for the socket. For information about well-known static socket IDs, see The Serial Link Protocol.

SlkReceivePacket Function ^TOP^

Purpose

Receive and validate a packet for a particular socket or for any socket. Check for format and checksum errors.

Declared In

SerialLinkMgr.h

Prototype

Err SlkReceivePacket (
   UInt16socket,
   BooleanandOtherSockets,
   SlkPktHeaderPtrheaderP,
   void*bodyP,
   UInt16bodySize,
   Int32timeout
)

Parameters

socket
The socket ID.
andOtherSockets
If TRUE, ignore destination in packet header.
headerP
Pointer to the packet header buffer (size of SlkPktHeaderType).
bodyP
Pointer to the packet client data buffer.
bodySize
Size of the client data buffer (maximum client data size which can be accommodated).
timeout
Maximum number of system ticks to wait for beginning of a packet; -1 means wait forever.

Returns

0
No error.
slkErrSocketNotOpen
The socket was not open.
slkErrTimeOut
Timed out waiting for a packet.
slkErrWrongDestSocket
The packet being received had an unexpected destination.
slkErrChecksum
Invalid header checksum or packet CRC-16.
slkErrBuffer
Client data buffer was too small for packet's client data.

If andOtherSockets is FALSE, this routine returns with an error code unless it gets a packet for the specific socket.

If andOtherSockets is TRUE, this routine returns successfully if it sees any incoming packet from the communications library used by socket.

Comments

You may request to receive a packet for the passed socket ID only, or for any open socket which does not have a socket listener. The parameters also specify buffers for the packet header and client data, and a timeout. The timeout indicates how long the receiver should wait for a packet to begin arriving before timing out. If a packet is received for a socket with a registered socket listener, it will be dispatched via its socket listener procedure. On success, the packet header buffer and packet client data buffer is filled in with the actual size of the packet's client data in the packet header's bodySize field.

SlkSendPacket Function ^TOP^

Purpose

Send a serial link packet via the serial output driver.

Declared In

SerialLinkMgr.h

Prototype

Err SlkSendPacket (
   SlkPktHeaderPtrheaderP,
   SlkWriteDataPtrwriteList
)

Parameters

headerP
Pointer to the packet header structure with client information filled in (see Comments).
writeList
List of packet client data blocks (see Comments).

Returns

0
No error.
slkErrSocketNotOpen
The socket was not open.
slkErrTimeOut
Handshake timeout.

Comments

SlkSendPacket stuffs the signature, client data size, and the checksum fields of the packet header. The caller must fill in all other packet header fields. If the transaction ID field is set to 0 (zero), the serial link manager automatically generates and stuffs a new non-zero transaction ID. The array of SlkWriteDataType structures enables the caller to specify the client data part of the packet as a list of noncontiguous blocks. The end of list is indicated by an array element with the size field set to 0 (zero). This call blocks until the entire packet is sent out or until an error occurs.

SlkSetSocketListener Function ^TOP^

Purpose

Register a socket listener for a particular socket.

Declared In

SerialLinkMgr.h

Prototype

Err SlkSetSocketListener (
   UInt16socket,
   SlkSocketListenPtrsocketP
)

Parameters

socket
Socket ID.
socketP
Pointer to a SlkSocketListenType structure.

Returns

0
No error.
slkErrBadParam
Invalid parameter.
slkErrSocketNotOpen
The socket was not open.

Comments

Called by applications to set up a socket listener.

Since the serial link manager does not make a copy of the SlkSocketListenType structure, but instead saves the passed pointer to it, the structure

  • must not be an automatic variable (that is, local variable allocated on the stack)
  • may be a global variable in an application
  • may be a locked chunk allocated from the dynamic heap

The SlkSocketListenType structure specifies pointers to the socket listener procedure and the data buffers for dispatching packets destined for this socket. Pointers to two buffers must be specified: the packet header buffer (size of SlkPktHeaderType), and the packet body (client data) buffer. The packet body buffer must be large enough for the largest expected client data size. Both buffers may be application global variables or locked chunks allocated from the dynamic heap.

The socket listener procedure is called when a valid packet is received for the socket. Pointers to the packet header buffer and the packet body buffer are passed as parameters to the socket listener procedure.


NOTE: The application is responsible for freeing the SlkSocketListenType structure or the allocated buffers when the socket is closed. The serial link manager doesn't do it.

Compatibility

If either 5.0 New Feature Set or Palm OS Cobalt Feature Set is present this function is unimplemented.

SlkSocketPortID Function ^TOP^

Purpose

Get the port ID associated with a particular socket; for use with the new serial manager.

Declared In

SerialLinkMgr.h

Prototype

ErrSlkSocketPortID (
   UInt16socket,
   UInt16*portIDP
)

Parameters

socket
The socket ID.
portIDP
Pointer to location for returning the port ID.

Returns

0
No error.
slkErrSocketNotOpen
The socket was not open.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SlkSocketSetTimeout Function ^TOP^

Purpose

Set the interbyte packet receive-timeout for a particular socket.

Declared In

SerialLinkMgr.h

Prototype

Err SlkSocketSetTimeout (
   UInt16socket,
   Int32timeout
)

Parameters

socket
Socket ID.
timeout
Interbyte packet receive-timeout in system ticks.

Returns

0
No error.
slkErrSocketNotOpen
The socket was not open.