OEMIoControl (Compact 2013)

Article
03/16/2015

10/16/2014

This function provides a generic I/O control code (IOCTL) for OEM-supplied information.

Syntax

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

Parameters

dwIoControlCode
[in] IOCTL, which can be pre-defined, or any OEM-defined control code. For more information, see OAL IOCTLs.

lpInBuf
[out] Pointer to the input buffer that can contain additional information associated with dwIoControlCode.

For example, when dwIoControlCode is set to IOCTL_HAL_GET_DEVICE_INFO, this parameter can contain an SPI code. For more information, see SystemParametersInfo.

nInBufSize
[in] Size in bytes of lpInBuf.

For example, when dwIoControlCode is set to IOCTL_HAL_GET_DEVICE_INFO and the input buffer contains the SPI code, nInBufsize is set to the value 4.

lpOutBuf
[out] Pointer to the output buffer supplied by the caller.

Your implementation should place the information requested by dwIoControlCode and lpInBuf into this parameter*,* set lpBytesReturned to indicate the size of the data in this parameter, and return TRUE.

If the size of the requested information exceeds the buffer size specified by nOutBufSize, call the function SetLastError using the ERROR_INSUFFICIENT_BUFFER flag and return FALSE.

nOutBufSize
[in] Specifies the maximum number of bytes that can be returned in lpOutBuf.

The caller sets this value.

lpBytesReturned
[in] Number of bytes returned inlpOutBuf.

Return Value

TRUE indicates success. FALSE indicates failure.

Remarks

This function is the means of returning system information requested by the SystemParametersInfo function. This function must be implemented. When a device driver or routine calls the KernelIoControl kernel routine to pass an IOCTL, the kernel calls this function.

The system can be pre-empted when this function is called. The kernel does no processing but passes all parameters directly to this function. The kernel function is provided to allow an OEM device driver to communicate with kernel mode OAL code.

From within this function, you can make Windows Embedded Compact API calls.

When adding custom IOCTLs handled by this function, the last identifier used is equal to 67 for kernel IOCTLs based on FILE_DEVICE_HAL.

Function codes 0 through 2047 are reserved for Microsoft; codes 2048 through 4095 are reserved for customers.

Currently, internal product teams and external customers are using values in the range of 1000 through 1100.

Best Practices

Calls to this function go through a kernel mode component (oalioctl.dll). This component has a list of user-accessible OAL IOCTL codes. If the call from user application is for one of the IOCTLs listed in this module, then the call is forwarded to the OAL code. Otherwise the calls form user mode applications are rejected. This does not impact calls to this function from kernel mode drivers.

OEM can add or delete an IOCTL code from this list by updating the following source file: %_WINCEROOT%\public\common\oak\oalioctl\oalioctl.cpp.

By default only the following OAL IOCTL codes are allowed from user mode applications:

Starting with Windows Embedded Compact 2013, IOCTL_HAL_GET_DEVICEID and IOCTL_HAL_GET_UUID are deprecated. They have been functionally replaced by new SPI_* codes in IOCTL_HAL_GET_DEVICE_INFO.

Requirements

Library

OEMMain.lib or OEMMain_StaticKITL.lib