OEMIoControl (Windows Embedded CE 6.0)

1/5/2010

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 the dwIoControlCode parameter.

  For example, when dwIoControlCode is set to IOCTL_HAL_GET_DEVICE_INFO, lpInBuf 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 the dwIoControlCode and lpInBuf parameters into lpOutBuf, set lpBytesReturned to indicate the size of the data in lpOutbuf, 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 in lpOutBuf.

Return Value

If this function succeeds, it returns TRUE.

If this function fails, it returns FALSE.

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

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 CE API calls.

When adding custom IOCTLs handled by OEMIoControl, 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

In Windows Embedded CE 6.0, calls to OEMIoControl** 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 OEMIoControl 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:

• IOCTL_HAL_GET_CACHE_INFO
• IOCTL_HAL_GET_DEVICE_INFO
• IOCTL_HAL_GET_DEVICEID
• IOCTL_HAL_GET_UUID
• IOCTL_PROCESSOR_INFORMATION

Starting with Windows Embedded CE 6.0, 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. For more information, see Device Information IOCTL Unification.

Requirements

See Also

Reference

Required OAL Functions
OEMSetRealTime
IOCTL_HAL_GET_CACHE_INFO
IOCTL_HAL_GET_DEVICE_INFO
IOCTL_HAL_GET_DEVICEID
IOCTL_HAL_GET_UUID
IOCTL_PROCESSOR_INFORMATION

Concepts

Implementing the OEMIoControl Function
Device Information IOCTL Unification

Other Resources

KernelIoControl
SetKernelCommDev
SystemParametersInfo