KernelIoControl

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function provides the kernel with a generic I/O control for carrying out I/O operations.

Syntax

BOOL KernelIoControl(
  DWORD dwIoControlCode,
  LPVOID lpInBuf,
  DWORD nInBufSize,
  LPVOID lpOutBuf,
  DWORD nOutBufSize,
  LPDWORD lpBytesReturned
);

Parameters

• dwIoControlCode
  [in] I/O control code, which should support the OAL I/O controls**

• lpInBuf
  [in] Pointer to a buffer that contains the data required to perform the operation.

  Set to NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

• nInBufSize
  [in] Size, in bytes, of the buffer pointed to by lpInBuf.

• lpOutBuf
  [out] Pointer to a buffer that receives the output data for the operation.

  Set to NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

• nOutBufSize
  [in] Size, in bytes, of the buffer pointed to by lpOutBuf.

• lpBytesReturned
  [in] Long pointer to a variable that receives the size, in bytes, of the data stored in the buffer pointed to by lpOutBuf. Even when an operation produces no output data, and lpOutBuf is NULL, the KernelIoControl function uses the variable pointed to by lpBytesReturned. After such an operation, the value of the variable has no meaning.

Return Value

TRUE indicates success. FALSE indicates failure.

Remarks

** This function is also called when the SystemParametersInfo function is called with SPI_GETOEMINFO or SPI_GETPLATFORMINFO. The system is fully preemptible when this function is called. The kernel does no processing, but it passes all parameters directly to the function supplied by you. This function is provided solely to allow your device driver or application to communicate with an OAL and its specific functionality.

An IOCTL call has this prototype:

BOOL KernelIOControl(UINT32 code, VOID* pInpBuffer, UINT32 inpSize, VOID* pOutBuffer, UINT32 outSize, UINT32 *pOutSize);

Assuming the caller passes a valid pOutSize pointer:

1. If an IOCTL will never return data in *pOutBuffer, then set *pOutSize = 0 regardless of success or failure.
2. If an IOCTL caller passes in otherwise correct parameters with a buffer that is too small (as determined by examining nOutSize), we will fail with ERROR_INSUFFICIENT_BUFFER and return *pOutSize = minimum buffer size necessary for success.
3. If an IOCTL caller passes in correct parameters with a sufficient buffer (nOutSize >= necessary size), we will return *pOutSize = # of bytes in the buffer that we actually filled upon completion (regardless of success or failure).

Requirements

See Also

Reference

System Management Functions

Other Resources

SystemParametersInfo