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

69    Virtual Drivers

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the Serial Manager virtual device driver API:

The header files SerialVdrv.h and SerialDrvr.h declare the virtual driver API. For more information on writing device drivers for the Serial Manager, see section "Writing a Virtual Device Driver" in the "Serial Communication" chapter of Palm OS Programmer's Companion, vol. II, Communications.

Driver Data Structures ^TOP^

DrvrInfoType Struct ^TOP^

Purpose

The DrvrInfoType structure defines information about the serial hardware. It is passed to and filled in by the DrvEntryPointProcPtr() for a virtual driver.

Prototype

typedef struct {
UInt32 drvrID;
UInt32 drvrVersion;
UInt32 maxBaudRate;
UInt32 handshakeThreshold;
UInt32 portFlags;
const Char*portDesc;
DrvrIRQEnum irqType;
UInt8 multipleEnumerations;
UInt32 dbCreator;
} DrvrInfoType;

Fields

drvrID
4-character creator type, such as 'u328'.
drvrVersion
Version of code that works for this hardware. See Driver Version Constants.
maxBaudRate
Maximum baud rate supported by this hardware.
handshakeThreshold
Baud rate at which the use of hardware handshaking is necessary.
portFlags
Bit flags denoting features of this hardware. The flags are described in Port Feature Constants.
portDesc
Pointer to null-terminated string describing this hardware. This string appears in the Connection panel to describe the port to the user (only if the portCncMgrVisible bit in portFlags is set). Can be NULL if the driver contains a resource (of type 'tSTR' and id kPortDescStrID) that supplies this string.
irqType
IRQ line being used for this hardware. For a virtual driver, specify drvrIRQNone.
multipleEnumerations
The number of entries in the driver table required for this driver. If 0, the driver has a single entry.
dbCreator
Creator ID of the database containing this driver.

Compatibility

The multipleEnumerations and dbCreator fields are only defined if New Serial Manager Feature Set Version 2 is present.

DrvrRcvQType Struct ^TOP^

Purpose

The DrvrRcvQType structure defines the virtual driver receive buffer and function pointers to functions that access and save data to the buffer. A pointer to this structure is passed to the VdrvOpenProcPtr() function. The DrvrHWRcvQPtr type defines a pointer to a DrvrRcvQType structure.

Prototype

typedef struct DrvrRcvQType {
void*rcvQ;
WriteByteProcPtr qWriteByte;
WriteBlockProcPtr qWriteBlock;
GetSizeProcPtr qGetSize;
GetSpaceProcPtr qGetSpace;
SignalCheckPtr qSignalCheck;
} DrvrRcvQType;
typedef DrvrRcvQType *DrvrHWRcvQPtr;

Fields

rcvQ
Pointer to the receive buffer.
qWriteByte
Function pointer to a function that the virtual driver can use to write one byte to the Serial Manager's receive queue. See the WriteByteProcPtr() function.
qWriteBlock
Function pointer to a function that the virtual driver can use to write a block of bytes to the Serial Manager's receive queue. See the WriteBlockProcPtr() function.
qGetSize
Function pointer to a function that the virtual driver can use to get the total size of the Serial Manager's receive queue. See the GetSizeProcPtr() function.
qGetSpace
Function pointer to a function that the virtual driver can use to get the available space in the Serial Manager's receive queue. See the GetSpaceProcPtr() function.
qSignalCheck
Function pointer to a function that the virtual driver can use to perform a signal check for the Serial Manager's receive queue. See the SignalCheckPtr() function.

Compatibility

The qSignalCheck field is only defined if New Serial Manager Feature Set Version 2 is present.

DrvrStatusEnum Enum ^TOP^

Purpose

The DrvrStatusEnum enumerated type specifies serial status bit flags. Return these enumerated types from the VdrvStatusProcPtr() call.

Prototype

typedef enum DrvrStatusEnum {
drvrStatusCtsOn = 0x0001,
drvrStatusRtsOn = 0x0002,
drvrStatusDsrOn = 0x0004,
drvrStatusTxFifoFull = 0x0008,
drvrStatusTxFifoEmpty = 0x0010,
drvrStatusBreakAsserted = 0x0020,
drvrStatusDataReady = 0x0040,
drvrStatusLineErr = 0x0080
} DrvrStatusEnum;

Constants

drvrStatusCtsOn
Set if CTS line is active.
drvrStatusRtsOn
Set if RTS line is active.
drvrStatusDsrOn
Set if DSR is on.
drvrStatusTxFifoFull
Set if transmit FIFO is full; cleared if FIFO has space.
drvrStatusTxFifoEmpty
Set if transmit FIFO is empty.
drvrStatusBreakAsserted
Set if sending break characters is enabled.
drvrStatusDataReady
Used by debugger only.
drvrStatusLineErr
Used by debugger only.

SrmRcvQType Struct ^TOP^

Purpose

The SrmRcvQType structure defines the Serial Manager receive queue. This queue is passed as a parameter to the virtual driver.

Prototype

typedef struct SrmRcvQType {
UInt32 qStart;
UInt32 qEnd;
UInt32 qSize;
UInt8 *qData;
void *qPort;
} SrmRcvQType;

Fields

qStart
The start of the queue.
qEnd
The end of the queue.
qSize
The size of the queue.
qData
The data currently in the queue.
qPort
A pointer to the current foreground port.

Compatibility

The SrmRcvQType structure was previously a private structure. It is declared publicly if New Serial Manager Feature Set Version 2 is present.

VdrvAPIType Struct ^TOP^

Purpose

The VdrvAPIType structure defines function pointers to the required virtual driver functions. When passed a pointer to this structure in the DrvEntryPointProcPtr() function, that function must fill in the pointers to the virtual driver functions appropriately.

Prototype

typedef struct {
VdrvOpenProcPtr drvOpen;
VdrvCloseProcPtr drvClose;
VdrvControlProcPtr drvControl;
VdrvStatusProcPtr drvStatus;
VdrvReadProcPtr drvRead;
VdrvWriteProcPtr drvWrite;
VdrvOpenProcV4Ptr drvOpenV4;
VdrvControlCustomProcPtr drvControlCustom;
} VdrvAPIType;

Fields

drvOpen
Pointer to the driver open function.
drvClose
Pointer to the driver close function.
drvControl
Pointer to the driver control function.
drvStatus
Pointer to the driver status function.
drvRead
Pointer to the driver read function.
drvWrite
Pointer to the driver write function.
drvOpenV4
Pointer to the driver open function for New Serial Manager Feature Set Version 2.
drvControlCustom
Pointer to the driver custom control function.

Compatibility

drvOpenV4 and drvControlCustom are declared if both New Serial Manager Feature Set Version 2 and 4.0 New Feature Set are present.

VdrvConfigType Struct ^TOP^

Purpose

The VdrvConfigType structure specifies parameters for opening a serial port. This structure is passed as a parameter to VdrvOpenProcV4Ptr().

Prototype

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

Fields

baud
Baud rate at which to open the connection. Serial drivers that do not require baud rates ignore this field.
drvrId
Creator ID of the application or library that is using the Serial Manager.
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.
serFncPPPSession
The connection is to be used for the PPP interface.
serFncSLIPSession
The connection is to be used for the SLIP session.
serFncDebugger
The connection is to be used for a debugging session.
serFncHotSync
The 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.

VdrvCtlOpCodeEnum Enum ^TOP^

Purpose

The VdrvCtlOpCodeEnum enumerated type specifies a serial control operation. You should handle each of these constants when passed for the controlCode parameter to the VdrvControlProcPtr() call.

Prototype

typedef enum VdrvCtlOpCodeEnum {
vdrvOpCodeNoOp = 0, 
vdrvOpCodeSetBaudRate = 0x1000,
vdrvOpCodeSetSettingsFlags,
vdrvOpCodeSetCtsTimeout,
vdrvOpCodeClearErr,
vdrvOpCodeSetSleepMode,
vdrvOpCodeSetWakeupMode,
vdrvOpCodeFIFOCount,
vdrvOpCodeStartBreak,
vdrvOpCodeStopBreak,
vdrvOpCodeStartLoopback,
vdrvOpCodeStopLoopback,
vdrvOpCodeFlushTxFIFO,
vdrvOpCodeFlushRxFIFO,
vdrvOpCodeSendBufferedData,
vdrvOpCodeRcvCheckIdle,
vdrvOpCodeEmuSetBlockingHook,
vdrvOpCodeGetOptTransmitSize,
vdrvOpCodeGetMaxRcvBlockSize,
vdrvOpCodeNotifyBytesReadFromQ,
vdrvOpCodeSetDTRAsserted,
vdrvOpCodeGetDTRAsserted,
vdrvOpCodeWaitForConfiguration,
vdrvOpCodeGetUSBDeviceDescriptor,
vdrvOpCodeGetUSBConfigDescriptor,
vdrvOpCodeEnableIRDA,
vdrvOpCodeDisableIRDA,
vdrvOpCodeEnableUART,
vdrvOpCodeDisableUART,
vdrvOpCodeRxEnable,
vdrvOpCodeRxDisable,
vdrvOpCodeLineEnable,
vdrvOpCodeEnableUARTInterrupts,
vdrvOpCodeDisableUARTInterrupts,
vdrvOpCodeSetReceiveQueue,
vdrvOpCodeSaveState,
vdrvOpCodeRestoreState,
vdrvOpCodeSetYieldPortCallback,
vdrvOpCodesetYieldPortRefCon,
vdrvOpCodeUserDef = 0x2000,
vdrvOpCodeSystem = 0x7000,
vdrvOpCodeCustom = 0x8000
} VdrvCtlOpCodeEnum;

Constants

vdvrOpCodeSetBaudRate
Sets the baud rate.
vdvrOpCodeSetSettingsFlags
Sets the data transmission options. The bit flags are described in Serial Settings Constants.
vdrvOpCodeSetCtsTimeout
Hardware handshake timeout.
vdvrOpCodeClearErr
Clears the hardware error state.
vdvrOpCodeSetSleepMode
Puts the port in sleep mode (not typically used for virtual drivers).
vdvrOpCodeSetWakeupMode
Wakes up the port from sleep mode (not typically used for virtual drivers).
vdvrOpCodeFIFOCount
Returns the number of bytes currently in the FIFO (or best estimate).
vdvrOpCodeStartBreak
Sends a break character or enables the sending of break characters.
vdvrOpCodeStopBreak
Stops sending break characters.
vdvrOpCodeStartLoopback
Starts loopback mode (not typically used for virtual drivers).
vdvrOpCodeStopLoopback
Stops loopback mode (not typically used for virtual drivers).
vdrvOpCodeFlushTxFIFO
Flushes the contents of the transmit FIFO.
vdrvOpCodeFlushRxFIFO
Flushes the contents of the receive FIFO.
vdrvOpCodeSendBufferedData
Notifies virtual device to send any buffered data it has not emptied from its internal buffers.
vdrvOpCodeRcvCheckIdle
Called periodically to allow the virtual device time to check if there is data to be received. Because virtual devices execute in the same thread as applications, they can be prevented from handling notifications of received data.
vdrvOpCodeEmuSetBlockingHook
Special op code for the Simulator.
vdrvOpCodeGetOptTransmitSize
Returns the optimum buffer size for sending data or returns 0 to specify any buffer size is acceptable.
vdrvOpCodeGetMaxRcvBlockSize
Returns the maximum receive block size that the Serial Manager should request from the virtual device. Can be used to implement flow control.
vdrvOpCodeNotifyBytesReadFromQ
Tells the virtual device that some number of bytes have been read from the receive queue by the client application. Can be used to implement flow control.
vdrvOpCodeSetDTRAsserted
Asserts or de-asserts the DTR signal.
vdrvOpCodeGetDTRAsserted
Gets the status of the DTR signal.
vdrvOpCodeWaitForConfiguration
Waits for USB enumeration to complete. Called from the send and receive functions of the Serial Manager. The driver should have a timeout for how long it waits for enumeration to complete. The driver should return with no error if enumeration has already occurred or has occurred within the driver's timeout. If the enumeration has not occurred within the driver's timeout, the driver should return serErrTimeOut.
vdrvOpCodeGetUSBDeviceDescriptor
Retrieves the device descriptor of a USB driver. Used to gather information about the device's capabilities. Implementation of this op code is optional. If the driver chooses to implement this op code, then the driver should return a pointer to the device descriptor. A driver that chooses not to implement this op code should return serErrNotSupported.
vdrvOpCodeGetUSBConfigDescriptor
Retrieves the configuration descriptor of a USB driver. Used to gather information about the device's capabilities. Implementation of this op code is optional. If the driver chooses to implement this op code, then the driver should return a pointer to the device descriptor. A driver that chooses not to implement this op code should return serErrNotSupported.
vdrvOpCodeEnableIRDA
Enable the IrDA mode and power up the IR line drivers.
vdrvOpCodeDisableIRDA
Disable the IrDA mode and disable the IR line drivers.
vdrvOpCodeEnableUART
Powers up the UART and the line drivers.
vdrvOpCodeDisableUART
Powers down the UART and the line drivers.
vdrvOpCodeRxEnable
Enables the receive FIFO, enables UART interrupts, and does whatever else is necessary to allow the UART to receive data.
vdrvOpCodeRxDisable
Disables the receive FIFO and UART interrupts and does whatever is needed to prevent the UART from receiving data.
vdrvOpCodeLineEnable
Enables the main serial line driver for the UART.
vdrvOpCodeEnableUARTInterrupts
Enables the appropriate UART receive interrupts.
vdrvOpCodeDisableUARTInterrupts
Disables all UART interrupts.
vdrvOpCodeSetReceiveQueue
This op code is used by the Serial Manager to set the driver's receive queue. This control code is called when a driver that has previously been opened as a background port is opened as a fully open bidirectional port.
vdrvOpCodeSaveState
Invoked when this port is yielded. This is a hook for the driver to save any current state.
vdrvOpCodeRestoreState
Invoked when the foreground port is closed and this port can become the foreground port.
vdrvOpCodeSetYieldPortCallback
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.
vdrvOpCodeSetYieldPortRefCon
Data to pass to the yield port callback function. System use only.
vdvrOpCodeUserDef
User defined function invoked through SrmControl().
vdrvOpCodeSystem
Reserves op codes between 0x7000 and 0x8000 for system use.
vdrvOpCodeCustom
Reserves op codes greater than 0x8000 for driver-specific use.

Compatibility

The op codes starting at vdrvOpCodeWaitForConfiguration are defined only if New Serial Manager Feature Set Version 2 is present. The op codes for yieldable ports and custom operations are defined only if both 4.0 New Feature Set is present as well.

Driver Constants ^TOP^

Driver Version Constants ^TOP^

The driver version constants specify which version of the driver API is implemented by this driver. The DrvEntryPointProcPtr() function passes this value back to the Serial Manager in the drvrVersion field of the DrvrInfoType function.

Constant

Value

Description

kDrvrVersion

4

The latest version of the API.

kDrvrVersion3

3

The version of the driver API that corresponds to New Serial Manager Feature Set Version 1 (which ships with roughly Palm OS® 3.3 up to Palm OS 4.0).

kDrvrVersion4

4

The version of the driver API that corresponds to New Serial Manager Feature Set Version 2 (which ships with roughly Palm OS 4.0 and higher).

Port Feature Constants ^TOP^

The port feature constants are flags that describe serial hardware capabilities.

Constant

Value

Description

portPhysicalPort

0x00000001

Should be set for a physical port, unset for a virtual port.

portBkgndModeSupported

0x00000002

Denotes that this port can be used for background ports. This flag is only applicable to virtual drivers. Background mode support is implied on physical drivers.

portRS232Capable

0x00000004

Set if this hardware has an RS-232 port.

portIRDACapable

0x00000008

Set if this hardware has an IR port and supports IrDA mode.

portCradlePort

0x00000010

Set if this hardware controls the cradle port.

portExternalPort

0x00000020

Set if this hardware port is external or on a memory card.

portModemPort

0x00000040

Set if this hardware communicates with a modem.

portCncMgrVisible

0x00000080

Set if this serial port's name is to be displayed in the Connection panel.

portConsolePort

0x00000100

Denotes this hardware controls the console port.

portUSBCapable

0x00000200

Set if this hardware has a USB port.

portPrivateUse

0x00001000

Set if this driver is for special software and not general applications.

Compatibility

USB support is only available if New Serial Manager Feature Set Version 2 is present.

Virtual Driver-Defined Functions ^TOP^

The functions in this section must be defined by your virtual driver.

DrvEntryPointProcPtr Function ^TOP^

Purpose

Entry point for the virtual driver.

Declared In

SerialDrvr.h

Prototype

Err (
   *DrvEntryPointProcPtr
) (
   DrvrEntryOpCodeEnumopCode,
   void*uartData
)

Parameters

opCode
Entry function code.
uartData
Pointer to data specific to opCode.

Returns

errNone
No error.
-1
The op code is invalid or the hardware could not be found.

Comments

This function's purpose is based on the value of the opCode parameter. The three possible codes are drvrEntryGetUartFeatures, drvrEntryGetDrvrFuncts, and drvrEntryGetUartFtrsNEntries.

DrvEntryPoint is called with the drvrEntryGetUartFeatures code when the Serial Manager is installed into the system at boot time and is looking for all installed drivers. When this op code is set, the uartData pointer points to a DrvrInfoType structure. This function does not allocate the structure, it just fills in the fields with information.

This function should check to make sure the associated serial device can operate under the current OS and system settings. If the hardware cannot be found, the function should leave the DrvrInfoType struct untouched and return a -1 error.

The driver needs to supply a string that describes the port it manages. This string is displayed to the user in the Connection panel and is returned by the SrmGetDeviceInfo() function. To set this string, copy it into the portDesc field of the DrvrInfoType structure. Alternatively, you can supply this string in a driver resource of type 'tSTR' and id kPortDescStrID.

If the DrvrInfoType structure has a positive value in the multipleEnumerations field upon return, the Serial Manager defines one port for each entry in the driver table. The DrvEntryPoint function is called again, this time with the drvrEntryGetUartFtrsNEntries code. The uartData pointer points to a new DrvrInfoType structure whose multipleEnumerations field indicates which port is to be defined. The function should supply all information specific to this port.

DrvEntryPoint is called with the drvrEntryGetDrvrFuncts code when a virtual port is opened. The uartData pointer points to a VdrvAPIType structure and DrvEntryPoint must fill in the fields of this structure with appropriate function pointers.

Compatibility

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

The drvrEntryGetUartFtrsNEntries is only supported if New Serial Manager Feature Set Version 2 is present. This function is fully backwards compatible. Passing 0 for the multipleEnumerations field defines a single port for the driver.

VdrvCloseProcPtr Function ^TOP^

Purpose

Handles all activities needed to close the virtual device.

Declared In

SerialDrvr.h

Prototype

Err (
   *VdrvCloseProcPtr
) (
   VdrvDataPtrdrvrData
)

Parameters

drvrData
Pointer to the driver's private global area.

Returns

errNone
No error.

Compatibility

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

VdrvControlProcPtr Function ^TOP^

Purpose

Extends the SrmControl function to the level of the virtual device.

Declared In

SerialDrvr.h

Prototype

Err (
   *VdrvControlProcPtr
) (
   VdrvDataPtrdrvrData,
   VdrvCtlOpCodeEnumcontrolCode,
   void*controlData,
   UInt16*controlDataLen
)

Parameters

drvrData
Pointer to the driver's private global area.
controlCode
Control function op code. One of the op codes listed in the VdrvCtlOpCodeEnum type.
controlData
Pointer to data for the specified control function.
controlDataLen
Pointer to length of control data being passed in or out.

Returns

errNone
No error.
serErrNotSupported
controlCode not supported.
serErrBadParam
controlData or controlDataLen is bad.

Comments

This function should support the op codes listed in the VdrvCtlOpCodeEnum type. If this function does not support an op code, it must return the serErrNotSupported error code for that op code.

Table 69.1 shows what is passed for the controlData and controlDataLen parameters for each of the control codes that use them. Control codes not listed do not use these parameters.

Table 69.1  VDrvControlProcPtr Parameters

vdvrOpCodeSetBaudRate

controlData = Pointer to Int32 (baud rate),
controlDataLen = Pointer to sizeof(Int32).

vdvrOpCodeSetSettingsFlags

controlData = Pointer to UInt32 (bitfield; see Serial Settings Constants)
controlDataLen = Pointer to sizeof(UInt32)

vdvrOpCodeFIFOCount

controlData = Pointer to Int16, which contains the number of bytes in the FIFO.
controlDataLen = Pointer to sizeof(Int16).

vdrvOpCodeGetOptTransmitSize

controlData = Pointer to Int32 (buffer size),
controlDataLen = Pointer to sizeof(Int32).

Return the optimum buffer size for sending data, or 0 to specify any buffer size is acceptable.

vdrvOpCodeGetMaxRcvBlockSize

controlData = Pointer to Int32 (block size),
controlDataLen = Pointer to sizeof(Int32).

Return the maximum block size that the Serial Manager should request from the virtual device.

vdrvOpCodeNotifyBytes
ReadFromQ

controlData = Pointer to Int32 (number of bytes read),
controlDataLen = Pointer to sizeof(Int32).

vdrvOpCodeSetDTRAsserted

controlData = Pointer to Boolean indicating whether to enable or disable DTR.
controlDataLen = Pointer to sizeof(Boolean)

vdrvOpCodeGetDTRAsserted

controlData = Pointer to Boolean indicating whether DTR is enabled.
controlDataLen = Pointer to sizeof(Boolean)

vdvrOpCodeUserDef

controlData = Pointer from SrmControl() (user-defined data),
controlDataLen = Pointer to sizeof(Int32).

Compatibility

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

VdrvControlCustomProcPtr Function ^TOP^

Purpose

Extends the SrmCustomControl function to the level of the virtual device.

Declared In

SerialDrvr.h

Prototype

Err (
   *VdrvControlCustomProcPtr
) (
   VdrvDataPtrdrvrData,
   UInt16opCode,
   UInt32creator,
   void*controlData,
   void*controlDataLenP
)

Parameters

drvrData
Pointer to the driver's private global area.
controlCode
Control function op code.
creator
Creator ID of the driver that defines the op code. The combination of creator ID and op code uniquely identifies the operation to be performed.
controlData
Pointer to data for the specified control function.
controlDataLen
Pointer to length of control data being passed in or out.

Returns

errNone
No error.
serErrNotSupported
controlCode not supported.
serErrBadParam
controlData or controlDataLen is bad.

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.

Compatibility

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

VdrvOpenProcPtr Function ^TOP^

Purpose

Initializes the virtual device to begin communication.

Declared In

SerialDrvr.h

Prototype

Err (
   *VdrvOpenProcPtr
) (
   VdrvDataPtr*drvrData,
   UInt32baudRate,
   DrvrHWRcvQPtrrcvQP
)

Parameters

drvrData
Pointer to a pointer to the driver's private global area (allocated by this function). A pointer to this private global area is passed to the other virtual driver functions.
baudRate
Initial baud rate setting.
rcvQP
Pointer to the driver's receive queue buffer structure. For details on the fields, see DrvrRcvQType.

Returns

errNone
No error.

Comments

This function must allocate and initialize any global variables (and pass back a pointer to a pointer to them in drvrDataP), do any set-up necessary for communicating with other software, and save the rcvQP pointer since it will need the functions and pointers to structures enclosed within to be able to save received data into the Serial Manager's receive queue.

Compatibility

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

VdrvOpenProcV4Ptr Function ^TOP^

Purpose

Initializes the virtual device to begin communication.

Declared In

SerialDrvr.h

Prototype

Err (
   *VdrvOpenProcV4Ptr
) (
   VdrvDataPtr*drvrData,
   VdrvConfigPtrconfigP,
   DrvrHWRcvQPtrrcvQP
)

Parameters

drvrData
Pointer to a pointer to the driver's private global area (allocated by this function). A pointer to this private global area is passed to the other virtual driver functions.
configP
Pointer to the configuration structure specifying the port's properties. See VdrvConfigType.
rcvQP
Pointer to the driver's receive queue buffer structure. For details on the fields, see DrvrRcvQType.

Returns

errNone
No error.

Comments

This function must allocate and initialize any global variables (and pass back a pointer to a pointer to them in drvrDataP), do any set-up necessary for communicating with other software, and save the rcvQP pointer since it will need the functions and pointers to structures enclosed within to be able to save received data into the Serial Manager's receive queue.

Compatibility

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

VdrvStatusProcPtr Function ^TOP^

Purpose

Returns virtual device status.

Declared In

SerialDrvr.h

Prototype

UInt16 (
   *VDrvStatusProcPtr
) (
   VdrvDataPtr drvrData
)

Parameters

drvrData
Pointer to the driver's private global area.

Returns

An unsigned long bitfield denoting the status of the virtual device, but only if the virtual device is emulating hardware. The individual bit flags are described in the DrvrStatusEnum type.

Comments

Generally, status is returned only to the client application using the virtual device. The Serial Manager does not use status information from virtual devices.

Compatibility

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

VdrvWriteProcPtr Function ^TOP^

Purpose

Writes a block of bytes.

Declared In

SerialDrvr.h

Prototype

UInt32 (
   *VdrvWriteProcPtr
) (
   VdrvDataPtrdrvrDataP,
   void*bufP,
   UInt32size,
   Err*errP
)

Parameters

drvrDataP
Pointer to the driver's private global area.
bufP
Pointer to buffer containing the data to be written to the virtual device.
size
Number of bytes in the buffer bufP.
errP
Pointer to an error code resulting from the operation. Zero is returned if there is no error.

Returns

Returns the actual number of bytes written.

Compatibility

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

Serial Manager Queue Functions ^TOP^

The functions in this section are supplied by the Serial Manager to the virtual driver through the DrvrRcvQType passed to the VdrvOpenProcPtr() function.

GetSizeProcPtr Function ^TOP^

Purpose

Returns the total size of the Serial Manager's receive queue.

Declared In

SerialDrvr.h

Prototype

typedef UInt32 (
   *GetSizeProcPtr
) (
   void*theQ
)

Parameters

theQ
Pointer to the receive queue.

Returns

Size in bytes of the Serial Manager's receive queue.

Comments

This function is useful for implementing flow control.

Compatibility

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

GetSpaceProcPtr Function ^TOP^

Purpose

Returns the available space in the Serial Manager's receive queue.

Declared In

SerialDrvr.h

Prototype

typedef UInt32 (
   *GetSpaceProcPtr
) (
   void*theQ
)

Parameters

theQ
Pointer to the receive queue.

Returns

Size in bytes of the available space in the Serial Manager's receive queue.

Comments

This function is useful for implementing flow control.

Compatibility

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

SignalCheckPtr Function ^TOP^

Purpose

Check the queue to see if the semaphore needs to be signalled.

Declared In

SerialDrvr.h

Prototype

typedef void (
   *SignalCheckPtr
) (
   void*theQ,
   UInt16lineErrsP
)

Parameters

theQ
Pointer to the receive queue.
lineErrsP
Any serial line errors received should be reported here.

Returns

Returns nothing.

Comments

This function signals that there is data to be received without writing anything to the receive queue. The WriteByteProcPtr() and WriteBlockProcPtr() functions also signal that there is data to be received after they have written the data to the queue.

Compatibility

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

WriteBlockProcPtr Function ^TOP^

Purpose

Writes a block of bytes to the Serial Manager's receive queue.

Declared In

SerialDrvr.h

Prototype

typedef Err (
   *WriteBlockProcPtr
) (
   void*theQ,
   UInt8*bufP,
   UInt16size,
   UInt16lineErrs
)

Parameters

theQ
Pointer to the receive queue.
bufP
Pointer to the buffer holding bytes to be written.
size
Size of bufP.
lineErrs
Any serial line errors received should be reported here.

Returns

errNone
No error.
serErrLineErr
There was a software overrun line error.

Compatibility

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

WriteByteProcPtr Function ^TOP^

Purpose

Writes one byte to the Serial Manager's receive queue.

Declared In

SerialDrvr.h

Prototype

typedef Err (
   *WriteByteProcPtr
) (
   void*theQ,
   UInt8theByte,
   UInt16lineErrs
)

Parameters

theQ
Pointer to the receive queue.
theByte
The byte to be written to the queue.
lineErrs
Any serial line errors received should be reported here.

Returns

errNone
No error.
serErrLineErr
There was a software overrun line error.

Compatibility

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