IWMDMDevice3::DeviceIoControl

  • Article
banner art

The DeviceIoControl method sends a Device I/O Control (IOCTL) code to the device. This is a pass-through method; Windows Media Device Manager just forwards the call to the service provider after validating the parameters.

Syntax

HRESULT DeviceIoControl(DWORDdwIoControlCode,BYTE*lpInBuffer,DWORDnInBufferSize,BYTE*lpOutBuffer,LPDWORDpnOutBufferSize);

Parameters

dwIoControlCode

[in]  Control code to send to the device. When calling this method on an MTP device, use the value IOCTL_MTP_CUSTOM_COMMAND defined in MtpExt.h included with the SDK.

lpInBuffer

[in]  Optional pointer to an input buffer supplied by the caller. It can be NULL if nInBufferSize is zero. When calling this method on an MTP device, you can pass in the MTP_COMMAND_DATA_IN structure.

nInBufferSize

[in]  Size of the input buffer, in bytes. When calling this method on an MTP device, you can use the macro SIZEOF_REQUIRED_COMMAND_DATA_IN to specify the size.

lpOutBuffer

[out]  Optional pointer to the output buffer supplied by the caller. It can be NULL if pnOutBufferSize points to a value of zero. When calling this method on an MTP device, you can pass in the MTP_COMMAND_DATA_OUT structure.

pnOutBufferSize

[in, out]  Size of the output buffer, in bytes. When the call returns, it specifies the number of bytes actually returned. When calling this method on an MTP device, this parameter will not specify the output buffer size. Instead, the method will return HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) if the buffer is too small.This parameter cannot be NULL.

Return Values

The method returns an HRESULT. All the interface methods in Windows Media Device Manager can return any of the following classes of error codes:

  • Standard COM error codes
  • Windows error codes converted to HRESULT values
  • Windows Media Device Manager error codes

For an extenstive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table. If the method fails with an error, it returns a standard error code.

Return code Description
S_OK The method succeeded.
E_INVALIDARG One or more of the parameters are invalid. This is possible if

a) lpInBuffer is NULL when nInBufferSize is non-zero.

b) lpOutBuffer is NULL when pnOutBufferSize points to a non-zero value.

c) pnOutBufferSize is NULL.

d) Any of the parameters is invalid for the service provider.
ERROR_INSUFFICIENT_BUFFER The given output buffer was too small. When calling this method on an MTP device, this error indicates that there was not enough space for both the MTP_COMMAND_DATA_OUT structure and the binary data supplied by the device. If this error occurs, the application should continue to invoke this method with increasingly larger buffers until the method succeeds.
WMDM_E_NOTSUPPORTED The service provider or device does not support this method or control code.

Remarks

This method provides a private mode of communication between the application and the service provider. The service provider can then process this IOCTL, optionally modify it, and pass it to the kernel mode driver.

Compared to IWMDMDevice::SendOpaqueCommand, this method better aligns with the DeviceIoControl Windows API because the output buffer is supplied by the caller. Also, unlike IWMDMDevice::SendOpaqueCommand, this method does not involve any MAC check and is more efficient.

This method can be used, for example, to send custom Media Transport Protocol (MTP) commands to an MTP device.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also