DosRequestVDD
Description
Allows a protected-mode OS/2 session to communicate with a virtual device driver (VDD).
Syntax
#define INCL_DOSMVDM
#include <os2.h>
HVDD hvdd; /* The handle of a VDD returned by a previous call to DosOpenVDD. */
SGID sgid; /* The identifier of a specific DOS session, or null. */
ULONG cmd; /* A function code that is specific to a virtual device. */
ULONG cbInput; /* The length, in bytes, of the application data in pInput. */
PVOID pInput; /* The address of the command-specific information. */
ULONG cbOutput; /* The length, in bytes, of pOutput. */
PVOID pOutput; /* The address of the buffer where the VDD returns the information for the specified command. */
APIRET ulrc; /* Return Code. */
ulrc = DosRequestVDD(hvdd, sgid, cmd, cbInput,
pInput, cbOutput, pOutput);
Parameters
- hvdd (HVDD) - input
- The handle of a VDD returned by a previous call to DosOpenVDD.
- sgid (SGID) - input
- The identifier of a specific DOS session, or null.
- cmd (ULONG) - input
- A function code that is specific to a virtual device.
- cbInput (ULONG) - input
- The length, in bytes, of the application data in pInput.
- pInput (PVOID) - input
- The address of the command-specific information.
The system sends this data to the virtual device driver to process the specified command.
- cbOutput (ULONG) - input
- The length, in bytes, of pOutput.
- pOutput (PVOID) - output
- The address of the buffer where the VDD returns the information for the specified command.
This information is specific to the command and the virtual device driver.
Return Code
ulrc (APIRET) - returns
DosRequestVDD returns one of the following values:
- 0 NO_ERROR
- 6 ERROR_INVALID_HANDLE
- 21 ERROR_NOT_READY
- 644 ERROR_INVALID_CALLER
Remarks
The system calls every DosRequestVDD procedure registered by VDHRegisterVDD under the VDD name associated with the specified handle. This calling continues until a virtual device driver gives a return code other than VDDREQ_PASS. There is no predefined order to the calling sequence.
Example Code
The following is NOT a complete C program. It is simply intended to provide an idea of how a protected-mode OS/2 process can communicate with a virtual device driver (VDD).
This example shows a protected-mode process calling a hypothetical VDD with a request to read a string of bytes from the VDD. Assume that the session identifier of the specified DOS session has been placed into SessionID already and that the sample virtual device driver has registered the name "VDD007" with the operating system.
#define INCL_DOSMVDM /* Multiple DOS sessions values */
#define INCL_DOSERRORS /* DOS Error values */
#include <os2.h>
#include <stdio.h>
UCHAR VDDName[10] = "VDD007"; /* Name of VDD */
HVDD VDDHandle = NULLHANDLE; /* Handle of VDD */
SGID SessionID = 0; /* Session identifier (should be initialized */
ULONG Command = 3; /* VDD function code (hypothetical) */
APIRET rc = NO_ERROR; /* Return code */
UCHAR InputBuffer[30] = "Your command here"; /* Command information */
UCHAR OutputBuffer[30] = ""; /* Output data (returned) */
rc = DosOpenVDD(VDDName, &VDDHandle);
if (rc != NO_ERROR) {
printf("VDD %s was not found.\n", rc);
return 1;
}
rc = DosRequestVDD(VDDHandle, /* Handle of VDD */
SessionID, /* Session ID */
Command, /* Command to send to VDD */
sizeof(InputBuffer), /* Length of input */
InputBuffer, /* Input buffer */
sizeof(OutputBuffer), /* Length of output area */
OutputBuffer); /* Output from command */
if (rc != NO_ERROR) {
printf("DosRequestVDD error: return code = %u\n", rc);
return 1;
}
rc = DosCloseVDD(VDDHandle); /* Close the VDD */
if (rc != NO_ERROR) {
printf("DosCloseVDD error: return code = %u\n", rc);
return 1;
}