Edit

Commands (WPD API)

  • Article

The client application and the driver communicate by means of commands that are sent from the client (via the Windows Portable Device API) to the driver (via the User-Mode Driver Framework). A command may or may not include a parameter, and may or may not return a result. A client can send a command explicitly, by calling either the IPortableDevice::SendCommand method or the IPortableDeviceService:SendCommand method, or implicitly, by calling any of the methods of the client interfaces. A few commands can only be sent explicitly; these are noted in the command's documentation. The command reference pages describe the purpose of a command, as well as what parameters it expects to receive, and what parameters it is expected to return.

A command is identified by a PROPERTYKEY structure. This is made up of two parts: a GUID part (the fmtid member) and a DWORD part (the pid member). The GUID part is used to indicate the category the command belongs to (related commands belong to the same category, and therefore will have the same fmtid). The DWORD part indicates the command ID, and is used to distinguish the individual commands within a command category (the pid values for commands in the same category will be different).

The following table lists the categories of commands that Windows Portable Devices defines. Device manufacturers can define their own commands by creating their own command categories and command IDs. However, a manufacturer should not add commands to the categories listed below, since these are reserved by Microsoft.

Command Categories

Command category Description
WPD_CATEGORY_COMMON Commands that are common to all objects and devices.
WPD_CATEGORY_DEVICE_HINTS Commands that are used to retrieve optional device information that can be used to improve end-user experience.
WPD_CATEGORY_SMS Commands that are used for devices that support short message service (SMS) functionality, which is typically exposed on mobile phones.
WPD_CATEGORY_STILL_IMAGE_CAPTURE Commands that are used for devices that support still image capture.
WPD_CATEGORY_STORAGE Commands that are used for storage functional objects.

 

The specific commands that are defined for each of these types are given in the following tables, organized by command type.

WPD_CATEGORY_COMMON Category

Command Description
WPD_COMMAND_COMMON_RESET_DEVICE Resets the device.

 

WPD_CATEGORY_DEVICE_HINTS Category

Command Description
WPD_COMMAND_DEVICE_HINTS_GET_CONTENT_LOCATION Retrieves the object IDs of folders that can hold an object of a specified type.

 

WPD_CATEGORY_STORAGE Category

Command Description
WPD_COMMAND_STORAGE_EJECT Ejects a storage medium that can be ejected remotely by the driver.
WPD_COMMAND_STORAGE_FORMAT Formats a storage functional object on the device.

 

WPD_CATEGORY_SMS Category

Command Description
WPD_COMMAND_SMS_SEND Initiates the sending of an SMS message by an SMS functional object.

 

WPD_CATEGORY_STILL_IMAGE_CAPTURE Category

Command Description
WPD_COMMAND_STILL_IMAGE_CAPTURE_INITIATE Initiates a still image capture by a still image functional object.

 

Programming Reference