< Home < Developers < Development Support < Documentation

## 65 Virtual Drivers

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 65 Virtual Drivers Driver Data Structures DrvrInfoType DrvrRcvQType DrvrStatusEnum SrmRcvQType VdrvAPIType VdrvConfigType VdrvCtlOpCodeEnum Driver Constants Driver Version Constants Port Feature Constants Virtual Driver-Defined Functions DrvEntryPoint VdrvCloseProcPtr VdrvControlProcPtr VdrvControlCustomProcPtr VdrvOpenProcPtr VdrvOpenProcV4Ptr VdrvStatusProcPtr VdrvWriteProcPtr Serial Manager Queue Functions GetSizeProcPtr GetSpaceProcPtr SignalCheckPtr WriteBlockProcPtr WriteByteProcPtr |  |  |  | This chapter provides reference material for the Serial Manager virtual device driver API: Driver Data Structures Driver Constants Virtual Driver-Defined Functions Serial Manager Queue Functions The header files SerialVdrv.hand 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 ## DrvrInfoType The DrvrInfoType structure defines information about the serial hardware. It is passed to and filled in by the DrvEntryPoint for a virtual driver.
    typedef struct {
      UInt32 drvrID;
      UInt32 drvrVersion;
      UInt32 maxBaudRate;
      UInt32 handshakeThreshold;
      UInt32 portFlags;
      const Char *portDesc;
      DrvrIRQEnum irqType;
      UInt8 multipleEnumerations;
      UInt32 dbCreator;
    } DrvrInfoType;
#### Value Descriptions #####
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 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.
    typedef struct DrvrRcvQType {
      void *rcvQ;
      WriteByteProcPtr qWriteByte;
      WriteBlockProcPtr qWriteBlock;
      GetSizeProcPtr qGetSize;
      GetSpaceProcPtr qGetSpace;
      SignalCheckPtr qSignalCheck;
    } DrvrRcvQType;

    typedef DrvrRcvQType *DrvrHWRcvQPtr;
#### Value Descriptions #####
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 The DrvrStatusEnum enumerated type specifies serial status bit flags. Return these enumerated types from the VdrvStatusProcPtr call.
    typedef enum DrvrStatusEnum {
      drvrStatusCtsOn = 0x0001,
      drvrStatusRtsOn = 0x0002,
      drvrStatusDsrOn = 0x0004,
      drvrStatusTxFifoFull = 0x0008,
      drvrStatusTxFifoEmpty = 0x0010,
      drvrStatusBreakAsserted = 0x0020,
      drvrStatusDataReady = 0x0040,
      drvrStatusLineErr = 0x0080
    } DrvrStatusEnum;
#### Value Descriptions #####
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 The SrmRcvQType structure defines the Serial Manager receive queue. This queue is passed as a parameter to the virtual driver.
    typedef struct SrmRcvQType {
      UInt32 qStart;
      UInt32 qEnd;
      UInt32 qSize;
      UInt8 *qData;
      void *qPort;
    } SrmRcvQType;
#### Field Descriptions #####
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 The VdrvAPIType structure defines function pointers to the required virtual driver functions. When passed a pointer to this structure in the DrvEntryPoint function, that function must fill in the pointers to the virtual driver functions appropriately.
    typedef struct {
      VdrvOpenProcPtr drvOpen;
      VdrvCloseProcPtr drvClose;
      VdrvControlProcPtr drvControl;
      VdrvStatusProcPtr drvStatus;
      VdrvReadProcPtr drvRead;
      VdrvWriteProcPtr drvWrite;
      VdrvOpenProcV4Ptr drvOpenV4;
      VdrvControlCustomProcPtr drvControlCustom;
    } VdrvAPIType;
#### Value Descriptions #####
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. ## New VdrvConfigType The VdrvConfigType structure specifies parameters for opening a serial port. This structure is passed as a parameter to VdrvOpenProcV4Ptr.
    typedef struct VdrvConfigType {
      UInt32 baud;
      UInt32 drvrId;
      UInt32 function;
      MemPtr drvrDataP;
      UInt16 drvrDataSize;
      UInt32 sysReserved1;
      UInt32 sysReserved2;
    } VdrvConfigType;
#### Field Descriptions #####
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 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.
    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;
#### Value Descriptions #####
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 ## Driver Version Constants The driver version constants specify which version of the driver API is implemented by this driver. The DrvEntryPoint 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 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 The functions in this section must be defined by your virtual driver. ## DrvEntryPoint #### Purpose Entry point for the virtual driver. #### Prototype Err DrvEntryPoint (DrvrEntryOpCodeEnum opCode, void *uartData) #### Parameters #####
-> opCode | Entry function code.
#####
<-> uartData | Pointer to data specific to opCode.
#### Result #####
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 #### Purpose Handles all activities needed to close the virtual device. #### Prototype Err (*VdrvCloseProcPtr) (VdrvDataPtr drvrData) #### Parameters #####
-> drvrData | Pointer to the driver's private global area.
#### Result #####
errNone | No error.
#### Compatibility Implemented only if New Serial Manager Feature Set Version 1 is present. ## VdrvControlProcPtr #### Purpose Extends the SrmControl function to the level of the virtual device. #### 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.
#### Result #####
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 65.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 65.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. ## New VdrvControlCustomProcPtr #### Purpose Extends the SrmCustomControl function to the level of the virtual device. #### 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.
#### Result #####
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 #### Purpose Initializes the virtual device to begin communication. #### 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.
#### Result #####
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. ## New VdrvOpenProcV4Ptr #### Purpose Initializes the virtual device to begin communication. #### 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.
#### Result #####
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 #### Purpose Returns virtual device status. #### Prototype UInt16 (*VDrvStatusProcPtr) (VdrvDataPtr drvrData) #### Parameters #####
-> drvrData | Pointer to the driver's private global area.
#### Result 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 #### Purpose Writes a block of bytes. #### 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.
#### Result Returns the actual number of bytes written. #### Compatibility Implemented only if New Serial Manager Feature Set Version 1 is present. ## Serial Manager Queue Functions The functions in this section are supplied by the Serial Manager to the virtual driver through the DrvrRcvQType passed to the VdrvOpenProcPtr function. ## GetSizeProcPtr #### Purpose Returns the total size of the Serial Manager's receive queue. #### Prototype typedef UInt32 (*GetSizeProcPtr) (void *theQ) #### Parameters #####
-> theQ | Pointer to the receive queue.
#### Result 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 #### Purpose Returns the available space in the Serial Manager's receive queue. #### Prototype typedef UInt32 (*GetSpaceProcPtr) (void *theQ) #### Parameters #####
-> theQ | Pointer to the receive queue.
#### Result 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. ## New SignalCheckPtr #### Purpose Check the queue to see if the semaphore needs to be signalled. #### 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.
#### Result 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 #### Purpose Writes a block of bytes to the Serial Manager's receive queue. #### 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.
#### Result #####
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 #### Purpose Writes one byte to the Serial Manager's receive queue. #### 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.
#### Result #####
errNone | No error.
#####
serErrLineErr | There was a software overrun line error.
#### Compatibility Implemented only if New Serial Manager Feature Set Version 1 is present. |