This chapter provides reference material for the Serial Manager API:
- Serial Manager Data Structures
- Serial Manager Constants
- Serial Manager Functions
- Serial Manager Application-Defined Functions
The header file SerialMgr.h
declares the Serial Manager API. The file SystemResources.h
defines some serial port constants.
Serial Manager Data Structures
DeviceInfoType Typedef
Purpose
The DeviceInfoType
structure defines information about a serial device. This structure is returned by the SrmGetDeviceInfo()
function.
Prototype
typedef struct DeviceInfoType { uint32_t serDevCreator; uint32_t serDevFtrInfo; uint32_t serDevMaxBaudRate; uint32_t serDevHandshakeBaud; char *serDevPortInfoStr; uint8_t reserved[8]; } DeviceInfoType;
typedef DeviceInfoType *DeviceInfoPtr;
Fields
-
serDevCreator
- Four-character creator ID for serial driver.
-
serDevFtrInfo
- Flags defining features of this serial hardware. See Serial Capabilities Constants for a description of these flags.
-
serDevMaxBaudRate
- Maximum baud rate for this device.
-
serDevHandshakeBaud
- Hardware handshaking is recommended for baud rates over this rate.
-
serDevPortInfoStr
- Description of serial hardware device or virtual device.
SrmOpenConfigType Struct
Purpose
The SrmOpenConfigType
structure specifies parameters for opening a serial port. This structure is passed as a parameter to SrmExtOpen()
.
Prototype
typedef struct SrmOpenConfigType { uint32_t baud; uint32_t function; MemPtr drvrDataP; uint16_t drvrDataSize; uint16_t sysReserved0; uint32_t sysReserved1; uint32_t sysReserved2; } SrmOpenConfigType;
Fields
-
baud
- Baud rate at which to open the connection. Serial drivers that do not require baud rates ignore this field.
-
function
- Reserved for system use.
-
drvrDataP
- Pointer to a driver-specific data block.
-
drvrDataSize
- The size of the data block pointed to by
drvrDataP
. -
sysReserved0
- Reserved for future use.
-
sysReserved1
- Reserved for future use.
-
sysReserved2
- Reserved for future use.
Comments
The function
field, which was used under Palm OS® 5.x and earlier, is now reserved for system use.
SrmRfCommOpenParamsType Struct
Purpose
Specifies open parameters for opening an RFCOMM port.
Prototype
typedef struct SrmRfcommOpenParamsType { BtLibDeviceAddressType btAddr; uint16_t sysReserved0; char *serviceClassIDName; } SrmRfcommOpenParamsType
Fields
-
btAddr
- The address of the Bluetooth device to connect to. If a null address (00:00:00:00:00:00) is specified, a Bluetooth discovery operation is performed at connect time.
-
sysReserved0
- Reserved for system use.
-
serviceClassIDName
- A string describing the service class ID to connect to. This is usually set to "serial_port" for a standard RFCOMM connection.
NOTE: This behavior has changed since Palm OS Garnet. 68K applications remain binary compatible, but source code compatibility is broken for newly-written applications. In addition, it is no longer possible to use the Serial Manager to open an RFCOMM port in server mode; use the IOS API instead.
Serial Manager Constants
Port Constants
Purpose
When you specify the port to open in the SrmOpen()
or SrmExtOpen()
call, you can specify one of these ports to select a standard interface instead of using the Connection Manager to select the interface you want to use.
Constants
-
serPortLocalHotSync
- The physical HotSync® port. The Serial Manager automatically detects whether this port is USB or RS-232.
-
serPortCradlePort
- Cradle port. The Serial Manager automatically detects whether this port is USB or RS-232. Most applications should specify this as the port.
-
serPortIrPort
- The IR port. This is a raw IrDA port with no protocol support.
-
serPortConsolePort
- The debug console port, either USB or RS-232. USB is preferred where both are available.
-
serPortCradleRS232Port
- Port for the RS-232 cradle. Specify this port if you want to ensure that your application uses RS-232 communications only.
-
serPortCradleUSBPort
- Port for the USB cradle. This port may only be used by the HotSync application.
-
sysFileCVirtIrComm
- Serial communications over infrared (IrComm). Retained for compatibility with previous versions of Palm OS.
-
sysFileCVirtRfComm
- Serial communications over Bluetooth (RFCOMM). Retained for compatibility with previous versions of Palm OS. This port must be used by calling
SrmExtOpen()
, withdrvrDataP
pointing to anSrmRfcommOpenParamsType
structure.
Serial Capabilities Constants
Purpose
The serial capabilities constant flags describe serial hardware capabilities. These flags are set in the serDevFtrInfo
field of the DeviceInfoType
structure.
Constants
-
serDevCradlePort
- Serial hardware controls RS-232 serial from cradle connector of the device.
-
serDevRS232Serial
- Serial hardware has RS-232 line drivers.
-
serDevIRDACapable
- Serial hardware has IR line drivers and generates IrDA mode serial signals.
-
serDevConsolePort
- Serial device is the default console port.
-
serDevUSBCapable
- Serial hardware controls USB serial from cradle connector of the device.
-
serDevHotsyncCapable
- Serial device can be used for HotSync.
Serial Settings Constants
Purpose
The serial settings constants identify bit flags that correspond to various serial hardware settings. Use SrmControl()
with the op code srmCtlSetFlags
to control which settings are used.
Constants
-
srmSettingsFlagStopBitsM
- Mask for stop bits field
-
srmSettingsFlagStopBits1
- 1 stop bit (default)
-
srmSettingsFlagStopBits2
- 2 stop bits
-
srmSettingsFlagParityOnM
- Mask for parity on
-
srmSettingsFlagParityEvenM
- Mask for parity even
-
srmSettingsFlagXonXoffM
- Mask for Xon/Xoff flow control (not implemented)
-
srmSettingsFlagRTSAutoM
- Mask for RTS receive flow control. This is the default.
-
srmSettingsFlagCTSAutoM
- Mask for CTS transmit flow control
-
srmSettingsFlagBitsPerCharM
- Mask for bits per character
-
srmSettingsFlagBitsPerChar5
- 5 bits per character
-
srmSettingsFlagBitsPerChar6
- 6 bits per character
-
srmSettingsFlagBitsPerChar7
- 7 bits per character
-
srmSettingsFlagBitsPerChar8
- 8 bits per character (default)
-
srmSettingsFlagFlowControlIn
- Protect the receive buffer from software overruns. When this flag and
srmSettingsFlagRTSAutoM
are set, which is the default case, it causes the Serial Manager to assert RTS to prevent the transmitting device from continuing to send data when the receive buffer is full. Once the application receives data from the buffer, RTS is de-asserted to allow data reception to resume. - Note that this feature effectively prevents software overrun line errors but may also cause CTS timeouts on the transmitting device if the RTS line is asserted longer than the defined CTS timeout value.
SrmCtlEnum Enum
Purpose
The SrmCtlEnum
enumerated type specifies a serial control operation. Specify one of these enumerated types for the op
parameter to the SrmControl()
call.
Constants
-
srmCtlSetBaudRate
- Sets the current baud rate for the serial hardware.
-
srmCtlGetBaudRate
- Gets the current baud rate for the serial hardware.
-
srmCtlSetFlags
- Sets the current flag settings for the serial hardware. Specify flags from the set described in Serial Settings Constants.
-
srmCtlGetFlags
- Gets the current flag settings for the serial hardware.
-
srmCtlSetCtsTimeout
- Sets the current CTS timeout value for hardware handshaking.
-
srmCtlGetCtsTimeout
- Gets the current CTS timeout value for hardware handshaking.
-
srmCtlIrDAEnable
- Enable IrDA connection on this serial port.ioctl
-
srmCtlIrDADisable
- Disable IrDA connection on this serial port.
-
srmCtlRxEnable
- Enable receiver (for IrDA).
-
srmCtlRxDisable
- Disable receiver (for IrDA).
-
srmCtlEmuSetBlockingHook
- Set a blocking hook routine for emulation mode only. Not supported on the actual device.
-
srmCtlSystemReserved
- Reserves op codes between 0x7000 and 0x8000 for system use.
NOTE: Palm OS Cobalt no longer supports custom opcodes. If you need the added flexibility, you should use IOS STDIO calls directly.
Status Constants
Purpose
The status constants identify bit flags that correspond to the status of serial signals. They can be returned by the SrmGetStatus()
function.
Constants
-
srmStatusCtsOn
- CTS line is active.
-
srmStatusRtsOn
- RTS line is active.
-
srmStatusDsrOn
- DSR line is active.
-
srmStatusBreakSigOn
- Break signal is active.
-
srmStatusDtrOn
- DTR is active.
-
srmStatusDcdOn
- DCD is active.
-
srmStatusRingOn
- Ring detected.
Line Error Constants
Purpose
The line error constants identify bit flags that correspond to the line errors that may occur on the port. They can be returned by the SrmGetStatus()
function.
Constants
-
serLineErrorParity
- Parity error
-
serLineErrorHWOverrun
- Hardware overrun
-
serLineErrorFraming
- Framing error
-
serLineErrorBreak
- Break signal asserted
-
serLineErrorHShake
- Line handshake error
-
serLineErrorSWOverrun
- Software overrun
-
serLineErrorCarrierLost
- Carrier detect signal dropped
Serial Manager Functions
SrmClearErr Function
Clears the port of any line errors.
Declared In
SerialMgr.h
Prototype
status_t SrmClearErr ( uint16_t portId )
Parameters
-
→ portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
.
Returns
This function returns the following error codes:
SrmClose Function
Purpose
Closes a serial port and makes it available to other applications, regardless of whether the port is a foreground or background port.
Declared In
SerialMgr.h
Prototype
status_t SrmClose ( uint16_t portId )
Parameters
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The serial port is not open.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
If a foreground port is being closed and a background port exists, the background will have access to the port as long as another foreground port is not opened.
If a foreground port is being closed and a yielded port exists, the yielded port will have access to the port as long as it does not yield to the opening of another foreground port. If there are both a yielded port and a background port for the foreground port being closed, the yielded port takes precedence over the background port.
See Also
SrmControl Function
Purpose
Performs a serial control function.
Declared In
SerialMgr.h
Prototype
status_t SrmControl ( uint16_t portId, uint16_t op, void *valueP, uint16_t *valueLenP )
Parameters
-
→ portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→ op
- Control operation to perform. Specify one of the
SrmCtlEnum
enumerated types. -
→ valueP
- Pointer to a value to use for the operation. See Comments for details.
-
↔ valueLenP
- Pointer to the size of
valueP
. See Comments for details.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadParam
- An invalid op code was specified.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The serial port is not open.
-
serErrNoDevicesAvail
- No serial devices could be found.
-
serErrNotSupported
- The specified op code is not supported in the current configuration.
Comments
Table 4.1 shows what to pass for the valueP
and valueLenP
parameters for each of the operation codes. Control codes not listed do not use these parameters. See SrmCtlEnum
for a complete list of control codes.
Table 4.1 SrmControl Parameters
-> |
|
<-> <-> For a serial driver, these pointers are passed to the driver's control function and they contain that functions return values (if any) upon return. |
|
<- <- If an error is returned by |
|
-> |
|
<- |
SrmExtOpen Function
Purpose
Opens a foreground port connection with the specified configuration.
Declared In
SerialMgr.h
Prototype
status_t SrmExtOpen ( uint32_t port, SrmOpenConfigType *configP, uint16_t configSize, uint16_t *newPortIdP )
Parameters
-
→
port
- The four-character port name (such as 'ircm' or 'u328') or logical port number to be opened. (See Port Constants.)
-
→
configP
- Pointer to the configuration structure specifying the serial port's properties. See
SrmOpenConfigType
. -
→
configSize
- The size of the configuration structure pointed to by
configP
. -
←
newPortIdP
- Contains the port ID to be passed to other Serial Manager functions.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- The
port
parameter does not specify a valid port. -
serErrBadParam
- The
configP
parameter isNULL
. -
serErrAlreadyOpen
- The Serial Manager already has a port open.
-
memErrNotEnoughSpace
- There was not enough memory available to open the port.
Comments
Do not keep the port open any longer than necessary. An open serial port consumes more energy from the device's batteries.
The values specified in the configP
parameter depend on the type of connection being made. For RS-232 connections, you specify the baud rate but not a purpose. For USB connections, you specify a purpose but not a baud rate.
When opening the RFCOMM ('rfcm'
) port, you should specify in the configP
->drvrDataP field a pointer to an SrmRfcommOpenParamsType
structure.
A newly opened port has its line errors cleared, the default CTS timeout set (specified by the constant srmDefaultCTSTimeout
), a 512-byte receive queue allocated, 1 stop bit, 8 bits per character, RTS enabled, and flow control enabled. To increase the receive queue size, use SrmSetReceiveBuffer()
. To change the other serial port settings, use SrmControl()
.
See Also
SrmGetDeviceCount Function
Purpose
Returns the number of available serial devices.
Declared In
SerialMgr.h
Prototype
status_t SrmGetDeviceCount ( uint16_t *numOfDevicesP )
Parameters
Returns
See Also
SrmGetDeviceInfo Function
Purpose
Returns information about a serial device.
Declared In
SerialMgr.h
Prototype
status_t SrmGetDeviceInfo ( uint32_t deviceID, DeviceInfoType *deviceInfoP )
Parameters
-
→
deviceID
- ID of serial device to get information for. You can pass a zero-based index (0, 1, 2, ...), a valid port ID returned from
SrmOpen()
orSrmExtOpen()
, or a 4-character port name (such as 'u328', 'u650', or 'ircm'). See Port Constants. -
←
deviceInfoP
- Pointer to a
DeviceInfoType
structure where information about the device is returned.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNoDevicesAvail
- The Serial Manager cannot find any serial devices.
See Also
SrmGetStatus Function
Purpose
Returns status information about the serial hardware.
Declared In
SerialMgr.h
Prototype
status_t SrmGetStatus ( uint16_t portId, uint32_t *statusFieldP, uint16_t *lineErrsP )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
←
statusFieldP
- Pointer to address where hardware status information for the port is returned. This is a 32-bit field using the flags described in Status Constants.
-
←
lineErrsP
- Pointer to address where the number of line errors for the port is returned. The line error flags are described in Line Error Constants.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotSupported
- The port is a yielded port.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
Typically, SrmGetStatus()
is called to retrieve the line errors for the port if some of the send and receive functions return a serErrLineErr
error code.
SrmOpen Function
Purpose
Opens a foreground port connection with the specified port name or logical port number.
Declared In
SerialMgr.h
Prototype
status_t SrmOpen ( uint32_t port, uint32_t baud, uint16_t *newPortIdP )
Parameters
-
→
port
- The four-character port name or logical port number to be opened. See Port Constants for more information.
-
→
baud
- Initial baud rate of port.
-
←
newPortIdP
- Contains the port ID to be passed to other Serial Manager functions.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrAlreadyOpen
- This port already has an installed foreground owner.
-
serErrBadPort
- This port doesn't exist.
-
memErrNotEnoughSpace
- There was not enough memory available to open the port.
Comments
Only one application or task may have access to a particular serial port at any time.
Do not keep the port open any longer than necessary. An open serial port consumes more energy from the device's batteries.
SrmPrimeWakeupHandler Function
Purpose
Sets the number of received bytes that triggers a call to the wakeup handler function.
Declared In
SerialMgr.h
Prototype
status_t SrmPrimeWakeupHandler ( uint16_t portId, uint16_t minBytes )
Parameters
-
→
portId
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→
minBytes
- Number of bytes that must be received before wakeup handler is called. Typically, this is set to 1.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
This function primes a wakeup handler installed by SrmSetWakeupHandler()
.
See Also
SrmSetWakeupHandler()
, WakeupHandlerProcPtr()
SrmReceive Function
Purpose
Receives a specified number of bytes.
Declared In
SerialMgr.h
Prototype
uint32_t SrmReceive ( uint16_t portId, void *rcvBufP, uint32_t count, int32_t timeout, status_t *errP )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
←
rcvBufP
- Pointer to buffer where received data is to be returned.
-
→
count
- Length of data buffer (in bytes). This specifies the number of bytes to receive.
-
→
timeout
- The amount of time (in milliseconds) that the Serial Manager waits to receive the requested block of data. At the end of the timeout, data received up to that time is returned.
-
←
errP
- Error code.
Returns
Number of bytes of data actually received.
Comments
IMPORTANT: Note that in versions of Palm OS prior to 6.0, the timeout was specified in ticks. It is now specified in milliseconds.
The following error codes can be returned in errP
:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrTimeOut
- Unable to receive data within the specified timeout period.
-
serErrConfigurationFailed
- The port needs time to configure, and the configuration has failed.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrConfigurationFailed
- The port could not configure itself.
-
serErrLineErr
- A line error occurred during the receipt of data. Use
SrmGetStatus()
to obtain the exact line error. -
serErrNoDevicesAvail
- No serial devices could be found.
See Also
SrmReceiveCheck()
, SrmReceiveFlush()
, SrmReceiveWait()
SrmReceiveCheck Function
Purpose
Checks the receive FIFO and returns the number of bytes in the serial receive queue.
Declared In
SerialMgr.h
Prototype
status_t SrmReceiveCheck ( uint16_t portId, uint32_t *numBytesP )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
←
numBytesP
- Number of bytes in the receive queue.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrLineErr
- A line error has occurred. Use
SrmGetStatus()
to obtain the exact line error.
See Also
SrmReceive()
, SrmReceiveFlush()
, SrmReceiveWait()
SrmReceiveFlush Function
Purpose
Declared In
SerialMgr.h
Prototype
status_t SrmReceiveFlush ( uint16_t portId, int32_t timeout )
Parameters
-
→ portId
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→ timeout
- Timeout value, in milliseconds.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
IMPORTANT: Note that in versions of Palm OS prior to 6.0, the timeout was specified in ticks. It is now specified in milliseconds.
The timeout
value forces this function to wait a period of microseconds after flushing the port to see if more data shows up to be flushed. If more data arrives within the timeout period, the port is flushed again and the timeout counter is reset and waits again. The function only exits after no more bytes are received by the port for the full timeout period since the last flush of the port. To avoid this waiting behavior, specify 0 for the timeout period.
Any errors on the line are cleared before this function returns.
See Also
SrmReceive
, SrmReceiveCheck
, SrmReceiveWait
SrmReceiveWait Function
Purpose
Waits until some number of bytes of data have arrived into the serial receive queue, then returns.
Declared In
SerialMgr.h
Prototype
status_t SrmReceiveWait ( uint16_t portId, uint32_t bytes, int32_t timeout )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→
bytes
- Number of bytes to wait for.
-
→
timeout
- Timeout value, in microseconds.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrTimeOut
- Unable to receive data within the specified timeout period.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrBadParam
- The bytes parameter exceeds the size of the receive queue. Use
SrmSetReceiveBuffer()
to increase the size of the receive queue. -
serErrLineErr
- A line error occurred during the receipt of data. Use
SrmGetStatus()
to obtain the exact line error. -
serErrNoDevicesAvail
- No serial devices could be found.
Comments
IMPORTANT: Note that in versions of Palm OS prior to 6.0, the timeout was specified in ticks. It is now specified in milliseconds.
If this function returns no error, the application can either check the number of bytes currently in the receive queue (using SrmReceiveCheck()
) or it can just specify a buffer and receive the data by calling SrmReceive()
.
Do not call SerReceiveWait()
from within a wakeup handler. If you do, the serErrTimeOut
error is returned.
See Also
SrmReceive()
, SrmReceiveCheck()
, SrmReceiveFlush()
SrmReceiveWindowClose Function
Purpose
Closes direct access to the Serial Manager's receive queue.
Declared In
SerialMgr.h
Prototype
status_t SrmReceiveWindowClose ( uint16_t portId, uint32_t bytesPulled )
Parameters
-
→
portId
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→
bytesPulled
- Number of bytes the application read from the receive queue.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
Call this function when the application has read as many bytes as it needs out of the receive queue or it has read all the available bytes.
See Also
SrmReceiveWindowOpen Function
Purpose
Provides direct access to the Serial Manager's receive queue.
Declared In
SerialMgr.h
Prototype
status_t SrmReceiveWindowOpen ( uint16_t portId, UInt8 **bufPP, uint32_t *sizeP )
Parameters
-
→
portId
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
←
bufPP
- Pointer to a pointer to the receive buffer.
-
←
sizeP
- Available bytes in buffer.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrLineErr
- The data in the queue contains line errors.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
This function lets applications directly access the Serial Manager's receive queue to eliminate buffer copying by the Serial Manager. This access is a "back door" route to the received data. After retrieving data from the buffer, the application must call SrmReceiveWindowClose()
.
Applications that want to empty the receive buffer entirely should call the SrmReceiveWindowOpen()
and SrmReceiveWindowClose()
functions repeatedly until the buffer size returned is 0.
IMPORTANT: Once an application calls
SrmReceiveWindowOpen()
, it should not attempt to receive data via the normal method of calling SrmReceive()
or SrmReceiveWait()
, as these functions interfere with direct access to the receive queue.
See Also
SrmSend Function
Purpose
Sends a block of data out the specified port.
Declared In
SerialMgr.h
Prototype
uint32_t SrmSend ( uint16_t portId, const void *bufP, uint32_t count, status_t *errP )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→
bufp
- Pointer to data to send.
-
→
count
- Length of data buffer, in bytes.
-
←
errP
- Error code. See the Comments section for details.
Returns
Number of bytes of data actually sent.
Comments
When SrmSend()
returns, you should check the value returned in the errP
parameter. If errNone
, then the entire data buffer was sent. If not errNone
, then the result equals the number of bytes sent before the error occurred. The possible error values are:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrTimeOut
- Unable to send data within the specified CTS timeout period.
-
serErrNoDevicesAvail
- No serial devices could be found.
-
serErrConfigurationFailed
- The port configuration has failed.
-
serErrNotSupported
- The specified port is not the foreground port.
See Also
SrmSendCheck()
, SrmSendFlush()
, SrmSendWait()
SrmSendCheck Function
Purpose
Checks the transmit FIFO and returns the number of bytes left to be sent.
Declared In
SerialMgr.h
Prototype
status_t SrmSendCheck ( uint16_t portId, uint32_t *numBytesP )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
←
numBytesP
- Number of bytes left in the FIFO queue.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNotSupported
- This feature not supported by the hardware.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
Not all serial devices support this feature.
See Also
SrmSend()
, SrmSendFlush()
, SrmSendWait()
SrmSendFlush Function
Purpose
Declared In
SerialMgr.h
Prototype
status_t SrmSendFlush ( uint16_t portId )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrNoDevicesAvail
- No serial devices could be found.
See Also
SrmSend()
, SrmSendCheck()
, SrmSendWait()
SrmSendWait Function
Purpose
Waits until all previous data has been sent from the transmit FIFO, then returns.
Declared In
SerialMgr.h
Prototype
status_t SrmSendWait ( uint16_t portId )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrTimeOut
- Unable to send data within the CTS timeout period.
-
serErrNotSupported
- The port is not the foreground port.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
Consider calling this function if your software needs to detect when all data has been transmitted by SrmSend()
. The SrmSend()
function blocks until all data has been transmitted or a timeout occurs. A subsequent call to SrmSendWait()
blocks until all data queued up for transmission has been transmitted or until another CTS timeout occurs (if CTS handshaking is enabled).
See Also
SrmSend()
, SrmSendCheck()
, SrmSendFlush()
SrmSetReceiveBuffer Function
Purpose
Installs a new buffer into the Serial Manager's receive queue.
Declared In
SerialMgr.h
Prototype
status_t SrmSetReceiveBuffer ( uint16_t portId, void *bufP, uint16_t bufSize )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→
bufP
- Pointer to new receive buffer. Ignored if
bufSize
isNULL
. -
→
bufSize
- Size of new receive buffer in bytes. To remove this buffer and allocate a new default buffer (512 bytes), specify 0.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- This port is not open.
-
memErrNotEnoughSpace
- Not enough memory to allocate default buffer.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
The buffer that you pass to this function must remain allocated while you have the serial port open. Before you close the serial port, you must restore the default queue by calling SrmSetReceiveBuffer()
with NULL
as the bufP
and 0 as the bufSize
parameter.
IMPORTANT: Applications must install the default buffer before closing the port (or disposing of the new receive queue).
SrmSetWakeupHandler Function
Purpose
Declared In
SerialMgr.h
Prototype
status_t SrmSetWakeupHandler ( uint16_t portId, WakeupHandlerProcPtr procP, uint32_t refCon )
Parameters
-
→
portID
- Port ID returned from
SrmOpen()
orSrmExtOpen()
. -
→
procP
- Pointer to a
WakeupHandlerProcPtr()
function. SpecifyNULL
to remove a handler. -
→
refCon
- User-defined data that is passed to the wakeup handler function. This can any 32-bit value, including a pointer.
Returns
This function returns the following error codes:
-
errNone
- No error.
-
serErrBadPort
- This port doesn't exist.
-
serErrNotOpen
- The port is not open.
-
serErrNoDevicesAvail
- No serial devices could be found.
Comments
The wakeup handler is a function in your application that you want to be called whenever there is data ready to be received on the specified port.
The wakeup handler function will not become active until it is primed with a number of bytes that is greater than 0, by the SrmPrimeWakeupHandler()
function. Every time a wakeup handler is called, it must be re-primed (using SrmPrimeWakeupHandler()
) in order to be called again.
See Also
SrmPrimeWakeupHandler()
, WakeupHandlerProcPtr()
Serial Manager Application-Defined Functions
WakeupHandlerProcPtr Function
Purpose
Called after some number of bytes are received by the Serial Manager's interrupt function.
Declared In
SerialMgr.h
Prototype
void ( *WakeupHandlerProcPtr )( uint32_t refCon )
Parameters
-
→
refCon
- User-defined data passed from the
SrmSetWakeupHandler()
function.
Returns
Comments
This handler function is installed by calling SrmSetWakeupHandler()
. The number of bytes after which it is called is specified by SrmPrimeWakeupHandler()
.
Under Palm OS Cobalt, the wakeup handler is called from a thread in the application's process. Because of this, it's possible that the handler can be called while the application is already calling a Serial Manager function.
If your application manages synchronization between the wakeup handler and its main thread, it can call Serial Manager functions within the wakeup handler. However, if your needs are complex, or you want to maximize performance, you may benefit from using the IOS API instead of the Serial Manager.
Two common implementations of wakeup handlers include:
- Calling
EvtWakeup()
, which causes any pendingEvtGetEvent
call to return and then sends anilEvent
to the current application. - Using
SrmReceiveWindowOpen()
andSrmReceiveWindowClose()
to gain direct access to the receive queue without blocking.
See Also
SrmPrimeWakeupHandler()
, SrmSetWakeupHandler()