DosDevIOCtl

Performs control functions on a device specified by an opened device handle.

Syntax
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.

Return Code

 * ulrc (APIRET) - returns:DosDevIOCtl returns one of the following values:
 * 0 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

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.
 * 1) define INCL_DOSDEVICES  /* Device values */
 * 2) define INCL_DOSERRORS   /* Error values */
 * 3) include 
 * 4) include 
 * 5) include 

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