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

71    Old Serial Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the serial manager API:

The header file SerialMgrOld.h declares the serial manager API. For more information on the serial manager, see the chapter "Serial Communication" in the Palm OS Programmer's Companion, vol. II, Communications.


NOTE: The API described in this chapter is obsolete if the New Serial Manager Feature Set is present. The API is still supported for backward compatibility; however, the Serial Manager APIs are preferred.

Serial Manager Data Structures ^TOP^

SerCtlEnum Enum ^TOP^

To perform a control function, applications call SerControl(), which performs one of the control operations specified by SerCtlEnum, which has the following elements:

Element

Description

serCtlFirstReserved = 0

Reserve 0

serCtlStartBreak

Turn RS232 break signal on. Applications have to make sure that the break is set long enough to generate a value BREAK!

valueP = 0; valueLenP = 0

serCtlStopBreak

Turn RS232 break signal off:

valueP = 0; valueLenP = 0

serCtlBreakStatus

Get RS232 break signal status (on or off):

valueP = ptr to Word for returning status (0 = off, !0 = on)

*valueLenP = sizeof(Word)

serCtlStartLocalLoopback

Start local loopback test;

valueP = 0, valueLenP = 0

serCtlStopLocalLoopback

Stop local loopback test

valueP = 0, valueLenP = 0

serCtlMaxBaud

valueP = ptr to for returned baud

*valueLenP = sizeof(DWord)

serCtlHandshakeThreshold

Retrieve HW handshake threshold; this is the maximum baud rate that does not require hardware handshaking

valueP = ptr to DWord for returned baud

*valueLenP = sizeof(DWord)

serCtlEmuSetBlockingHook

Set a blocking hook routine.


WARNING! WARNING: For use with the Simulator on Mac OS only: NOT SUPPORTED ON THE PALM DEVICE.

valueP = ptr to SerCallbackEntryType

*valueLenP=sizeof(SerCallbackEntryType)

Returns the old settings in the first argument.

serCtlLAST

Add new address entries before this one.

SerSettingsType Struct ^TOP^

Purpose

The SerSettingsType structure defines serial port attributes; it is used by the calls SerGetSettings() and SerSetSettings(). The SerSettingsPtr type points to a SerSettingsType structure.

Prototype

typedef struct SerSettingsType {
UInt32baudRate;
UInt32flags;
Int32ctsTimeout;
} SerSettingsType;
typedef SerSettingsType *SerSettingsPtr;

Fields

baudRate
Baud rate
flags
Miscellaneous settings
ctsTimeout
Maximum number of ticks to wait for CTS to become asserted before transmitting; used only when configured with the serSettingsFlagCTSAutoM flag.

Serial Manager Functions ^TOP^

SerClearErr Function ^TOP^

Purpose

Reset the serial port's line error status.

Declared In

SerialMgrOld.h

Prototype

Err SerClearErr (
   UInt16refNum
)

Parameters

refNum
The serial library reference number.

Returns

0
No error.

Comments

Call SerClearErr only after a serial manager function (SerReceive, SerReceiveCheck, SerSend, etc.) returns with the error code serErrLineErr.

The reason for this is that SerClearErr resets the serial port. So, if SerClearErr is called unconditionally while a byte is coming into the serial port, that byte is guaranteed to become corrupted.

The right strategy is to always check the error code returned by a serial manager function. If it 's serErrLineErr, call SerClearErr immediately. However, don't make unsolicited calls to SerClearErr.

When you get serErrLineErr, consider flushing the receive queue for a fraction of a second by calling SerReceiveFlush. SerReceiveFlush calls SerClearErr for you.

SerClose Function ^TOP^

Purpose

Release the serial port previously acquired by SerOpen.

Declared In

SerialMgrOld.h

Prototype

Err SerClose (
   UInt16refNum
)

Parameters

refNum
Serial library reference number.

Returns

0
No error.
serErrNotOpen
Port wasn't open.
serErrStillOpen
Port still held open by another process.

Comments

Releases the serial port and shuts down serial port hardware if the open count has reached 0. Open serial ports consume more energy from the device's batteries; it's therefore essential to keep a port open only as long as necessary.

Caveat

Don't call SerClose unless the return value from SerOpen() was 0 (zero) or serErrAlreadyOpen.

See Also

SerOpen()

SerControl Function ^TOP^

Purpose

Perform a control function.

Declared In

SerialMgrOld.h

Prototype

Err SerControl (
   UInt16refNum,
   UInt16op,
   void*valueP,
   UInt16*valueLenP
)

Parameters

refNum
Reference number of library.
op
Control operation to perform (SerCtlEnum).
valueP
Pointer to value for operation.
valueLenP
Pointer to size of value.

Returns

0
No error.
serErrBadParam
Invalid parameter (unknown).
serErrNotOpen
Library not open.

Comments

This function provides extensible control features for the serial manager. You can

  • Turn on/off the RS232 break signal and check its status.
  • Perform a local loopback test.
  • Get the maximum supported baud rate.
  • Get the hardware handshake threshold baud rate.

Compatibility

Implemented only if 2.0 New Feature Set is present.

SerGetSettings Function ^TOP^

Purpose

Fill in the SerSettingsType structure with current serial port attributes.

Declared In

SerialMgrOld.h

Prototype

Err SerGetSettings (
   UInt16refNum,
   SerSettingsPtrsettingsP
)

Parameters

refNum
Serial library reference number.
settingsP
Pointer to SerSettingsType structure to be filled in.

Returns

0
No error.
serErrNotOpen
The port wasn't open.

Comments

The information returned by this call includes the current baud rate, CTS timeout, handshaking options, and data format options.

See the SerSettingsType structure for more details.

See Also

SerSend()

SerGetStatus Function ^TOP^

Purpose

Return the pending line error status for errors that have been detected since the last time SerClearErr() was called.

Declared In

SerialMgrOld.h

Prototype

UInt16 SerGetStatus (
   UInt16refNum,
   Boolean*ctsOnP,
   Boolean*dsrOnP
)

Parameters

refNum
Serial library reference number.
ctsOnP
Pointer to location for storing a Boolean value.
dsrOnP
Pointer to location for storing a Boolean value.

Returns

Returns any combination of the following constants, bitwise OR'ed together:

serLineErrorParity
Parity error.
serLineErrorHWOverrun
Hardware overrun.
serLineErrorFraming
Framing error.
serLineErrorBreak
Break signal detected.
serLineErrorHShake
Line handshake error.
serLineErrorSWOverrun
Software overrun.

Comments

When another serial manager function returns an error code of serErrLineErr, SerGetStatus can be used to find out the specific nature of the line error(s).

The values returned via ctsOnP and dsrOnP are not meaningful in the present version of the software

See Also

SerClearErr()

SerOpen Function ^TOP^

Purpose

Acquire and open a serial port with given baud rate and default settings.

Declared In

SerialMgrOld.h

Prototype

Err SerOpen (
   UInt16refNum,
   UInt16port,
   UInt32baud
)

Parameters

refNum
Serial library reference number.
port
Port number.
baud
Baud rate.

Returns

0
No error.
serErrAlreadyOpen
Port was open. Enables port sharing by "friendly" clients (not recommended).
serErrBadParam
Invalid parameter.
memErrNotEnoughSpace
Insufficient memory.

Comments

Acquires the serial port, powers it up, and prepares it for operation. To obtain the serial library reference number, call SysLibFind() with "Serial Library" as the library name. This reference number must be passed as a parameter to all serial manager functions. The device currently contains only one serial port with port number 0 (zero).

The baud rate is an integral baud value (for example - 300, 1200, 2400, 9600, 19200, 38400, 57600, etc.). The Palm OS® device has been tested at the standard baud rates in the range of 300 - 57600 baud. Baud rates through 1 Mbit are theoretically possible. Use CTS handshaking at baud rates above 19200 (see SerSetSettings()).

An error code of 0 (zero) or serErrAlreadyOpen indicates that the port was successfully opened. If the port is already open when SerOpen is called, the port's open count is incremented and an error code of serErrAlreadyOpen is returned. This ability to open the serial port multiple times allows cooperating tasks to share the serial port. Other tasks must refrain from using the port if serErrAlreadyOpen is returned and close it by calling SerClose().

SerReceive Function ^TOP^

Purpose

Receives size bytes worth of data or returns with error if a line error or timeout is encountered.

Declared In

SerialMgrOld.h

Prototype

UInt32 SerReceive (
   UInt16refNum,
   void*bufP,
   UInt32count,
   Int32timeout,
   Err *errP
)

Parameters

refNum
Serial library reference number.
bufP
Buffer for receiving data.
count
Number of bytes to receive.
timeout
Interbyte timeout in ticks, 0 for none, -1 forever.
errP
For returning error code.

Returns

Number of bytes received:

*errP = 0
No error.
serErrLineErr
RS232 line error.
serErrTimeOut
Interbyte timeout.

Compatibility

Implemented only if 2.0 New Feature Set is present.


NOTE: The old versions of SerSend and SerReceive are still available as SerSend10 and SerReceive10 (not V10).

See Also

SerReceive10()

SerReceive10 Function ^TOP^

Purpose

Receive a stream of bytes.

Declared In

SerialMgrOld.h

Prototype

Err SerReceive10 (
   UInt16refNum,
   void*bufP,
   UInt32bytes,
   Int32timeout
)

Parameters

refNum
The serial library reference number.
bufP
Pointer to the buffer for receiving data.
bytes
Number of bytes desired.
timeout
Interbyte time out in system ticks (-1 = forever).

Returns

0
No error. Requested number of bytes was received.
serErrTimeOut
Interbyte time out exceeded while waiting for the next byte to arrive.
serErrLineErr
Line error occurred (see SerClearErr() and SerGetStatus()).

Comments

SerReceive blocks until all the requested data has been received or an error occurs. Because this call returns immediately without any data if line errors are pending, it is important to acknowledge the detection of line errors by calling SerClearErr(). If you just need to retrieve all or some of the bytes which are already in the receive queue, call SerReceiveCheck() first to get the count of bytes presently in the receive queue.

Compatibility

This function corresponds to the 1.0 version of SerReceive.

SerReceiveCheck Function ^TOP^

Purpose

Return the count of bytes presently in the receive queue.

Declared In

SerialMgrOld.h

Prototype

Err SerReceiveCheck (
   UInt16refNum,
   UInt32*numBytesP
)

Parameters

refNum
Serial library reference number.
numBytesP
Pointer to location for returning the byte count.

Returns

0
No error.
serErrLineErr
Line error pending (see SerClearErr() and SerGetStatus()).

Comments

Because this call does not return the byte count if line errors are pending, it is important to acknowledge the detection of line errors by calling SerClearErr().

See Also

SerReceiveWait()

SerReceiveFlush Function ^TOP^

Purpose

Discard all data presently in the receive queue and flush bytes coming into the serial port. Clear the saved error status.

Declared In

SerialMgrOld.h

Prototype

void SerReceiveFlush (
   UInt16refNum,
   Int32timeout
)

Parameters

refNum
Serial library reference number.
timeout
Interbyte time out in system ticks (-1 = forever).

Returns

Returns nothing.

Comments

SerReceiveFlush blocks until a timeout occurs while waiting for the next byte to arrive.

SerReceiveWait Function ^TOP^

Purpose

Wait for at least bytes bytes of data to accumulate in the receive queue.

Declared In

SerialMgrOld.h

Prototype

Err SerReceiveWait (
   UInt16refNum,
   UInt32bytes,
   Int32timeout
)

Parameters

refNum
Serial library reference number.
bytes
Number of bytes desired.
timeout
Interbyte timeout in system ticks (-1 = forever).

Returns

0
No error.
serErrTimeOut
Interbyte timeout exceeded while waiting for next byte to arrive.
serErrLineErr
Line error occurred (see SerClearErr() and SerGetStatus()).

Comments

This is the preferred method of waiting for serial input, since it blocks the current task and allows switching the processor into a more energy-efficient state.

SerReceiveWait blocks until the desired number of bytes accumulate in the receive queue or an error occurs. The desired number of bytes must be less than the current receive queue size. The default queue size is 512 bytes. Because this call returns immediately if line errors are pending, it is important to acknowledge the detection of line errors by calling SerClearErr().

See Also

SerReceiveCheck(), SerSetReceiveBuffer()

SerSend Function ^TOP^

Purpose

Send one or more bytes of data over the serial port.

Declared In

SerialMgrOld.h

Prototype

UInt32 SerSend (
   UInt16refNum,
   void*bufP,
   UInt32count,
   Err*errP

Parameters

refNum
Serial library reference number.
bufP
Pointer to data to send.
count
Number of bytes to send.
errP
For returning error code.

Returns

Returns the number of bytes transferred.

Stores in errP:

0
No error.
serErrTimeOut
Handshake timeout.

The old calls worked, but they did not return enough info when they failed. The new calls (available in Palm OS v2.0 and greater) add more parameters to solve this problem and make serial communications programming simpler.

Don't call the new functions when running on Palm OS 1.0.

Compatibility

Implemented only if 2.0 New Feature Set is present.


NOTE: The old versions of SerSend and SerReceive are still available as SerSend10 and SerReceive10 (not V10).

See Also

SerSend10(), SerSendWait()

SerSend10 Function ^TOP^

Purpose

Send a stream of bytes to the serial port.

Declared In

SerialMgrOld.h

Prototype

Err SerSend10 (
   UInt16refNum,
   void*bufP,
   UInt32size
)

Parameters

refNum
Serial library reference number.
bufP
Pointer to the data to send.
size
Size (in number of bytes) of the data to send.

Returns

0
No error.
serErrTimeOut
Handshake timeout (such as waiting for CTS to become asserted).

Comments

In the present implementation, SerSend10 blocks until all data is transferred to the UART or a timeout error (if CTS handshaking is enabled) occurs. Future implementations may queue up the request and return immediately, performing transmission in the background. If your software needs to detect when all data has been transmitted, see SerSendWait.

This routine observes the current CTS time out setting if CTS handshaking is enabled (see SerGetSettings() and SerSend()).

Compatibility

This function corresponds to the 1.0 version of SerSend.

See Also

SerSend(), SerSendWait()

SerSendFlush Function ^TOP^

Purpose

Discard all data presently in the transmit queue.

Declared In

SerialMgrOld.h

Prototype

Err SerSendFlush (
   UInt16refNum
)

Parameters

refNum
Serial library reference number.

Returns

0
No error.

See Also

SerSend(), SerSendWait()

SerSendWait Function ^TOP^

Purpose

Wait until the serial transmit buffer empties.

Declared In

SerialMgrOld.h

Prototype

Err SerSendWait (
   UInt16refNum,
   Int32timeout
)

Parameters

refNum
Serial library reference number.
timeout
Reserved for future enhancements. Set to (-1) for compatibility.

Returns

0
No error.
serErrTimeOut
Handshake timeout (such as waiting for CTS to become asserted).

Comments

SerSendWait blocks until all data is transferred or a timeout error (if CTS handshaking is enabled) occurs. This routine observes the current CTS timeout setting if CTS handshaking is enabled (see SerGetSettings() and SerSend()).

See Also

SerSend()

SerSetReceiveBuffer Function ^TOP^

Purpose

Replace the default receive queue. To restore the original buffer, pass bufSize = 0.

Declared In

SerialMgrOld.h

Prototype

Err SerSetReceiveBuffer (
   UInt16refNum,
   void*bufP,
   UInt16bufSize
)

Parameters

refNum
Serial library reference number.
bufP
Pointer to buffer to be used as the new receive queue.
bufSize
Size of buffer, or 0 to restore the default receive queue.

Returns

Returns 0 if successful.

Comments

The specified buffer needs to contain 32 extra bytes for serial manager overhead (its size should be your application's requirement plus 32 bytes). The default receive queue must be restored before the serial port is closed. To restore the default receive queue, call SerSetReceiveBuffer() passing 0 (zero) for the buffer size. The serial manager does not free the custom receive queue.

SerSetSettings Function ^TOP^

Purpose

Set the serial port settings; that is, change its attributes.

Declared In

SerialMgrOld.h

Prototype

Err SerSetSettings (
   UInt16refNum,
   SerSettingsPtrsettingsP
)

Parameters

refNum
Serial library reference number.
settingsP
Pointer to the filled in SerSettingsType structure.

Returns

0
No error.
serErrNotOpen
The port wasn't open.
serErrBadParam
Invalid parameter.

Comments

The attributes set by this call include the current baud rate, CTS timeout, handshaking options, and data format options. See the definition of the SerSettingsType structure for more details.

To do 7E1 transmission, OR together:

serSettingsFlagBitsPerChar7 | serSettingsFlagParityOnM | serSettingsFlagParityEvenM | serSettingsFlagStopBits1

If you're trying to communicate at speeds greater than 19.2 Kbps, you need to use hardware handshaking: serSettingsFlagRTSAutoM | serSettingsFlagCTSAutoM.

See Also

SerGetSettings()