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
SerCtlEnum Enum
To perform a control function, applications call SerControl()
, which performs one of the control operations specified by SerCtlEnum
, which has the following elements:
SerSettingsType Struct
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 { UInt32 baudRate; UInt32 flags; Int32 ctsTimeout; } 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
SerClearErr Function
Purpose
Reset the serial port's line error status.
Declared In
SerialMgrOld.h
Prototype
Err SerClearErr ( UInt16 refNum )
Parameters
Returns
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
Purpose
Release the serial port previously acquired by SerOpen.
Declared In
SerialMgrOld.h
Prototype
Err SerClose ( UInt16 refNum )
Parameters
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
SerControl Function
Purpose
Declared In
SerialMgrOld.h
Prototype
Err SerControl ( UInt16 refNum, UInt16 op, 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
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
Purpose
Fill in the SerSettingsType
structure with current serial port attributes.
Declared In
SerialMgrOld.h
Prototype
Err SerGetSettings ( UInt16 refNum, SerSettingsPtr settingsP )
Parameters
-
→
refNum
- Serial library reference number.
-
↔
settingsP
- Pointer to
SerSettingsType
structure to be filled in.
Returns
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
SerGetStatus Function
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 ( UInt16 refNum, 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
SerOpen Function
Purpose
Acquire and open a serial port with given baud rate and default settings.
Declared In
SerialMgrOld.h
Prototype
Err SerOpen ( UInt16 refNum, UInt16 port, UInt32 baud )
Parameters
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
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 ( UInt16 refNum, void *bufP, UInt32 count, Int32 timeout, 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
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 Function
Purpose
Declared In
SerialMgrOld.h
Prototype
Err SerReceive10 ( UInt16 refNum, void *bufP, UInt32 bytes, Int32 timeout )
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()
andSerGetStatus()
).
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
Purpose
Return the count of bytes presently in the receive queue.
Declared In
SerialMgrOld.h
Prototype
Err SerReceiveCheck ( UInt16 refNum, 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()
andSerGetStatus()
).
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
SerReceiveFlush Function
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 ( UInt16 refNum, Int32 timeout )
Parameters
-
→
refNum
- Serial library reference number.
-
→
timeout
- Interbyte time out in system ticks (-1 = forever).
Returns
Comments
SerReceiveFlush
blocks until a timeout occurs while waiting for the next byte to arrive.
SerReceiveWait Function
Purpose
Wait for at least bytes
bytes of data to accumulate in the receive queue.
Declared In
SerialMgrOld.h
Prototype
Err SerReceiveWait ( UInt16 refNum, UInt32 bytes, Int32 timeout )
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()
andSerGetStatus()
).
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
Purpose
Send one or more bytes of data over the serial port.
Declared In
SerialMgrOld.h
Prototype
UInt32 SerSend ( UInt16 refNum, void *bufP, UInt32 count, 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.
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 Function
Purpose
Send a stream of bytes to the serial port.
Declared In
SerialMgrOld.h
Prototype
Err SerSend10 ( UInt16 refNum, void *bufP, UInt32 size )
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
Comments
In the present implementation, S
erSend10 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
SerSendFlush Function
Purpose
Discard all data presently in the transmit queue.
Declared In
SerialMgrOld.h
Prototype
Err SerSendFlush ( UInt16 refNum )
Parameters
Returns
See Also
SerSendWait Function
Purpose
Wait until the serial transmit buffer empties.
Declared In
SerialMgrOld.h
Prototype
Err SerSendWait ( UInt16 refNum, Int32 timeout )
Parameters
-
→
refNum
- Serial library reference number.
-
→
timeout
- Reserved for future enhancements. Set to (-1) for compatibility.
Returns
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
SerSetReceiveBuffer Function
Purpose
Replace the default receive queue. To restore the original buffer, pass bufSize
= 0.
Declared In
SerialMgrOld.h
Prototype
Err SerSetReceiveBuffer ( UInt16 refNum, void *bufP, UInt16 bufSize )
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
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
Purpose
Set the serial port settings; that is, change its attributes.
Declared In
SerialMgrOld.h
Prototype
Err SerSetSettings ( UInt16 refNum, SerSettingsPtr settingsP )
Parameters
-
→
refNum
- Serial library reference number.
-
↔
settingsP
- Pointer to the filled in
SerSettingsType
structure.
Returns
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
.