(68K) Virtual Drivers | Palm OS® Programmer's API Reference

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:; 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
) (
   DrvrEntryOpCodeEnum opCode,
   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
) (
   VdrvDataPtr drvrData
)

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
) (
   VdrvDataPtr drvrData,
   VdrvCtlOpCodeEnum controlCode,
   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
) (
   VdrvDataPtr drvrData,
   UInt16 opCode,
   UInt32 creator,
   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,
   UInt32 baudRate,
   DrvrHWRcvQPtr rcvQP
)

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,
   VdrvConfigPtr configP,
   DrvrHWRcvQPtr rcvQP
)

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

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
) (
   VdrvDataPtr drvrDataP,
   void *bufP,
   UInt32 size,
   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,
   UInt16 lineErrsP
)

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,
   UInt16 size,
   UInt16 lineErrs
)

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,
   UInt8 theByte,
   UInt16 lineErrs
)

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.

69 Virtual Drivers

Driver Data Structures ^TOP^

DrvrInfoType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

DrvrRcvQType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

DrvrStatusEnum Enum ^TOP^

Purpose

Prototype

Constants

SrmRcvQType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

VdrvAPIType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

VdrvConfigType Struct ^TOP^

Purpose

Prototype

Fields

Compatibility

VdrvCtlOpCodeEnum Enum ^TOP^

Purpose

Prototype

Constants

Compatibility

Driver Constants ^TOP^

Driver Version Constants ^TOP^

Port Feature Constants ^TOP^

Compatibility

Virtual Driver-Defined Functions ^TOP^

DrvEntryPointProcPtr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

VdrvCloseProcPtr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Compatibility

VdrvControlProcPtr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

VdrvControlCustomProcPtr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

VdrvOpenProcPtr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility