Serial Manager
 

 < Home   < Developers   < Development Support   < Documentation

66 Serial Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part III: Communications

66 Serial Manager

Serial Manager Data Structures

DeviceInfoType

SrmCtlEnum

SrmOpenConfigType

Serial Manager Constants

Port Constants

Serial Capabilities Constants

Serial Settings Constants

Status Constants

Line Error Constants

Serial Manager Functions

SrmClearErr

SrmClose

SrmControl

SrmCustomControl

SrmExtOpen

SrmExtOpenBackground

SrmGetDeviceCount

SrmGetDeviceInfo

SrmGetStatus

SrmOpen

SrmOpenBackground

SrmPrimeWakeupHandler

SrmReceive

SrmReceiveCheck

SrmReceiveFlush

SrmReceiveWait

SrmReceiveWindowClose

SrmReceiveWindowOpen

SrmSend

SrmSendCheck

SrmSendFlush

SrmSendWait

SrmSetReceiveBuffer

SrmSetWakeupHandler

Serial Manager Application-Defined Functions

WakeupHandlerProcPtr

       

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. For more information on the Serial Manager, see the chapter "Serial Communication" of the Palm OS Programmer's Companion, vol. II, Communications.

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]; 
} DeviceInfoType; 
typedef DeviceInfoType *DeviceInfoPtr; 

Value Descriptions

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.

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, 
  srmCtlSetBaudRate,  
  srmCtlGetBaudRate,  
  srmCtlSetFlags,  
  srmCtlGetFlags,  
  srmCtlSetCtsTimeout,  
  srmCtlGetCtsTimeout,  
  srmCtlStartBreak,  
  srmCtlStopBreak,  
  srmCtlStartLocalLoopback,  
  srmCtlStopLocalLoopback,  
  srmCtlIrDAEnable,  
  srmCtlIrDADisable,  
  srmCtlRxEnable,  
  srmCtlRxDisable,  
  srmCtlEmuSetBlockingHook,  
  srmCtlUserDef,  
  srmCtlGetOptimalTransmitSize,  
  srmCtlSetDTRAsserted, 
  srmCtlGetDTRAsserted, 
  srmCtlSetYieldPortCallback, 
  srmCtlSetYieldPortRefCon, 
  srmCtlSystemReserved = 0x7000 
  srmCtlCustom = 0x8000, 
  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 RS-232 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 RS-232 break signal off.
srmCtlStartLocalLoopback
Start local loopback test.
srmCtlStopLocalLoopback
Stop local loopback test.
srmCtlIrDAEnable
Enable IrDA connection on this serial port.

NOTE: You cannot enable an IrDA connection on a VZ processor.
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.
srmCtlUserDef
This is a user-defined function that third-party hardware developers can use to set or retrieve hardware-specific information from the serial driver. This op code invokes the driver's corresponding control function with its user-defined op code and the parameters are passed directly through to the serial driver. A serial driver that does not handle this function returns a serErrBadParam error.

The srmCtlUserDef op code is superseded by defining a custom op code if New Serial Manager Feature Set Version 2 is present.
srmCtlGetOptimalTransmitSize
Ask the port for the most efficient buffer size for transmitting data packets. This op code returns an error (buffering not necessary), 0 (buffering requested, but application can choose buffer size), or a number greater than 0 (recommended buffer size).
srmCtlSetDTRAsserted
Enabled or disable the DTR signal. This is not supported by all hardware.
srmCtlGetDTRAsserted
Ask the port whether the DTR signal is enabled or disabled.
srmCtlSetYieldPortCallback
Set the function to be called if the Serial Manager attempts to open another port when this one is open. This op code is for system use only.
srmCtlSetYieldPortRefCon
Data to pass to the yield port callback function. System use only.
srmCtlSystemReserved
Reserves op codes between 0x7000 and 0x8000 for system use.
srmCtlCustom
Reserves op codes greater than 0x8000 for driver-specific use.

Compatibility

Custom control op codes are only supported if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present.

New SrmOpenConfigType

The SrmOpenConfigType structure specifies parameters for opening a serial port. This structure is passed as a parameter to SrmExtOpen.

typedef struct SrmOpenConfigType { 
  UInt32 baud; 
  UInt32 function; 
  MemPtr drvrDataP; 
  UInt16 drvrDataSize; 
  UInt32 sysReserved1; 
  UInt32 sysReserved2;  
} SrmOpenConfigType; 

Field Descriptions

baud
Baud rate at which to open the connection. Serial drivers that do not require baud rates ignore this field.
function
The reason why the port was opened. Specify the creator ID of the application that is opening the port or one of the following values:
serFncUndefined Undefined function. This is the default value for this field.
serFncPPPSessionThe connection is to be used for the PPP interface.
serFncSLIPSessionThe connection is to be used for the SLIP session.
serFncDebuggerThe connection is to be used for a debugging session.
serFncHotSyncThe connection is to be used for a HotSync operation.
serFncConsole The connection is to the debugging console.
serFncTelephony The connection is to the telephony library.

The function field is used by protocols such as USB and Bluetooth that perform different setup tasks based on which type of application is using them. RS-232 drivers ignore this parameter.
drvrDataP
Pointer to a driver-specific data block.
drvrDataSize
The size of the data block pointed to by drvrDataP.
sysReserved1
Reserved for future use.
sysReserved2
Reserved for future use.

Compatibility

This structure is only defined if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present.

Serial Manager Constants

Port Constants

When you specify the port to open in the SrmOpen, SrmOpenBackground, SrmExtOpen, or SrmExtOpenBackground call, you can use either a logical port constant, physical port constant, or a virtual port constant, but it is highly recommended that you use a logical port constant wherever possible.

Logical Serial Port Constants

These constants specify the logical port names.

Constant
Value
Description
serPortLocalHotSync
0x8000
The physical HotSync port. The Serial Manager automatically detects whether this port is USB or RS-232.
serPortCradlePort
0x8000
Cradle port. The Serial Manager automatically detects whether this port is USB or RS-232. Most applications should specify this as the port.
serPortIrPort
0x8001
The IR port. This is a raw IrDA port with no protocol support.
serPortConsolePort
0x8002
The debug console port, either USB or RS-232. USB is preferred where both are available.
serPortCradleRS232Port
0x8003
Port for the RS-232 cradle. Specify this port if you want to ensure that your application uses RS-232 communications only.
serPortCradleUSBPort
0x8004
Port for the USB cradle. Specify this port if you want to ensure that your application uses USB communications only.

Compatibility

USB ports are only supported if New Serial Manager Feature Set Version 2 is present.

Physical Serial Port Constants

The physical port constants specify 4-character constants that reference the physical hardware of the device. Doing so is not recommended because the hardware they reference may not exist on a particular device.

Physical port
Value
Description
sysFileCUart328
'u328'
Cradle port using the 68328 UART. This port can be switched between RS232 and IrDA mode using the SrmControl call.
sysFileCUart328EZ
'u8EZ'
Cradle port using the 68328EZ UART. This port can also be switched between RS232 and IrDA mode.
sysFileCUart650
'u650'

Specifies the IR port on the upgrade card for Palm Personal or Palm Professional devices. This gives you a raw IR port like calling SrmControl does, but it only exists on devices that have the upgrade card.

Virtual Serial Port Constants

The virtual port constants specify 4-character constants that identify virtual ports, simulating a hardware interface. Virtual ports are not tied to specific hardware.

Physical port
Value
Description
sysFileCVirtIrComm
'ircm'
A virtual serial cable over an IrDA link using the IRComm protocol. It can only be used to talk to another IRComm device.
sysFileCVirtRfComm
'rfcm'
RFCOMM (Bluetooth) virtual port plug-in.
sysFileCBtConnectPanelHelper
'btcp'
Bluetooth Connection Panel helper application.

Compatibility

All virtual port constants other than sysFileCVirtIrComm are only defined if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present.

Serial Capabilities Constants

The serial capabilities constant flags describe serial hardware capabilities. These flags are set in the serDevFtrInfo field of the DeviceInfoType structure.

Constant
Value
Description
serDevCradlePort
0x00000001
Serial hardware controls RS-232 serial from cradle connector of Palm device.
serDevRS232Serial
0x00000002
Serial hardware has RS-232 line drivers.
serDevIRDACapable
0x00000004
Serial hardware has IR line drivers and generates IrDA mode serial signals.
serDevModemPort
0x00000008
Serial hardware drives modem connection.
serDevCncMgrVisible
0x00000010
Serial device port name string is to be displayed in the Connection panel.
serDevConsolePort
0x00000020
Serial device is the default console port.
serDevUSBCapable
0x00000040
Serial hardware controls USB serial from cradle connector of Palm device.

Compatibility

USB ports are only supported if New Serial Manager Feature Set Version 2 is present.

Serial Settings Constants

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.

Constant
Value
Description
srmSettingsFlagStopBitsM
0x00000001
Mask for stop bits field
srmSettingsFlagStopBits1
0x00000000
1 stop bit (default)
srmSettingsFlagStopBits2
0x00000001
2 stop bits
srmSettingsFlagParityOnM
0x00000002
Mask for parity on
srmSettingsFlagParityEvenM
0x00000004
Mask for parity even
srmSettingsFlagXonXoffM
0x00000008
Mask for Xon/Xoff flow control (not implemented)
srmSettingsFlagRTSAutoM
0x00000010
Mask for RTS receive flow control. This is the default.
srmSettingsFlagCTSAutoM
0x00000020
Mask for CTS transmit flow control
srmSettingsFlagBitsPerCharM
0x000000C0
Mask for bits per character
srmSettingsFlagBitsPerChar5
0x00000000
5 bits per character
srmSettingsFlagBitsPerChar6
0x00000040
6 bits per character
srmSettingsFlagBitsPerChar7
0x00000080
7 bits per character
srmSettingsFlagBitsPerChar8
0x000000C0
8 bits per character (default)
srmSettingsFlagFlowControlIn
0x00000100
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.
srmSettingsFlagRTSInactive
0x00000200
If this flag is set and srmSettingsFlagRTSAutoM is not set, RTS is held in the inactive (flow off) state forever.

Status Constants

The status constants identify bit flags that correspond to the status of serial signals. They can be returned by the SrmGetStatus function.

Constant
Value
Description
srmStatusCtsOn
0x00000001
CTS line is active.
srmStatusRtsOn
0x00000002
RTS line is active.
srmStatusDsrOn
0x00000004
DSR line is active.
srmStatusBreakSigOn
0x00000008
Break signal is active.

Line Error Constants

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.

Constant
Value
Description
serLineErrorParity
0x0001
Parity error
serLineErrorHWOverrun
0x0002
Hardware overrun
serLineErrorFraming
0x0004
Framing error
serLineErrorBreak
0x0008
Break signal asserted
serLineErrorHShake
0x0010
Line handshake error
serLineErrorSWOverrun
0x0020
Software overrun
serLineErrorCarrierLost
0x0040
Carrier detect signal dropped

Serial Manager Functions

SrmClearErr

Purpose

Clears the port of any line errors.

Prototype

Err SrmClearErr (UInt16 portId)

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.

Result

This function returns the following error codes:

errNoneNo error.
serErrNotSupportedThe port is not the foreground port.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 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

-> portIdPort ID for port to be closed.

Result

This function returns the following error codes:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe serial port is not open.
serErrNoDevicesAvailNo 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.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmOpen, SrmOpenBackground

SrmControl

Purpose

Performs a serial control function.

Prototype

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

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
-> opControl operation to perform. Specify one of the SrmCtlEnum enumerated types.
<-> valuePPointer to a value to use for the operation. See Comments for details.
<-> valueLenPPointer to the size of *valueP. See Comments for details.

Result

This function returns the following error codes:

errNone No error.
serErrBadParamAn invalid op code was specified.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe serial port is not open.
serErrNoDevicesAvailNo serial devices could be found.
serErrNotSupportedThe specified op code is not supported in the current configuration.

Comments

Table 66.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 66.1 SrmControl Parameters 
Operation Code
Parameters
srmCtlSetBaudRate
-> valueP = Pointer to Int32 (baud rate)
-> valueLenP = Pointer to sizeof(Int32)
srmCtlGetBaudRate
<- 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
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 driver's control function and they contain that functions return values (if any) upon return.
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 cannot 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.
srmCtlSetDTRAsserted
-> valueP = Pointer to Boolean indicating whether to enable or disable DTR.
-> valueLenP = Pointer to sizeof(Boolean)
srmCtlGetDTRAsserted
<- valueP = Pointer to Boolean indicating whether DTR is enabled.
<- valueLenP = Pointer to Int16

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmCustomControl

New SrmCustomControl

Purpose

Performs a custom serial control function.

Prototype

Err SrmCustomControl (UInt16 portId, UInt16 opCode, UInt32 creator, void *valueP, UInt16 *valueLenP)

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
-> opCodeControl operation to perform. The op code must be greater than srmCtlCustom.
-> creatorCreator ID of the driver that defines the op code. The combination of creator ID and op code uniquely identifies the operation to be performed.
<-> valuePPointer to a value to use for the operation.
<-> valueLenPPointer to the size of *valueP.

Result

This function returns the following error codes:

errNone No error.
serErrNotSupportedThe port is not the foreground port.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe serial port is not open.
serErrNoDevicesAvailNo serial devices could be found.

Comments

This function is a mechanism for a virtual driver to create control codes specific to that driver, allowing for the support of new technologies that have interfaces through the Serial Manager.

This function simply forwards the opCode and any valueP parameter to the virtual driver for the port. The virtual driver may return its own error code if the opCode or the input in valueP is invalid.

Compatibility

Implemented only if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present.

See Also

SrmControl

New SrmExtOpen

Purpose

Opens a foreground port connection with the specified configuration.

Prototype

Err SrmExtOpen (UInt32 port, SrmOpenConfigType *configP, UInt16 configSize, UInt16 *newPortIdP)

Parameters

-> portThe four-character port name (such as 'ircm' or 'u328') or logical port number to be opened. (See Port Constants.)
-> configPPointer to the configuration structure specifying the serial port's properties. See SrmOpenConfigType.
-> configSizeThe size of the configuration structure pointed to by configP.
<- newPortIdPContains the port ID to be passed to other Serial Manager functions.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThe port parameter does not specify a valid port.
serErrBadParamThe configP parameter is NULL.
serErrAlreadyOpenThe Serial Manager already has a port open.
memErrNotEnoughSpaceThere 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.

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.

Compatibility

Implemented only if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present. The SrmExtOpen function replaces the SrmOpen function.

See Also

SrmOpen, SrmExtOpenBackground

New SrmExtOpenBackground

Purpose

Opens a port with the specified configuration in the background. Background ports relinquish control when another task opens the port with the SrmOpen or SrmExtOpen call.

Prototype

Err SrmExtOpenBackground (UInt32 port, SrmOpenConfigType *configP, UInt16 configSize, UInt16 *newPortIdP)

Parameters

-> portPhysical or logical port number to be opened. See Port Constants for more information.
-> configPPointer to the configuration structure specifying the serial port's properties. See SrmOpenConfigType.
-> configSizeThe size of the configuration structure pointed to by configP.
<- newPortIdPContains the port ID to be passed to other Serial Manager functions.

Result

This function returns the following error codes:

errNone No error.
serErrAlreadyOpenThis port already has an installed background owner.
serErrBadPortThis port doesn't exist.
serErrNotSupportedThis type of port cannot be opened in the background.
serErrBadParamThe configP parameter is NULL.
memErrNotEnoughSpaceThere 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.

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.

Compatibility

Implemented only if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present. The SrmExtOpenBackground function replaces the SrmOpenBackground function.

See Also

SrmOpen, SrmExtOpen

SrmGetDeviceCount

Purpose

Returns the number of available serial devices.

Prototype

Err SrmGetDeviceCount (UInt16 *numOfDevicesP)

Parameters

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

Result

errNoneNo error.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmGetDeviceInfo

SrmGetDeviceInfo

Purpose

Returns information about a serial device.

Prototype

Err SrmGetDeviceInfo (UInt32 deviceID, DeviceInfoType *deviceInfoP)

Parameters

-> deviceIDID 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 SrmExtOpen, or a 4-character port name (such as 'u328', 'u650', or 'ircm'). See Port Constants.
<- deviceInfoPPointer to a DeviceInfoType structure where information about the device is returned.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNoDevicesAvailThe Serial Manager cannot find any serial devices.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmGetDeviceCount

SrmGetStatus

Purpose

Returns status information about the serial hardware.

Prototype

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

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
<- statusFieldPPointer to address where hardware status information for the port is returned. This is a 32-bit field using the flags described in Status Constants.
<- lineErrsPPointer to address where the number of line errors for the port is returned. The line error flags are described in Line Error Constants.

Result

This function returns the following error codes:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotSupportedThe port is a yielded port.
serErrNoDevicesAvailNo 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.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 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

-> portThe four-character port name or logical port number to be opened. See Port Constants for more information.
-> baudInitial baud rate of port.
<- newPortIdPContains the port ID to be passed to other Serial Manager functions.

Result

This function returns the following error codes:

errNone No error.
serErrAlreadyOpenThis port already has an installed foreground owner.
serErrBadPortThis port doesn't exist.
memErrNotEnoughSpaceThere 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.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

If New Serial Manager Feature Set Version 2 is present, the SrmOpen function is replaced by SrmExtOpen. SrmOpen is supported for backward compatibility.

See Also

SrmOpenBackground

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

-> portThe four-character port name or logical port number to be opened. See Port Constants for more information.
-> baudInitial baud rate of port.
<- newPortIdPContains the port ID to be passed to other Serial Manager functions.

Result

This function returns the following error codes:

errNoneNo error.
serErrAlreadyOpenThis port already has an installed background owner.
serErrBadPortThis port doesn't exist.
memErrNotEnoughSpaceThere 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 Version 1 is present.

If New Serial Manager Feature Set Version 2 is present, the SrmOpenBackground function is replaced by SrmExtOpenBackground. SrmOpenBackground is supported for backward compatibility.

See Also

SrmOpen

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

-> portIdPort ID returned from SrmOpen or SrmExtOpen.
-> minBytesNumber of bytes that must be received before wakeup handler is called. Typically, this is set to 1.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNoDevicesAvailNo serial devices could be found.

Comments

This function primes a wakeup handler installed by SrmSetWakeupHandler.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmSetWakeupHandler, WakeupHandlerProcPtr

SrmReceive

Purpose

Receives a specified number of bytes.

Prototype

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

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
<- rcvBufPPointer to buffer where received data is to be returned.
-> countLength of data buffer (in bytes). This specifies the number of bytes to receive.
-> timeoutThe amount of time (in ticks) 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.
<- errPError code.

Result

Number of bytes of data actually received.

Comments

The following error codes can be returned in errP:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrTimeOutUnable to receive data within the specified timeout period.
serErrConfigurationFailedThe port needs time to configure, and the configuration has failed.
serErrNotSupportedThe port is not the foreground port.
serErrConfigurationFailedThe port could not configure itself.
serErrLineErrA line error occurred during the receipt of data. Use SrmGetStatus to obtain the exact line error.
serErrNoDevicesAvailNo serial devices could be found.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmReceiveCheck, SrmReceiveFlush, SrmReceiveWait

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

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
<- numBytesPNumber of bytes in the receive queue.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrLineErrA line error has occurred. Use SrmGetStatus to obtain the exact line error.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmReceive, SrmReceiveFlush, SrmReceiveWait

SrmReceiveFlush

Purpose

Flushes the receive FIFOs.

Prototype

Err SrmReceiveFlush (UInt16 portId, Int32 timeout)

Parameters

-> portIdPort ID returned from SrmOpen or SrmExtOpen.
-> timeoutTimeout value, in ticks.

Result

This function returns the following error codes:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNotSupportedThe port is not the foreground port.
serErrNoDevicesAvailNo serial devices could be found.

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.

Any errors on the line are cleared before this function returns.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmReceive, SrmReceiveCheck, SrmReceiveWait

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

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
-> bytesNumber of bytes to wait for.
-> timeoutTimeout value, in ticks.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrTimeOutUnable to receive data within the specified timeout period.
serErrNotSupportedThe port is not the foreground port.
serErrBadParamThe bytes parameter exceeds the size of the receive queue. Use SrmSetReceiveBuffer to increase the size of the receive queue.
serErrLineErrA line error occurred during the receipt of data. Use SrmGetStatus to obtain the exact line error.
serErrNoDevicesAvailNo serial devices could be found.

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.

Do not call SerReceiveWait from within a wakeup handler. If you do, the serErrTimeOut error is returned.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmReceive, SrmReceiveCheck, SrmReceiveFlush

SrmReceiveWindowClose

Purpose

Closes direct access to the Serial Manager's receive queue.

Prototype

Err SrmReceiveWindowClose (UInt16 portId, UInt32 bytesPulled)

Parameters

-> portIdPort ID returned from SrmOpen or SrmExtOpen.
-> bytesPulledNumber of bytes the application read from the receive queue.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNotSupportedThe port is not the foreground port.
serErrNoDevicesAvailNo 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.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmReceiveWindowOpen

SrmReceiveWindowOpen

Purpose

Provides direct access to the Serial Manager's receive queue.

Prototype

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

Parameters

-> portIdPort ID returned from SrmOpen or SrmExtOpen.
<- bufPPPointer to a pointer to the receive buffer.
<- sizePAvailable bytes in buffer.

Result

This function returns the following error codes:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNotSupportedThe port is not the foreground port.
serErrLineErrThe data in the queue contains line errors.
serErrNoDevicesAvailNo 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.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmReceiveWindowClose

SrmSend

Purpose

Sends a block of data out the specified port.

Prototype

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

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
-> bufpPointer to data to send.
-> countLength of data buffer, in bytes.
<- errPError code. See the Comments section for details.

Result

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.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrTimeOutUnable to send data within the specified CTS timeout period.
serErrNoDevicesAvailNo serial devices could be found.
serErrConfigurationFailed The port configuration has failed.
serErrNotSupported The specified port is not the foreground port.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmSendCheck, SrmSendFlush, SrmSendWait

SrmSendCheck

Purpose

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

Prototype

Err SrmSendCheck (UInt16 portId, UInt32 *numBytesP)

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
<- numBytesPNumber of bytes left in the FIFO queue.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNotSupportedThis feature not supported by the hardware.
serErrNoDevicesAvailNo serial devices could be found.

Comments

Not all serial devices support this feature.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmSend, SrmSendFlush, SrmSendWait

SrmSendFlush

Purpose

Flushes the transmit FIFO.

Prototype

Err SrmSendFlush (UInt16 portId)

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNotSupportedThe port is not the foreground port.
serErrNoDevicesAvailNo serial devices could be found.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmSend, SrmSendCheck, SrmSendWait

SrmSendWait

Purpose

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

Prototype

Err SrmSendWait (UInt16 portId)

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.

Result

This function returns the following error codes:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrTimeOutUnable to send data within the CTS timeout period.
serErrNotSupportedThe port is not the foreground port.
serErrNoDevicesAvailNo 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).

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmSend, SrmSendCheck, SrmSendFlush

SrmSetReceiveBuffer

Purpose

Installs a new buffer into the Serial Manager's receive queue.

Prototype

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

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
-> bufPPointer to new receive buffer. Ignored if bufSize is NULL.
-> bufSizeSize of new receive buffer in bytes. To remove this buffer and allocate a new default buffer (512 bytes), specify NULL.

Result

This function returns the following error codes:

errNone No error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThis port is not open.
memErrNotEnoughSpaceNot enough memory to allocate default buffer.
serErrNoDevicesAvailNo 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 bufSize arguments.


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 Version 1 is present.

SrmSetWakeupHandler

Purpose

Installs a wakeup handler.

Prototype

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

Parameters

-> portIDPort ID returned from SrmOpen or SrmExtOpen.
-> procPPointer to a WakeupHandlerProcPtr function. Specify NULL to remove a handler.
-> refConUser-defined data that is passed to the wakeup handler function. This can be a pointer or not.

Result

This function returns the following error codes:

errNoneNo error.
serErrBadPortThis port doesn't exist.
serErrNotOpenThe port is not open.
serErrNoDevicesAvailNo 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.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmPrimeWakeupHandler, WakeupHandlerProcPtr

Serial Manager Application-Defined Functions

WakeupHandlerProcPtr

Purpose

Called after some number of bytes are received by the Serial Manager's interrupt function.

Prototype

void (*WakeupHandlerProcPtr)(UInt32 refCon)

Parameters

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


IMPORTANT: Because wakeup handlers are called during interrupt time, they cannot call any Palm OS® system functions, including SrmReceive, that may block the system in any way. Wakeup handlers should also be very short so as to reduce interrupt latency.

Two common implementations of wakeup handlers include:

Calling EvtWakeup, which causes any pending EvtGetEvent call to return and then sends a nilEvent to the current application.

Using SrmReceiveWindowOpen and SrmReceiveWindowClose to gain direct access to the receive queue without blocking.

Compatibility

Implemented only if New Serial Manager Feature Set Version 1 is present.

See Also

SrmPrimeWakeupHandler, SrmSetWakeupHandler