DosDevIOCtl

Description

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

Syntax

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

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.

 #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