Palm OS SDK Reference

56 New Serial Manager

This chapter provides reference material for the new serial manager API: New Serial Manager Data Structures New Serial Manager Constants New Serial Manager Functions New Serial Manager Application-Defined Function
The header file SerialMgr.h declares the serial manager API. For more information on the new serial manager, see the chapter "Serial Communication" in the Palm OS Programmer's Companion.

New Serial Manager Data Structures

DeviceInfoType

The DeviceInfoType structure defines information about a serial device. This structure is returned by the SrmGetDeviceInfo function.

typedef struct DeviceInfoType {
UInt32 serDevCreator;
UInt32 serDevFtrInfo;
UInt32 serDevMaxBaudRate;
UInt32 serDevHandshakeBaud;
Char *serDevPortInfoStr;
UInt8 reserved[8]; // Reserved
} DeviceInfoType;
typedef DeviceInfoType *DeviceInfoPtr;

Value Descriptions


`serDevCreator`	Four-character creator type for serial driver ('sdrv').
`serDevFtrInfo`	Flags defining features of this serial hardware. Specify one of the flags described in Serial Capabilities Constants.
`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.

SrmCtlEnum

The SrmCtlEnum enumerated type specifies a serial control operation. Specify one of these enumerated types for the op parameter to the SrmControl call.

typedef enum SrmCtlEnum {
srmCtlFirstReserved = 0, // RESERVE 0
srmCtlSetBaudRate,
srmCtlGetBaudRate,
srmCtlSetFlags,
srmCtlGetFlags,
srmCtlSetCtsTimeout,
srmCtlGetCtsTimeout,
srmCtlStartBreak,
srmCtlStopBreak,
srmCtlStartLocalLoopback,
srmCtlStopLocalLoopback,
srmCtlIrDAEnable,
srmCtlIrDADisable,
srmCtlRxEnable,
srmCtlRxDisable,
srmCtlEmuSetBlockingHook,
srmCtlUserDef,
srmCtlGetOptimalTransmitSize,
srmCtlLAST
} SrmCtlEnum;

Value Descriptions


`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.
`srmCtlStartBreak`	Turn RS232 break signal on. Caller is responsible for turning this signal on and off and insuring it is on long enough to generate a viable break.
`srmCtlStopBreak`	Turn RS232 break signal off.
`srmCtlStartLocalLoopback`	Start local loopback test.
`srmCtlStopLocalLoopback`	Stop local loopback test.
`srmCtlIrDAEnable`	Enable IrDA connection on this serial port.
`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 Palm device.
`srmCtlUserDef`	This is a user-defined function that 3rd party hardware developers can use to set or retrieve hardware-specific information from the serial driver. This opCode invokes the SdrvControl (or VdrvControl) function with its user-defined opCode and the parameters are passed directly through to the serial driver. A serial driver that does not handle this function returns a `serErrBadParam` error.
`srmCtlGetOptimalTransmitSize`	Ask the port for the most efficient buffer size for transmitting data packets. This opCode returns an error (buffering not necessary), 0 (buffering requested, but application can choose buffer size), or a number > 0 (recommended buffer size).

SrmCallbackEntryType

The SrmCallbackEntryType structure defines a callback function for the SrmControl function's srmCtlEmuSetBlockingHook opCode.

typedef struct SrmCallbackEntryType {
BlockingHookProcPtr funcP;
UInt32 userRef; // ref value to pass to callback
} SrmCallbackEntryType;

Value Descriptions


`funcP`	Function pointer to the callback function. Pass `NULL` if you no longer want a callback function to be called.
`userRef`	User-defined reference value passed to the callback function.

New Serial Manager Constants

Serial Capabilities Constants

These constants describe serial hardware capabilities. serDevCradlePort Serial hardware controls RS-232 serial from cradle connector of Palm device. serDevRS232Serial Serial hardware has RS-232 line drivers serDevIRDACapable Serial hardware has IR line drivers and generates IrDA mode serial signals serDevModemPort Serial hardware drives modem connection serDevCncMgrVisible Serial device port name string is to be displayed in the Connection panel.

`serDevCradlePort`	Serial hardware controls RS-232 serial from cradle connector of Palm device.
`serDevRS232Serial`	Serial hardware has RS-232 line drivers
`serDevIRDACapable`	Serial hardware has IR line drivers and generates IrDA mode serial signals
`serDevModemPort`	Serial hardware drives modem connection
`serDevCncMgrVisible`	Serial device port name string is to be displayed in the Connection panel.

Serial Settings Constants

These constants identify bit flags that correspond to various serial hardware settings. srmSettingsFlagStopBitsM mask for stop bits field srmSettingsFlagStopBits1 1 stop bit 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 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 srmSettingsFlagFlowControl Protect the receive buffer from software overruns. When this flag, and srmSettingsFlagRTSAutoM are set, it causes the new 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 deasserted 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.

`srmSettingsFlagStopBitsM`	mask for stop bits field
`srmSettingsFlagStopBits1`	1 stop bit
`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
`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
`srmSettingsFlagFlowControl`	Protect the receive buffer from software overruns. When this flag, and `srmSettingsFlagRTSAutoM` are set, it causes the new 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 deasserted 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.

Status Constants

These constants identify bit flags that correspond to the status of serial signals. They can be returned by the SrmGetStatus function. srmStatusCtsOn CTS line is active. srmStatusRtsOn RTS line is active. srmStatusDsrOn DSR line is active. srmStatusBreakSigOn Break signal is active.

`srmStatusCtsOn`	CTS line is active.
`srmStatusRtsOn`	RTS line is active.
`srmStatusDsrOn`	DSR line is active.
`srmStatusBreakSigOn`	Break signal is active.

New Serial Manager Functions

SrmClearErr

Purpose

Clears the port of any line errors.

Prototype

Err SrmClearErr(UInt16 portId)

Parameters

-> portID Port ID.

Result


0	No error.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmClose

Purpose

Closes a serial port and makes it available to other applications, regardless of whether the port is a foreground or background port.

Prototype

Err SrmClose(UInt16 portID)

Parameters

-> portID Port ID for port to be closed.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

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 (via SrmOpen).

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmControl

Purpose

Performs a serial control function.

Prototype

Err SrmControl(UInt16 portId, UInt16 op, void *valueP, UInt16 *valueLenP)

Parameters

-> portID Port ID.

-> 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.

Comments

Table 56.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.

Table 56.1 SrmControl Parameters

Operation Code Parameters

srmCtlSetBaudRate -> valueP = Pointer to Int32 (baud rate) -> valueLenP = Pointer to sizeof(Int32)

srmCtlGetBaud <- valueP = Pointer to Int32 (baud rate) <- valueLenP = Pointer to Int16

srmCtlSetFlags -> valueP = Pointer to Uint32 (bitfield; see Serial Settings Constants) -> valueLenP = Pointer to sizeof(UInt32)

srmCtlGetFlags <- valueP = Pointer to UInt32 (bitfield) <- valueLenP = Pointer to Int16

srmCtlSetCtsTimeout -> valueP = Pointer to Int32 (timeout value) -> valueLenP = Pointer to sizeof(Int32)

srmCtlGetCtsTimeout <- valueP = Pointer to Int32 (timeout value) <- valueLenP = Pointer to Int16

srmCtlEmuSetBlockingHook <-> valueP = Pointer to SrmCallbackEntryType struct <-> valueLenP = Pointer to sizeof(SrmCallbackEntryType) Returns the old settings in the first parameter.

srmCtlUserDef <-> valueP = Pointer passed to the serial or virtual driver <-> valueLenP = Pointer to sizeof(Int32) For a serial driver, these pointers are passed to the SdrvControl function's sdrvOpCodeUserDef opCode. For a virtual driver, these pointers are passed to the VdrvControl function's vdrvOpCodeUserDef opCode.

srmCtlGetOptimalTransmitSize <- valueP = Pointer to Int32 <- valueLenP = Pointer to sizeof(Int32) If an error is returned by SrmControl, no buffering should be done. If valueP points to zero, buffering is requested, but the transmitting application can determine the buffer size. If valueP points to a number > 0, then try to send data in blocks of this number of bytes, as this is the most efficient block size for this particular device.

**Table 56.1 SrmControl Parameters**
Operation Code	Parameters
`srmCtlSetBaudRate`	-> `valueP` = Pointer to `Int32` (baud rate) -> `valueLenP` = Pointer to `sizeof(Int32)`
`srmCtlGetBaud`	<- `valueP` = Pointer to `Int32` (baud rate) <- `valueLenP` = Pointer to `Int16`
`srmCtlSetFlags`	-> `valueP` = Pointer to `Uint32` (bitfield; see Serial Settings Constants) -> `valueLenP` = Pointer to `sizeof(UInt32)`
`srmCtlGetFlags`	<- `valueP` = Pointer to `UInt32` (bitfield) <- `valueLenP` = Pointer to `Int16`
`srmCtlSetCtsTimeout`	-> `valueP` = Pointer to `Int32` (timeout value) -> `valueLenP` = Pointer to `sizeof(Int32)`
`srmCtlGetCtsTimeout`	<- `valueP` = Pointer to `Int32` (timeout value) <- `valueLenP` = Pointer to `Int16`
`srmCtlEmuSetBlockingHook`	<-> `valueP` = Pointer to SrmCallbackEntryType struct <-> `valueLenP` = Pointer to `sizeof(SrmCallbackEntryType)` Returns the old settings in the first parameter.
`srmCtlUserDef`	<-> `valueP` = Pointer passed to the serial or virtual driver <-> `valueLenP` = Pointer to `sizeof(Int32)` For a serial driver, these pointers are passed to the SdrvControl function's `sdrvOpCodeUserDef` opCode. For a virtual driver, these pointers are passed to the VdrvControl function's `vdrvOpCodeUserDef` opCode.
`srmCtlGetOptimalTransmitSize`	<- `valueP` = Pointer to Int32 <- `valueLenP` = Pointer to `sizeof(Int32)` If an error is returned by `SrmControl`, no buffering should be done. If `valueP` points to zero, buffering is requested, but the transmitting application can determine the buffer size. If `valueP` points to a number > 0, then try to send data in blocks of this number of bytes, as this is the most efficient block size for this particular device.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmGetDeviceCount

Purpose

Returns the number of available serial devices.

Prototype

Err SrmGetDeviceCount(UInt16* numOfDevicesP)

Parameters

<- numOfDevicesP Pointer to address where the number of serial devices is returned.

Result


0	No error.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmGetDeviceInfo

Purpose

Returns information about a serial device.

Prototype

Err SrmGetDeviceInfo(UInt32 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, or a 4-character port name (such as 'u328', 'u650', or 'ircm').

<- deviceInfoP Pointer to a DeviceInfoType structure where information about the device is returned.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmGetStatus

Purpose

Returns status information about the serial hardware.

Prototype

Err SrmGetStatus(UInt16 portId, UInt32* statusFieldP), UInt16* lineErrsP)

Parameters

-> portId Port ID.

<- 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.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

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.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmOpen

Purpose

Opens a foreground port connection with the specified port name or logical port number.

Prototype

Err SrmOpen(UInt32 port, UInt32 baud, UInt16* newPortIdP)

Parameters

-> port Port name or logical port number to be opened. For information about how to identify a port, see "Specifying the portID Parameter" in the Palm OS Programmer's Companion.

-> baud Initial baud rate of port.

<- newPortIdP Pointer to address where the port ID to be used with other new serial manager functions is returned.

Result


0	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.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmOpenBackground

Purpose

Allows a task to open, initialize, and use the port, but always relinquishes control of the port when another task opens the port with the SrmOpen call.

Prototype

Err SrmOpenBackground(UInt32 port, UInt32 baud, UInt16* newPortIdP)

Parameters

-> port Physical or logical port number to be opened.

-> baud Initial baud rate of port.

<- newPortIdP Pointer to address where the port ID to be used with other new serial manager functions is returned.

Result


0	No error.
`serErrAlreadyOpen`	This port already has an installed background owner.
`serErrBadPort`	This port doesn't exist.
`memErrNotEnoughSpace`	There was not enough memory available to open the port.

Comments

This function is provided to support tasks that want to use a serial device to receive data only when no other task is using the port.
If a background port is forced to surrender control of the hardware as a result of another task opening a foreground connection, all buffers for the background port are flushed. After this active task closes the port, active control of the port is returned to the background task. Only one task can have background ownership of the port.
Note that background ports have limited functionality: they can only receive data and notify owning clients of what data has been received.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmPrimeWakeupHandler

Purpose

Sets the number of received bytes that triggers a call to the wakeup handler function.

Prototype

Err SrmPrimeWakeupHandler(UInt16 portId, UInt16 minBytes)

Parameters

-> portId Port ID.

-> minBytes Number of bytes that must be received before wakeup handler is called. Typically, this is set to 1.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

Comments

This function primes a wakeup handler installed by SrmSetWakeupHandler.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmReceive

Purpose

Receives a specified number of bytes.

Prototype

UInt32 SrmReceive(UInt16 portId, void *rcvBufP, UInt32 count, Int32 timeout, Err* errP)

Parameters

-> PortId Port ID.

<- 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 ticks) that the new 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.

Result

Number of bytes of data actually received.

Comments

The following error codes can be returned in *errP: 0 No error. serErrBadPort This port doesn't exist. serErrTimeoutErr Unable to receive data within the specified ctsTimeout period.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmReceiveCheck

Purpose

Checks the receive FIFO and returns the number of bytes in the serial receive queue.

Prototype

Err SrmReceiveCheck(UInt16 portId, UInt32* numBytesP)

Parameters

-> portId Port ID.

<- numBytesP Number of bytes in the receive queue.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmReceiveFlush

Purpose

Flushes the receive FIFOs.

Prototype

Err SrmReceiveFlush(UInt16 portId, Int32 timeout)

Parameters

-> portId Port ID.

-> timeout Timeout value, in ticks.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

Comments

The timeout value forces this function to wait a period of ticks 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.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmReceiveWait

Purpose

Waits until some number of bytes of data have arrived into the serial receive queue, then returns.

Prototype

Err SrmReceiveWait(UInt16 portId, UInt32 bytes, Int32 timeout)

Parameters

-> portId Port ID.

-> bytes Number of bytes to wait for.

-> timeout Timeout value, in ticks.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.
`serErrTimeoutErr`	Unable to receive data within the specified `timeout` period.

Comments

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.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmReceiveWindowClose

Purpose

Closes direct access to the new serial manager's receive queue.

Prototype

Err SrmReceiveWindowClose(UInt16 portId, UInt32 bytesPulled)

Parameters

-> portId Port ID.

-> bytesPulled Number of bytes the application read from the receive queue.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

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.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmReceiveWindowOpen

Purpose

Provides direct access to the new serial manager's receive queue.

Prototype

Err SrmReceiveWindowOpen(UInt16 portId, UInt8 **bufPP, UInt32* sizeP)

Parameters

-> portId Port ID.

<- bufPP Pointer to a pointer to the receive buffer.

<- sizeP Available bytes in buffer.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.
`serErrLineErr`	The data in the queue contains line errors.

Comments

This function lets applications directly access the new 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.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmSend

Purpose

Sends a block of data out the specified port.

Prototype

UInt32 SrmSend(UInt16 portId, void *bufP, UInt32 count, Err* errP)

Parameters

-> portId Port ID.

-> bufp Pointer to data to send.

-> count Length of data buffer, in bytes.

<- errP Error code. See Comments section for details.

Result

Number of bytes of data actually sent.

Comments

If *errP is NULL, the result value should be the same as the count parameter. If *errP is not NULL, then the result equals the number of bytes sent before the error occurred.
The following error codes can be returned in *errP: 0 No error. serErrBadPort This port doesn't exist. serErrTimeoutErr Unable to send data within the specified ctsTimeout period.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmSendCheck

Purpose

Checks the transmit FIFO and returns the number of bytes left to be sent.

Prototype

Err SrmSendCheck(UInt16 portId, UInt32* numBytesP)

Parameters

-> portID Port ID.

<- numBytesP Number of bytes left in the FIFO queue.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.
`serErrNotSupported`	This feature not supported by the hardware.

Comments

Not all serial devices support this feature.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmSendFlush

Purpose

Flushes the transmit FIFO.

Prototype

Err SrmSendFlush(UInt16 portId)

Parameters

-> portId Port ID.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmSendWait

Purpose

Waits until all previous data has been sent from the transmit FIFO, then returns.

Prototype

Err SrmSendWait(UInt16 portId)

Parameters

-> portId Port ID.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.
`serErrTimeoutErr`	Unable to send data within the `ctsTimeout` period.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmSetReceiveBuffer

Purpose

Installs a new buffer into the new serial manager's receive queue.

Prototype

Err SrmSetReceiveBuffer(UInt16 portId, void *bufP, UInt16 bufSize)

Parameters

-> portId Port ID.

-> bufP Pointer to new receive buffer. Ignored if bufSize is NULL.

-> bufSize Size of new receive buffer in bytes. To remove this buffer and allocate a new default buffer (512 bytes), specify NULL.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.
`memErrNotEnoughSpace`	Not enough memory to allocate default buffer.

Comments

IMPORTANT: Applications must install the default buffer before closing the port (or disposing of the new receive queue.)

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SrmSetWakeupHandler

Purpose

Installs a wakeup handler.

Prototype

Err SrmSetWakeupHandler(UInt16 portId, WakeupHandlerProcPtr procP, UInt32 refCon)

Parameters

-> portId Port ID.

-> procP Pointer to a WakeupHandlerProc function. Specify NULL to remove a handler.

-> refCon User-defined data that is passed to the wakeup handler function. This can be a pointer or not.

Result


0	No error.
`serErrBadPort`	This port doesn't exist.

Comments

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 reprimed (via SrmPrimeWakeupHandler) in order to be called again.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

New Serial Manager Application-Defined Function

WakeupHandlerProc

Purpose

Called after some number of bytes are received by the new serial manager's interrupt function.

Prototype

void WakeupHandlerProcPtr(UInt32 refCon)

Parameters

->refCon User-defined data passed from the SrmSetWakeupHandler function.

Result

Returns nothing.

Comments

This handler function is installed by calling SrmSetWakeupHandler. The number of bytes after which it is called is specified by SrmPrimeWakeupHandler.
Because wakeup handlers are called during interrupt time, they cannot call ANY Palm OS^® system functions that may block the system in any way. Wakeup handlers should also be very short so as to reduce interrupt latency.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

56 New Serial Manager

New Serial Manager Data Structures

DeviceInfoType

Value Descriptions

SrmCtlEnum

Value Descriptions

SrmCallbackEntryType

Value Descriptions

New Serial Manager Constants

Serial Capabilities Constants

Serial Settings Constants

Status Constants

New Serial Manager Functions

SrmClearErr

Purpose

Prototype

Parameters

Result

Compatibility

SrmClose

Purpose

Prototype

Parameters

Result

Comments

Compatibility

See Also

SrmControl

Purpose

Prototype

Parameters

Comments

Table 56.1 SrmControl Parameters

Compatibility

SrmGetDeviceCount

Purpose

Prototype

Parameters

Result

Compatibility

See Also

SrmGetDeviceInfo

Purpose

Prototype

Parameters

Result

Compatibility

See Also

SrmGetStatus

Purpose

Prototype

Parameters

Result

Comments

Compatibility

SrmOpen

Purpose

Prototype

Parameters

Result

Comments

Compatibility

See Also

SrmOpenBackground

Purpose

Prototype

Parameters

Result

Comments

Compatibility

See Also

SrmPrimeWakeupHandler

Purpose

Prototype

Parameters

Result

Comments

Compatibility

See Also

SrmReceive