Windows Portable Devices Team Blog : PTP

Cancellation Behavior of MTP USB Devices

wpdblog — Sun, 15 Apr 2007 19:01:00 GMT

The MTP Specification contains this definition of the CancelTransaction Event:

G.2.2 CancelTransaction
Event Code: 0x4001
Parameter 1: None
Parameter 2: None
Parameter 3: None

This event is used to initiate the cancellation of a transaction over transports which do not have their own mechanism for canceling transactions. The details of how a transaction is cancelled may be transport-specific. When an initiator or responder receives this event, it should cancel the transaction identified by the TransactionID in the event dataset. If the transaction has already completed, this event should be ignored.

After receiving a CancelTransaction event from the initiator during an object transfer, the responder should send an Transaction_Cancelled response for the transfer which was in progress.

MTP USB Transport Cancellation Behavior

Why then does an MTP/USB device send a Status_OK (0x2001) instead of Transaction_Cancelled (0x201F) response when it receives a CancelTransaction (0x4001) from the application?

The reason is that the MTP USB transport has defined how cancellation is to be implemented. As pointed out in the MTP Specification above, CancelTransaction is intended for "transports which do not have their own mechanism for canceling transactions", and will not apply to MTP/USB devices.

Here are the MTP/USB specifications for each cancellation scenario. In the cases below, "Host" can be a PC running Windows Media Player 11, and "Device" can be a MTP music player or a PTP camera that connects to the PC through USB.

Case A. When the Host Cancels
When the device receives a cancellation request from the host, it should return Device_Busy (0x2019) for a GetDeviceStatus query. The device should then perform cancellation and clean up, and return Status_OK (0x2001) for subsequent GetDeviceStatus requests. The device should NOT send a response for the cancelled transaction through the BULK-IN pipe.

After the host receives a Status_OK response from a GetDeviceStatus query on the device, it may issue the next transaction through the BULK-OUT pipe.

Case B. When the Device Cancels
If the device wants to cancel, it should STALL both BULK-IN and BULK-OUT endpoints. When the device receives a GetDeviceStatus request from host, the device should return Transaction_Cancelled (0x201F) as the reason for the STALL, and the STALL-ed endpoint numbers.

The host may then issue the ClearFeature request to clear the STALL-ed endpoints. The device should clear, get ready for next command, and return Status_OK for next GetDeviceStatus query.

Case C. When the Host and Device Both Cancel
When the device receives a cancel request from the host while it is trying to cancel, it should clear any pending device-initiated cancellations, respond to the host with Device_Busy (0x2019) for subsequent GetDeviceStatus requests, and proceed with normal host-initiated cancellation.

When the device wants to cancel (this could be initiated by the user), it first checks if there are any pending host-initiated cancellation. If yes, the device can simply return. If not, the device should STALL the BULK endpoints.

Cancellation Examples

For cancellation examples, refer to the Picture Transfer Protocol (PTP) Specification - ISO 15740 Annex D: Sections D.7.2.1.2 (for device behavior) and D.9, available on the I3A PTP website.

In addition, the PTP USB Transport specification also contains a definition for the GetDeviceStatus and further descriptions of the BULK cancellation behavior.

This posting is provided "AS IS" with no warranties, and confers no rights.

WIA Camera Support in Windows Vista (Part 2 of 2)

wpdblog — Tue, 13 Feb 2007 21:33:00 GMT

In the previous post, we gave an overview of the WIA-WPD Compatibility Layer and how WIA Applications can register for WIA_EVENT_DEVICE_CONNECTED events.

In this post, we will cover a more advanced topic: customization for PTP and MTP devices. The WIA-WPD Compatibility Layer supports basic extensibility for custom WIA events and WIA properties. These events and properties were provided in the PTP WIA class driver that shipped with Windows XP.

Adding Custom PTP/MTP WIA Event Codes

To specify a list of supported PTP/MTP event codes the 'WiaEventCodes' entry should be provided.

The following example shows 3 custom event codes being reported.

HKR,,"WiaEventCodes",”0x0001,0x0002,0x0003”

For each event code specified in the 'WiaEventCodes' entry, a corresponding 'WiaEventCodeXXX' entry must exist that specifies the name of the event and the GUID to use when reporting the event to WIA applications. The entry should be constructed using the prefix ‘WiaEventCode + the event code specified in WiaEventCodes entry’. If the WiaEventCodeXXX entry is missing, the event will not be reported to WIA applications.

HKR,,"WiaEventCode0x0001”,”{20179E3D-139C-40D3-A0CA-962B33D67EE3},My Custom Event”
HKR,,"WiaEventCode0x0002”,”{259A62CF-D8FE-44D0-A747-B14F54A02133},My Amazing Event”
HKR,,"WiaEventCode0x0003”,”{639F80C6-94D1-48E2-9D8E-6D0F12237E48},My Super Event”

Adding Custom PTP/WIA Property Codes

To specify a list of supported PTP/MTP property codes the ‘WiaPropertyCodes’ entry should be provided. WIA properties will only appear on the root item. These properties are commonly used to control/program the device.

The following example shows 3 custom property codes being reported.

HKR,,"WiaPropertyCodes",”0x0001,0x0002,0x0003”

For each property code specified in the ‘WiaPropertyCodes’ entry, a corresponding ‘WiaPropertyCodeXXX’ entry must exist that specifies the name of the property and the WIA property code to use when reporting the property to WIA applications. The entry should be constructed using the prefix ‘WiaPropertyCode + the property code specified in WiaPropertyCodes entry’. If the WiaPropertyCodeXXX entry is missing, the event will not be reported to WIA applications.

HKR,,"WiaPropertyCode0x0001”,”My Custom Device Property”
HKR,,"WiaPropertyCode0x0002”,”My Amazing Device Property”
HKR,,"WiaPropertyCode0x0003”,”My Super Device Property”

Sending PTP Custom Commands through WIA

PTP extension commands can be sent to the vendor's driver using IWiaItemExtras::Escape. In Windows Vista, the WIA-WPD Compatibility Layer repackages PTP extension commands sent using this method into WPD MTP/PTP extension commands, which are dispatched to the WPD MTP class driver. This mechanism exists to support legacy WIA vendor applications that relied on custom PTP commands from Windows XP.

Sending MTP Custom Commands through WPD

WPD supports sending of custom MTP commands to the MTP driver using the IPortableDevice::SendCommand API. For a step-by-step description, visit DimeBy8's excellent post here.

WIA to WPD Content Type and Format Mapping

The following table maps WIA Item Types to the WPD_OBJECT_CONTENT_TYPE.

In addition to video and image content, the WIA-WPD Compatiliby Layer supports thumbnails and audio annotations for objects that have them. Any data objects that do not fall under these categories (e.g. music files) will not appear in WIA applications.

WPD Object	WPD Content Type	WIA Item	WIA Item Type
Device object	N/A	Root item	(WiaItemTypeFolder \| WiaItemTypeDevice \| WiaItemTypeRoot)
Folder object	WPD_CONTENT_TYPE_FOLDER	Folder Item	WiaItemTypeFolder
Functional Object	WPD_CONTENT_TYPE_FUNCTIONAL_OBJECT	Folder Item	WiaItemTypeFolder
Image Object	WPD_CONTENT_TYPE_IMAGE	Image Item	(WiaItemTypeImage \| WiaItemTypeFile \| WiaItemTypeTransfer)
Video Object	WPD_CONTENT_TYPE_VIDEO	Video Item	(WiaItemTypeVideo \| WiaItemTypeFile \| WiaItemTypeTransfer)
Audio Object (used for annotations)	WPD_CONTENT_TYPE_AUDIO	Audio Item	(WiaItemTypeAudio \| WiaItemTypeFile \| WiaItemTypeTransfer)
Other objects	WPD_CONTENT_TYPE_XXXX	N/A (These are ignored)	N/A (These are ignored)

The following table maps the WIA_IPA_Format property to the WPD_OBJECT_FORMAT property:

WIA_IPA_FORMAT

The formats will be mapped as follows:

WiaImgFmt_EXIF	WPD_OBJECT_FORMAT_EXIF
WiaImgFmt_JPEG	WPD_OBJECT_FORMAT_JFIF
WiaImgFmt_PNG	WPD_OBJECT_FORMAT_PNG
WiaImgFmt_GIF	WPD_OBJECT_FORMAT_GIF
WiaImgFmt_TIFF	WPD_OBJECT_FORMAT_TIFF
WiaAudFmt_WAV	WPD_OBJECT_FORMAT_WAVE
WiaAudFmt_MP3	WPD_OBJECT_FORMAT_MP3
WiaAudFmt_AIFF	WPD_OBJECT_FORMAT_AIFF
WiaAudFmt_WMA	WPD_OBJECT_FORMAT_WMA
WiaImgFmt_MPG	WPD_OBJECT_FORMAT_MPEG
WiaImgFmt_AVI	WPD_OBJECT_FORMAT_AVI
WiaImgFmt_ASF	WPD_OBJECT_FORMAT_ASF

Configuration of the WIA-WPD Compatibility Layer

The following section lists the customization options in the WIA-WPD Compatibility Layer that can be disabled/enabled by the device's INF [AddReg] section:

Report EXIF Image Format as JPG

Some WIA applications expect the EXIF image format to be reported as WiaImgFmt_JPG and not WiaImgFmt_EXIF. To "opt-in" for this functionality, vendors can add the following to your device's INF:

HKR,,"ReportJPGFormatForEXIF",0x10001,1

WIA Item Tree Behavior for DCF

If the WIA-WPD Compatibility layer encounters a storage that supports DCF, it will ‘shift’ the WIA item tree contents closer to the root item so items are easily found. This will reduce the number of folder levels an application or user will have to navigate to get to the image or video content stored on the device. This functionality can be disabled by adding the following to your device’s .INF [AddReg] section.

HKR,,"DisableDCFSpecialProcessing",0x10001,1

This posting is provided "AS IS" with no warranties, and confers no rights.

WIA Camera Support in Windows Vista (Part 1 of 2)

wpdblog — Tue, 13 Feb 2007 11:23:00 GMT

In this two-part post, we will cover WIA support for cameras on Windows Vista, and the migration from WIA to WPD for richer applications.

WIA-WPD Compatibility Layer

On Windows XP, Picture Transfer Protocol (PTP) cameras are accessible through the WIndows Image Acquisition (WIA) infrastructure. This is still supported on Windows Vista through the WIA-WPD Compatibility Layer (PortableDeviceWiaCompat.dll). This component is a WIA mini-driver that communicates to the inbox Media Transfer Protocol (MTP) class driver using the WPD API.

The following classes of devices have the WIA-WPD Compatibility Layer enabled:

1. PTP Cameras

2. MTP devices that report WPD_DEVICE_TYPE_CAMERA (subcomp = 2) or WPD_DEVICE_TYPE_VIDEO (subcomp = 6)

3. WPD devices that support WPD_CONTENT_TYPE_VIDEO or WPD_CONTENT_TYPE_IMAGE, and with the lowest bit set in the EnableLegacySupport entry under Device Parameters. This can be set in the driver INF:

HKR,,"EnableLegacySupport",0x10001,1

WIA Event Registration for Cameras

On Windows Vista, WIA imaging applications communicate to PTP cameras via the WPD-WIA Compatibility Layer and the Media Transfer Protocol (MTP) class driver. Windows Autoplay is supported, third party applications can register for WIA device-connected events and appear in the autoplay dialog. Note that some third-party WIA applications may require Elevation ("Run as Administrator") at first launch to in order to successfully register for WIA events.

1. Only Global WIA Event Registration for WIA_EVENT_DEVICE_CONNECTED is supported. Any WIA application that registers for this event will be listed in the Windows Autoplay dialog when any WIA-compatible PTP camera is connected.

2. Supported registration mechanisms: STI Proxy registration (IStillImage::RegisterLaunchApplication), WIA CLSID registration (IWiaDevMgr::RegisterEventCallbackCLSID), and WIA Program registration (IWiaDevMgr::RegisterEventCallbackProgram).

Custom Vendor Events

To enable Device-Specific WIA Event Registration for custom vendor events, there is an "opt-in" mechanism. There are 2 steps to this:

Step 1: The vendor camera driver INF will need to add the UseWiaAutoPlay setting in the Device Parameters section in the registry. This is a DWORD setting. If set to 1, the WPD-WIA Compatiliby Layer will mark "device connected" and custom vendor events as "action events." If unset, the default value is 0 (WIA autoplay is disabled).

HKR,,"UseWiaAutoPlay",0x10001,1

Step 2: The vendor's application calls the IWiaDevMgr APIs to create a Device-specific WIA event registration for their custom WIA event.

The overall effect of enabling device-specific registration is the WIA Autoplay dialog will appear for the custom event. This XP-style dialog is implemented by the WIA Service. It is recommended that applications only register via Windows Autoplay or WIA Autoplay, but not both. Windows Autoplay registration is preferred.

Image and Video Acquisition

On Windows Vista, the camera image import functionality of the Scanner and Camera Wizard is replaced by the Photo Acquisition Wizard and the Windows Photo Gallery. This is also known as the "Importing Pictures and Videos" dialog.

The Photo Acquisition wizard communciates to PTP cameras using WPD APIs (more specifically, it uses the WPD Namespace Extension). It does not use the WIA APIs.

Video Content Support

Video content support is removed from WIA for Windows Vista. The effect is video content on your device will not appear in WIA applications running on Windows Vista.

To access video content from your device, we recommend migrating your applciation to use the WPD API. WPD provides broader content coverage (supports both video and image content) on Windows Vista for camera devices. For instance, the Vista Photo Acquisition Wizard uses WPD to retrieve pictures and video from PTP devices.

For ease of migration, there is usually a straighforward correlation from WIA metadata to WPD object properties. For example, WiaImgFmt_AVI corresponds to WPD_CONTENT_TYPE_VIDEO and WPD_OBJECT_FORMAT_AVI. For more details, refer to the WPD video properties and video format GUIDs on MSDN.

Next Post...

Watch the next post for more details on custom PTP vendor commands through the WIA Escape mechanism, custom WIA property and event codes.

This posting is provided "AS IS" with no warranties, and confers no rights.