DosDevIOCtl
Syntax
Performs control functions on a device specified by an opened device handle.
#define INCL_DOSDEVICES
#define INCL_DOSDEVIOCTL
#include <os2.h>
[[hDevice]]; /* Device handle returned by [[DosOpen]], or a standard (open) device handle. */
[[category]]; /* Device category. */
[[function]]; /* Device-specific function code. */
[[pParams]]; /* Address of the command-specific argument list. */
[[cbParmLenMax]]; /* Length, in bytes, of ''pParams''. */
[[pcbParmLen]]; /* Pointer to the length of parameters. */
[[pData]]; /* Address of the data area. */
[[cbDataLenMax]]; /* Length, in bytes, of ''pData''. */
[[pcbDataLen]]; /* Pointer to the length of data. */
[[ulrc]]; /* Return Code. */
ulrc = DosDevIOCtl(hDevice, category, function,
pParams, cbParmLenMax, pcbParmLen,
pData, cbDataLenMax, pcbDataLen);
Parameters
hDevice (HFILE) - input
Device handle returned by DosOpen, or a standard (open) device handle.
category (ULONG) - input
Device category.
The valid range is 0 to 255.
function (ULONG) - input
Device-specific function code.
The valid range is 0 to 255.
pParams (PVOID) - input
Address of the command-specific argument list.
cbParmLenMax (ULONG) - input
Length, in bytes, of pParams.
This is the maximum length of the data to be returned in pParams. pcbParmLen may be larger than this on input, but not on output.
pcbParmLen (PULONG) - in/out
Pointer to the length of parameters.
Input
Pointer to the length, in bytes, of the parameters passed in pParams. by the application. Output
Pointer to the length, in bytes, of the parameters returned.
If this function returns ERROR_BUFFER_OVERFLOW, then pcbParmLen points to the size of the buffer required to hold the parameters returned. No other data is returned in this case.
pData (PVOID) - input
Address of the data area.
cbDataLenMax (ULONG) - input
Length, in bytes, of pData.
This is the maximum length of the data to be returned in pData. pcbDataLen may be larger than this on input, but not on output.
pcbDataLen (PULONG) - in/out
Pointer to the length of data.
Input
Pointer to the length, in bytes, of the data passed by the application in pData. Output
Pointer to the length, in bytes, of the data returned.
If this function returns ERROR_BUFFER_OVERFLOW, then pcbDataLen points to the size of the buffer required to hold the data returned.
ulrc (APIRET) - returns
Return Code.
DosDevIOCtl returns one of the following values:
NO_ERROR 1
ERROR_INVALID_FUNCTION 6
ERROR_INVALID_HANDLE 15
ERROR_INVALID_DRIVE 31
ERROR_GEN_FAILURE 87
ERROR_INVALID_PARAMETER 111
ERROR_BUFFER_OVERFLOW 115
ERROR_PROTECTION_VIOLATION 117
ERROR_INVALID_CATEGORY 119
ERROR_BAD_DRIVER_LEVEL 163
ERROR_UNCERTAIN_MEDIA 165
ERROR_MONITORS_NOT_SUPPORTED For a full list of error codes, see Errors.
Returns
ulrc (APIRET) - returns
Return Code.
DosDevIOCtl returns one of the following values:
NO_ERROR
ERROR_INVALID_FUNCTION
ERROR_INVALID_HANDLE
15
ERROR_INVALID_DRIVE 31
ERROR_GEN_FAILURE 87
ERROR_INVALID_PARAMETER 111
ERROR_BUFFER_OVERFLOW 115
ERROR_PROTECTION_VIOLATION 117
ERROR_INVALID_CATEGORY 119
ERROR_BAD_DRIVER_LEVEL 163
ERROR_UNCERTAIN_MEDIA 165
ERROR_MONITORS_NOT_SUPPORTED For a full list of error codes, see Errors.
Remarks
Values returned in the range 0xFF00 through 0xFFFF are user-dependent error codes. Values returned in the range 0xFE00 through 0xFEFF are device-driver-dependent error codes.
This function provides a generic, expandable IOCtl facility.
A null (zero) value for pData specifies that this parameter is not defined for the generic IOCtl function being specified. A null value for pData causes the values passed in cbDataLenMax and pcbDataLen to be ignored.
A null (zero) value for pParams specifies that this parameter is not defined for the generic IOCtl function being specified. A null value for pParams causes the values passed in cbParmLenMax and pcbParmLen to be ignored.
The kernel formats a generic IOCtl packet and calls the device driver. Because OS/2 Version 1.0 and Version 1.1 device drivers do not understand generic IOCtl packets with cbDataLenMax, pcbDataLen, cbParmLenMax, and pcbParmLen, the kernel does not pass these fields to the device driver. Device drivers that are marked as level 2 or higher must support receipt of the generic IOCtl packets with associated length fields.
Do not pass a non-null pointer with a zero length.
See Generic IOCtl Commands for a complete listing of the generic IOCtl control functions (the IOCtl interface).
For debugging considerations, see DosDebug.
Example Code
The following is NOT a complete C program. It is simply intended to provide an idea of how to issue control functions to a device.
This example assumes that DevHandle contains the handle to the device, and
that the device recognizes category code hex 83, function code hex 1D and
the input parameters and input data area.
#define INCL_DOSDEVICES /* Device values */
#define INCL_DOSERRORS /* Error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
HFILE DevHandle = NULLHANDLE; /* Handle for device */
ULONG ulCategory = 0x83; /* Device category */
ULONG ulFunction = 0x1D; /* Device-specific function */
UCHAR uchParms[120] = {0}; /* Input and output for function */
ULONG ulParmLen = 0; /* Input and output parameter size */
UCHAR uchDataArea[200] = {0}; /* Input and output data area */
ULONG ulDataLen = 0; /* Input and output data size */
APIRET rc = NO_ERROR; /* Return code */
strcpy(uchParms,"/X /Y /Z"); /* Input parameters */
ulParmLen = strlen(uchParms); /* Length of input parameters */
strcpy(uchDataArea,"DF=123;NP=BCR;UN=1993;MAX=328"); /* Input data */
ulDataLen = strlen(uchDataArea); /* Length of data */
rc = DosDevIOCtl(DevHandle, /* Handle to device */
ulCategory, /* Category of request */
ulFunction, /* Function being requested */
uchParms, /* Input/Output parameter list */
sizeof(uchParms), /* Maximum output parameter size */
&ulParmLen, /* Input: size of parameter list */
/* Output: size of parameters returned */
uchDataArea, /* Input/Output data area */
sizeof(uchDataArea), /* Maximum output data size */
&ulDataLen); /* Input: size of input data area */
/* Output: size of data returned */
if (rc != NO_ERROR) {
printf("DosDevIOCtl error: return code = %u\n", rc);
return 1;
}
Related Functions
- DosBeep
- DosDevConfig
- DosPhysicalDisk