Windows Media Device Manager 11 SDK (deprecated)

This topic documents a feature of the Windows Media Device Manager SDK. We recommend that you migrate your application to use the Windows Portable Devices API. For more information, see the Windows Portable Devices SDK.

The Microsoft® Windows Media® Device Manager Software Development Kit (SDK) enables you to build desktop applications and components that can communicate with connected portable devices. Windows Media Device Manager enables your application or component to enumerate, explore, and exchange files with a device, query for metadata, and request play count information. Applications or components built on Windows Media Device Manager have a consistent API for communicating with a wide range of devices including Media Transfer Protocol (MTP), Mass Storage Class (MSC), RAPI, and other devices built on both the latest and previous versions of Windows Media technology.

You can build the following items using the Windows Media Device Manager SDK:

  • Desktop applications, such as custom media players. All communication between an application and a portable device must go through Windows Media Device Manager, which acts as a broker between the application, the Microsoft digital rights management system, and the service provider.
  • Service providers, which act as the communication link between a custom device and a desktop application. Although Microsoft provides a number of service providers that can communicate with most devices out of the box, you can build a custom service provider to customize the communication between a device and a desktop application.
  • Plug-ins, which can perform tasks such as requesting and logging play counts on devices. These plug-ins can be attached to other desktop applications, such as the Windows Media Player to send information to content providers to handle royalty payments to artists.

To download the Windows Media Device Manager SDK, see the Windows Media Download page on the MSDN Web site.

This SDK is a component of the Microsoft Windows Media Software Development Kit. Other components include the Windows Media Format SDK, the Windows Media Services SDK, the Windows Media Encoder SDK, the Windows Media Rights Manager SDK, and the Windows Media Player SDK.

This documentation includes the following sections.

Section | Description
Getting Started | Describes what is new in this version of Windows Media Device Manager, gives an overview of how Windows Media Device Manager works, describes what will be needed to develop an application or service provider, and explains the samples shipped with the SDK.
Programming Guide | Discusses how to build applications and service providers.
Programming Reference | Provides C++ reference information for the interfaces, methods, classes, and structures supported by the Windows Media Device Manager SDK.
Glossary | Defines terms used in this documentation.

Next

© 2006 Microsoft Corporation. All rights reserved.


Getting Started

This section provides the basic information you need to get started developing applications and service providers that use Windows Media Device Manager. This section includes the following topics.

Topic | Description
What's Included with the SDK | Describes the files included in this SDK.
Windows Media Device Manager Architecture | Gives a general overview of how Windows Media Device Manager works.
Tools for Development | Describes related SDKs that you may need, and the certificates and keys required for development.
Samples | Describes the two sample projects included with the SDK (one service provider and one application).

See Also

  • Windows Media Device Manager 11 SDK


What's Included with the SDK

The following table describes the contents of the Windows Media Device Manager SDK. All files or folders are described in relation to the root SDK installation path.

File | Description
WMDM\ | Top-level folder for the Windows Media Device Manager SDK. This folder includes the makefile for building all the sample applications.
idl\ | Folder that contains all the IDL files required to build headers needed for Windows Media Device Manager methods. However, instead of using these files, you can use the header files supplied in the inc\ folder. To see a list of these IDL files, and to learn which header files are built from which IDL files, see Compiling the IDL Files Supplied with the SDK.
inc\ .... | Folder that includes all the headers that define the interfaces and data types in this SDK.
mswmdm.h | Defines all the application interfaces, service provider interfaces, secure content provider interfaces, error codes, constants, structures, and the IComponentAuthenticate interface.
mswmdm_i.c | Defines the IWMDMNotification interface.
MtpExt.h | Defines MTP-specific structures required for applications calling IWMDMDevice3::DeviceIoControl.
resource.h | Defines various resource constants used by the SDK samples.
sac.h | Defines secure authenticated channel data required by all applications and service providers.
scclient.h | Defines the CSecureChannelClient class required by all applications.
scserver.h | Defines the CSecureChannelServer class required by all service providers.
wmdm_ver.h | Optional version information about Windows Media Device Manager.
wmdmlog.h, wmdmlog_i.c | Required for applications or service providers that use the IWMDMLogger interface.
wmdrmdeviceapp.h | Required for applications that handle content metering (see Metering Content Usage).
wmsstd.h | Defines helper macros used by the SDK samples.
lib\ | Folder that holds the Windows Media Device Manager libraries.
mssachlp.lib | The static library required by all Windows Media Device Manager applications and service providers.
drmcrypto.lib | The static library required by all Windows Media Device Manager applications and service providers that use DRM.
mdsp\ .... | Folder that contains the code for a sample service provider. For information about this sample, including how to compile and run it, see Sample Service Provider.
apps\ .... | Folder that contains two subfolders that hold two halves of the code for a sample desktop application provided with the SDK. For information about this sample, including how to compile it, see Sample Desktop Application.
devicekit\ .... | Folder that contains a suite of tools for testing your portable device using Windows Media Device Manager 11. Testing includes device and file enumeration and transfer, DRM capabilities, and MTP compliance. These tools have their own documentation file.

See Also

  • Getting Started


Windows Media Device Manager Architecture

Windows Media Device Manager enables an application or plug-in to communicate with a device. Applications can request device metadata, enumerate and explore attached devices, and send or receive objects (folders, files, playlists, and so on). Windows Media Device Manager provides a single API to the calling application, no matter what type of device is being called (MTP or Mass Storage Class, service providers built on version 10 or service providers built on earlier versions of Windows Media Device Manager).

Windows Media Device Manager acts as a go-between for the three major components of the system: the application, which makes requests (for information, to read or write data, and so on); a secure content provider, which is a component that handles communication with DRM-protected files; and a service provider, which receives requests from the application and communicates with the device to perform these requests. Both the application and the service provider are built on the Windows Media Device Manager SDK.

The following diagram shows how a desktop application communicates with a device using Windows Media Device Manager 11.

Diagram showing an application communicating with four different types of devices.

The preceding diagram shows an application communicating with four different types of devices, each with its own service provider. Every service provider is designed to communicate with a specific type of device; this diagram shows the three Microsoft-provided service providers (generic class drivers for Mass Storage Class devices, RAPI devices, and MTP devices), as well as a custom service provider for a proprietary device built by a third party. When a device connects, Windows Media Device Manager instantiates an instance of the service provider registered for that device. The service providers get requests from the application through Windows Media Device Manager interfaces that they implement, use appropriate drivers to communicate with the device, and return appropriate results. Communication between the service provider and the device is outside the domain of Windows Media Device Manager.

Service providers are invisible to the application; an application sees only a list of "devices" because Windows Media Device Manager exposes a standard set of methods and interfaces for all devices. If a manufacturer creates a custom service provider, it must handle all the standard Windows Media Device Manager methods if applications are to be able to use the device.

This diagram also shows a secure content provider (SCP) module. This module is responsible for handling digital rights management (DRM) protected content. Microsoft provides an SCP module that can handle DRM-protected WMA and WMV files. If an application or device intends to handle other protected formats, it must provide its own SCP module. Neither the application nor the service provider deals with the SCP directly.

Both the application and the service provider are built on Windows Media Device Manager, which routes calls between the application and the appropriate service provider for a device; the service provider is responsible for communicating directly with the device. Windows Media Device Manager does perform some actions itself (such as enumerating connected devices, routing calls, and handling component verification); however, most of the work is done by the service provider, which receives requests from the application and communicates with the device.

An application built on Windows Media Device Manager can communicate with devices and service providers built on earlier versions of Windows Media Device Manager; however, these older devices will be run through 9 Series components (not shown), and will not support the newest features, particularly the more advanced digital rights management technology.

Architecture of a Device

The following diagram shows a simplified hierarchy of devices and storages as seen by an application using Windows Media Device Manager.

Diagram showing storages on a device.

The preceding diagram shows a simplified version of a connected flash drive, as seen by a Windows Media Device Manager application. The flash drive has attributes and properties, such as a serial number and supported format configurations. An immediate child of the flash device is the root storage object, which contains a folder, which itself contains an image and a song.

An application enumerates the list of attached devices by calling an enumeration method exposed by the root IWMDeviceManager interface. Devices are represented by an IWMDMDevice (or a derived) interface. This interface exposes methods to retrieve the device name, format capabilities, serial number, and so on, as well as a method that enumerates storages on the device. In Windows Media Device Manager, a storage is any kind of object on the device, whether or not it is an actual blob of data. For example: audio files, text files, folders, playlists stored as files, and playlists stored as metadata are all considered storages, even though folders and metadata items probably do not represent a physical file. The type (or format) of a storage can be retrieved by calling GetAttributes (or GetMetadata, requesting the format of the storage).

Storages on a device are stored hierarchically, and all devices have a root storage. Each storage can hold zero or more child objects, enumerated by calling that storage's IWMDMStorage::EnumStorage method.

Note that each storage in the diagram has attributes and metadata associated with it (not all values are shown). Attributes are simple, Boolean information often describing management or navigational information (such as "has folders" or "can delete"), whereas metadata can be string values, numbers, or complex information (such as rendering capabilities). Attributes are described by a fairly limited set of flags defined by the SDK and retrieved by calling IWMDMStorage::GetAttributes or IWMDMStorage2::GetAttributes2. Metadata values are retrieved by a unique name; the SDK defines a number of metadata values that devices should support, but devices can define their own metadata constants. However, if a device or service provider defines a new metadata constant, applications won't be able to request or set this value unless the application developers were aware of this new constant. A service provider must support IWMDMStorage3 or later to support retrieving or setting metadata. For more information, see Getting and Setting Metadata and Attributes.

Service Providers

The service provider acts as a middleman between the application and the device. The service provider is invisible to the application developer, so an application developer does not need to know anything about developing a service provider. However, it is the service provider that does the work of communicating with a device.

A service provider is a COM DLL built on Windows Media Device Manager that receives requests from an application and communicates with the device to perform them. Communication with the desktop application is mediated by Windows Media Device Manager; communication with the device is under the control of the service provider.

A service provider receives requests from the application to enumerate device content, requests for device capabilities, requests to read or write data, and so on. It must know the design of a device well enough that it can send commands in the proper format and protocol. It should also be able to hide device-specific requirements, such as a required file extension for playlists, so that applications do not need to know these requirements in order to use the device.

Microsoft provides a number of service providers for standard device types, including generic MTP devices, Mass Storage Class devices, and RAPI devices. The only reason a device designer should need to create a custom service provider is if a device has some specific or unusual data storage requirements that the standard service providers do not handle—for instance, if files must be stored in specific locations and the device operating system does not handle this automatically.

When a device is connected to the computer, the operating system creates one instance of the appropriate service provider for each Windows Media Device Manager application. If a second Windows Media Device Manager application starts, a second instance of the service provider will be loaded. However, each service provider can handle multiple devices. The following diagram illustrates this.

Diagram showing two MTP devices communicating with two applications.

The preceding diagram shows two different applications communicating with two MTP devices. The devices use the same service provider class, but each application has its own instance of the same service provider. Each service provider instance is communicating with devices. The different instances of the service provider are not aware of each other.

Many application methods have a correspondingly named service provider method. When the application calls a method, Windows Media Device Manager routes the call to the corresponding method on the service provider (though it might perform some additional internal actions first). For example, when the application calls IWMDMDevice3::GetProperty, Windows Media Device Manager routes this call to the service provider's implementation of IMDSPDevice3::GetProperty. (Most application interfaces begin with IWMDM, and the corresponding service provider interface begins with IMDSP). The service provider is expected to handle this method call and return an appropriate result.

An application never explores or communicates with a device directly (unless it calls IWMDMDevice3::DeviceIoControl or IWMDMStorage::SendOpaqueCommand); the application communicates with the service provider, which must represent a device in the most logical and simple manner possible. When the application requests information about the device, or enumerates objects on the device, the service provider queries the device in an appropriate manner and acquires and returns the appropriate information. It may expose the file organization on the device differently from how it is physically stored on the device, if that is appropriate. However it exposes the device, it should be in a consistent, logical manner, to enable the application to find what it needs and handle the commands it sends. A good service provider will hide device-specific peculiarities—for example, if the device physically stores a playlist as a file with a custom file extension, the service provider should add that extension automatically when the application creates a playlist on the device; it should not expect the application to know the proper extension when creating a playlist object.

Service providers run inside the process of the calling application. The only exception to this is the MTP service provider, which runs in its own process. Because of this, there is some risk that a blocked service provider will cause the calling application to block. Therefore, service providers should be designed to be robust and prevent blocking, and applications should be designed to avoid stalling if a particular method call does not return quickly.

See Also

  • Getting Started


Tools for Development

This section describes the various certificates and keys, libraries, and SDKs you will need to program using the Windows Media Device Manager SDK.

Certificates and Keys

The Windows Media Device Manager SDK ships with a test key/certificate pair (in the key.c file) that can be used by an application or a service provider to use Windows Media Device Manager methods on unprotected content. This key/certificate pair allows the application or service provider to use most of the Windows Media Device Manager functionality.

However, to develop an application or service provider that can handle DRM-protected content, you must request one or more certificates (each with a key) from the Windows Media Licensing Page. Certificates are required for the following applications or objects:

  • Service Providers that handle DRM-protected content require a Windows Media Device Manager Service Provider Certificate (and key)
  • Applications that transfer DRM-protected content require a Windows Media Device Manager Transfer Certificate (and key)
  • Applications that play DRM-protected content require a DRM Certificate (and key).
  • License metering components require a metering certificate. This is provided by a license metering service built on the Windows Media Rights Manager SDK, which can be requested on the Windows Media Licensing Page.

Libraries and Headers

In addition to the libraries and headers mentioned in Required Library and Header Files for an Application or Required Libraries and Headers for a Service Provider, any application or plug-in that formerly linked to WMDRMSDK.lib to call Windows Media Format SDK functions should now instead link to WMDRMSDKStub.Lib. This library file is used to access DRM-protected files. You can request this library from the Windows Media Licensing Page as well.

Related SDKs

The following Microsoft SDKs provide elements you may need in designing solutions for portable media devices.

SDK Required | Required for...
Windows Media Device Manager SDK | Desktop media player applications that communicate with portable devices Desktop applications that can exchange files or information with portable devices Windows Media Player metering COM objects
Windows Media Player SDK | Windows Media Player plug-ins Windows Media Player metering COM objects Windows Media Player skins
Windows Media Format SDK | Audio or video players that can create or play files (particularly ASF files) Audio or video editing applications
Windows Media Rights Manager SDK | Applications or plug-ins that meter play counts on the desktop or device.

See Also

  • Getting Started


Samples

The Windows Media Device Manager SDK includes two compilable samples: a sample graphical desktop application that enables you to browse connected devices, create playlists, and drag files to and from a device; and a sample service provider that communicates with virtual "devices" on the computer (which are actually the hard drives on your computer). The documentation explains how to compile and run these projects, and also provides information about how they work.

These two projects are documented in the following sections:

  • Sample Desktop Application
  • Sample Service Provider

See Also

  • Getting Started


Sample Desktop Application

The Windows Media Device Manager ships with a sample desktop application called wmdmapp. This application has a graphical user interface that allows you to browse connected devices, create playlists on the device, and drag media files to the device.

This sample application consists of two pieces:

  • wmdapp.exe, an executable that displays a window and performs most of the user interface and basic functionality of the program, and
  • proghelp.dll, a helper DLL that performs utility functions for the application. You must register this DLL after building the project.

To compile the sample application, you can use Visual Studio. The following section describes how this is done:

  • Compiling the Sample Application Using Visual Studio

After compiling the project, register the proghelp.dll file. To register this DLL, open a command prompt and browse to the directory containing this DLL and type regsvr32 proghelp.dll.


Compiling the Sample Application Using Visual Studio

The Windows Media Device Manager SDK includes a Visual Studio solution that is compatible with Microsoft Visual Studio 2005.

Before you compile the sample application, you must rename the header file shtypes.h to prevent conflicts with a file of the same name that is found in the Microsoft Platform SDK. For example, you could rename <SDK Installation Path>\WMFSDK11\include\shtypes.h to <SDK Installation Path>\WMFSDK11\include\shtypes.h.backup.

To build the application, start an instance of Visual Studio 2005, open the solution file, wmdmapp.sln, which is found in the folder <SDK installation path>\WMFSDK11\apps\wmdmapp and choose the Build/Build Solution option. This will create two project files: the helper project, proghelp.vcproj, as well as the main application wmdmapp.vcproj. In addition, it will create the progress helper DLL and the main application (WMDMApp.exe).

See Also

  • Sample Desktop Application


Using the Sample Desktop Application

The sample desktop application is a basic two-paned window somewhat like Windows Explorer. It allows you to browse the contents of a device, using a tree view display of folders in the left pane, and files in the right pane. The root of each folder tree is logically considered a different device, although some devices might represent themselves as several objects (one for each root storage). To read the basic properties of either a folder or a file, right-click the object and select Properties.

You can delete files on the device by selecting a file in the right pane and selecting Delete on the File menu. To add media files to the device, you can drag files from the desktop onto the right pane of the program. Note that files must be of a media format supported by the device; files of unacceptable formats (non-media files such as .txt files, or media formats not supported by the device) will not be sent to the device. (Note that this restriction is the program's; Windows Media Device Manager enables you to send any file to a device if the device will accept it.)

To capture callback events sent to the IWMDMOperation interface, you must check the "Use Operation Interface" option in the Options menu.

The Options menu also enables you to choose whether to use several more advanced interfaces with features supported by advanced devices.

The Containers menu has options to allow you to create a playlist or an album. To create a playlist, select one or more songs on the device and click Create Playlist on the Containers menu. This feature only works on MTP devices, because the code only supports the creation of an "virtual" playlist file. (A virtual playlist is a playlist that is specified only by metadata values, rather than by a physical file, for example a WPL file.) The device must support empty playlists to use this feature.

To create an album (a playlist with an associated image), select one or more songs on the device and click Create Album on the Containers menu. A dialog box allows you to browse to a picture file on your computer to associate with the album. Similarly to the way it creates playlists, the application creates an "empty" album file; if the device does not support empty albums, this feature will not work.

See Also

  • Sample Desktop Application


Structure of the Sample Desktop Application

The sample desktop application consists of two main pieces:

  • The wmdapp project contains most of the classes that display the user interface, handle dragging and dropping, and perform all the required functionality of the program.
  • The proghelp project is a helper application that contains nonessential classes to handle status notifications and manual file transfers from the desktop to the application.

The executable uses the helper project only when the user selects Use Operation Interface on the Options menu to handle manual file transfer to the device, and to increment the status bar in the download progress form. All the rest of the application is handled in the wmdapp project.

Class | File | Description
— | wmdmapp.cpp | The class that handles the parent window of the user interface. The code in this file also handles some user input not handled by CDevFiles, such as creating a playlist or album on a device, deleting files, and registering menu choices.
CDevices | Devices.cpp | The class that handles the left-hand pane of the main application window, where the available devices are listed. This class manages the messaging loop, which handles user input such as selecting a device and notifying the CDevFiles pane to load the appropriate files when the device selection has changed.
CDevFiles | Devfiles.cpp | The class that handles the right-hand pane of the main application window, where the files on the selected device are listed. This class manages the messaging loop, and handles user input such as dragging files onto the device and deleting files from the device.
CStatus | Status.cpp | The class that handles the bottom status bar in the main window, where the number of devices and files is listed, along with the amount of free and used memory on the selected device.
CWMDM | Wmdevmgr.cpp | The top-level interface for Windows Media Device Manager. This class handles authentication, retrieves the top-level IWMDeviceManager interface, and registers for notifications with the IWMDMNotification interface.
CProgress | Progress.cpp | The class in the main application project that creates and manages the dialog box showing the progress of an event.
CItemData | ItemData.cpp | A wrapper class that holds a pointer to a storage (if representing a file or folder on the device) or a device (if representing a device), as well as a variety of information about the object including size and attributes.
CNotificationHandler | Notificationhandler.cpp | Handles device arrival and removal notifications by alerting the CDevices window.
CProgressHelper | ProgressHelper.cpp | Created by CDevFiles in local functions to receive notifications from Windows Media Device Manager by implementing IWMDMProgress. It is used by the CProgress class to determine the amount of bars in the progress bar, and when an action is finished. This class is defined as a COM object that exposes the SDK interface IWMDMProgress and a custom interface IWMDMProgressHelper.
COperationHelper | Operationhelper.cpp | This class implements IWMDMOperation to handle manual transfer of files. It is multi-threaded to allow it to occur asynchronously, and is defined as a COM object that exposes a custom interface, IWMDMOperationHelper, to instantiate and initialize the class. This class is only used if the user selects "Use Operation Interface" in the Options menu.

The following lists outline the basic steps that occur for various user actions:

On startup

The following main steps occur when the sample application is started.

  1. The global CWMDM variable is instantiated and authenticated, and registers to receive notifications
  2. A global CDevices is instantiated, and CDevices::Create is called to create and fill the devices pane.
  3. A global CDevFiles is instantiated, and CDevFiles::Create is called to create the files pane (which is not filled until the user selects a device).
  4. A global CStatus is instantiated, and CStatus::Create is called to instantiate the status bar.
  5. _OnViewRefresh enumerates through all devices and initializes and adds all devices (CItemData) to CDevices and updates the status bar to show the number of devices.
  6. CDevices::AddItem adds the item to the treeview representing the devices, with a pointer to itself as the TVITEM.lparam. All CDevice (devices) and CDevFiles (file) objects are stored in this member of the treeview node in the appropriate window.

On selecting a device

The following main steps occur when the user selects a device in the left-hand pane of the application window.

  1. The CDevices window traps a click and posts a WM_DRM_UPDATEDEVICE message, to itself.
  2. CDevices receives its own message and calls UpdateSelection, which tells the global CDevFiles object to clear everything, enumerate all the top-level items in the device, and calls CDevFiles::AddItem to add each to the files pane.
  3. Finally, CDevices calls CDevFiles::UpdateStatusBar to update the status bar with the correct device and file information.

On creating a playlist

After clicking "Create Playlist" on the Containers menu, the application calls the local function _OnCreatePlaylist, which performs the following actions:

  1. Get the number of selected items from the global CDevFiles variable.
  2. Call the local function DlgNamePlaylist to open a dialog box to get a name for the playlist.
  3. Call the CProgress::Create to create a dialog window showing the progress of the action, and set parameters on the CProgress class, such as the title text, range, current value, and so on.
  4. Loop through all the selected items in the CDevFiles tree view object, and request the CItemData object associated with each selected file in the tree view, incrementing the progress dialog bar with each file. The files are added to an array of IWMDMStorage interfaces.
  5. Get a handle to the currently selected item and query it for an IWMDMStorageControl3 interface, which will be used later to create the new playlist on the device.
  6. Query the selected object for IWMDMStorage3, and call CreateEmptyMetadataObject to create a new IWMDMMetaData interface.
  7. Add the WMDM_FORMATCODE_ABSTRACTAUDIOVIDEOPLAYLIST format code to the new IWMDMMetadata interface and create a playlist on the device by calling IWMDMStorageControl3::Insert3, passing in the metadata interface. The method retrieves a pointer to the new IWMDMStorage on the device.
  8. Fill the playlist by querying the new storage for IWMDMStorage4, and calling IWMDMStorage4::SetReferences, passing in the array of IWMDMStorage pointers collected in step 4.
  9. Finally, create a new CItemData object to hold the new playlist on the device, initialize it with the new storage, and call CDevFiles::AddItem to add it to the CDevFiles pane.

See Also

  • Sample Desktop Application


Sample Service Provider

The Windows Media Device Manager SDK includes a sample service provider for you to use. This service provider includes a class that reports each hard drive on the computer as if it were an attached device. The only application that will use this service provider is the sample application; Windows Explorer will not see the "devices" reported by this service provider. The service provider sample is a COM object built on ATL. The following steps explain how to use the sample service provider:

Note The sample service provider implements very few features, and so it should not be used for testing Windows Media Device Manager applications. To test an application, use a fully-implemented service provider.

  1. The sample was shipped with a coding error that will cause the service provider to malfunction. To correct this error, open the MDSPEnumStorage.cpp file installed in the folder <SDK installation path>\WMFSDK95\WMDM\mdsp\mshdsp, go to line 185, and change the following line:

wcsncpy(pStg->m_wcsName, m_wcsPath, dwLen);

To this:

wcsncpy(pStg->m_wcsName, m_wcsPath, ARRAYSIZE(pStg->m_wcsName));

  2. Compile the MsHDSP.dll file. You can do this using either NMAKE or Visual Studio. See Compiling the Sample Service Provider Using NMAKE or Compiling the Sample Service Provider Using Visual Studio to learn how to compile the application.
    3.

  3. Register MsHDSP.dll using regsvr32. The following line, typed into a command-prompt window in the same folder as MsHDSP.dll, will register the sample service provider:

    regsvr32 mshdsp.dll

    To stop impersonating a device, enter the following line at the command prompt:

    regsvr32 /u mshdsp.dll

    4.

  4. The removable devices impersonated by this DLL can only be seen by the sample application shipped with this SDK. Compile the sample application using one of the methods described in Sample Desktop Application.
    5.

  5. To debug the service provider with Visual Studio, open the service provider in Visual Studio and select Start on the Debug menu. In the popup dialog box, browse to the sample application you built in the preceding step, and click OK, and the service provider will begin running in debug mode.

    To run the service provider without debugging in Visual Studio, simply register the msdhsp.dll and run the sample desktop application that ships with the SDK. The sample desktop application runs the sample service provider automatically.
    6.

See Also

  • Samples
    •


Compiling the Sample Service Provider Using NMAKE

To compile the sample service provider using NMAKE, open a Visual Studio command window, navigate to <SDK installation path>\WMFSDK95\WMDM\mdsp, and enter nmake at the prompt.

See Also

  • Sample Service Provider


Compiling the Sample Service Provider Using Visual Studio

The Windows Media Format SDK does not include a Visual Studio solution file. However, this document includes two files that enable you to use Visual Studio to build and debug the sample service provider. Both the files provided are for Visual Studio .NET 2003.

  1. Save the following code as a text file named mshdsp.vcproj in the folder <SDK installation path>\WMFSDK\WMFSDK95\WMDM\mdsp\mshdsp.
<?xml version="1.0" encoding="Windows-1252"?>
<VisualStudioProject
    ProjectType="Visual C++"
    Version="7.10"
    Name="mshdsp"
    ProjectGUID="{B0BD0EEB-2048-46E2-ADCB-DA058B246F5E}"
    Keyword="AtlProj">
    <Platforms>
        <Platform
            Name="Win32"/>
    </Platforms>
    <Configurations>
        <Configuration
            Name="Debug|Win32"
            OutputDirectory="Debug"
            IntermediateDirectory="Debug"
            ConfigurationType="2"
            UseOfATL="1"
            ATLMinimizesCRunTimeLibraryUsage="FALSE"
            CharacterSet="2">
            <Tool
                Name="VCCLCompilerTool"
                Optimization="0"
                AdditionalIncludeDirectories="..\..\inc"
                PreprocessorDefinitions="WIN32;_WINDOWS;_DEBUG;_USRDLL;_ATL_ATTRIBUTES;ATL_STATIC_REGISTRY;INC_OLE2;"
                MinimalRebuild="TRUE"
                BasicRuntimeChecks="3"
                RuntimeLibrary="3"
                UsePrecompiledHeader="0"
                WarningLevel="3"
                Detect64BitPortabilityProblems="TRUE"
                DebugInformationFormat="4"/>
            <Tool
                Name="VCCustomBuildTool"/>
            <Tool
                Name="VCLinkerTool"
                IgnoreImportLibrary="TRUE"
                AdditionalOptions="/FIXED:NO"
                AdditionalDependencies="advapi32.lib gdi32.lib kernel32.lib ole32.lib oleaut32.lib olepro32.lib user32.lib uuid.lib mssachlp.lib oldnames.lib shell32.lib atlsd.lib shlwapi.lib msvcrtd.lib"
                OutputFile="$(OutDir)/mshdsp.dll"
                LinkIncremental="2"
                AdditionalLibraryDirectories="..\..\lib"
                IgnoreAllDefaultLibraries="TRUE"
                ModuleDefinitionFile="MsHDSP.def"
                MergedIDLBaseFileName="_mshdsp.idl"
                GenerateDebugInformation="TRUE"
                SubSystem="2"
                OptimizeReferences="1"
                ImportLibrary="$(OutDir)/mshdsp.lib"
                TargetMachine="1"/>
            <Tool
                Name="VCMIDLTool"
                PreprocessorDefinitions="_DEBUG;UNICODE;_UNICODE"
                MkTypLibCompatible="FALSE"
                TargetEnvironment="1"
                GenerateStublessProxies="TRUE"
                TypeLibraryName="$(IntDir)/mshdsp.tlb"
                HeaderFileName="mshdsp.h"
                DLLDataFileName=""
                InterfaceIdentifierFileName="mshdsp_i.c"
                ProxyFileName="mshdsp_p.c"/>
            <Tool
                Name="VCPostBuildEventTool"
                Description="Performing registration"
                CommandLine="regsvr32 /s /c &quot;$(TargetPath)&quot;"/>
            <Tool
                Name="VCPreBuildEventTool"/>
            <Tool
                Name="VCPreLinkEventTool"/>
            <Tool
                Name="VCResourceCompilerTool"
                PreprocessorDefinitions="_DEBUG"
                Culture="1033"
                AdditionalIncludeDirectories="$(IntDir)"/>
            <Tool
                Name="VCWebServiceProxyGeneratorTool"/>
            <Tool
                Name="VCXMLDataGeneratorTool"/>
            <Tool
                Name="VCWebDeploymentTool"/>
            <Tool
                Name="VCManagedWrapperGeneratorTool"/>
            <Tool
                Name="VCAuxiliaryManagedWrapperGeneratorTool"/>
        </Configuration>
        <Configuration
            Name="Release|Win32"
            OutputDirectory="Release"
            IntermediateDirectory="Release"
            ConfigurationType="2"
            UseOfATL="1"
            ATLMinimizesCRunTimeLibraryUsage="FALSE"
            CharacterSet="2">
            <Tool
                Name="VCCLCompilerTool"
                PreprocessorDefinitions="WIN32;_WINDOWS;NDEBUG;_USRDLL;_ATL_ATTRIBUTES"
                RuntimeLibrary="2"
                UsePrecompiledHeader="3"
                WarningLevel="3"
                Detect64BitPortabilityProblems="TRUE"
                DebugInformationFormat="3"/>
            <Tool
                Name="VCCustomBuildTool"/>
            <Tool
                Name="VCLinkerTool"
                IgnoreImportLibrary="TRUE"
                OutputFile="$(OutDir)/mshdsp.dll"
                LinkIncremental="1"
                MergedIDLBaseFileName="_mshdsp.idl"
                GenerateDebugInformation="TRUE"
                SubSystem="2"
                OptimizeReferences="2"
                EnableCOMDATFolding="2"
                ImportLibrary="$(OutDir)/mshdsp.lib"
                TargetMachine="1"/>
            <Tool
                Name="VCMIDLTool"
                PreprocessorDefinitions="NDEBUG"
                MkTypLibCompatible="FALSE"
                TargetEnvironment="1"
                GenerateStublessProxies="TRUE"
                TypeLibraryName="$(IntDir)/mshdsp.tlb"
                HeaderFileName="mshdsp.h"
                DLLDataFileName=""
                InterfaceIdentifierFileName="mshdsp_i.c"
                ProxyFileName="mshdsp_p.c"/>
            <Tool
                Name="VCPostBuildEventTool"
                Description="Performing registration"
                CommandLine="regsvr32 /s /c &quot;$(TargetPath)&quot;"/>
            <Tool
                Name="VCPreBuildEventTool"/>
            <Tool
                Name="VCPreLinkEventTool"/>
            <Tool
                Name="VCResourceCompilerTool"
                PreprocessorDefinitions="NDEBUG"
                Culture="1033"
                AdditionalIncludeDirectories="$(IntDir)"/>
            <Tool
                Name="VCWebServiceProxyGeneratorTool"/>
            <Tool
                Name="VCXMLDataGeneratorTool"/>
            <Tool
                Name="VCWebDeploymentTool"/>
            <Tool
                Name="VCManagedWrapperGeneratorTool"/>
            <Tool
                Name="VCAuxiliaryManagedWrapperGeneratorTool"/>
        </Configuration>
    </Configurations>
    <References>
    </References>
    <Files>
        <Filter
            Name="Source Files"
            Filter="cpp;c;cxx;def;odl;idl;hpj;bat;asm;asmx"
            UniqueIdentifier="{4FC737F1-C7A5-4376-A066-2A32D752A2FF}">
            <File
                RelativePath=".\hdsppch.cpp">
            </File>
            <File
                RelativePath=".\key.c">
            </File>
            <File
                RelativePath=".\loghelp.cpp">
            </File>
            <File
                RelativePath=".\MDServiceProvider.cpp">
            </File>
            <File
                RelativePath=".\Mdsp.cpp">
            </File>
            <File
                RelativePath=".\MDSPDevice.cpp">
            </File>
            <File
                RelativePath=".\MDSPEnumDevice.cpp">
            </File>
            <File
                RelativePath=".\MDSPEnumStorage.cpp">
            </File>
            <File
                RelativePath=".\MDSPStorage.cpp">
            </File>
            <File
                RelativePath=".\MDSPStorageGlobals.cpp">
            </File>
            <File
                RelativePath=".\MDSPutil.cpp">
            </File>
            <File
                RelativePath=".\MsHDSP.def">
            </File>
            <File
                RelativePath=".\MsHDSP.idl">
            </File>
            <File
                RelativePath=".\proppage.cpp">
            </File>
        </Filter>
        <Filter
            Name="Header Files"
            Filter="h;hpp;hxx;hm;inl;inc;xsd"
            UniqueIdentifier="{93995380-89BD-4b04-88EB-625FBE52EBFB}">
            <File
                RelativePath=".\hdsppch.h">
            </File>
            <File
                RelativePath=".\hdsprc.h">
            </File>
            <File
                RelativePath=".\loghelp.h">
            </File>
            <File
                RelativePath=".\MDServiceProvider.h">
            </File>
            <File
                RelativePath=".\MdspDefs.h">
            </File>
            <File
                RelativePath=".\MDSPDevice.h">
            </File>
            <File
                RelativePath=".\MDSPEnumDevice.h">
            </File>
            <File
                RelativePath=".\MDSPEnumStorage.h">
            </File>
            <File
                RelativePath=".\MDSPStorage.h">
            </File>
            <File
                RelativePath=".\MDSPStorageGlobals.h">
            </File>
            <File
                RelativePath=".\proppage.h">
            </File>
            <File
                RelativePath=".\verinfo.h">
            </File>
        </Filter>
        <Filter
            Name="Resource Files"
            Filter="rc;ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe;resx"
            UniqueIdentifier="{67DA6AB6-F800-4c08-8B7A-83BB121AAD01}">
            <File
                RelativePath=".\icon_hd.ico">
            </File>
            <File
                RelativePath=".\MDServiceProvider.rgs">
            </File>
            <File
                RelativePath=".\mdsp.rc">
            </File>
            <File
                RelativePath=".\proppage.rgs">
            </File>
        </Filter>
        <File
            RelativePath=".\Makefile">
        </File>
        <File
            RelativePath=".\mshdsp.ncb">
        </File>
    </Files>
    <Globals>
    </Globals>
</VisualStudioProject>
  2. Save the following code as a text file named mshdsp.sln in the same folder where you saved mshdsp.vcproj.
Microsoft Visual Studio Solution File, Format Version 8.00
Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "mshdsp", "mshdsp.vcproj", "{B0BD0EEB-2048-46E2-ADCB-DA058B246F5E}"
    ProjectSection(ProjectDependencies) = postProject
    EndProjectSection
EndProject
Global
    GlobalSection(SolutionConfiguration) = preSolution
        Debug = Debug
        Release = Release
    EndGlobalSection
    GlobalSection(ProjectConfiguration) = postSolution
        {B0BD0EEB-2048-46E2-ADCB-DA058B246F5E}.Debug.ActiveCfg = Debug|Win32
        {B0BD0EEB-2048-46E2-ADCB-DA058B246F5E}.Debug.Build.0 = Debug|Win32
        {B0BD0EEB-2048-46E2-ADCB-DA058B246F5E}.Release.ActiveCfg = Release|Win32
        {B0BD0EEB-2048-46E2-ADCB-DA058B246F5E}.Release.Build.0 = Release|Win32
        {C82A4AF9-14FD-474E-AD38-6EED4A0C0903}.Debug.ActiveCfg = Debug|Win32
        {C82A4AF9-14FD-474E-AD38-6EED4A0C0903}.Release.ActiveCfg = Release|Win32
    EndGlobalSection
    GlobalSection(ExtensibilityGlobals) = postSolution
    EndGlobalSection
    GlobalSection(ExtensibilityAddIns) = postSolution
    EndGlobalSection
EndGlobal

See Also

  • Sample Service Provider


Code Files for the Source Provider Sample

The sample source provider project includes the following source code files, with associated headers:

File | Description
hdsppch.cpp | Includes standard ATL files.
key.c | Contains a dummy authentication key.
loghelp.cpp | Contains functions that log activity and errors by using the WMDMLogger class, which is implemented in the WMDMLOG.dll system file.
MDServiceProvider.cpp | Implements a class, CMDServiceProvider, that implements the IMDServiceProvider and IComponentAuthenticate interfaces.
mdsp.cpp | DLL entry point and registration code.
MDSPDevice.cpp | Implements a class, CMDSPDevice, that implements the IMDSPDevice2, IMDSPDeviceControl, and ISpecifyPropertyPages interfaces.
MDSPEnumDevice.cpp | Implements a class, CMDSPEnumDevice, that implements the IMDSPEnumDevice interface.
MDSPEnumStorage.cpp | Implements a class, CMDSPEnumStorage, that implements the IMDSPEnumStorage interface.
MDSPStorage.cpp | Implements a class, CMDSPStorage, that implements the IMDSPStorage2, IMDSPObjectInfo, and IMDSPObject interfaces.
MDSPStorageGlobals.cpp | Implements a class, CMDSPStorageGlobals, that implements the IMDSPStorageGlobals interface.
MDSPutil.cpp | Contains various utility functions for device and file management.
proppage.cpp | Implements a class, CPropPage, that inherits the ATL classes IPropertyPageImpl (to implement IPropertyPage) and CDialogImpl, which inherits the ATL class CDialogImpl (to manage windows and messages).

See Also

  • Sample Service Provider


Programming Guide

This section describes actions that an application or service provider built on Windows Media Device Manager should perform.

  • Tasks Common to Applications and Service Providers describes tasks that both applications and service providers will perform, such as logging, encryption and decryption, and authentication.
  • Creating a Windows Media Device Manager Application describes all the actions an application typically must perform.
  • Creating a Service Provider describes all the actions a service provider typically must perform.


Tasks Common to Applications and Service Providers

This section describes the following tasks that apply to both applications and service providers built on Windows Media Device Manager.

  • Compiling the IDL Files Supplied with the SDK describes which IDL files are used to create which header files, if you choose not to use the header files provided with the SDK.
  • Enabling Logging describes a logging object provided by Windows Media Device Manager to log data from a running object.
  • Using Secure Authenticated Channels describes Secure Authenticated Channels, which are used for encryption, decryption, and component and message authentication. Anything built on Windows Media Device Manager must at least be able to perform component authentication.
  • Handling Protected Content describes how your application can handle content protected by Windows Media digital rights management (DRM).
  • Getting and Setting Metadata and Attributes describes how an application can retrieve and set attributes and metadata for a storage or device.

See Also

  • Programming Guide


Compiling the IDL Files Supplied with the SDK

The Windows Media Device Manager SDK includes both header files and the source IDL files for most of these header files. The header files are located in the \inc\ folder in the SDK installation path. The IDL files are located in the \idl\ folder.

The precompiled headers are much simpler to use, and several of the IDL files are combined into a single provided header. However, if you decide to process your own header files from the provided IDL files, this topic describes which IDL files create which header files, and also describes the dependencies of each IDL file.

Equivalent IDL and Provided Header Files

IDL | Equivalent supplied header | Description
WMDM.idl WMSP.idl WMSCP.idl icomponentauthenticate.idl | Mswmdm.h | All four IDL files are included in this single provided header. WMDM.idl Defines all the application interfaces and required structures, constants, and error codes. WMSP.idl Defines all the service provider interfaces. WMSCP.idl Defines all the interfaces, GUID values, and constants required by secure content providers. icomponentauthenticate.idl Defines the IComponentAuthenticate interface.
Wmdmlog.idl | Wmdmlog.h wmdmlog_i.c | Defines the logging interfaces. Both supplied header files must be used, rather than just the .h file, because of a problem with the IDL file.
WMDRMDeviceApp.idl | Wmdrmdeviceapp.h | Defines the IWMDRMDeviceApp and IWMDRMDeviceApp2 interfaces used by applications that update DRM on devices or meter play counts on devices.

IDL Dependencies

Several of the provided IDL files have build dependencies. If you plan to compile the IDL files yourself, you must process these external dependencies in the order shown in the following table.

IDL | Dependencies
icomponentauthenticate.idl | import "oaidl.idl"; #include "icomponentauthenticate.idl"
WMDM.idl | No external dependencies
WmdmLog.idl | No external dependencies
WMDRMDeviceApp.idl | No external dependencies
WMSCP.idl | #include "WMDRMDeviceApp.idl" #include "WMSP.idl"
WMSP.idl | #include "WMDM.idl"

See Also

  • Tasks Common to Applications and Service Providers


Enabling Logging

Windows Media Device Manager provides a logging object that can save information to a text file at run time. Developers of both applications and service providers can use this object to store messages in a log file while their application or service provider is running. This object is especially useful when handling DRM-protected files, because Windows Media Device Manager will not allow you to attach a debugger to a process that is handling DRM-protected files.

The logger is a COM object with the class ID CLSID_WMDMLogger that exposes one interface, IWMDMLogger. Components do not need a certificate to use the logging object.

By default, Windows Media Device Manager maintains a log file, regardless of whether an application uses IWMDMLogger. This log file is a simple text file, and each entry includes an entry preceded by a time stamp in the format YYYYMMDDHHMMSS, using 24-hour local time. Windows Media Device Manager logs all API calls, along with any entries you add by calling IWMDMLogger messages. All log file entries are appended to the file until Reset is called, or the file exceeds its maximum size. The file is closed automatically after each logging operation. The same log file is used for application entries and system entries.

The following steps show how to use the logging object:

  1. Include wmdmlog.h in your project.
  2. Create a logging object by calling CoCreateInstance(CLSID_WMDMLogger) and requesting the IWMDMLogger interface. Assign the interface pointer to a global variable.
  3. Verify that logging is enabled by calling IWMDMLogger::IsEnabled; if it is not, enable it by calling IWMDMLogger::Enable.
  4. Specify a custom log file name and size. This is done by calling IWMDMLogger::SetLogFileName and IWMDMLogger::SetSizeParams.
  5. At points in your code where you want to make an entry in the log, call either IWMDMLogger::LogDword to log strings containing variables (this method is similar to wsprintf in the way it allows you to format a string containing a variable value), or call IWMDMLogger::LogString to log constant strings.

For example code, see the reference pages for the methods of IWMDMLogger.

See Also

  • Tasks Common to Applications and Service Providers


Using Secure Authenticated Channels

Windows Media Device Manager enables authentication and secure communication between components by providing two helper classes, CSecureChannelClient (for applications) and CSecureChannelServer (for service providers), and one interface, IComponentAuthenticate (for both). Together these make up an API for the use of secure authenticated channels (SAC). SAC handles the following three tasks for service providers or applications using Windows Media Device Manager:

  • Component Authentication
  • Encryption and Decryption
  • Message Authentication

An application or service provider must handle component authentication, encryption, and decryption; message authentication is optional.

See Also

  • Tasks Common to Applications and Service Providers


Component Authentication

Every application and service provider must be authenticated before it can begin to call or implement Windows Media Device Manager methods.

Authentication is handled differently for service providers and applications. See the topic that applies to your project:

  • Authenticating the Application
  • Authenticating the Service Provider

See Also

  • Using Secure Authenticated Channels


Encryption and Decryption

Windows Media Device Manager requires encryption of files sent between the service provider and the application. This can be done in one of two ways:

  • If the service provider supports only IMDSPObject::Read and IMDSPObject::Write, the data must be encrypted and decrypted by the application and service provider by using CSecureChannelClient and CSecureChannelServer methods respectively.
  • If the service provider supports IMDSPObject2::ReadOnClearChannel and IMDSPObject2::WriteOnClearChannel, your application can avoid costly secure channel message authentication. (The secure channel is retained so that legacy service providers that do not implement IMDSPObject2 can still continue to function.)

The encryption requirement prevents malicious applications from obtaining data that is being passed between software components, and also protects the integrity of data being sent to or from the device.

The following three methods require encryption or decryption.

Method | Description
IWMDMOperation::TransferObjectData | (Application) Encryption or decryption, depending on whether the application is sending or receiving data.
IMDSPObject::Read | (Service provider) Encryption.
IMDSPObject::Write | (Service Provider) Decryption.

Encryption and decryption are both done by single method calls. Encryption is done by CSecureChannelClient::EncryptParam for applications or by CSecureChannelServer::EncryptParam for service providers. Decryption is done by CSecureChannelClient::DecryptParam for applications or CSecureChannelServer::DecryptParam for service providers. The parameters are identical between the client and server methods.

The following steps show how to encrypt and decrypt data. (These steps are important only if your application communicates with a legacy service provider that does not implement IWMDMOperation3::TransferObjectDataOnClearChannel.)

Encryption

  1. Create the MAC key for the encrypted data, as described in Message Authentication.
  2. Call EncryptParam with the data to encrypt, to perform in-place encryption.

The following code example demonstrates a service provider's implementation of IMDSPObject::Read. This method creates the MAC key using the data to encrypt and the size of the data, and sends them both to the application.

HRESULT CMyStorage::Read(
    BYTE  *pData,
    DWORD *pdwSize,
    BYTE   abMac[WMDM_MAC_LENGTH])
{
    HRESULT  hr;
    DWORD    dwToRead;         // Bytes to read.
    DWORD    dwRead   = NULL;  // Bytes read.
    BYTE    *pTmpData = NULL;  // Temporary buffer to hold data before
                               // it is copied to pData.

    // Use a global CSecureChannelServer member to verify that
    // the client is authenticated.
    if (!(g_pAppSCServer->fIsAuthenticated()))
    {
        return WMDM_E_NOTCERTIFIED;
    }

    // Verify that the handle to the file to read is valid.
    if(m_hFile == INVALID_HANDLE_VALUE)
    {
        return E_FAIL;
    }

    // Create a buffer to hold the data read.
    dwToRead = *pdwSize;
    pTmpData = new BYTE [dwToRead] ;
    if(!pTmpData)
        return E_OUTOFMEMORY;

    // Read data into the temporary buffer.
    if(ReadFile(m_hFile,(LPVOID)pTmpData,dwToRead,&dwRead,NULL))
    {
        *pdwSize = dwRead;

        if( dwRead )
        {
            // Create a MAC from all the parameters.
            // CORg is a macro that goes to Error label on failure.
            // MAC consists of data and size of data.
            HMAC hMAC;

            CORg(g_pAppSCServer->MACInit(&hMAC));
            CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pTmpData), dwRead));
            CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(DWORD)));
            CORg(g_pAppSCServer->MACFinal(hMAC, abMac));

            // Encrypt the data.
            CORg(g_pAppSCServer->EncryptParam(pTmpData, dwRead));

            // Copy data from the temporary buffer into the out parameter.
            memcpy(pData, pTmpData, dwRead);
        }

        hr = S_OK;
    }
    else
    {
        *pdwSize = 0;

        hr = E_FAIL;
    }

Error:

    if(pTmpData)
    {
        delete [] pTmpData;
    }

    return hr;
}

Decryption

  1. Call DecryptParam with the data to encrypt, to perform in-place decryption.
  2. Verify the MAC key for the decrypted data, as described in Message Authentication.

The following code example demonstrates a service provider's implementation of IMDSPObject::Write. This method creates the MAC key using the data to encrypt and the size of the data, and sends them both to the application.

HRESULT CMyStorage::Write(BYTE *pData, DWORD *pdwSize,
                                 BYTE abMac[WMDM_MAC_LENGTH])
{
    HRESULT  hr;
    DWORD    dwWritten = 0;
    BYTE    *pTmpData  = NULL;          // Temporary buffer to hold the
                                        // data during decryption.
    BYTE     pTempMac[WMDM_MAC_LENGTH]; // Temporary MAC that will be
                                        // copied into the abMac
                                        // out parameter.

    if( m_hFile == INVALID_HANDLE_VALUE )
    {
        return E_FAIL;
    }

    // Allocate the temporary buffer and copy the encrypted data into it.
    pTmpData = new BYTE [*pdwSize];
    if(!pTmpData)
        return E_OUTOFMEMORY;
    memcpy(pTmpData, pData, *pdwSize);

    // Decrypt the data.
    CHRg(g_pAppSCServer->DecryptParam(pTmpData, *pdwSize));

    // Check the MAC passed to the method. The MAC is built from
    // the data and data size parameters.
    // CORg is a macro that goes to the Error label on failure.
    HMAC hMAC;
    CORg(g_pAppSCServer->MACInit(&hMAC));
    CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pTmpData), *pdwSize));
    CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(*pdwSize)));
    CORg(g_pAppSCServer->MACFinal(hMAC, pTempMac));

    // If the MAC values don't match, return an error.
    if (memcmp(abMac, pTempMac, WMDM_MAC_LENGTH) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
        goto Error;
    }

    // The MAC values matched, so write the decrypted data to a local file.
    if( WriteFile(m_hFile,pTmpData,*pdwSize,&dwWritten,NULL) )
    {
        hr = S_OK;
    }
    else
    {
        hr = HRESULT_FROM_WIN32(GetLastError());
    }

    *pdwSize = dwWritten;

Error:

    if( pTmpData )
    {
        delete [] pTmpData;
    }

    return hr;
}

See Also

  • Using Secure Authenticated Channels


Message Authentication

Message authentication is a process that enables applications and service providers to verify that data passed between them has not been tampered with. Windows Media Device Manager allows applications and service providers to perform message authentication by using message authentication codes (MACs). Here is how MAC authentication works:

The data sender, usually the service provider, passes one or more pieces of data through a one-way cryptographic function that produces a single signature, the MAC, for all the data. The sender then sends all the signed pieces of data together with the MAC to the receiver (usually the application). The receiver passes the data through the same cryptographic function to generate a MAC and compares it to the MAC that was sent. If the MAC matches, the data has not been modified.

To perform MAC authentication, the application or service provider requires an encryption key and a matching certificate. For information on where to get these, see Tools for Development.

The following steps describe how data is signed by the sender, and later checked by the receiver. In Windows Media Device Manager, the service provider uses the CSecureChannelServer class to generate MACs, and the application uses the CSecureChannelClient class. Both classes provide identical functions with identical parameters, so the following steps apply to both classes.

The sender (typically the service provider):

  1. Get the data to be signed.
  2. Create a new MAC handle by calling MACInit.
  3. Add a piece of data to be signed to the handle by calling MACUpdate. This function accepts the previously created handle, plus a piece of data that must be signed.
  4. Repeat step 3 with each additional piece of data that must be signed. It does not matter in what order data is added to the MAC.
  5. Copy the MAC from the handle to a new byte buffer by calling MACFinal. This function accepts the MAC handle and a buffer that you allocate, and copies the MAC from the handle into the provided buffer.

When performing MAC authentication, it is important that both the sender and the receiver are putting the same data into the MAC. For the application methods that provide a MAC, typically all parameters are included in the MAC value (except for the MAC itself, of course). For example, consider the IWMDMOperation::TransferObjectData method:

HRESULT TransferObjectData(BYTE* pData, DWORD* pdwSize, BYTE[WMDM_MAC_LENGTH] abMac);

In this method, the MAC would include pData and pdwSize. If you do not include both the parameters, the MAC you create will not match the MAC passed to abMac. A service provider must be sure to put all the required parameters in the application method into the MAC value.

The following C++ code demonstrates creating a MAC in a service provider's implementation of IMDSPStorageGlobals::GetSerialNumber.

HRESULT CMyDevice::GetSerialNumber(
    PWMDMID pSerialNumber,
    BYTE abMac[WMDM_MAC_LENGTH])
{
    HRESULT hr;

    // g_pSecureChannelServer is a global CSecureChannelServer object
    // created earlier.

    // Standard check that the CSecureChannelServer was authenticated previously.
    if ( !(g_pSecureChannelServer->fIsAuthenticated()) )
    {
        return WMDM_E_NOTCERTIFIED;
    }

    // Call a helper function to get the device serial number.
    hr = UtilGetSerialNumber(m_wcsName, pSerialNumber, TRUE);
    if(hr == HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED))
    {
        hr = WMDM_E_NOTSUPPORTED;
    }

    if(hr == S_OK)
    {
        // Create the MAC handle.
        HMAC hMAC;
        hr = g_pSecureChannelServer->MACInit(&hMAC);
        if(FAILED(hr))
            return hr;

        // Add the serial number to the MAC.
        g_pSecureChannelServer->MACUpdate(hMAC, (BYTE*)(pSerialNumber), sizeof(WMDMID));
        if(FAILED(hr))
            return hr;

        // Get the created MAC value from the handle.
        g_pSecureChannelServer->MACFinal(hMAC, abMac);
        if(FAILED(hr))
            return hr;
    }

    return hr;
}

The receiver (typically the application):

If the receiver has not implemented the IWMDMOperation3 interface, it should perform the same steps as the sender, and then compare the two MAC values. The following C++ code example shows how an application would check the MAC received in a call to IWMDMStorageGlobals::GetSerialNumber to ensure that the serial number was not tampered with in transit.

//
// Get and verify the serial number.
//
WMDMID serialNumber;
BYTE receivedMAC[WMDM_MAC_LENGTH];
hr = pIWMDMDevice->GetSerialNumber(&serialNumber, receivedMAC);

// Check the MAC to guarantee the serial number has not been tampered with.
if (hr == S_OK)
{
    // Initialize a MAC handle,
    // add all parameters to the MAC,
    // and retrieve the calculated MAC value.
    // m_pSAC is a global CSecureChannelClient object created earlier.
    HMAC hMAC;
    BYTE calculatedMAC[WMDM_MAC_LENGTH];
    hr = m_pSAC->MACInit(&hMAC);
    if(FAILED(hr))
        return hr;

    hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(&serialNumber), sizeof(serialNumber));
    if(FAILED(hr))
        return hr;

    hr = m_pSAC->MACFinal(hMAC, (BYTE*)calculatedMAC);
    if(FAILED(hr))
        return hr;

    // If the two MAC values match, the MAC is authentic.
    if (memcmp(calculatedMAC, receivedMAC, sizeof(calculatedMAC)) == 0)
    {
        // The MAC is authentic; print the serial number.
        CHAR* serialNumberBuffer =
            new CHAR[serialNumber.SerialNumberLength + 1];
        ZeroMemory(serialNumberBuffer,
            (serialNumber.SerialNumberLength + 1) * sizeof(CHAR));
        memcpy(serialNumberBuffer, serialNumber.pID,
            serialNumber.SerialNumberLength * sizeof(CHAR));
        // TODO: Display the serial number.
        delete serialNumberBuffer;
    }
    else
    {
        // TODO: Display a message indicating that the serial number MAC
        // does not match.
    }
}

See Also

  • Using Secure Authenticated Channels


Handling Protected Content

If you are building an application or service provider that will consume content protected by Windows Media digital rights management (DRM), you must have a key/certificate pair issued by Microsoft. To learn where to get this certificate, see Tools for Development. If you do not intend to handle protected content, you can use the dummy key and certificate provided with this SDK in a file named key.c.

For any file that is protected by DRM technology, Windows Media Device Manager requires the presence of a secure content provider (SCP) for that file format. Microsoft provides an SCP module for WMA and WMV files. If your application or service provider will be handling DRM-protected content of another format, you must provide your own SCP module. An SCP module is a COM object that implements all the interfaces for Secure Content Providers.

An application can send DRM-protected content to devices built on either Windows Media DRM 10 for Portable Devices, or Portable Device DRM (PDDRM). However, you can only create a service provider for devices built on PDDRM; you cannot create a service provider for devices built on Windows Media DRM 10 for Portable Devices. These latter devices can only use the Microsoft-provided MTP service provider.

Devices built on PDDRM can only support licenses for purchased content. Licenses that have time-expiration conditions are only supported by devices built on Windows Media DRM 10 for Portable Devices, which have special requirements such as a secure clock and individualization. Windows Media DRM 10 for Portable Devices SDK gives details on device requirements to support version 10 technology.

Before sending DRM content to the device, an application should verify several things:

  • That the device supports DRM technology.
  • What version of DRM technology it supports (version 10 or earlier).
  • If the device is built on version 10, that all its components are up to date (such as the secure clock and any individualization requirements).

All method calls to answer these questions are made by the client and handled by Windows Media Device Manager and the secure content provider component; the service provider does not handle any of these calls.

If the device does not support Windows Media DRM 10 for Portable Devices, it might still be able to consume protected content (depending on the content license and the device design), but any content sent to it will have a simplified use license with limited rights (for example, no time expiration).

  • For examples demonstrating how an application verifies whether a device can handle protected content, and whether it needs to update its DRM components, see Handling Protected Content in the Application.
  • For more information about building a service provider that can handle protected content, see Handling Protected Content in the Service Provider.

Note Many Windows Media Device Manager file transfer or rights requesting methods will fail (often with a mysterious HRESULT value) when handling DRM-protected files with a debugger attached. Therefore, you must use alternate ways to debug your code, such as logging outputs to a Windows form or a log file. For more information on logging options, see Enabling Logging. If you are running a debugger on protected content, a method will return one of the error codes listed in the DRM section Error Codes, or possibly an unknown error code. If you get mysterious HRESULT values when running a debugger on protected content or methods, DRM protection might be the cause.

See Also

  • Programming Guide


Getting and Setting Metadata and Attributes

An application can get two kinds of information about a storage or device: attributes and metadata. Attributes are simpler Boolean values that generally describe file system information, such as whether a storage has child objects, whether it can be renamed, read, or deleted, and so on. Attributes are retrieved as flags values by calling IWMDMStorage::GetAttributes or IWMDMStorage2::GetAttributes2. Attributes are set by calling IWMDMStorage3::SetMetadata.

An application can also request more complex data (numeric, string, or other data types) as metadata. Metadata values are identified by unique string names. Windows Media Device Manager defines a list of string constants that can be used to request values; these defined values are listed in Metadata Constants. A service provider can define its own constants, but a calling application must be aware of these definitions in order to request or set these custom metadata values. The application requests metadata by calling IWMDMStorage3::GetMetadata or IWMDMStorage4::GetSpecifiedMetadata.

An important aspect of getting and setting metadata and attributes is understanding where the retrieved values come from. The service provider or the device can get these values from many different places, including the following:

  • From the file header. For example, in an ASF file, the bit rate is stored in the file header.
  • From values set explicitly by the application when calling a method. These values may be saved in an external metadata store in the service provider or the device. This store may or may not persist when the device disconnects or turns off. For example, the play count and user star ratings are typically stored in external stores on the computer or device.
  • By examining information provided by the file system. For example, whether a file is read-only or whether a folder has children.
  • By opening and parsing the file data.

It is important to realize that a property might be stored in more than one location (within the file header and also in a local store), and that it may or may not be editable. For example, changing a file description may or may not be persistent; if the service provider stores the description locally, it will not persist on the device. Similarly, if the file description is taken from the file header, modifying this will only be persistent if the service provider or device opens and modifies the header data. Most applications make a best attempt by changing desired values, but do not depend on any properties to be persistently changed.

More information on getting and setting values is given in the appropriate sections for application developers and service provider developers later in the documentation.

See Also

  • Tasks Common to Applications and Service Providers


Creating a Windows Media Device Manager Application

This section describes how to use Windows Media Device Manager in your application. The term "application" here means either an executable, such as a media player, or a COM plug-in, such as a metering plug-in.

Microsoft includes several service providers with Windows XP and Windows Media Player 10, including an MTP service provider, a Windows CE service provider (for devices running Windows CE and using the RAPI protocol, such as the Pocket PC), and a service provider for mass-storage category (MSC) devices.. You can also create your own service provider to ensure communication with your own device; for more information, see Creating a Service Provider.

There are a number of third-party legacy service providers that address a particular manufacturer's non-MTP, non-RAPI, or non-MSC device. These service providers are included on the driver disk shipped with these devices.

An application that uses Windows Media Device Manager must perform the following steps.

  1. Become aware of privacy issues involved with developing an application. See Privacy Statement to learn about some privacy issues involving developing a Windows Media Device Manager application.
  2. Include the required library and header files for your application. See Required Library and Header Files for an Application to learn what files you will need to include in your project.
  3. Authenticate the application and acquire the root IWMDMDevice interface. The first task an application must do to use Windows Media Device Manager is to authenticate itself. This process verifies the identity of the application to Windows Media Device Manager using a dummy certificate for limited Windows Media Device Manager functionality, or using an official certificate for full functionality. For more information, see Authenticating the Application.
  4. Enumerate the connected devices. The first step in communicating with devices is to find out what devices are connected and accessible to Windows Media Device Manager. For more information, see Enumerating Devices.
  5. Check the status of the device's DRM components. To use DRM-protected files, a device must be built on some version of Windows Media DRM for Portable Devices, and the DRM components must be up to date. Before you begin handling files on the device, it is best to see if the device supports DRM-protected files, and whether the device needs to be updated. For more information, see Handling Protected Content in the Application.
  6. Explore a device. After you have found the device you want, you can explore the contents of that device. For more information, see Exploring a Device.
  7. Read files from the device, and write files to the device. After you know about the layout of the device, you can begin transferring files to and from the device. For more information, see Reading Files from the Device and Writing Files to the Device.
  8. Create playlists on the device. One kind of file you can write to the device is an abstract file, which is a collection of references to other files. Although the ability to write abstract files to a device depends on the service provider and the device, generally only MTP devices have this capability. For more information, see Creating a Playlist on the Device.

In addition to these steps, there are several more features that you can enable in your application:

  • Notifications. You can enable your application to receive notifications when devices connect or disconnect from the computer. For more information, see Enabling Notifications.
  • Logging. Windows Media Device Manager uses a logging object that saves a record of its actions to a local text file. You can add messages to this log to help you analyze errors or performance in your application. For more information, see Enabling Logging.
  • Metering content usage. You can retrieve content usage statistics for licenses that grant this right. These statistics can then be sent up to a Web server to calculate royalty payments to content owners. For more information, see Metering Content Usage.

A note of caution

Your application may need to work with a variety of devices, including some that you have not developed and have never tested your code against. These devices might or might not accurately respond to queries and commands, or implement MTP or other specifications. Be sure to include robust error checking and fallback functionality to deal with the unexpected. Program defensively.

See Also

  • Programming Guide


Privacy Statement

Developers who build Windows Media Device Manager applications should clearly communicate to their users how their privacy could be affected. To help you create an end user privacy statement, Microsoft has posted privacy guidelines on the Windows Media Privacy Web page.

See Also

  • Creating a Windows Media Device Manager Application


Required Library and Header Files for an Application

This section lists the libraries, header files or IDL files you will need to include to develop a Windows Media Device Manager application or plug-in. As mentioned in Compiling the IDL Files Supplied with the SDK, the SDK includes both IDL files and prebuilt header files, and your application can use either. (Note that some header files do not have corresponding IDL files, and you cannot build them yourself.) If building your own IDL files, include the dependencies listed in Compiling the IDL Files Supplied with the SDK.

Not all applications will require all files; read the description to learn whether your application requires a file.

Prebuilt header or library | Equivalent IDL | Description
mssachlp.lib | none | Required by all applications. Contains Windows Media Device Manager objects.
wmvcore.lib | none | Required by applications that use Windows Media Format SDK objects or functions.
initguid.h | none (Platform SDK header) | Required by all applications to define the GUID values using the prebuilt Mswmdm.h file. You must include initguid.h once and only once in your project. This header redefines the DEFINE_GUID macro to avoid external GUID naming problems.
mmreg.h | none (Platform SDK header) | Required by applications that reference various standard Windows Media format definitions, such as WAVEFORMATEX.
mswmdm.h | WMDM.idl icomponentauthenticate.idl | Required by all applications. Defines all the application interfaces, as well as structures, metadata, error, and other constants.
sac.h | none | Required by all applications. Defines SAC protocols.
scclient.h | none | Required by all applications. Declares the CSecureChannelClient class.
wmdmlog.h wmdmlog_i.c | Wmdmlog.idl | Required by applications that use the IWMDMLogger interface.
wmdrmdeviceapp.h | WMDRMDeviceApp.idl | Required by applications or plug-ins that update DRM components or meter play counts on devices.
wmsdk.h | none (provided by Windows Media Format SDK) | Required for applications that use Windows Media Format SDK methods.
MtpExt.h | none | Required for applications that call IWMDMDevice3::DeviceIoControl on MTP devices. Defines various standard MTP constants and structures.
Key.c | none | Defines a key and certificate from Microsoft. The version shipped with the SDK includes a test dummy key that will allow the use of non-DRM protected Windows Media files.

See Also

  • Programming Guide


Authenticating the Application

The first step your application must perform is authentication. Authentication verifies the application's identity to Windows Media Device Manager. Once you authenticate your application, you can call QueryInterface to get the root IWMDeviceManager interface, which can be queried for other required interfaces, which can themselves be queried for all other interfaces. Authentication need only take place once, on startup.

To authenticate your application, perform these steps:

  1. CoCreate the MediaDevMgr object (class ID MediaDevMgr), and request an IComponentAuthenticate interface.
  2. Create a CSecureChannelClient object to handle the authentication.
  3. Pass your application key and transfer certificate to the secure channel object. You can use the dummy key/certificate shown in the following example code to get basic functionality from SDK functions. However, to get full functionality (important for passing files to and from the device), you must request a key and certificate from Microsoft as described in Tools for Development.
  4. Pass the IComponentAuthenticate interface you created in step 1 to the secure channel object.
  5. Call CSecureChannelClient::Authenticate to authenticate your application.
  6. Query IComponentAuthenticate for the IWMDeviceManager interface.

These steps are shown in the following C++ code.

HRESULT CWMDMController::Authenticate()
{
    // Use a dummy key/certificate pair to allow basic functionality.
    // An authentic keypair is required for full SDK functionality.
    BYTE abPVK[] = {0x00};
    BYTE abCert[] = {0x00};
    HRESULT hr;
    CComPtr<IComponentAuthenticate> pAuth;

    // Create the WMDM object and acquire
    // its authentication interface.
    hr = CoCreateInstance(
        __uuidof(MediaDevMgr),
        NULL,
        CLSCTX_INPROC_SERVER,
        __uuidof(IComponentAuthenticate),
        (void**)&pAuth);

    if (FAILED(hr)) return hr;

    // Create the secure channel client class needed to authenticate the application.
    // We'll use a global member variable to hold the secure channel client
    // in case we need to handle encryption, decryption, or MAC verification
    // during this session.
    m_pSAC = new CSecureChannelClient;
    if (m_pSAC == NULL) return E_FAIL;

    // Send the application's transfer certificate and the associated
    // private key to the secure channel client.
    hr = m_pSAC->SetCertificate(
        SAC_CERT_V1,
        (BYTE *)abCert, sizeof(abCert),
        (BYTE *)abPVK,  sizeof(abPVK));
    if (FAILED(hr)) return hr;

    // Send the authentication interface we created to the secure channel
    // client and authenticate the application with the V1 protocol.
    // (This is the only protocol currently supported.)
    m_pSAC->SetInterface(pAuth);
    hr = m_pSAC->Authenticate(SAC_PROTOCOL_V1);
    if (FAILED(hr)) return hr;

    // Authentication succeeded, so we can use WMDM.
    // Query for the root WMDM interface.
    hr = pAuth->QueryInterface( __uuidof(IWMDeviceManager), (void**)&m_IWMDMDeviceMgr);

    return hr;
}

See Also

  • Creating a Windows Media Device Manager Application


Enumerating Devices

After authenticating an application, you can begin to enumerate the devices detected by Windows Media Device Manager. Enumeration is done by using an enumeration interface, IWMDMEnumDevice, obtained by using either IWMDeviceManager2::EnumDevices2 or IWMDeviceManager::EnumDevices. If supported, use the EnumDevices2 method, because the earlier version only returned legacy interfaces on devices, whereas the new version returns both the legacy and the new interfaces.

Before obtaining an enumerator, you should decide what enumeration view to use. Some devices expose each storage as a different device. For example, two flash memory cards on a device will enumerate as if they were separate devices. You can specify that all storages on a device are enumerated together as a single device. You can set this preference only once in your application; if you want to change it, you must shut down the application and restart it. However, note that legacy devices will sometimes ignore a request to enumerate separate device storages as a single device, and continue to enumerate them separately.

The following steps show how to enumerate connected devices:

  1. Set the device enumeration preference using IWMDeviceManager3::SetDeviceEnumPreference. If this method is not called, the default method is to show storages as separate devices. To determine whether individual "devices" are actually storages on the same device, call IWMDMDevice2::GetCanonicalName; storages from the same device will return identical values, except for the final digit after the last "$" sign.
  2. Query for IWMDeviceManager or IWMDeviceManager2, and then call IWMDeviceManager2::EnumDevices2 to obtain the device enumerator interface, IWMDMEnumDevice. (If supported, use EnumDevices2, which is more efficient, as the earlier version may not return MTP devices).
  3. Call the IWMDMEnumDevices::Next method to retrieve one or more devices at a time. Continue to call this method until the method returns S_FALSE or an error message. If retrieving only one device at a time, you do not need to allocate an array to hold the devices.

Because users can attach or remove devices from the computer while your application is running, it is a good idea to implement notification of device connection or removal. This is done by implementing the IWMDMNotification interface and registering it. For more information on this, see Enabling Notifications.

The following C++ code enumerates devices and requests information about each device.

HRESULT CWMDMController::EnumDevices()
{
    HRESULT hr = S_OK;

    // Change behavior to show devices as one object, not each storage as a device.
    // This can be called only once for each instance of this application.
    CComQIPtr<IWMDeviceManager3>pDevMgr3(m_IWMDMDeviceMgr);
    hr = pDevMgr3->SetDeviceEnumPreference(DO_NOT_VIRTUALIZE_STORAGES_AS_DEVICES);

    // Get number of attached devices.
    DWORD iDevices = 0;
    hr = m_IWMDMDeviceMgr->GetDeviceCount(&iDevices);
    if (hr == S_OK)
    {
        // TODO: Display count of devices.
    }

    //
    // Get a device enumerator to enumerate devices.
    //
    CComPtr<IWMDeviceManager2> pDevMgr2;
    hr = m_IWMDMDeviceMgr->QueryInterface (__uuidof(IWMDeviceManager2), (void**) &pDevMgr2);
    if (hr == S_OK)
    {
        // TODO: Display message indicating that application obtained IWMDeviceManager2.
    }
    else
    {
        // TODO: Display message indicating that we couldn't
        // get IWMDeviceManager2 in EnumDevices.
        return hr;
    }
   CComPtr<IWMDMEnumDevice> pEnumDevice;
   hr = pDevMgr2->EnumDevices2(&pEnumDevice);
    if (hr != S_OK)
    {
        // TODO: Display messaging indicating that an error occurred
        // in calling EnumDevices2.
        return hr;
    }

    // Length of all the strings we'll send in.
    const UINT MAX_CHARS = 100;

    // Iterate through devices.
    while(TRUE)
    {
        // Get a device handle.
        IWMDMDevice *pIWMDMDevice;
        ULONG ulFetched = 0;
        hr = pEnumDevice->Next(1, &pIWMDMDevice, &ulFetched);
        if ((hr != S_OK) || (ulFetched != 1))
        {
            break;
        }

        // Get a display icon for the device.
        ULONG deviceIcon = 0;
        hr = pIWMDMDevice->GetDeviceIcon(&deviceIcon);

        // Print the device manufacturer.
        WCHAR manufacturer[MAX_CHARS];
        hr = pIWMDMDevice->GetManufacturer((LPWSTR)&manufacturer, MAX_CHARS);
        if (hr == S_OK)
        {
            // TODO: Display manufacturer name.
        }

        // Get the device name.
        WCHAR name[MAX_CHARS];
        hr = pIWMDMDevice->GetName((LPWSTR)&name, MAX_CHARS);
        if (hr == S_OK)
        {
            // TODO: Display name.
        }

        // TODO: Get other device information if wanted.

        // Obtain an IWMDMDevice2 interface and call some methods.
        CComQIPtr<IWMDMDevice2> pIWMDMDevice2(pIWMDMDevice);
        if (pIWMDMDevice2 != NULL)
        {
            // Get the canonical name.
            WCHAR canonicalName[MAX_CHARS];
            hr = pIWMDMDevice2->GetCanonicalName(canonicalName, MAX_CHARS);
            if (hr == S_OK)
            {
                // TODO: Display canonical name.
            }
        }

        // Obtain an IWMDMDevice3 interface and call some methods.
        CComQIPtr<IWMDMDevice3>pIWMDMDevice3(pIWMDMDevice);
        if (pIWMDMDevice3 != NULL)
        {
            // Find out what protocol is being used.
            PROPVARIANT val;
            PropVariantInit(&val);
            hr = pIWMDMDevice3->GetProperty(g_wszWMDMDeviceProtocol, &val);

            if (hr == S_OK)
            {
                if (*val.puuid == WMDM_DEVICE_PROTOCOL_RAPI)
                {
                    // TODO: Display message indicating device is a RAPI device.
                }
                else if (*val.puuid == WMDM_DEVICE_PROTOCOL_MTP)
                {
                    / /TODO: Display message indicating device is an MTP device.
                }
                else if (*val.puuid == WMDM_DEVICE_PROTOCOL_MSC)
                {
                    // TODO: Display message indicating device is an MSC device.
                }
                else
                {
                    // TODO: Display message indicating that the
                    // application encountered an unknown protocol.
                }
                PropVariantClear(&val);
            }
        }

        // Examine the device capabilities. You could use some of these
        // to enable or disable the application's UI elements.
        CComQIPtr<IWMDMDeviceControl> pDeviceControl(pIWMDMDevice);
        if (pDeviceControl != NULL)
        {
            DWORD caps = 0;
            hr = pDeviceControl->GetCapabilities(&caps);
            if (caps & WMDM_DEVICECAP_CANPLAY)
            {
                // TODO: Display message indicating that the media
                // device can play MP3 audio.
            }
            // TODO: Test for other capabilities here.
        }
    } // Get the next device.
    return hr;
}

See Also

  • Creating a Windows Media Device Manager Application


Exploring a Device

Exploring a device is similar to exploring a disk drive. All objects on a device are called storages. A storage can be a file, folder, or abstract object (such as a playlist) on the device. You must examine a storage's attributes and metadata (if supported) to understand what kind of storage it is. Storages are organized hierarchically on the device; every storage has exactly one parent, and all storages ultimately descend from a single root device storage, typically named "\".

The following steps describe how to explore a device:

  1. Get the IWMDMDevice interface of a device as described in Enumerating Devices.
  2. Call IWMDMDevice::EnumStorage to retrieve an IWMDMEnumStorage interface. This interface is used to get all child objects of the storage that returns this interface. When getting this interface from the device, as we are here, it will hold only one storage: the root device storage.
  3. Call IWMDMEnumStorage::Next with a count of 1 to retrieve the IWMDMStorage interface for the root device storage. (You cannot request more than one child from the device.)
  4. Examine all storages on the device by recursively calling IWMDMStorage::EnumStorage and then IWMDMEnumStorage::Next to get children of a storage. To see if a storage has children to avoid the calls to EnumStorage and Next, you can call IWMDMStorage::GetAttributes to check for the flags WMDM_STORAGE_ATTR_HAS_FILES or WMDM_STORAGE_ATTR_HAS_FOLDERS. For more information about how to get the properties of a storage, see Getting and Setting Metadata and Attributes and Getting and Setting Metadata and Attributes in the Application.

Windows Media Device Manager does not expose a standard set of folders to hold media of a specific type (for example, a "My Playlists" folder for playlists). Every device has a unique file system, and you will have to decide on an appropriate place to look for, or to send, a specific file.

Note Windows Explorer can show virtual folders that do not actually exist on the device. Example virtual folders are the "Media" and "Data" folders displayed for MTP devices. These folders are created by Windows to make downloads simpler for end users; they do not actually exist on the device. Your application should not depend on finding these types of general folders. Conversely, Windows Explorer might not show some folders or objects that do exist on the device (for example, playlists).

The following C++ example code demonstrates the recursive exploration of a device. It uses two functions:

  • ExploreDevice, a starting function that receives a device pointer and obtains a pointer to the root enumerator for that device.
  • RecursiveExploreStorage, which is called to explore a device recursively.
// Get the root enumerator and start the recursive function.
HRESULT ExploreDevice(IWMDMDevice* pDevice)
{
    HRESULT hr = S_OK;

    // Get a root enumerator.
    CComPtr<IWMDMEnumStorage> pEnumStorage;
    hr = pDevice->EnumStorage(&pEnumStorage);
    if (SUCCEEDED(hr))
    {
        RecursiveExploreStorage(pEnumStorage);
    }
    return hr;
}

// Recursively explore a storage.
void RecursiveExploreStorage(IWMDMEnumStorage* pEnumStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage> pStorage;

    ULONG numRetrieved = 0;
    // Loop through all storages in the current storage.
    while((pEnumStorage->Next(1, &pStorage, &numRetrieved) == S_OK) && (numRetrieved == 1))
    {
        // Get the name of the object.
        const UINT MAX_LEN = 255;
        WCHAR name[MAX_LEN];
        hr = pStorage->GetName((LPWSTR)&name, MAX_LEN);
        // TODO: Display the retrieved storage name

        // If this is a folder, recurse into it.
        if (attributes & WMDM_FILE_ATTR_FOLDER)
        {
            CComPtr<IWMDMEnumStorage> pEnumSubStorage;
            hr = pStorage->EnumStorage(&pEnumSubStorage);
            if (SUCCEEDED(hr)
            {
                RecursiveExploreStorage(pEnumSubStorage);
            }
        }
        pStorage.Release();
    } // Get the next storage pointer.
    return;
}

See Also

  • Creating a Windows Media Device Manager Application


Getting and Setting Metadata and Attributes in the Application

A general discussion of metadata and attributes is available in Getting and Setting Metadata and Attributes. This section covers specific application method calls to retrieve or set values.

Applications can retrieve attributes or metadata about a specific storage by calling IWMDMStorage::GetAttributes, IWMDMStorage2::GetAttributes2, IWMDMStorage3::GetMetadata or IWMDMStorage4::GetSpecifiedMetadata. GetMetadata retrieves a full collection of all the metadata associated with a storage, and the application can then enumerate through all values or request specific values from the collection. GetSpecifiedMetadata creates a metadata object on behalf of the caller. The caller may request a subset of the available data by filling in the ppwszPropNames parameter with an array of the desired Windows Media Device Manager property strings, and the count of that array. The returned metadata object will be filled with those properties that could be retrieved. Those properties that couldn't be retrieved will be absent. Metadata is returned on a best-effort basis.

A device can set attributes or metadata on a storage by calling IWMDMStorage::SetAttributes, IWMDMStorage2::SetAttributes2, or IWMDMStorage3::SetMetadata. Note that there is no guarantee that any values set will persist, because they may be stored in a non-persistent external file store, the values may not be supported, or, the device may not support the properties as writeable.

You can also get or set metadata about a device by calling IWMDMDevice3::GetProperty or IWMDMDevice3::SetProperty. There is a separate table of device metadata constants listed at the end of Metadata Constants.

Examples of using these methods are given in each method's reference documentation.

See Also

  • Creating a Windows Media Device Manager Application
  • Getting and Setting Metadata and Attributes


Handling Protected Content in the Application

An application must have a transfer certificate to be able to handle DRM-protected content. To learn where to get this certificate, see Tools for Development. For handling unprotected content, you can use a dummy certificate as described in Authenticating the Application.

Before using a device, your application should determine whether the device supports Windows Media DRM 10 for Portable Devices, and if so, that the DRM components are current. (Current means that the secure clock is correct and that the device has been properly individualized.) If the device does not support this version of DRM, or if it cannot be updated, you can still send files to the device, but they might not be playable, depending on the license version.

Note Individualization of devices is not currently supported.

If your application will link to Windows Media Format SDK methods, it will need to link to the Windows Media Format library WMStubDRM.lib. For more information on calling Windows Media Format methods on DRM-protected content, see "Enabling DRM Support" in the Windows Media Format SDK documentation. Note that there is a problem with linking to both Mssachlp.lib and WMStubDRM.lib. This is covered in KB article 890079 on MSDN.

The following C++ code example determines whether a device is a Windows Media DRM 10 device and, if so, that its clock is up to date.

HRESULT IsDRMClockUpToDate()

{
    HRESULT hr = S_OK;

    // Create the DRM handler class.
    CComPtr<IWMDRMDeviceApp> pDRM;
    hr = pDRM.CoCreateInstance(CLSID_WMDRMDeviceApp, 0, CLSCTX_ALL);

    // Find out first if the device is a WMDRM 10 device, and if so,
    // whether it requires clock updates.
    DWORD status = 0;
    hr = pDRM->QueryDeviceStatus(pDevice, &status);

    if (FAILED(hr)
       || (!(WMDRM_DEVICE_ISWMDRM & status)) // Device is not WMDRM 10.
       || (status & WMDRM_DEVICE_REVOKED))   // Device is revoked.
    {
        return E_FAIL;
    }
    else if (status & WMDRM_DEVICE_NEEDCLOCK ||
        status & WMDRM_DEVICE_REFRESHCLOCK)
    {
        // Attempt update. See following example.
        hr = UpdateDRM(status);
    }
    return hr;
}

If the device does support Windows Media DRM 10 for Portable Devices, and needs to be updated (that is, if the value of status in the previous example is not simply WMDM_DEVICE_ISWMDRM), the application should call IWMDRMDeviceApp::AcquireDeviceData and pass in the value of status to perform the required updates. The desktop computer must be connected to the Internet.

The following C++ example function attempts to update a DRM device.

HRESULT UpdateDRM(DWORD status)
{
    HRESULT hr = S_OK;
    hr = pDRM->AcquireDeviceData(pDevice, this, status, &result);
    if (hr != S_OK || result != 0)
    {
            return E_FAIL;
    }
    return hr;
}

See Also

  • Creating a Windows Media Device Manager Application
  • Handling Protected Content


Reading Files from the Device

When you have found a file you would like to copy from the device, you can then copy the file from the device to the computer in a single call, or use a callback to have the file bytes read directly to your application, which can then process or store the data as it sees fits.

The following steps show the basic way to copy a file from a device in a single call:

  1. Get a handle to the file on the device. You might obtain the handle by using a recursive file search or, if you know the persistent ID of the storage, by calling IWMDMDevice3::FindStorage. In either case, you need the IWMDMStorage interface of the object.
  2. Determine whether the storage is a file or a folder. Only files can be copied from the device. Call IWMDMStorage::GetAttributes to get storage attributes, which will tell you whether the storage is a file or a folder.
  3. Query IWMDMStorage for IWMDMStorageControl, and call IWMDMStorageControl::Read to read the file from the device and save it to a specified location.

If, instead, you want to read the file block by block from the device, you must implement the IWMDMOperation callback interface. Pass this interface into the IWMDMStorageControl::Read call, and Windows Media Device Manager will send chunks of file data sequentially to your callback. The following steps show how to read a device file block by block:

  1. Get the IWMDMStorage interface for the storage and determine whether it is a file, as described previously.
  2. Prepare any file handles or other handles you need to hold the received data.
  3. Query for the storage's IWMDMStorageControl interface
  4. Call IWMDMStorageControl::Read to begin the read operation, passing in the IWMDMOperation interface you have implemented.
  5. Windows Media Device Manager will send the data block by block to your device as described in Handling File Transfers Manually.

The following C++ example function reads a storage object from a device. The function accepts an optional IWMDMOperation interface pointer; if submitted, the function will create a file explicitly and handle writing the data to file on its implementation of IWMDMOperation::TransferObjectData; if not, it will read the file and save to the destination specified by pwszDestName.

HANDLE m_File = NULL;

HRESULT myFileRead(IWMDMStorage pStorage, LPWSTR pwszDestName, IWMDMOperation* pOperation)
{
    HRESULT hr = S_OK;
    if ((pStorage == NULL) || (pwszDestName == NULL))
    {
        return E_INVALIDPARAM;
    }

    // Check that the storage is readable.
    DWORD attributes = 0;
    UINT flags = 0;
    hr = pStorage->GetAttributes(&attributes, NULL);
    if (FAILED(hr))
    {
        return hr;
    }

    // Check that content is readable.
    if ((attributes & WMDM_FILE_ATTR_CANREAD) == 0)
    {
        return E_FAIL;
    }
    // Check that it is not abstract (such as an abstract playlist).
    else if (attributes & WMDM_STORAGE_ATTR_VIRTUAL)
    {
        return E_FAIL;
    }

    // Set some flag values for the read operation.
    flags |= WMDM_MODE_BLOCK;
    if (attributes & WMDM_FILE_ATTR_FOLDER)
    {
        flags |= WMDM_CONTENT_FOLDER;
    }
    if (attributes & WMDM_FILE_ATTR_FILE)
    {
        flags |= WMDM_CONTENT_FILE;
    }

    // Get the IWMDMStorageControl interface.
    CComQIPtr<IWMDMStorageControl> pStgControl(pStorage);

    // Extra steps if we want to read the file ourselves using IWMDMOperation3.
    if (pOperation != NULL)
    {
        // Create a new file and get the handle. m_File is a global variable
        // that we will use in IWMDMOperation::TransferObjectData.
        // This can also be done when IWMDMOperation::BeginRead is called.
        m_File = CreateFile(
            pwszDestName,   // Destination file name.
            GENERIC_WRITE,  // Write and append writes
            NULL,           // File can't be shared while using, and must be closed.
            NULL,           // Handle can't be inherited.
            CREATE_ALWAYS,  // Overwrite existing files.
            FILE_ATTRIBUTE_NORMAL, // No special attributes.
            NULL            // No template file supplied.
           );
        if (m_File == INVALID_HANDLE_VALUE) return E_FAIL;
        // Modify the Read() method flag. WMDM_CONTENT_FILE and WMDM_CONTENT_FOLDER
        // are not valid flags when pOperation != NULL.
        flags |= WMDM_CONTENT_OPERATIONINTERFACE;
    }

    // Read the file.
    hr = pStgControl->Read(
             flags,        // Synchronous call specified.
             pwszDestName, // Ignored if pOperation is not NULL.
             NULL,         // No progress callback sent.
             pOperation);  // IWMDMOperation interface, if provided.
    return hr;
}

See Also

  • Creating a Windows Media Device Manager Application


Writing Files to the Device

Before sending a file to a device, your application must find out what types of files and formats the device can handle, so that the application can determine whether the file should be transcoded before sending, or sent unmodified, or not sent at all.

The following steps show how to send an existing file down to the device. To create a new file on the device, such as a playlist, see Creating a Playlist on the Device.

  1. Get the format of the file you intend to send to the device. For more information, see Discovering a File's Format.
  2. If the device is intended to play the file,
    • Query the file for its format capabilities. For more information, see Discovering Device Format Capabilities.
    • Find an acceptable format that the application can create from the original file.
    • If the file needs to be transcoded, transcode it.
  3. Find a parent storage for the new object. Windows Media Device Manager does not provide a way to discover the standard storage location for any particular file types (video or audio files, WMV or BMP, a "Favorites" folder, and so on), so you will have to examine each device to try to figure out where best to store the new object. (Other applications enforce a certain folder structure, for example, Windows Media Player creates Albums, Playlists and Music folders where the Music folder contains an Artist and AlbumName heirarchy. For this reason, and because some devices may not have been tested with software other than Windows Media Player, be aware that the placement of playlist or album objects in any folder other than the Playlists or Albums folders may sometimes lead to nonfunctioning objects on some devices.)
  4. If the target storage supports IWMDMStorageControl3, create a new metadata interface by calling IWMDMStorage3::CreateEmptyMetadataObject. Set metadata on an IWMDMMetaData interface. For more information, see Setting Metadata on a File. The only required metadata is g_wszWMDMFormatCode (a WMDM_FORMATCODE value describing the content), but the more metadata you can provide, the more efficient the transfer will be for the service provider.
  5. Send the file to the device by using the Insert, Insert2, or Insert3 method. Insert3 allows you to include the metadata on the device as part of the method. For more information, see Sending the File to the Device.

Code demonstrating each of these steps is provided on the linked topic pages.

See Also

  • Creating a Windows Media Device Manager Application


Discovering a File's Format

Before sending a file to the device, an application should determine whether the device supports that file format.

Discovering the format of a file can be complex. The simplest way is to create a list of file extensions mapped to specific WMDM_FORMATCODE enumeration values. However, there are a few problems with this system: one is that a single format can have multiple extensions (such as .jpg, .jpe, and .jpeg for JPEG images). Also, the same file extension can be used by different programs for different formats.

To overcome the limitations of a strict mapping, it is best for an application to verify that the format matches the extension. The DirectShow SDK provides tools that enable an application to discover a limited set of details about most media file types. The Windows Media Format SDK exposes a large number of details, but only about ASF files. Because all file types should have their format code verified if possible, it is therefore best to use DirectShow to discover or verify the basic format code, and use the Windows Media Format SDK to discover any additional metadata desired about ASF files. DirectShow can also be used to discover basic metadata for non-ASF files.

The following is one way to discover a file format using extension mapping and DirectShow.

First, compare the file name extension to a list of known extensions. Be sure to make your comparison case-insensitive. If the extension is not mapped, set the format to WMDM_FORMATCODE_UNDEFINED.

  9. If the format code was not found (or you want to verify that a file is a media file), you can perform the following steps:
    1. Create a DirectShow Media Detector object using CoCreateInstance(CLSID_MediaDet), and retrieving the IMediaDet interface.
    2. Open the file by calling IMediaDet::put_Filename. This call will fail if the file is protected.
    3. Get the media type of the default stream by calling IMediaDet::get_StreamMediaType, which returns an AM_MEDIA_TYPE.
    4. Get the number of streams by calling IMediaDet::get_OutputStreams.
      • If there is only one stream and it is audio, the file type is WMDM_FORMATCODE_UNDEFINEDAUDIO
      • If there is only one stream and it is video, the file type is WMDM_FORMATCODE_UNDEFINEDVIDEO
      • If there is only one stream and it is video and the bit rate is zero, the file type is WMDM_FORMATCODE_WINDOWSIMAGEFORMAT.

You could also try matching audio or video codecs from the VIDEOINFOHEADER or WAVEFORMATEX members retrieved from get_StreamMediaType.

The following C++ function demonstrates file extension matching and using DirectShow to try to analyze unknown files.

// For IMediaDet, you must link to strmiids.lib. Also include the following:
//#include <Qedit.h>  // for IMediaDet declaration.
//#include <Dshow.h>  // for VIDEOINFOHEADER declaration.
WMDM_FORMATCODE CWMDMController::myGetWMDM_FORMATCODE(LPCWSTR pFileName)
{
    HRESULT hr = S_OK;

    // Declare the variable to hold the WMDM format code.
    WMDM_FORMATCODE fmt = WMDM_FORMATCODE_UNDEFINED;

    // Get the file extension.
    wstring ext = pFileName;
    ext = ext.substr(ext.find_last_of(L".") + 1);

    // This is not an exhaustive list.
    // It is also case-sensitive.
    if (ext == L"js" || ext == L"vb")
        fmt = WMDM_FORMATCODE_SCRIPT;
    else if (ext == L".exe")
        fmt = WMDM_FORMATCODE_EXECUTABLE;
    else if (ext == L"txt")
        fmt = WMDM_FORMATCODE_TEXT;
    else if (ext == L"html" || ext == L"htm" || ext == L"shtm")
        fmt = WMDM_FORMATCODE_HTML;
    else if (ext == L"aiff")
        fmt = WMDM_FORMATCODE_AIFF;
    else if (ext == L"wav")
        fmt = WMDM_FORMATCODE_WAVE;
    else if (ext == L"mp3")
        fmt = WMDM_FORMATCODE_MP3;
    else if (ext == L"mpg" || ext == L"mpeg" || ext == L"mp2")
        fmt = WMDM_FORMATCODE_MPEG;
    else if (ext == L"bmp")
        fmt = WMDM_FORMATCODE_IMAGE_BMP;
    else if (ext == L"avi")
        fmt = WMDM_FORMATCODE_AVI;
    else if (ext == L"asf")
        fmt = WMDM_FORMATCODE_ASF;
    else if (ext == L"tif")
        fmt = WMDM_FORMATCODE_IMAGE_TIFF;
    else if (ext == L"gif")
        fmt = WMDM_FORMATCODE_IMAGE_GIF;
    else if (ext == L"pct")
        fmt = WMDM_FORMATCODE_IMAGE_PICT;
    else if (ext == L"png")
        fmt = WMDM_FORMATCODE_IMAGE_PNG;
    else if (ext == L"wma")
        fmt = WMDM_FORMATCODE_WMA;
    else if (ext == L"wpl")
        fmt = WMDM_FORMATCODE_WPLPLAYLIST;
    else if (ext == L"asx")
        fmt = WMDM_FORMATCODE_ASXPLAYLIST;
    else if (ext == L"m3u")
        fmt = WMDM_FORMATCODE_M3UPLAYLIST;
    else if (ext == L"wmv")
        fmt = WMDM_FORMATCODE_WMV;
    else if (ext == L"jpg" || ext == L"jpeg" || ext == L"jpe")
        fmt = WMDM_FORMATCODE_IMAGE_EXIF;
    else if (ext == L"jp2")
        fmt = WMDM_FORMATCODE_IMAGE_JP2;
    else if (ext == L"jpx" || ext == L"jpf")
        fmt = WMDM_FORMATCODE_IMAGE_JPX;

    // If we couldn't get the type from the extension, perhaps DirectShow
    // can determine the type. You could also modify this to verify that
    // the major media type matches the file extension (for example, that
    // a .gif file has a video image stream with a bit rate of zero).
    if (fmt == WMDM_FORMATCODE_UNDEFINED)
    {
        CComPtr<IMediaDet> pIMediaDet;
        hr = pIMediaDet.CoCreateInstance(CLSID_MediaDet, NULL);
        if (hr == S_OK && pIMediaDet != NULL)
        {
            hr = pIMediaDet->put_Filename(BSTR(pFileName));
            if (FAILED(hr)) return WMDM_FORMATCODE_UNDEFINED;

            AM_MEDIA_TYPE mediaType;
            if (hr == S_OK)
            {
                hr = pIMediaDet->get_StreamMediaType(&mediaType);
                CHECK_HR(hr,
                  "get_StreamMediaType succeeded in myGetWMDM_FORMATCODE.",
                  "get_StreamMediaType failed in myGetWMDM_FORMATCODE.");
            }

            if (hr == S_OK)
            {
                LONG numStreams = 0;
                hr = pIMediaDet->get_OutputStreams(&numStreams);

                // If there is at least one video stream, the file is video.
                // If there are only audio streams, it is audio.
                // Loop through all streams or until first video stream is found.
                for (int i = 0; i < numStreams; i++)
                {
                    // Choices are either VIDEOINFOHEADER or WAVEFORMATEX.
                    // VIDEOINFOHEADER2 is not supported.
                    if (IsEqualGUID(mediaType.formattype,
                        FORMAT_VideoInfo))
                    {
                        VIDEOINFOHEADER* data =
                            (VIDEOINFOHEADER*) mediaType.pbFormat;

                        // If only one stream and there was no matching
                        // extension, it is undefined video. If no
                        // bit rate, it's a still image.
                        if (data->dwBitRate == 0) fmt =
                            WMDM_FORMATCODE_WINDOWSIMAGEFORMAT;
                        else fmt = WMDM_FORMATCODE_UNDEFINEDVIDEO;
                        break; // Found video--any additional streams are soundtracks.
                    }
                    if (IsEqualGUID(mediaType.formattype, FORMAT_WaveFormatEx))
                    {
                        // If only one stream and there was no matching
                        // extension, it is undefined audio.
                        if (fmt == WMDM_FORMATCODE_UNDEFINED)
                        {
                            fmt = WMDM_FORMATCODE_UNDEFINEDAUDIO;
                        }
                        WAVEFORMATEX* data =
                            (WAVEFORMATEX*) mediaType.pbFormat;
                    }
                } // Loop through streams.
            }     // Got a stream media type.
        }         // Created a media detector object.
    }
    return fmt;
}

See Also

  • Writing Files to the Device


Discovering Device Format Capabilities

Your application might try to determine a device's playback capabilities before sending a file to it. If a device cannot handle the format of a file you want to send, your application might attempt to transcode the file into a format that the device can use, or notify the user that the device cannot support the requested file.

Note that some devices, such as mass storage class devices, might serve only as removable storage media without playback capabilities. In this case, it would be inappropriate for your application to transcode a file before sending it to the device.

Although the IWMDMDevice::GetType method enables a device to report its capabilities, some devices return incorrect values for this method. Before copying a file to a device, you might want to ask the user whether playback is intended, and if so, attempt to transcode the file to one of the device's reported formats (or a reasonable format, if the device claims support for any format). Another approach is to assume that any formats specifically listed as supported by the device are intended for playback, and all other files should be transferred unmodified.

After discovering the format of the file to be transferred, and the formats supported by a device, you can decide which is the best target format for transcoding.

In the past, it was common for an application to return zero for a property to indicate support for any values of that property. For example, a value of zero for _WAVEFORMATEX.nSamplesPerSec would indicate support for any bit rate. Now, the recommended way to indicate support for any value is to specify WMDM_ENUM_PROP_VALID_VALUES_ANY in WMDM_PROP_DESC.ValidValuesForm. Some properties, though, can legitimately return zero to indicate specific support. For example, if _BITMAPINFOHEADER .biSizeImage is set to zero, this indicates a BI_RGB bitmap. Exceptions for zero values are noted in the documentation for the relevant structures.

However, it is important to note that devices often do not report their format capabilities properly, or in a standard way. For example, devices often report that they support any format, when in fact they can only handle specific formats, or specific bit rates within a format type. It is up to you to decide whether your application should accept such reports, or whether it should assume some kind of upper limit to a device's playback abilities (for example, 192 kbps).

The recommended method for requesting a device's format support is IWMDMDevice3::GetFormatCapability. If this method is not supported, your application should fall back on IWMDMDevice::GetFormatSupport. GetFormatSupport, unlike GetFormatSupport2, does not return video information.

How an application requests a device's format capabilities depends on which interface the application supports. For more details, see the following topics:

  • Getting Format Capabilities on Devices That Support IWMDMDevice3
  • Getting Format Capabilities on Devices That Support Only IWMDMDevice

See Also

  • Writing Files to the Device


Getting Format Capabilities on Devices That Support IWMDMDevice3

IWMDMDevice3::GetFormatCapability is the preferred method for asking a device what formats it supports. The following steps show how to use this method to query a device for its format capabilities:

  1. The application must determine which formats a device supports and which are of interest. To do this, the application can request a list of formats supported by the device by calling IWMDMDevice3::GetProperty.
  2. The application loops through all of the supported formats and requests a device's format capabilities for a specific format (such as WMA or WMV) by calling IWMDMDevice3::GetFormatCapability and specifying a format using the WMDM_FORMATCODE enumeration. This method retrieves a WMDM_FORMAT_CAPABILITY structure.
  3. Loop through all the WMDM_PROP_CONFIG structures in the retrieved WMDM_FORMAT_CAPABILITY structure. Each WMDM_PROP_CONFIG structure holds a group of properties with supported values, representing one configuration for that format. Each configuration has a preference number, where a lower number indicates a greater preference by the device.
  4. Loop through all the WMDM_PROP_DESC structures in the retrieved WMDM_PROP_CONFIG. Each WMDM_PROP_DESC contains a list of supported property/value pairs.
  5. Retrieve the property names and values from the WMDM_PROP_DESC structure. Properties include bit rate, codec, and frame size. Property names are defined in the mswmdm.h header file; a list of most of these constants is given in Metadata Constants. Three types of property values are possible:
    • A single value, WMDM_ENUM_PROP_VALID_VALUES_ANY, indicating support for any values for this property.
    • A range of values, defined by a maximum value, minimum value, and interval.
    • A list of discrete values.
  6. Clear the stored values. Memory for these values is allocated by Windows Media Device Manager; your device is responsible for freeing the memory. How to do this is described at the end of this topic.

When responding to GetFormatCapability, a device can report WMDM_ENUM_PROP_VALID_VALUES_ANY for WMDM_FORMAT_CAPABILITY.WMDM_PROP_CONFIG.WMDM_PROP_DESC.ValidValuesForm to claim support for any values for bit rate, channels, and so on. However, you should treat this claim with caution, because devices can sometimes report support for any values when in fact they do not support all bit rates or image sizes. You might consider having your application transcode extremely large or high-bit-rate files to smaller versions or less memory-intensive and CPU-intensive versions when sending them to devices that are intended to play these files.

The following C++ function shows how to request device format support for a specific format.

HRESULT GetFormatCaps(WMDM_FORMATCODE formatCode, IWMDMDevice3* pDevice)
{
    HRESULT hr = S_OK;

    // Get a list of supported configurations for the format.
    WMDM_FORMAT_CAPABILITY formatCapList;
    hr = pDevice->GetFormatCapability(formatCode, &formatCapList);
    if (FAILED(hr)) return E_FAIL;

    // TODO: Display the format name.
    // Loop through the configurations and examine each one.
    for (UINT iConfig = 0; iConfig < formatCapList.nPropConfig; iConfig++)
    {
        WMDM_PROP_CONFIG formatConfig = formatCapList.pConfigs[iConfig];

        // Preference level for this configuration (lower number means more preferred).
        // TODO: Display the preference level for this format configuration.

        // Loop through all properties for this configuration and get supported
        // values for the property. Values can be a single value, a range,
        // or a list of enumerated values.
        for (UINT iDesc = 0; iDesc < formatConfig.nPropDesc; iDesc++)
        {
            WMDM_PROP_DESC propDesc = formatConfig.pPropDesc[iDesc];
            // TODO: Display the property name.

            // Three ways a value can be represented: any, a range, or a list.
            switch (propDesc.ValidValuesForm)
            {
                case WMDM_ENUM_PROP_VALID_VALUES_ANY:
                    // TODO: Display a message indicating that all values are valid.
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
                    {
                        // List these in the docs as the propvariants set.
                        WMDM_PROP_VALUES_RANGE rng =
                            propDesc.ValidValues.ValidValuesRange;
                        // TODO: Display the min, max, and step values.
                    }
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
                    {
                        // TODO: Display a banner for the list of valid values.
                        WMDM_PROP_VALUES_ENUM list = propDesc.ValidValues.EnumeratedValidValues;
                        PROPVARIANT pVal;
                        for (UINT iValue = 0; iValue < list.cEnumValues; iValue++)
                        {
                            pVal = list.pValues[iValue];
                            // TODO: Display each valid value.
                            PropVariantClear(&pVal);
                            PropVariantInit(&pVal);
                        }
                    }

                    break;
                default:
                    return E_FAIL,
                    break;
            }
        }
    }
    // Now clear the memory used by WMDM_FORMAT_CAPABILITY.
    FreeFormatCapability(formatCapList);
    return hr;
}

Clearing allocated memory

After retrieving format capabilities from a device, the application must free the memory allocated to hold the description. GetFormatSupport and GetFormatSupport2 have arrays of simple structures that can be cleared by simply calling CoTaskMemFree with the array. However, GetFormatCapability has a more complex data structure with dynamically allocated memory that must be cleared by looping through all the elements and freeing them individually.

The following C++ code shows how an application can free the memory allocated for a WMDM_FORMAT_CAPABILITY structure.

void CWMDMController::FreeFormatCapability(WMDM_FORMAT_CAPABILITY formatCap)
{
    // Loop through all configurations.
    for (UINT i = 0; i < formatCap.nPropConfig; i++)
    {
        // Loop through all descriptions of a configuration and delete
        // the values particular to that description type.
        for (UINT j=0; j < formatCap.pConfigs[i].nPropDesc; j++)
        {
            switch (formatCap.pConfigs[i].pPropDesc[j].ValidValuesForm)
            {
                case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
                    for (UINT k=0; k < formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.cEnumValues; k++)
                    {
                        PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.pValues[k]));
                    }
                    CoTaskMemFree(formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.pValues);
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
                    PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeMin));
                    PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeMax));
                    PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeStep));
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_ANY:
                    // No dynamically allocated memory for this value.
                default:
                    break;
            }

            // Free the memory for the description name.
            CoTaskMemFree(formatCap.pConfigs[i].pPropDesc[j].pwszPropName);
        }
        // Free the memory holding the array of description items for this configuration.
        CoTaskMemFree(formatCap.pConfigs[i].pPropDesc);
    }

    // Free the memory pointing to the array of configurations.
    CoTaskMemFree(formatCap.pConfigs);
    formatCap.nPropConfig = 0;
}

Querying for all supported formats

Typically, an application queries a device for a specific format, because it is interested in sending a specific file to the device. However, if you want to query an application for all its supported formats, you can call IWMDMDevice3::GetProperty and pass in g_wszWMDMFormatsSupported to retrieve a full list.

If a device only returns one element, WMDM_FORMATCODE_UNDEFINED, this usually means that the device does not support format codes. Calling GetFormatCapability with WMDM_FORMATCODE_UNDEFINED might retrieve capabilities, but these properties might be fairly generic (such as name, file size, last modified date, and so on).

The following steps show how to query for a list of all supported formats:

  1. Request a list of all format codes supported by calling IWMDMDevice3::GetProperty and passing in g_wszWMDMFormatsSupported. This returns a PROPVARIANT containing a SAFEARRAY of supported formats.
  2. Loop through the elements by calling SafeArrayGetElement. Each element is a WMDM_FORMATCODE enumeration.
  3. Request the capabilities for each format, freeing the memory for each WMDM_FORMAT_CAPABILITY element once done with it.
  4. Clear the PROPVARIANT retrieved in step 1 by calling PropVariantClear.

The following C++ example code retrieves a list of supported formats for a device.

// Query a device for supported configurations for each media or format type.
HRESULT CWMDMController::GetCaps(IWMDMDevice3* pDevice)
{
    HRESULT hr = S_OK;

    // Request the "formats supported" property to get a list of supported formats.
    PROPVARIANT pvFormatsSupported;
    PropVariantInit(&pvFormatsSupported);
    hr = pDevice->GetProperty(g_wszWMDMFormatsSupported, &pvFormatsSupported);
    HANDLE_HR(hr, "Got a property list in GetCaps", "Couldn't get a property list in GetCaps.");

    // Loop through the retrieved format list.
    // For each format, get a list of format configurations.
    SAFEARRAY* formatList = pvFormatsSupported.parray;
    WMDM_FORMATCODE formatCode = WMDM_FORMATCODE_NOTUSED;
    for (LONG iCap = 0; iCap < formatList->rgsabound[0].cElements; iCap++)
    {
        // Get a format from the SAFEARRAY of retrieved formats.
        SafeArrayGetElement(formatList, &iCap, &formatCode);

        // Call a custom function to request the format capabilities.
        if (formatCode != WMDM_FORMATCODE_NOTUSED)
            myGetFormatCaps(formatCode, pDevice);
    }

e_Exit:
    // Clear out the memory we used.
    PropVariantClear(&pvFormatsSupported);
    return hr;
}

See Also

  • Discovering Device Format Capabilities


Getting Format Capabilities on Devices That Support Only IWMDMDevice

The recommended method for querying a device for its playback capabilities is IWMDMDevice3::GetFormatCapability. However, if a device does not support this method, the application instead can call IWMDMDevice::GetFormatSupport to retrieve an array of supported audio formats as _WAVEFORMATEX structures and MIME formats as strings from the device.

The following steps show how an application can use this method to query a device for supported formats:

  1. Call GetFormatSupport to retrieve arrays of both audio and mime formats.
  2. Loop through the retrieved audio formats and examine each _WAVEFORMATEX structure to try to find an acceptable audio format
  3. Loop through the retrieved MIME format strings (if desired) to find an acceptable file type. The SDK does not define constants for MIME formats; you should use industry standard values (which can be found at the iana.org Web site). A device should list the specific MIME types that it supports.

The following C++ code demonstrates retrieving format capabilities from a device, using GetFormatSupport.

// Function to print out device caps for a device
// that supports only IWMDMDevice.
void CWMDMController::GetCaps(IWMDMDevice* pDevice)
{
    HRESULT hr = S_OK;

    // Get all capabilities for audio and mime support.
    _WAVEFORMATEX* pAudioFormats;
    LPWSTR* pMimeFormats;
    UINT numAudioFormats = 0;
    UINT numMimeFormats = 0;
    hr = pDevice->GetFormatSupport(
        &pAudioFormats,
        &numAudioFormats,
        &pMimeFormats,
        &numMimeFormats);
    if (FAILED(hr)) return;

    // Print out audio format data.
    if (numAudioFormats > 0)
    {
        // TODO: Display a banner for the supported audio-format listing.
    }
    else
    {
        // TODO: Display a message indicating that no audio formats are supported.
    }
    for (int i = 0; i < numAudioFormats; i++)
    {
// TODO: For each valid audio format, display the max channel,
// max samples/second, avg. bytes/sec, block alignment, and
// max bits/sample values.
    }

    // Print out MIME formats.
    if (numMimeFormats > 0)
        // TODO: Display a banner to precede the MIME format listing.
    else
        // TODO: Display a banner indicating that no MIME formats are supported.
    for (i = 0; i < numMimeFormats; i++)
    {
        // TODO: Display the specified MIME format.
    }
    return;
}

See Also

  • Discovering Device Format Capabilities
  • Getting Format Capabilities on Devices That Support IWMDMDevice3


Setting Metadata on a File

You can set metadata on a file before writing it to the device (when using IWMDMStorageControl3::Insert3) or on an existing storage (by calling IWMDMStorage3::SetMetadata). You can set attributes only on an existing storage (by calling IWMDMStorage::SetAttributes or IWMDMStorage2::SetAttributes2).

Setting metadata is done by creating and filling an IWMDMMetaData interface that is passed into IWMDMStorageControl3::Insert3. However, this method can clear all existing metadata on the file, other than hard-coded metadata stored in the file system itself, such as file name or size. Therefore, you must copy all existing metadata that you wish to retain into the IWMDMMetaData interface you submit. Because Windows Media Device Manager cannot be used to retrieve metadata from local files, you must use the Windows Media Format SDK (or some other tool) to retrieve such metadata.

To use the Windows Media Format SDK to retrieve ASF file properties, follow these steps:

  1. Create a metadata editor object by calling WMCreateEditor and requesting an IWMMetadataEditor interface.
  2. Open the file for metadata reading by calling IWMMetadataEditor::Open.
  3. If the file is a valid ASF file and can be opened, query the editor for the IWMHeaderInfo interface.
  4. Retrieve file properties by calling IWMHeaderInfo::GetAttributeByName, passing in the desired Windows Media Format SDK property constant. A list of Format SDK constants with equivalent Windows Media Device Manager SDK constants is given in the following table.
Windows Media Format SDK Constant | Windows Media Device Manager SDK Constant
g_wszWMTitle | g_wszWMDMTitle
g_wszWMAuthor | g_wszWMDMAuthor
g_wszWMAlbumTitle | g_wszWMDMAlbumTitle
g_wszWMGenre | g_wszWMDMGenre
g_wszWMYear | g_wszWMDMYear
g_wszWMTrackNumber or g_wszWMTrack | g_wszWMDMTrack
g_wszWMComposer | g_wszWMDMComposer
g_wszWMDuration | g_wszWMDMDuration
g_wszWMCopyright | g_wszWMDMProviderCopyright
g_wszWMDescription | g_wszWMDMDescription
g_wszWMBitrate | g_wszWMDMBitrate
g_wszWMRating | g_wszWMDMUserRating
g_wszWMAlbumArtist | g_wszWMDMAlbumArtist
g_wszWMParentalRating | g_wszWMDMParentalRating
g_wszWMRadioStationName | g_wszWMDMMediaStationName
g_wszWMSubTitle | g_wszWMDMSubTitle
g_wszWMVideoWidth | g_wszWMDMWidth
g_wszWMVideoHeight | g_wszWMDMHeight
g_wszWMMood | g_wszWMDMTrackMood
g_wszWMCodec | g_wszAudioWAVECodec or g_wszVideoFourCCCodec

The following C++ example code demonstrates retrieving a number of metadata properties from an ASF file using the Windows Media Format SDK and converting them to the equivalent Windows Media Device Manager values.

// Structure and array to hold equivalent Windows Media Format SDK
// and Windows Media Device Manager SDK metadata property names.
struct EquivalentProperty
{
    LPCWSTR FormatSDKConst;
    LPCWSTR WMDMSDKConst;
};
EquivalentProperty EquivalentProperties []=
{
    {g_wszWMTitle,        g_wszWMDMTitle},
    {g_wszWMAuthor,      g_wszWMDMAuthor},
    {g_wszWMAlbumTitle,  g_wszWMDMAlbumTitle},
    {g_wszWMGenre,       g_wszWMDMGenre},
    {g_wszWMYear,        g_wszWMDMYear},
    {g_wszWMTrackNumber, g_wszWMDMTrack},
    {g_wszWMTrack,       g_wszWMDMTrack},
    {g_wszWMComposer,    g_wszWMDMComposer},
    {g_wszWMBitrate,     g_wszWMDMBitrate},
    {g_wszWMDuration,    g_wszWMDMDuration},
    {g_wszWMCopyright,   g_wszWMDMProviderCopyright},
    {g_wszWMDescription, g_wszWMDMDescription},
    {g_wszWMRating,      g_wszWMDMUserRating},
    {g_wszWMAlbumArtist, g_wszWMDMAlbumArtist},
    {g_wszWMParentalRating,    g_wszWMDMParentalRating},
    {g_wszWMRadioStationName,  g_wszWMDMMediaStationName},
    {g_wszWMSubTitle,    g_wszWMDMSubTitle},
    {g_wszWMVideoWidth,  g_wszWMDMWidth},
    {g_wszWMVideoHeight, g_wszWMDMHeight},
    {g_wszWMMood,        g_wszWMDMTrackMood},
    {g_wszWMCodec,       g_wszAudioWAVECodec},
    {g_wszWMCodec,       g_wszVideoFourCCCodec}
};
// Function that tries to get metadata by using the Format SDK.
// If it cannot open the file, it returns E_FAIL.
HRESULT GetFileMetadataFromFormatSDK(IWMDMMetaData* pMetadata, LPCWSTR file)
{
    if ((pMetaData == NULL) || (file == NULL)) return E_INVALIDPARAM;
    HRESULT hr = S_OK;
    CComPtr<IWMMetadataEditor> pEditor;

    // Do loop to allow easy error trapping. Even if there are no errors,
    // the loop executes only once.
    do {
        hr = WMCreateEditor(&pEditor);
        if (FAILED(hr))
            break;

        // Open the file.
        hr = pEditor->Open(file);
        if (FAILED(hr))
            break;

        CComPtr<IWMHeaderInfo>pHeaderInfo;
        hr = pEditor->QueryInterface(__uuidof(IWMHeaderInfo), (void**)&pHeaderInfo);
        if (FAILED(hr))
            break;

        // Copy values from Format SDK to equivalent WMDM SDK metadata values.

        // Loop through all known values
        WORD stream = 0;
        WMT_ATTR_DATATYPE wmfType;
        WORD len = 0;
        BYTE* value = NULL;
        WMDM_TAG_DATATYPE wmdmType;
        for (int i = 0; i < sizeof(EquivalentProperties) / sizeof(EquivalentProperties[0]); i++)
        {
            // Request each value from our equivalency list by name.
            // The function is called twice: once to get the buffer size,
            // and once to get the value in the allocated buffer.
            if (FAILED(pHeaderInfo->GetAttributeByName(
                &stream, EquivalentProperties[i].FormatSDKConst, &wmfType, NULL, &len)))
            {
                continue;
            }

            value = new BYTE[len];
            if (value == NULL) continue;

            if (FAILED(pHeaderInfo->GetAttributeByName(&stream, EquivalentProperties[i].FormatSDKConst, &wmfType, value, &len)))
            {
                delete[] value;
                continue;
            }

            // Send the data to the equivalent WMDM metadata value.
            // First, find the equivalent WMDM type for the WMF type.
            switch(wmfType)
            {
            case WMT_TYPE_BINARY:
                wmdmType = WMDM_TYPE_BINARY;
                break;
            case WMT_TYPE_DWORD:
                wmdmType = WMDM_TYPE_DWORD;
                break;
            case WMT_TYPE_STRING:
                wmdmType = WMDM_TYPE_STRING;
                break;
            case WMT_TYPE_BOOL:
                wmdmType = WMDM_TYPE_BOOL;
                break;
            case WMT_TYPE_QWORD:
                wmdmType = WMDM_TYPE_QWORD;
                break;
            case WMT_TYPE_WORD:
                wmdmType = WMDM_TYPE_WORD;
                break;
            case WMT_TYPE_GUID:
                wmdmType = WMDM_TYPE_GUID;
                break;
            default:
                wmdmType = WMDM_TYPE_BINARY;
                break;
            }

            // Don't worry about trapping errors, because there's nothing
            // we can do about it.
            pMetadata->AddItem(wmdmType,
                EquivalentProperties[i].WMDMSDKConst, value, len);
            delete[] value;
        } // Add next value.
    } while (FALSE); // End Do loop error trap.

    // Close the file opened with IWMMetadataEditor.
    pEditor->Close();
    return hr;
}

The following C++ example function shows how to use DirectShow to get some file information and add it to the metadata.

// For IMediaDet, you must link to strmiids.lib. Also include the following:
//#include <Qedit.h>  // for IMediaDet declaration.
//#include <Dshow.h>  // for VIDEOINFOHEADER declaration.
HRESULT GetFileMetadataFromDShow(IWMDMMetaData* pMetadata, LPCWSTR file)
{
    HRESULT hr = S_OK;

    // Add file metadata properties from DirectShow.
    // This is good for non-ASF files, or to add any information
    // that the Format SDK didn't get.

    // Do loop to allow easy error trapping. Even if there are no errors,
    // the loop executes only once.
    do
    {
        // Create the Media Detector object.
        CComPtr<IMediaDet> pIMediaDet;
        hr = pIMediaDet.CoCreateInstance(CLSID_MediaDet, NULL);
        if (FAILED(hr))
            break;

        // Open the file.
        hr = pIMediaDet->put_Filename(BSTR(file));
        if (FAILED(hr))
            break;

        // Get the media type for the default stream.
        AM_MEDIA_TYPE mediaType;
        hr = pIMediaDet->get_StreamMediaType(&mediaType);
        if (FAILED(hr))
            break;

        // We have the file open, so start requesting information from the
        // Media Detector and adding it to the metadata. When adding
        // individual metadata values, ignore the HRESULT, because failure
        // to add these metadata values is not a breaking issue.

        // Get major and minor types.
        WCHAR strMediaType[64];
        ZeroMemory(strMediaType, 64);

        //Change the major type to a string, then add to IWMDMMetaData.
        StringFromGUID2(reinterpret_cast<GUID&>(mediaType.majortype),
            (LPOLESTR)strMediaType, 64);
        hr = pMetadata->AddItem(WMDM_TYPE_STRING,
             g_wszWMDMediaClassPrimaryID,
            (BYTE*) strMediaType,
             sizeof(strMediaType) / sizeof(strMediaType[0]));

        // Clear local string, then retrieve subtype the same way.
        ZeroMemory(strMediaType, 64);
        StringFromGUID2(reinterpret_cast<GUID&>(mediaType.subtype),
            (LPOLESTR)strMediaType, 64);
        hr = pMetadata->AddItem(WMDM_TYPE_STRING,
            g_wszWMDMMediaClassSecondaryID, (BYTE*) strMediaType,
            sizeof(strMediaType) / sizeof(strMediaType[0]));

        // Get the duration. Duration is retrieved in seconds, but set
        // in 100-nanosecond units.
        double duration = 0;
        hr = pIMediaDet->get_StreamLength(&duration);
        if (duration > 0)
        {
            duration *= 10E7;
            hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMDuration, (BYTE*) &duration, sizeof(duration));
        }

        // Get the frame rate.
        double frameRate = 0;
        hr = pIMediaDet->get_FrameRate(&frameRate);
        if (frameRate > 0)
        {
            hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMFrameRate,
                (BYTE*) &frameRate,
                sizeof(frameRate));
        }

        // Get the structure for the default stream's major type and
        // fill in additional information.

        if (IsEqualGUID(mediaType.formattype, FORMAT_VideoInfo))
        {
            VIDEOINFOHEADER* data = (VIDEOINFOHEADER*) mediaType.pbFormat;
            hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMVideoBitrate,
               (BYTE*) &data->dwBitRate, sizeof(DWORD));
            hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMHeight,
               (BYTE*) &data->bmiHeader.biHeight, sizeof(LONG));
            hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMWidth,
               (BYTE*) &data->bmiHeader.biWidth, sizeof(LONG));
        }

        if (IsEqualGUID(mediaType.formattype, FORMAT_WaveFormatEx))
        {
            WAVEFORMATEX* data = (WAVEFORMATEX*) mediaType.pbFormat;
            hr = pMetadata->AddItem(WMDM_TYPE_WORD, g_wszWMDMBlockAlignment,
                (BYTE*) &data->nBlockAlign, sizeof(WORD));
            hr = pMetadata->AddItem(WMDM_TYPE_WORD, g_wszWMDMNumChannels,
               (BYTE*) &data->nChannels, sizeof(WORD));
        }
    } while (FALSE); // End of error loop.
    return hr;
}

See Also

  • Writing Files to the Device


Sending the File to the Device

After the file has been transcoded if necessary, and all metadata including the format has been set, your application can send the file to the device. In order to do so, you must first get an IWMDMStorageControl interface (or a later version) for a target location on the device. The Insert flags specify whether the new storage should be a sibling or child of the target. Once you have gotten the target, you can call IWMDMStorageControl::Insert, IWMDMStorageControl2::Insert2, or IWMDMStorageControl3::Insert3 to transfer the file. The application can handle reading the file data itself by implementing IWMDMOperation, or it can allow the Insert method to read and transfer the file automatically by not providing a pointer to an application-implemented IWMDMOperation.

The following C++ code demonstrates calling Insert3 to write a file to a device. If the pOperation pointer passed to Insert3 is NULL, the file will be sent in one step; if this pointer is a valid interface pointer, Windows Media Device Manager will call your callback method to get data in blocks. For details on how to implement IWMDMOperation, see Handling File Transfers Manually.

// Set the flags for the operation
UINT flags = WMDM_MODE_BLOCK | // Synchronous call.
    WMDM_STORAGECONTROL_INSERTINTO | // Insert it into the destination folder.
    WMDM_CONTENT_FILE | // We're inserting a file.
    WMDM_FILE_CREATE_OVERWRITE; // Overwrite existing files.
if (pOperation != NULL)
    flags |= WMDM_CONTENT_OPERATIONINTERFACE;

// Send the file and metadata.
hr = pStgCtl3->Insert3(
    flags,
    WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
    const_cast<WCHAR*>(pwszFileName), // Source file.
    L"My New File.wma",//NULL, // Destination file name.
    pOperation, // NULL to allow the SDK to read the file;
                // non-NULL to present raw data bytes to the SDK.
    pProgress, // Interface to send simple progress notifications.
    pMetadata, // IWMDMMetaData interface previously created and filled.
    NULL,
    &pNewStorage); // Out: handle to the new storage, if the method succeeds.

See Also

  • Writing Files to the Device


Handling File Transfers Manually

Your application can implement the IWMDMOperation interface to manage part of the reading or writing process. On a read from device, the implementation enables the application to receive blocks of raw data from a device file. On a write to device, it enables the application to send blocks of raw data to a file on the device.

In both read and write operations, the IWMDMOperation::TransferObjectData method passes the data between the computer and the device. To know the direction of the data transfer, your application must set a flag when Windows Media Device Manager calls BeginRead or BeginWrite. When the End method is called, the application should reset this flag.

Note If the service provider and device properly implement IMDSPObject2, it will first call the application's IWMDMOperation3::TransferObjectDataOnClearChannel method, if implemented. This method is a more efficient way of transferring data. TransferObjectDataOnClearChannel is handled the same way as TransferObjectData, except that the data is never encrypted and has no MAC values to verify.

The following sections describe both the reading and the writing process, when your application implements IWMDMOperation.

Reading from a device

When reading a file from a device, Windows Media Device Manager calls the following IWMDMOperation methods in order:

  • BeginRead Called to notify the application that a read from device is beginning.
  • TransferObjectData Called one or more times. The processing of data is described in the following steps:
    1. TransferObjectData receives a buffer, pData, of size pdwSize bytes, filled with data, and a MAC to verify the incoming data.
    2. The application verifies the incoming parameters with the incoming data MAC.
    3. The application decrypts and read as much of the data in pData as it can, and modifies the returned value of pdwSize to indicate how many bytes were actually read.
    4. The application decrypts the data, using CSecureChannelClient::DecryptParam, and stores it or uses it, as needed.
    5. TransferObjectData returns S_OK.
    6. Windows Media Device Manager continues to call TransferObjectData until the application has read all the data from the file, or the application returns WMDM_E_USER_CANCELLED to cancel the operation (in which case the read is canceled, and Windows Media Device Manager calls End).
  • End Called to notify the application that a read from device is ending.

Writing to a device

When writing a file to the device, Windows Media Device Manager calls the following IWMDMOperation methods in order:

  • GetObjectName Called to allow the application to specify a name for the new storage. This method is only called if the application did not specify a name in the Insert method.
  • GetObjectAttributes Called to allow the application to specify attributes for the new storage on the device.
  • BeginWrite Called to notify that that a write to device is beginning.
  • GetObjectTotalSize Called to retrieve the total size of the object being written to the device, to enable optimization of the transfer, and also to give Windows Media Device Manager an opportunity to cancel the transfer if the file is too large for the device.
  • TransferObjectData Called one or more times. The processing of data is described in the following steps:
    1. TransferObjectData receives a pointer to a buffer of size pdwSize bytes.
    2. The application gets a block of data to send to the device, usually by reading data from a file, and fills the received buffer with up to pdwSize bytes. It should modify pdwSize (if necessary) to reflect how many bytes were added to the buffer.
    3. The application creates a MAC of all the method parameters.
    4. The application encrypts the data in the buffer, using CSecureChannelClient::EncryptParam.
    5. TransferObjectData returns S_OK to indicate that there is more data, or S_FALSE to indicate that there is no more data. If the application returns WMDM_E_USER_CANCELLED, the write operation is canceled and Windows Media Device Manager will call End.
    6. Windows Media Device Manager continues to call TransferObjectData as long as the application returns S_OK.
  • End Called to notify that that a write to device is ending.

For a code example, see Encryption and Decryption.

See Also

  • Creating a Windows Media Device Manager Application


Creating a Playlist on the Device

The Windows Media Device Manager SDK provides the means for an MTP application to create a playlist on a device. This type of playlist is called an abstract playlist, because the file created on the device contains no media data, but only metadata, which holds the links to media files in the playlist.

Other abstract items that can be created on the device include albums (essentially playlists with extra properties such as cover art), contacts, and messages.

To create a playlist

  1. Acquire an IWMDMDevice3 interface to the target device.
  2. Call IWMDMDevice3::GetProperty to obtain the g_wszWMDMFormatsSupported property.
  3. If no playlist formats are supported, disallow sending playlists to the device, and skip the following steps. Otherwise, choose the device-supported format code that matches most closely the intended object type. The generic WMDM_FORMATCODE_ABSTRACTAUDIOVIDEOPLAYLIST and WMDM_FORMATCODE_ABSTRACTAUDIOLAYLIST format codes are the most commonly supported.
  4. Obtain an IWMDMStorage3 interface for the storage (the root or a folder) where you want to create the object. Some devices work best if the playlist object is placed in a top level folder named "Playlists".
  5. Create an empty metadata object by using IWMDMStorage3::CreateEmptyMetadataObject.
  6. Using the IWMDMMetaData interface obtained in the previous step, call IWMDMMetaData::AddItem to add your chosen format code (from step 3) to the storage metadata properties.
  7. Obtain the IWMDMStorageControl3 interface from the IWMDMStorage3 interface.
  8. Call IWMDMStorageControl3::Insert3 to insert a new playlist file in the selected storage. This file contains the metadata represented by the IWMDMMetaData interface you created in step 5 and passed to Insert3. The method returns an IWMDMStorage interface for the playlist file; you can query for the IWMDMStorage4 interface.
  9. Call IWMDMStorage4::SetReferences to create references to the IWMDMStorage interfaces of the media files in the playlist.

For example code, see the _OnCreatePlaylist function in the Sample Desktop Application.

Note The Microsoft-provided MTP service provider enables an application to set references in metadata. To implement playlists, your application must be communicating with an MTP device or using a custom service provider that can handle abstract objects. The CE service provider handles playlist and album objects.

See Also

  • Writing Files to the Device


Enabling Notifications

Windows Media Device Manager declares four interfaces that an application can implement in a COM class to receive event notifications. These interfaces fall into two groups, as shown in the following table.

Interfaces | Description
IWMDMNotification | Notifies the application when devices or storage media are connected or disconnected.
IWMDMProgress IWMDMProgress2 IWMDMProgress3 | A very simple notification system to alert an application about the progress of any event. The application is not required to take any actions in response to these messages.

IWMDMNotification

IWMDMNotification alerts the application when Plug and Play devices are connected or disconnected from the computer, as well as when Plug and Play storage media (such as flash cards) are inserted or removed from the device. These notifications can help the application update its user interface to reflect changes.

In order to receive these notifications, your application must register to receive them using the Platform SDK IConnectionPointContainer and IConnectionPoint interfaces. Your application should register to receive events when it starts up, and unregister when it closes. Follow these steps to register to receive these notifications.

  1. Query the main IWMDeviceManager interface you received when you authenticated your application for IConnectionPointContainer.
  2. Call IConnectionPointContainer::FindConnectionPoint to retrieve a container connection point for IWMDMNotification interfaces.
  3. Register to receive events by calling IConnectionPoint::Advise. Pass in the class that implements IWMDMNotification, and retrieve a cookie, a unique ID that identifies your connection point. This must be stored, and used later to unregister for event notifications.

The following C++ code demonstrates how you can register to receive notifications from IWMDMNotification.

HRESULT CWMDMController::RegisterForNotifications()
{
    HRESULT hr = S_OK;
    CComPtr<IConnectionPointContainer> pConxnPointCont;
    CComPtr<IConnectionPoint> pIConnPoint;

    // Get the IConnectionPointContainer interface from IWMDeviceManager.
    if (SUCCEEDED (hr = m_IWMDMDeviceMgr->QueryInterface(IID_IConnectionPointContainer, (void**) & pConxnPointCont)))
    {
        // Get a connection point from the container.
        if (SUCCEEDED (hr = pConxnPointCont->FindConnectionPoint(IID_IWMDMNotification, &pIConnPoint)))
        {
            // Add ourselves as a callback handler for the connection point.
            // If we succeeded, indicate that by storing the connection point ID.
            DWORD dwCookie;
            if (SUCCEEDED (hr = pIConnPoint->Advise((IUnknown*)((IWMDMNotification*)this), &dwCookie)))
            {
                m_dwNotificationCookie = dwCookie;
            }
        }
    }

    return hr;
}

When your application closes, you must unregister with IConnectionPoint to indicate that it should no longer send you notifications. Follow these steps to unregister for notifications:

  1. Query the main IWMDeviceManager interface for IConnectionPointContainer.
  2. Get a connection point for IWMDMNotification interfaces.
  3. Unregister your application for event notifications by calling IConnectionPoint::Unadvise, passing in the unique ID received when you registered to receive events.

The following C++ code shows how to unregister for IWMDMNotification events when your application closes.

HRESULT CWMDMController::UnregisterForNotifications()
{
    HRESULT hr = S_FALSE;

    // On class initialization, we initialized the handle to -1 as a flag
    // to indicate we had not yet registered for notifications. If registration
    // never happened, don't bother to unregister.
    if (-1 != m_dwNotificationCookie)
    {
        CComPtr<IConnectionPointContainer> pConxnPointCont;
        CComPtr<IConnectionPoint> pIConnPoint;

        // Get the connection point container from IWMDeviceManager.
        if (SUCCEEDED (hr =
           m_IWMDMDeviceMgr->QueryInterface(IID_IConnectionPointContainer,
           (void**) & pConxnPointCont)))
        {
            // Get a connection point from the container.
            if (SUCCEEDED (hr = pConxnPointCont->FindConnectionPoint(IID_IWMDMNotification, &pIConnPoint)))
            {
                // Remove ourselves as a callback from the connection point.
                // If successful, reset the ID to a flag value.
                if (SUCCEEDED (hr =
                    pIConnPoint->Unadvise(m_dwNotificationCookie)))
                {
                    m_dwNotificationCookie = -1;
                    hr = S_OK;
                }
            }
        }
    }

    return hr;
}

Using IWMDMProgress

Windows Media Device Manager can send your application status messages when specific actions, such as content transfer, secure clock acquisition, and encountering DRM file information, occur. Your application can use these messages to monitor the status of the event or cancel an event. To use this interface, implement IWMDMProgress, IWMDMProgress2, or IWMDMProgress3, and pass it in as a parameter to a method that will accept a progress message. Note that IWMDMProgress3 is the superior interface because it provides an identification GUID that specifies what action is being tracked. The following application methods accept a progress interface (the corresponding service provider methods should be able to send notifications to a submitted interface):

IWMDMStorageControl::Delete

IWMDMStorageControl::Insert

IWMDMStorageControl::Move

IWMDMStorageControl::Read

IWMDMStorageControl::Rename

IWMDMStorageControl2::Insert2

IWMDMStorageControl3::Insert3

IWMDMStorageGlobals::Initialize

IWMDRMDeviceApp::AcquireDeviceData

Examples of passing an interface into a method are given in the documentation for these methods. For examples of implementing the callback interfaces, see the documentation for the methods of IWMDMProgress, IWMDMProgress2, or IWMDMProgress3.

See Also

  • Creating a Windows Media Device Manager Application


Metering Content Usage

With Windows Media 10 technology, you can now meter content usage on a portable device. If a Windows Media 10 license allows metering, the device can store the play count for songs and upload usage back to the license issuer over the Internet. This system enables content providers to adjust their royalty fees by accurately measuring content usage.

To meter content, the application must have a metering certificate provided by a licensing service built on the Windows Media Rights Manager 10 SDK. Only content licensed by this same service can be metered. For more information on how metering works, and how to build a license metering service, see the Windows Media Rights Manager SDK documentation on MSDN. The SDK can be acquired by filling out the necessary information on the Windows Media Licensing Page.

An application can have metering built in to it, or you can build a COM plug-in for an existing application, such as the Windows Media Player, if the application accepts metering plug-ins.

An application should warn users if content usage will be metered. For more information, see the Microsoft Web pages listed in the Privacy Statement.

Acquiring metering data from a device can be slow. Therefore, if an application meters usage, it should do so frequently to prevent large amounts of data from accumulating on the device and slowing down the data transfer. To prevent data transfers that would be too slow, device manufacturers can send subsets of available metering data. The application should monitor the flags retrieved by IWMDRMDeviceApp::ProcessMeterResponse to see if any more metering data remains on the device.

The following steps show how an application can meter content usage.

  1. Because metering is only available on devices that support Windows Media DRM 10 for Portable Devices, your application should at some point call QueryDeviceStatus, as described in Handling Protected Content in the Application, to ensure that the device is valid and up to date.
  2. Request metering information from the device by calling IWMDRMDeviceApp::GenerateMeterChallenge.
  3. Send the retrieved metering data to the metering service at the URL retrieved by GenerateMeterChallenge. The format of data sent to the service depends on the scripting on that particular service. For example, some services might require the data sent as a POST command as a name/value pair. The service provider should let you know their particular formatting requirements.
  4. Get a response from the metering service, and send it to the device by calling IWMDRMDeviceApp::ProcessMeterResponse. This causes the device to reset play counts, and also returns a value indicating whether more metering data exists on the device that should be retrieved by calling GenerateMeterChallenge again.

For extensive information and sample code for metering, see the Windows Media Web site.


Mapping RSS Feeds to Windows Media Device Manager Properties

Windows Media Player 11 provides an RSS aggregator feature that enables users to store content obtained from podcasts on their computers. This topic describes the XML elements found in an RSS feed. In addition, it maps these RSS elements to Windows Media Device Manager properties.

The elements in an RSS feed have the following hierarchy and attributes:

<channel>
    <title />
    <link />
    <description />
    <language />
    <copyright />
    <managingEditor />
    <webMaster />
    <pubDate />
    <lastBuildDate />
    <category />
    <generator />
    <docs />
    <cloud />
    <ttl />

    <image>
        <url />
        <title />
        <link />
        <width />
        <height />
        <description />
    </image>

    <rating />

    <textInput>
        <title />
        <description />
        <name />
        <link />
    </textInput>

    <skipHours />
    <skipDays />

    <item>
        <title />
        <link />
        <description />
        <author />
        <category domain = " "/>
        <comments />
        <enclousure url = " " length = " " type = " "/>
        <guid isPermaLink = " "/>
        <pubDate />
        <source url = " " />
    </item>
</channel>

The following table lists the channel elements in an RSS feed and the corresponding Windows Media Device Manager properties.

Channel element | Status | Corresponding Windows Media Device Manager property
category | Optional | g_wszWMDMGenre
cloud | Not applicable | Not applicable
copyright | Optional | g_wszWMDMProviderCopyright
description | Required | g_wszWMDMDescription
docs | Not applicable | Not applicable
generator | Not applicable | Not applicable
language | Not applicable | Not applicable
lastBuildDate | Optional | g_wszWMDMLastModifiedDate
link | Required | g_wszWMDMDestinationURL
managingEditor | Optional | g_wszWMDMEditor
pubDate | Optional | g_wszWMDMYear
rating | Not applicable | Not applicable
skipDays | Not applicable | Not applicable
skipHours | Not applicable | Not applicable
textInput | Not applicable | Not applicable
title | Required | g_wszWMDMTitle
ttl | Optional | g_wszWMDMTimeToLive
webMaster | Optional | g_wszWMDMWebMaster

The following table lists the image elements in an RSS feed and the corresponding WMDM properties.

Image element | Status | Corresponding Windows Media Device Manager property
description | Optional | g_wszWMDMDescription
height | Optional | g_wszWMDMHeight
link | Optional | g_wszWMDMDestinationURL
title | Optional | g_wszWMDMTitle
url | Optional | g_wszWMDMSourceURL
width | Optional | g_wszWMDMWidth

The following table lists the item elements in an RSS feed and the corresponding Windows Media Device Manager properties.

Item element | Attribute | Status | Corresponding Windows Media Device Manager property
author |  | Optional | g_wszWMDMAuthor
category |  | Optional | g_wszWMDMGenre
 | domain | Not applicable | Not applicable
description |  | Optional | g_wszWMDMDescription
enclosure |  | Optional | Not applicable
 | length | Required | g_wszWMDMFileSize
 | type | Required | (The MIME type should be mapped to the property content type.)
 | url | Required | g_wszWMDMSourceURL
guid |  | Optional | g_wszWMDMediaGuid
 | isPermaLink | Not applicable | Not applicable
link |  | Optional | g_wszWMDMDestinationURL
pubDate |  | Optional | g_wszWMDMYear
source |  | Not applicable | Not applicable
title |  | Optional | g_wszWMDMTitle

Example

The following example shows a complete RSS feed for a fictitious podcast supplied by the CEO of a publishing company.

<channel>
    <title>The Digital Publication</title>
    <link>http://www.lucernepublishing.com/podcasting</link>
    <description>Lucerne Publishing CEO Peter Bankov takes a look at the latest trends in online publications.</description>
    <language>en-us</language>
    <copyright>2006 Lucerne Publishing LP, LLLP. All Rights Reserved.</copyright>
    <managingEditor>someone@example.com</managingEditor>
    <webMaster>someone@example.com</webMaster>
    <pubDate>Fri, 9 June 2006 14:00:28 EDT</pubDate>
    <lastBuildDate Fri, 9 June 2006 14:00:28 EDT />
    <category>News</category>
    <generator>Podcaster version 1.0</generator>
    <docs>http://www.lucernepublishing.com/tech/rss</docs>
    <cloud />
    <ttl>240</ttl>
    <rating />
    <textInput />
    <skipHours />
    <skipDays />

<image>
     <url>http://www.lucernepublishing.com/images/logo.gif</url>
     <title>Lucerne Publishing</title>
     <link>http://www.lucernepublishing.com/community/podcasts</link>
     <width>300</width>
     <height>300</height>
     <description>Lucerne Logo</description>
</image>

<item>
    <title>The Digital Publication</title>
    <link>http://www.lucernepublishing/services/podcasting/digital.publishing/audio/2006/06/digital0601.mp3</link>
    <description>Online publications are rapidly changing. A publishing house CEO examines the trends of the past five years and their implications.</description>
    <author>Lucerne</author>
    <category>News</category>
    <comments />
    <enclosure url="http://www.lucernepublishing/services/podcasting/digital.publishing/audio/2006/06/digital0601.mp3" length="10329011" type="audio/mpeg" />
    <guid>http://www.lucernepublishing/services/podcasting/digital.publishing/audio/2006/06/digital0601.mp3</guid>
    <pubDate>Thur, 1 June 2006 14:00:28 EDT</pubDate>
    <source />
</item>

</channel>

Mapping of RSS Channel Elements to Windows Media Device Manager Property Values

The following table describes how the values in the RSS Channel elements in the previous example map to particular Windows Media Device Manager properties.

Windows Media Device Manager property | Value
g_wszWMDMAuthorDate | Fri, 9 June 2006 14:00:28 EDT
g_wszWMDMDESCRIPTION | Lucerne Publishing CEO Peter Bankov takes a look at the latest trends in online publications.
g_wszWMDMDESTINATION_URL | http://www.lucernepublishing/services/podcasting
g_wszWMDMEDITOR | someone@example.com
g_wszWMDMFileCreationDate | Fri, 9 June 2006 14:00:28 EDT
g_wszWMDMFileName | The Digital Publication
g_wszWMDMFileSize | 13,790
g_wszWMDMFormatCode | WMDM_FORMATCODE_MEDIA_CAST
g_wszWMDMGENRE | News
g_wszWMDMLAST_MODIFIED_DATE | Fri, 9 June 2006 14:00:28 EDT
g_wszWMDMLastModifiedDate | Fri, 9 June 2006 14:00:28 EDT
g_wszWMDMProviderCopyright | 2006 Lucerne Publishing LP, LLLP. All Rights Reserved.
g_wszWMDMTimeToLive | 240
g_wszWMDMTitle | The Digital Publication
g_wszWMDMWEBMASTER | someone@example.com
g_wszWMDMYear | Fri, 9 June 2006 14:00:28 EDT

Mapping of RSS Image Elements to Windows Media Device Manager Property Values

The following table describes how the values in the RSS Image elements in the previous example map to particular Windows Media Device Manager properties.

Windows Media Device Manager property | Value
g_wszWMDMAlbumCoverFormat | WPD_OBJECT_FORMAT_GIF
g_wszWMDMAlbumCoverSize | 512
g_wszWMDMDescription | Lucerne Logo
g_wszWMDMDestinationURL | //www.lucernepublishing.com/community/podcasts
g_wszWMDMHeight | 300
g_wszWMDMSourceURL | http://www.lucernepublishing.com/images/logo.gif
g_wszWMDMTitle | Lucerne Publishing
g_wszWMDMWidth | 300

Mapping of RSS Item Elements to Windows Media Device Manager Property Values

The following table describes how the values in the RSS Item elements in the previous example map to particular Windows Media Device Manager properties.

Windows Media Device Manager property | Value
g_wszWMDMAuthor | Lucerne
g_wszWMDMAuthorDate | Thur, 1 June 2006 14:00:28 EDT
g_wszWMDMDescription | Online publications are rapidly changing. A publishing house CEO examines the trends of the past five years and their implications.
g_wszWMDMDestinationURL | http://www.lucernepublishing/services/podcasting/digital.publishing/audio/2006/06/digital0601.mp3
g_wszWMDMDuration | 120325445
g_wszWMDMFileCreationDate | Thur, 1 June 2006 14:00:28 EDT
g_wszWMDMFileSize | 10329011
g_wszWMDMFormatCode | WMDM_FORMATCODE_MP3
g_wszWMDMGenre | News
g_wszWMDMLastModifiedDate | Thur, 1 June 2006 14:00:28 EDT
g_wszWMDMMediaGuid | http://www.lucernepublishing/services/podcasting/digital.publishing/audio/2006/06/digital0601.mp3
g_wszWMDMSourceURL | http://www.lucernepublishing/services/podcasting/digital.publishing/audio/2006/06/digital0601.mp3
g_wszWMDMTitle | The Digital Publication
g_wszWMDMYear | Thur, 1 June 2006 14:00:28 EDT

See Also

  • Metadata Constants


Creating a Service Provider

A service provider is component that serves as a middleman between an application and a device. Windows Media Device Manager routes requests from the application to the service provider, which is then responsible for communicating with the device or performing the requested action. A service provider usually communicates with a driver to enable communication with the device. A service provider is a COM component that implements the interfaces called by Windows Media Device Manager. The root interface of the service provider object is IMDServiceProvider. After obtaining this interface, Windows Media Device Manager can obtain other interfaces through the service provider's implementation of various methods. The interfaces that a service provider must implement are listed in Mandatory and Optional Interfaces. The hierarchy of interfaces is shown in Interfaces for Service Providers.

Note You should not try to create an MTP service provider; instead, you should use the MTP service provider and drivers provided by Microsoft.

Before trying to create a service provider, you should thoroughly understand what calls an application will make on a service provider. Read Creating a Windows Media Device Manager Application to get some idea of the basic tasks and calls that an application will make on a service provider when it is attempting to communicate with a device.

The following list shows the key steps in developing a service provider:

  1. Include (and optionally compile) the required header and library files for your project. See Required Libraries and Headers for a Service Provider for the list of required files.
  2. Implement all the other required or optional service provider interfaces (see Mandatory and Optional Interfaces). Typically, interfaces will be called in this order:
    • IComponentAuthenticate
    • IMDServiceProvider/2
    • IMDSPEnumDevice
    • IMDSPDevice/2
    • IMDSPEnumStorage
    • IMDSPStorage/2/3
  3. Be sure your service provider or device installs the proper registry keys during installation. These keys specify device parameters, register the service provider as a plug-in, and enable Plug and Play notifications for device arrival and removal. See Device Parameters, Registering the Service Provider, and Enabling PnP for Devices.
  4. On instantiation of your class, authenticate the service provider in the constructor. To do this, create a CSecureChannelServer class and set the certificate. Implement the IComponentAuthenticate interface and call the methods of the CSecureChannelServer class instantiated previously. See Authenticating the Service Provider to learn how to instantiate the CSecureChannelServer class and implement the IComponentAuthenticate methods.
  5. Windows Media Device Manager will query your service provider for a list of connected devices by calling IMDServiceProvider2::CreateDevice or IMDServiceProvider::EnumDevices, depending on whether the service provider handles Plug and Play devices. The service provider must return a list of IMDSPDevice objects representing connected devices. See Enumerating Devices for more details.
  6. Before handling any call, verify that a secure channel has been established. Call CSecureChannelServer::fIsAuthenticated before performing any actions. If this call fails, return WMDM_E_NOTCERTIFIED.
  7. You will need a certificate/key pair issued by Microsoft to be able to handle DRM-protected material. See Handling Protected Content in the Service Provider for more information.
  8. To enable your device to synchronize automatically with Windows Media Player, it must fulfill the requirements listed in Enabling Synchronization with Windows Media Player.
  9. To enable your device to appear in Windows Explorer, you must take a few special steps, detailed in Requirements for Portable Audio Players to Appear in Windows Explorer.

See Also

  • Programming Guide


Required Libraries and Headers for a Service Provider

This section lists the libraries, header files or IDL files you will need to include to develop a Windows Media Device Manager application or plug-in. As mentioned in Compiling the IDL Files Supplied with the SDK, the SDK includes both IDL files and prebuilt header files, and your application can use either. (Note that some header files do not have corresponding IDL files, and you cannot build them yourself.) If building your own IDL files, include the dependencies listed in Compiling the IDL Files Supplied with the SDK.

Not all applications will require all files; read the description to learn if your application requires a file.

Prebuilt header or library | Equivalent IDL | Description
mssachlp.lib | none | Required by all service providers. Defines Windows Media Device Manager objects.
initguid.h | none (Platform SDK header) | Required by all service providers to define the GUID values using the prebuilt Mswmdm.h file. You must include initguid.h once and only once in your project. This header redefines the DEFINE_GUID macro to avoid external GUID naming problems.
mswmdm.h | WMDM.idl WMSP.idl icomponentauthenticate.idl | Required by all service providers. Defines all the service provider interfaces, structures, metadata, error codes, and other constants.
sac.h | none | Required by all service providers. Defines SAC protocols.
scserver.h | none | Required by all service providers. Declares the CSecureChannelServer class.
wmdmlog.h wmdmlog_i.c | Wmdmlog.idl | Required by service providers that use the IWMDMLogger interface.
wmsdk.h | none (provided by Windows Media Format SDK) | Required for service providers that use Windows Media Format SDK methods.
wmvcore.lib | none | Required by service providers that use Windows Media Format SDK objects or functions.
mmreg.h | none (Platform SDK header) | Required by service providers that reference various standard Windows Media format definitions, such as WAVEFORMATEX.
MtpExt.h | none | Required for service providers that handle IMDSPDevice3::DeviceIoControl on MTP devices. Defines various standard MTP constants and structures.
Key.c | none | Defines a key and certificate from Microsoft. The version shipped with the SDK includes a test dummy key that will allow the use of non-DRM protected Windows Media files.

See Also

  • Creating a Service Provider


Device Parameters

Windows Media Device Manager uses device parameters to control the behavior of a device. These parameters are added to the registry as specified in the device's installation file (INF file). The following table lists the device parameters that Windows Media Device Manager queries.

Device parameter name | Registry data type | Description
WMDMSPCLSID REG_SZ Value that specifies the CLSID of the service provider controlling this device. This parameter is mandatory for PnP support.

The parameter value must be the CLSID, not the ProgID of the service provider. This parameter is mandatory to support Plug and Play (PnP) under Windows Media Device Manager. For more information, see Enabling PnP for Devices.
OptimalTransferSize | REG_DWORD | Optional value that specifies the preferred transfer size that Windows Media Device Manager uses during read and write operations. If it is not supplied, a default transfer size is used.
UseMetadataViews REG_DWORD Optional parameter that specifies whether Windows Media Device Manager organizes the content by metadata while presenting device content to applications. If not specified, the default value is 0.

When applications enumerate the content on the storages of a portable audio player, Windows Media Device Manager can present the content organized by metadata. This is especially useful for devices with large storage capacity.

Applications and devices have the ability to control this behavior. Devices indicate their preference through the device parameter UseMetadataViews.

The following two integer values are supported:

Requests that content be presented to the applications exactly as organized on the file system of the device.

Requests that the content be presented to the applications organized by metadata.
ShowInShell | REG_DWORD | Optional parameter that specifies whether the device should appear in Windows Explorer. The value 1 indicates that the device should appear in Windows Explorer. For more information, see Requirements for Portable Audio Players to Appear in Windows Explorer.
UseExtendedWmdm REG_DWORD Optional parameter that alerts Windows Media Device Manager that the service provider supports IMDSPDevice3, IMDSPObject2, and IMDSPStorage4. Without this flag, Windows Media Device Manager will never call these interfaces. The value 1 indicates that these interfaces are supported.

This flag is required for service providers that synchronize with Windows Media Player. (See Enabling Synchronization with Windows Media Player).

Coding the INF file

The following example code from a device's INF file demonstrates setting some device parameters during device installation.

; Set parameters on Windows 95 and Windows 98 operating systems.
[DriverInstall.hw]
AddReg=DriverHwPropReg

; Set parameters on Windows NT-based operating systems.
[DriverInstall.NT.hw]
AddReg=DriverHwPropReg

; Related section that specifies the device parameters.
[DriverHwPropReg]
; Add your own CLSID here.
HKR,,WMDMSPCLSID,,"{00000000-0000-0000-0000-000000000000}"
HKR,,OptimalTransferSize,0x10001,0x10000
HKR,,UseMetadataViews,0x10001,0x1

See Also

  • Creating a Service Provider
  • IMDServiceProvider2 Interface
  • IMDServiceProvider2::CreateDevice
  • IWMDMDevice Interface


Choosing a Threading Model for the Service Provider

All service providers should be compiled as free threaded.

See Also

  • Creating a Service Provider


Registering the Service Provider

In addition to being registered as a COM object, a service provider must be registered as a plug-in to Windows Media Device Manager. To register, a service provider must create the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Media Device Manager\Plugins\SP\<your service provider name>\ProgID

In this key, <your service provider name> is the name of your DLL; for example, the sample service provider uses MsHDSP. The ProgID key should have a string value that corresponds to the CLSID of your service provider. For instance, the sample service provider has the value "MDServiceProviderHD.MDServiceProviderHD".

The sample service provider's implementation of DLLRegisterServer in Mdsp.cpp adds this registry key when you register the sample service provider DLL.

See Also

  • Creating a Service Provider


Enabling PnP for Devices

Windows Media Device Manager monitors arrival and removal notifications of devices that advertise a Portable Audio Player device interface. On the arrival of such a device, Windows Media Device Manager queries a device parameter named WMDMSPCLSID for the class ID of the service provider responsible for this device. Windows Media Device Manager calls IMDServiceProvider2::CreateDevice on this service provider to create a device object, which is exposed to the application as an IWMDMDevice object.

A service provider can either handle PnP devices, or non-PnP devices; it cannot handle both types.

For a device to work with the preceding mechanism (and thus enable arrival and removal notifications for the device under Windows Media Device Manager applications), the following requirements must be met:

  • The device driver of this device must advertise the Windows Media Device Manager Portable Audio Player device interface. The GUID for this device interface is defined as:
    {0xf33fdc04, 0xd1ac, 0x4e8e, {0x9a, 0x30, 0x19, 0xbb, 0xd4, 0xb1, 0x8, 0xae} }

    Note A device should not advertise this interface if the device advertises the Volume interface (defined as VolumeClassGuid or GUID_DEVINTERFACE_VOLUME in winioctl.h). If the device advertises the Volume Interface, it is already PnP-enabled under Windows Media Device Manager.

    -AND/OR-

    A new registry subkey for the service provider must be created inside the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Media Device Manager\KnownDevices. This key should have the name of your service provider and must have the following two Reg_SZ value entries:

    DeviceInterface         {25DBCE51-6C8F-4A72-8A6D-B54C2B4FC835}
WMDMSPCLSID             {067B4B81-B1EC-489F-B111-940EBDC44EBE}
  • The device must have a device parameter named WMDMSPCLSID. The value of this parameter should be set as the CLSID of the service provider in a string form. For more information about device parameters, see Device Parameters.

    Note The parameter value must be the CLSID, not the ProgID of the service provider.

  • The service provider for this device must implement the IMDServiceProvider2 interface.
  • The service provider key under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Media Device Manager\Plugins\SP\<SPName> must contain the following DWORD value
    PnPAware    1

See Also

  • Creating a Service Provider


Enumerating Devices

Windows Media Device Manager maintains a cache of connected devices that is updated when a Windows Media Device Manager application starts, when a Plug and Play (PnP) device connects or disconnects, or when the application calls IWMDeviceManager2::Reinitialize. This cache is exposed to the application when it calls IWMDeviceManager::EnumDevices or IWMDeviceManager2::EnumDevices2. Each device is exposed to the application as an IWMDMDevice interface. If the service provider is registered to handle PnP devices, Windows Media Device Manager will be aware of the current list of connected devices. If the service provider is registered to handle non-PnP devices, the service provider is responsible for discovering attached devices. A service provider can only be registered for PnP or non-PnP devices, never both.

The following actions show how Windows Media Device Manager maintains or updates its cache. Notice that the cache is never updated when a non-PnP device connects or disconnects.

A Windows Media Device Manager application starts

  • Windows Media Device Manager retrieves a list of attached PnP devices from the PnP subsystem, and calls IMDServiceProvider2::CreateDevice on the SP registered for each connected device. (It discovers the correct service provider by querying the WMDMSPCLSID device parameter for the class ID of the service provider responsible for this device. See Device Parameters for more information.) All devices returned are added to the Windows Media Device Manager cache of devices.
  • Windows Media Device Manager finds all non-PnP service providers registered with it and calls IMDServiceProvider::EnumDevices on each service provider to get a list devices from each one. All devices returned are added to the cache.

The application calls IWMDeviceManager/2::EnumDevices/2

  • Windows Media Device Manager returns its cached device list.

A PnP device connects

  • Windows Media Device Manager finds the relevant service provider and calls IMDServiceProvider2::CreateDevice, and adds the device to its cache.
  • If the application implements IWMDMNotification, Windows Media Device Manager calls IWMDMNotification::WMDMMessage with an arrival notification.

A PnP device disconnects

  • Windows Media Device Manager removes the item from its cache.
  • If the application implements IWMDMNotification, Windows Media Device Manager calls IWMDMNotification::WMDMMessage with a departure notification.

The application calls IWMDeviceManager2::Reinitialize

  • Refreshes the cache with all connected devices.

A non-PnP device connects or disconnects

  • Windows Media Device Manager is not informed of the arrival or departure, and takes no action.

See Also

  • Creating a Service Provider


Authenticating the Service Provider

To be accessible from Windows Media Device Manager, a service provider must inherit and implement the IComponentAuthenticate interface.

To authenticate itself, a service provider performs the following steps:

  1. On instantiation, it creates a new global CSecureChannelServer object and sets the certificate and key values from its key file.
  2. It implements the IComponentAuthenticate::SACAuth and IComponentAuthenticate::SACGetProtocols methods by simply passing the parameters into its global CSecureChannelServer member.
  3. Before handling any implemented Windows Media Device Manager methods, the service provider must verify the caller's authentication by calling CSecureChannelServer::fIsAuthenticated, and failing if the caller is not authenticated.

These steps are shown in the following C++ examples.

Creating the CSecureChannelServer object

CMyServiceProvider::CMyServiceProvider()
{
    HRESULT hr = S_OK;

    // Create the persistent SAC object.
    g_pSAC = new CSecureChannelServer();

    // Set the SAC certificate.
    if (g_pSAC)
    {
        hr = g_pSAC->SetCertificate(
             SAC_CERT_V1,
            (BYTE*)abCert, sizeof(abCert), // SP's certificate.
            (BYTE*)abPVK, sizeof(abPVK)    // SP's key.
        );
    }
    if (FAILED(hr)) return hr;

    //... Perform other class initialization here ...

    return hr;
}

Implementing the IComponentAuthenticate methods

STDMETHODIMP CMDServiceProvider::SACAuth(
    DWORD   dwProtocolID,
    DWORD   dwPass,
    BYTE   *pbDataIn,
    DWORD   dwDataInLen,
    BYTE  **ppbDataOut,
    DWORD  *pdwDataOutLen)
{
    HRESULT hr = S_OK;

    // Verify that the global CSecureChannelServer member still exists.
    if (!g_pSAC)
        return E_FAIL;

    // Just pass the call to the global SAC member.
    hr = g_pSAC->SACAuth(
        dwProtocolID,
        dwPass,
        pbDataIn, dwDataInLen,
        ppbDataOut, pdwDataOutLen
    );
    return hr;
}

STDMETHODIMP CMDServiceProvider::SACGetProtocols(
    DWORD **ppdwProtocols,
    DWORD  *pdwProtocolCount)
{
    HRESULT hr = E_FAIL;

    if (!g_pSAC)
        return hr;

    hr = g_pSAC->SACGetProtocols(
        ppdwProtocols,
        pdwProtocolCount
    );
    return hr;
}

Verifying the caller's authentication

The following code example shows a service provider checking the caller's authentication as part of its implementation of the IMDServiceProvider interface.

STDMETHODIMP CMyServiceProvider::GetDeviceCount(DWORD * pdwCount)
{
    HRESULT hr = S_OK;
    if (!g_pSAC)
        return E_FAIL;

    if (!(g_pSAC->fIsAuthenticated()))
        return WMDM_E_NOTCERTIFIED;

    *pdwCount = m_DeviceCount;

    return hr;
}

See Also

  • Creating a Service Provider


Mandatory and Optional Interfaces

The following table describes the mandatory and optional interfaces and methods for service providers to implement. All the interfaces with one or more mandatory methods must be implemented. A mandatory method cannot return WMDM_E_NOTSUPPORTED or E_NOTIMPL.

Interface and method | Implementation option
IMDServiceProvider::EnumDevices | Mandatory.
IMDServiceProvider::GetDeviceCount | Mandatory.
IMDServiceProvider2::CreateDevice | Optional. This method must be implemented for PnP and Windows Explorer support.
IMDSPDevice::EnumStorage | Mandatory.
IMDSPDevice::GetDeviceIcon | Mandatory.
IMDSPDevice::GetFormatSupport | Mandatory.
IMDSPDevice::GetManufacturer | Mandatory.
IMDSPDevice::GetName | Mandatory.
IMDSPDevice::GetPowerSource | Optional.
IMDSPDevice::GetSerialNumber | Optional. For protected content transfer, Windows Media Device Manager uses IMDSPStorageGlobals::GetSerialNumber.
IMDSPDevice::GetStatus | Mandatory.
IMDSPDevice::GetType | Mandatory.
IMDSPDevice::GetVersion | Optional.
IMDSPDevice::SendOpaqueCommand | Optional.
IMDSPDevice2::GetCanonicalName | Optional.
IMDSPDevice2::GetFormatSupport2 | Mandatory.
IMDSPDevice2::GetSpecifyPropertyPages | Optional.
IMDSPDevice2::GetStorage | Optional.
IMDSPDeviceControl Interface | Optional.
IMDSPEnumDevice::Clone | Mandatory.
IMDSPEnumDevice::Next | Mandatory.
IMDSPEnumDevice::Reset | Mandatory.
IMDSPEnumDevice::Skip | Mandatory.
IMDSPEnumStorage::Clone | Mandatory.
IMDSPEnumStorage::Next | Mandatory.
IMDSPEnumStorage::Reset | Mandatory.
IMDSPEnumStorage::Skip | Mandatory.
IMDSPObject::Close | Mandatory.
IMDSPObject::Delete | Mandatory.
IMDSPObject::Move | Optional.
IMDSPObject::Open | Mandatory.
IMDSPObject::Read | Mandatory (if Windows Media Player support is desired).
IMDSPObject::Rename | Optional.
IMDSPObject::Seek | Optional.
IMDSPObject::Write | Mandatory.
IMDSPObjectInfo Interface | Optional.
IMDSPRevoked Interface | Optional.
IMDSPStorage::CreateStorage | Mandatory only if dwAttributes is WMDM_FILE_ATTR_FILE.
IMDSPStorage::EnumStorage | Mandatory.
IMDSPStorage::GetAttributes | Mandatory.
IMDSPStorage::GetDate | Mandatory.
IMDSPStorage::GetName | Mandatory.
IMDSPStorage::GetRights | Optional.
IMDSPStorage::GetSize | Mandatory.
IMDSPStorage::GetStorageGlobals | Mandatory.
IMDSPStorage::SendOpaqueCommands | Optional.
IMDSPStorage::SetAttributes | Optional.
IMDSPStorage2::CreateStorage2 | Mandatory.
IMDSPStorage2::GetAttributes2 | Mandatory.
IMDSPStorage2::GetStorage | Optional.
IMDSPStorage2::SetAttributes2 | Optional.
IMDSPStorage3 Interface | Optional. However, if the device parameter UseMetadataViews is set to 1, this interface must be implemented, and IMDSPStorage3::GetMetadata becomes mandatory, although IMDSPStorage3::SetMetadata is still optional.
IMDSPStorageGlobals::GetCapabilities | Mandatory.
IMDSPStorageGlobals::GetDevice | Mandatory.
IMDSPStorageGlobals::GetRootStorage | Mandatory.
IMDSPStorageGlobals::GetSerialNumber | Mandatory for PDDRM only. Optional otherwise.
IMDSPStorageGlobals::GetStatus | Mandatory.
IMDSPStorageGlobals::GetTotalBad | Mandatory.
IMDSPStorageGlobals::GetTotalFree | Mandatory.
IMDSPStorageGlobals::GetTotalSize | Mandatory.
IMDSPStorageGlobals::Initialize | Optional. This method should be implemented if the device supports this functionality. If this method is not implemented, IMDSPStorageGlobals::GetCapabilites must return WMDM_STORAGECAP_NOT_INITIALIZABLE in addition to any other flags.
IMDSPDevice3 IMDSPObject2 IMDSPStorage4 | Required to support automatic synchronization with Windows Media Player

See Also

  • Creating a Service Provider


Handling Protected Content in the Service Provider

You can build a service provider that can send DRM-protected content to a device built on Portable Device DRM (PDDRM), but you cannot build a service provider that can send DRM-protected content to devices built on Windows Media DRM 10 for Portable Devices. These devices use MTP, and you cannot build your own MTP service provider.

The only extra step that a service provider must take to send DRM material to a PDDRM device is to get a Microsoft-issued certificate/key pair. See Tools for Development to learn where to get this certificate/key. The licenses issued to these devices will be simplified licenses that only support simple playback of purchased content; they will not support time-expiring licenses. This license will be created for you by the secure content provider (provided by Microsoft for WMA/WMV files) and stored in the header of the file sent to the service provider. You will not have to take any special steps for protected files.

After sending the protected file, Windows Media Device Manager will call the service provider to request a special license storage file from the device. Windows Media Device Manager will add a copy of the new license to this file, and return it to the service provider to send back to the device. However, even if the service provider fails to find or return this file, the device should still be able to play the protected file by using the license copy in the file header.

See Also

  • Creating a Service Provider
  • Handling Protected Content


Enabling Synchronization with Windows Media Player

You can enable a device to participate in automatic synchronization with Windows Media Player. Automatic synchronization means that when a user-designated synchronized device connects to the computer, Windows Media Player will automatically download, update, or delete files from the device without requiring any additional user input.

By default the following devices are synchronized with Windows Media Player:

  • MTP devices
  • Mass-storage devices
  • Windows CE devices (Windows Media Player 10 Mobile and later)

For any other device to synchronize with Windows Media Player, the following requirements must met:

  • The device must advertise a PAP device interface that is {F33FDC04-D1AC-4E8E-9A30-19BBD4B108AE}
  • The device objects returned by service provider must support the IMDSPDevice3 interface.
  • The device parameter UseExtendedWmdm must be set to a DWORD value of 1. See Device Parameters for more information.
  • The service provider should implement the following interfaces:

    IMDSPDevice3

    IMDSPObject2

    IMDSPStorage4

See Also

  • Creating a Service Provider
  • Device Parameters


Requirements for Portable Audio Players to Appear in Windows Explorer

The portable audio player shell namespace extension provides Windows users with a consistent way to manage audio devices that are managed by Windows Media Device Manager. If you author your service provider and driver components according to the following guidelines, your device will show up in the shell namespace. Users will be able to interact with the contents of your device in a consistent manner in Windows Explorer to perform basic operations such as copy, delete, and rename.

The following shell requirements for service provider and driver components are intended to supplement the general Windows Media Device Manager guidelines.

Device Capabilities

Windows Media Device Manager service providers should be explicit in their supported capabilities. If a call is not supported, an error code must be returned. The appropriate fields must be set for the presence or absence of capabilities on return from the following functions:

  • IMDSPStorageGlobals::GetCapabilities
  • IMDSPStorage::GetAttributes
  • IMDSPDevice::GetFormatSupport

Service providers must support the following capabilities to be compatible with the shell:

  • Copy to device (with support for cancel and progress callbacks)
  • Delete file from device (with support for cancel and progress callbacks)
  • Rename file on device
  • Space reporting (total space, free space, unusable space)
  • Plug and Play (see Enabling PnP for Devices)
  • Format (preferably with support for cancel and progress callbacks)

If metadata is supported, the following fields must be supported for individual files. If no data is available, the field should be initialized as an empty string:

Field | Constant (defined in WMDM.idl) | Metadata tag
Song Title | g_wszWMDMTitle | WMDM/Title
Track Number | g_wszWMDMTrack | WMDM/Track
Artist | g_wszWMDMAuthor | WMDM/Author
Album | g_wszWMDMAlbumTitle | WMDM/AlbumTitle
Year | g_wszWMDMYear | WMDM/Year
Genre | g_wszWMDMGenre | WMDM/Genre

Concurrency

Kernel mode drivers for Windows Media Device Manager need to be robust in handling concurrent access. For example, a user can be concurrently accessing the device through both the shell and media player or simply through multiple windows in the shell. As part of handling concurrency, drivers should not assume, just because the service provider is loaded, that the device is in use. Instead, they should implement a locking mechanism to serialize access to the device as needed for individual operations.

UI

Service providers for Windows Media Device Manager should not show any user interface. Any errors should be returned from method calls as specific Windows Media Device Manager error codes whenever possible.

Enabling in the Shell

If your package meets all of the shell requirements, you can enable your device to be shown in the shell by setting the ShowInShell value to 1 under the device parameters. For more information, see Device Parameters.

See Also

  • Creating a Service Provider


Programming Reference

The Windows Media Device Manager SDK consists of a collection of interfaces, structures, enumerations, and constants. The reference section divides the interfaces into groups according to the type of object that uses them.

Section | Description
Interfaces for Applications | Describes interfaces that are used or implemented only by desktop applications, Windows Media Player plug-ins, or COM objects that need high-level access to a portable device.
Interfaces for Service Providers | Describes interfaces that are used or implemented only by service providers, which handle the actual low-level communication with a portable device.
Windows Media DRM-Implemented Interfaces | Describes interfaces that are not intended to be implemented by third-party service providers, but are implemented and called internally by the Windows Media DRM and Windows Media Device Manager.
Interfaces for Service Providers and Applications | Describes interfaces that can be used either by applications or by service providers.
Interfaces for Secure Content Providers | Describes interfaces that must be implemented by a device or application that will use DRM-protected content.
Structures | Describes structures used for Windows Media Device Manager methods.
Enumeration Types | Describes enumerations used for Windows Media Device Manager methods.
Metadata Constants | Describes the constants defined by the Windows Media Device Manager SDK for setting or retrieving various metadata properties for a device or object on the device.
Error Codes | Describes the error codes that can be returned by Windows Media Device Manager SDK methods.


Interfaces for Applications

This section describes interfaces used or implemented by applications using the Windows Media Device Manager SDK to communicate with devices. The term "application" used here means any executable, plug-in, or COM object that exists on a desktop computer and needs high-level communication with a connected portable device. This can include a media player application, a Windows Media Player plug-in (if it needs direct access to a portable device), or a play-count metering COM object.

Some of these interfaces are implemented by the application, while others are called by the application. The documentation for each interface indicates whether it is implemented or called (and if implemented, whether it is optional or required).

The following interfaces or classes are used by applications.

Interface or class | Description
CSecureChannelClient Class | A helper class that enables applications to authenticate themselves, encrypt and decrypt data, and create MACs.
IWMDeviceManager | The top level Windows Media Device Manager interface for applications.
IWMDeviceManager2 | Extends IWMDeviceManager by providing advanced enumeration methods and other methods.
IWMDeviceManager3 | Extends the IWMDeviceManager2 interface by providing a method that sets the device enumeration preference.
IWMDMDevice | Provides methods to examine and explore a single portable device.
IWMDMDevice2 | Extends IWMDMDevice by making it possible to get the video formats supported by a device, find a storage by name, and use property pages.
IWMDMDevice3 | Extends IWMDMDevice2 by providing methods to query a device for properties, send device I/O controle codes, and also providing upgraded methods to search for storages and retrieve device format capabilities.
IWMDMDeviceControl | Provides methods for controlling devices.
IWMDMDeviceSession | Improves the efficiency of device operations by bundling multiple operations into one session
IWMDMEnumDevice | Enumerates portable devices attached to a computer.
IWMDMEnumStorage | Enumerates storages on a device.
IWMDMMetaData | Sets and retrieves metadata properties (such as artist, album, genre, and so on) of a storage.
IWMDMObjectInfo | Gets and sets information that controls how playable files on device are handled by the IWMDMDeviceControl interface
IWMDMRevoked | Retrieves the URL from which updated components can be downloaded, if a transfer fails with a revocation error.
IWMDMStorage | Provides methods to examine and explore a storage (file, folder, playlist) on a device.
IWMDMStorage2 | Extends IWMDMStorage by making it possible to get a child storage by name, and to get and set extended attributes.
IWMDMStorage3 | Extends IWMDMStorage2 by exposing metadata.
IWMDMStorage4 | Extends IWMDMStorage3 by providing methods for retrieving a subset of available metadata for a storage, and for setting and retrieving a list of references to other storages.
IWMDMStorageControl | Used to insert, delete, or move files within a device, or between a device and the computer.
IWMDMStorageControl2 | Extends IWMDMStorageControl by making it possible to set the name of the destination file when inserting content into a storage.
IWMDMStorageControl3 | Extends IWMDMStorageControl2 by making it possible to pass in an IWMDMMetaData interface pointer.
IWMDMStorageGlobals | Provides methods for retrieving global information about a storage medium (such as a flash ROM card) on a device.
IWMDRMDeviceApp | Enables an application to perform metering, license synchronization, and update of a device's DRM components.
IWMDRMDeviceApp2 | Extends IWMDRMDeviceApp by providing a new version of the QueryDeviceStatus method.

Callback Interfaces

The following optional interfaces are implemented by an application in order to track the progress of an asynchronous request, such as a read or write request.

Interface | Description
IWMDMNotification | Allows applications and service providers to receive notifications when devices or memory storages (such as RAM cards) are connected or disconnected from the computer.
IWMDMOperation2 | Extends IWMDMOperation by providing methods to get and set extended attributes.
IWMDMOperation3 | Extends IWMDMOperation by providing a new method for transferring data unencrypted for added efficiency.
IWMDMOperation | Allows an application to control how data is read from or written to the computer during a file transfer.
IWMDMProgress2 | Extends the IWMDMProgress::End method by providing a status indicator.
IWMDMProgress3 | Extends IWMDMProgress2 by providing additional input parameters to specify the event ID and context-specific information.
IWMDMProgress | Allows an application to track the progress of operations, such as formatting media or file transfers.

The following diagram shows how most of the important application interfaces are acquired from the root IWMDeviceManager interface. An application gets this root interface by cocreating the MediaDevMgr object, requesting the IComponentAuthenticate interface, authenticating the component, and then requesting the IWMDeviceManager (these steps are described in Authenticating the Application). Once this root interface has been acquired, IWMDeviceManager::EnumDevices is called to create an object that implements IWMDMEnumDevice. Other interfaces are obtained by calling methods on interfaces in the order shown. Derived interfaces such as IWMDMDevice2 are obtained by calling QueryInterface on the base interface.

In the following diagram, derived interfaces are labeled by slash marks, so "IWMDMStorage/2/3" would indicate IWMDMStorage, IWMDMStorage2, and IWMDMStorage3.

Diagram showing how to get the major application interfaces in Windows Media Device Manager.

See Also

  • Programming Reference


CSecureChannelClient Class (deprecated)

The CSecureChannelClient class is a helper class (not an interface) that enables applications to authenticate themselves, encrypt and decrypt data, and create MACs.

The CSecureChannelClient class exposes the following methods.

Method | Description
Authenticate | Triggers the exchange of certificates between components to establish trust.
DecryptParam | Decrypts data received through a parameter.
EncryptParam | Encrypts data being sent out through a parameter.
fIsAuthenticated | Verifies that a secure authentication channel has been successfully established. This method is not used by applications.
GetAppSec | Retrieves the application security levels of the local and remote components.
GetSessionKey | Retrieves the current session key. This method is not used by applications.
MACFinal | Releases the message authentication code (MAC) channel and retrieves a final MAC value.
MACInit | Acquires a message authentication code (MAC) channel.
MACUpdate | Adds a value to a message authentication code (MAC).
SetCertificate | Specifies the certificate and private key of the secure authenticated channel (SAC) client.
SetInterface | Selects the interface used for secure authenticated channel (SAC) communications.
SetSessionKey | Sets the session key that is used to communicate with another component. This method is not used by applications.

See Also

  • CSecureChannelServer Class
  • IComponentAuthenticate Interface
  • Interfaces for Applications


CSecureChannelClient::Authenticate (deprecated)

The Authenticate method authenticates communication between components to establish trust. In applications, it is used to establish trust between the application and Windows Media Device Manager. Messages are exchanged and trust established if both the client and server certificates are validated.

Syntax

HRESULT Authenticate(
  DWORD  dwProtocolID
);

Parameters

dwProtocolID

[in] DWORD specifying the protocol identifier. Currently, the only value accepted is SAC_PROTOCOL_V1, defined in the SDK in ...\inc\sac.h.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The dwProtocol parameter is invalid.
E_FAIL | An unspecified error occurred.

Remarks

This method specifies which protocol method is to be used. That method is then called. In this version of Windows Media Device Manager, SAC_PROTOCOL_V1 must be used.

CSecureChannelClient::SetCertificate and CSecureChannelClient::SetInterface must be called before Authenticate.

Example Code

The following C++ code authenticates the Windows Media Device Manager session and acquires an IWMDeviceManager interface.

// Authenticates the WMDM, and acquires an interface to the top-level object.
HRESULT MyClass::Authenticate()
{
    HRESULT hr;
    CComPtr<IComponentAuthenticate> pAuth;

    // Create the WMDM object and acquire
    // its authentication interface.
    hr = CoCreateInstance(
        __uuidof(MediaDevMgr),
        NULL,
        CLSCTX_INPROC_SERVER,
        __uuidof(IComponentAuthenticate),
        (void**)&pAuth);

    if (hr != S_OK)
        return hr;

    // Create the secure channel client class needed to authenticate the application.
    // We'll use a global member variable to hold the secure channel client
    // in case we need to handle encryption, decryption, or MAC verification
    // during this session.
    m_pSAC = new CSecureChannelClient;
    if (m_pSAC == NULL)
        return E_FAIL;

    // Send the application's transfer certificate and the associated
    // private key to the secure channel client.
    hr = m_pSAC->SetCertificate(
        SAC_CERT_V1,
        (BYTE *)abCert, sizeof(abCert),
        (BYTE *)abPVK,  sizeof(abPVK));
    if (hr != S_OK)
        return hr;

    // Send the authentication interface we created to the secure channel
    // client and try authenticating the application with the V1 protocol.
    m_pSAC->SetInterface(pAuth);
    hr = m_pSAC->Authenticate(SAC_PROTOCOL_V1);
    if (hr != S_OK)
        return hr;

    // Authenticated succeeded, so we can use the WMDM.
    // Acquire an interface to the top-level WMDM interface
    // and store it in a global variable.
    hr = pAuth->QueryInterface(__uuidof(IWMDeviceManager), (void**)&m_IWMDeviceMgr);

    return hr;
}

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Authenticating the Application
  • CSecureChannelClient Class


CSecureChannelClient::DecryptParam (deprecated)

The DecryptParam method decrypts data received through a parameter. Encryption is performed in-place on the encrypted data.

Syntax

HRESULT DecryptParam(
  BYTE*  pbData,
  DWORD  dwDataLen
);

Parameters

pbData

[in, out] Pointer to the data buffer that holds the information to decrypt. On input contains the encrypted data; on output, contains the decrypted data. The decrypted data is the same length as the encrypted data.

dwDataLen

[in] Pointer to a DWORD specifying the length of the buffer to which pbData points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This is used by IWMDMOperation::TransferObjectData to decrypt data read from the device.

For robustness, before calling the DecryptParam method, components should copy the data to a temporary buffer and then use DecryptParam to decrypt the temporary buffer. Decryption is handled in-place in the buffer; the buffer does not need to be resized.

For example code, see IWMDMOperation::TransferObjectData.

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Using Secure Authenticated Channels
  • IWMDMOperation::TransferObjectData
  • CSecureChannelClient::EncryptParam
  • CSecureChannelClient Class


CSecureChannelClient::EncryptParam (deprecated)

The EncryptParam method encrypts data being sent out through a parameter. Data is encrypted in-place, in the submitted buffer.

Syntax

HRESULT EncryptParam(
  BYTE*  pbData,
  DWORD  dwDataLen
);

Parameters

pbData

[in, out] Pointer to the data buffer that holds the information to encrypt. Encryption is handled in-place in the buffer, and the retrieved encrypted data is the same size as the original data.

dwDataLen

[in] Pointer to a DWORD specifying the length of the pbData buffer.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is used to encrypt data before sending it to the device in IWMDMOperation::TransferObjectData.

Encrypt only the parameters that are specified as requiring encryption. See Using Secure Authenticated Channels for a table of methods that must use the message authentication code algorithm and encrypted parameters.

For example code, see IWMDMOperation::TransferObjectData.

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Using Secure Authenticated Channels
  • IWMDMOperation::TransferObjectData
  • CSecureChannelClient::DecryptParam
  • CSecureChannelClient Class


CSecureChannelClient::fIsAuthenticated (deprecated)

The fIsAuthenticated method verifies that a secure authenticated channel has been successfully established. This method is not used by applications.

Syntax

BOOL fIsAuthenticated();

Parameters

This method takes no parameters.

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.

Remarks

This method is used to ensure that a secure authentication channel has been established between components before allowing other operations. This includes calls by devices and storages prior to accessing and transferring data streams.

Applications do not need to call this method, but service providers call the corresponding CSecureChannelServer::fIsAuthenticated method and return WMDM_E_NOTCERTIFIED if it returns FALSE.

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Authenticating the Application
  • CSecureChannelClient Class


CSecureChannelClient::GetAppSec (deprecated)

The GetAppSec method retrieves the application security levels of the local and remote components.

Syntax

HRESULT GetAppSec(
  DWORD*  pdwLocalAppSec,
  DWORD*  pdwRemoteAppSec
);

Parameters

pdwLocalAppSec

[out] Pointer to a DWORD specifying the application security level of the local component (the application).

pdwRemoteAppSec

[out] Pointer to a DWORD specifying the application security level of the remote component (typically the service provider).

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • CSecureChannelClient Class


CSecureChannelClient::GetSessionKey (deprecated)

The GetSessionKey method retrieves the current session key. This method is not used by applications.

Syntax

HRESULT GetSessionKey(
  BYTE*  pbSPSessionKey
);

Parameters

pbSPSessionKey

[out] Pointer to the first byte of a buffer specifying the session key. The session key is used for encryption and decryption by the EncryptParam and DecryptParam methods.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pbSPSessionKey parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • CSecureChannelClient::SetSessionKey
  • CSecureChannelClient Class


CSecureChannelClient::MACFinal (deprecated)

The MACFinal method releases the message authentication code (MAC) channel and retrieves a final MAC value.

Syntax

HRESULT MACFinal(
  HMAC  hMAC,
  BYTE  abData[WMDM_MAC_LEN]
);

Parameters

hMAC

[in] Handle for the MAC for the current parameter data. This handle is created by calling the MACInit method. This datatype is declared in the SDK file ...\inc\Sac.h. After this method is called, the handle passed in is no longer valid.

abData

[out] Array of bytes to receive the final MAC value for the current parameter data.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid.
E_FAIL | An unspecified error occurred.

Remarks

This method completes creating a MAC key. For information about MAC creation, see

Example Code

The following example code checks the MAC received by a call to IWMDMStorage::GetRights to verify that the data has not been tampered with.

HRESULT hr;
CSecureChannelClient *pSPClient = NULL;
hr = m_pStorage->GetRights(ppRights, pnRightsCount, abTempMAC);
if (SUCCEEDED(hr))
{
    // Verify MAC returned by GetRights on the service provider.
    pSPClient->MACInit(&hMAC);
    pSPClient->MACUpdate(hMAC, (BYTE*)(*ppRights),
                       sizeof(WMDMRIGHTS) * (*pnRightsCount));
    pSPClient->MACUpdate(hMAC, (BYTE*)(pnRightsCount),
                        sizeof(*pnRightsCount));
    pSPClient->MACFinal(hMAC, abMACVerify);
    if (memcmp(abMACVerify, abTempMAC, WMDM_MAC_LENGTH) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
        goto exit;
    }
}

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Message Authentication
  • CSecureChannelClient::MACUpdate
  • CSecureChannelClient Class


CSecureChannelClient::MACInit (deprecated)

The MACInit method acquires a message authentication code (MAC) channel.

Syntax

HRESULT MACInit(
  HMAC*  phMAC
);

Parameters

phMAC

[out] Pointer to the MAC handle for the parameter data. The handle is acquired by MACInit to be used for subsequent MACUpdate and MACFinal calls. This datatype is declared in Sac.h installed with the Windows Media Format SDK.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The phMAC parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

MACInit begins a message authentication code (MAC) session. For example, MACInit should be called before content is transferred when writing to a storage device to verify the MAC returned by the IMDSPStorage::GetRights call on the service provider.

Example Code

The following example code checks the MAC received by a call to IWMDMStorage::GetRights to verify that the data has not been tampered with.

HRESULT hr;
CSecureChannelClient *pSPClient = NULL;
hr = m_pStorage->GetRights(ppRights, pnRightsCount, abTempMAC);
if (SUCCEEDED(hr))
{
    // Verify MAC returned by GetRights on the service provider.
    pSPClient->MACInit(&hMAC);
    pSPClient->MACUpdate(hMAC, (BYTE*)(*ppRights),
                       sizeof(WMDMRIGHTS) * (*pnRightsCount));
    pSPClient->MACUpdate(hMAC, (BYTE*)(pnRightsCount),
                        sizeof(*pnRightsCount));
    pSPClient->MACFinal(hMAC, abMACVerify);
    if (memcmp(abMACVerify, abTempMAC, WMDM_MAC_LENGTH) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
        goto exit;
    }
}

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Message Authentication
  • CSecureChannelClient::MACFinal
  • CSecureChannelClient::MACUpdate
  • CSecureChannelClient Class


CSecureChannelClient::MACUpdate (deprecated)

The MACUpdate method adds a value to a message authentication code (MAC).

Syntax

HRESULT MACUpdate(
  HMAC  hMAC,
  BYTE*  pbData,
  DWORD  dwDataLen
);

Parameters

hMAC

[in] Handle to the array specifying the MAC for the current parameter data. This handle is returned from the MACInit method. This datatype is declared in Sac.h installed with the Windows Media Format SDK.

pbData

[in] Pointer to the parameter data to add to the MAC value.

dwDataLen

DWORD specifying the length of the data to which pbData points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

An application calls MACUpdate repeatedly with each piece of data to add to the MAC. MACInit must always be called before MACUpdate, and MACFinal must always be called after MACUpdate. MACInit acquires the MAC handle, phMAC, to be used by the MACUpdate and MACFinal methods.

Example Code

The following example code checks the MAC received by a call to IWMDMStorage::GetRights to verify that the data has not been tampered with.

HRESULT hr;
CSecureChannelClient *pSPClient = NULL;
hr = m_pStorage->GetRights(ppRights, pnRightsCount, abTempMAC);
if (SUCCEEDED(hr))
{
    // Verify MAC returned by GetRights on the service provider.
    pSPClient->MACInit(&hMAC);
    pSPClient->MACUpdate(hMAC, (BYTE*)(*ppRights),
                       sizeof(WMDMRIGHTS) * (*pnRightsCount));
    pSPClient->MACUpdate(hMAC, (BYTE*)(pnRightsCount),
                        sizeof(*pnRightsCount));
    pSPClient->MACFinal(hMAC, abMACVerify);
    if (memcmp(abMACVerify, abTempMAC, WMDM_MAC_LENGTH) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
        goto exit;
    }
}

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Message Authentication
  • CSecureChannelClient Class


CSecureChannelClient::SetCertificate (deprecated)

The SetCertificate method specifies the certificate and private key of the secure authenticated channel (SAC) client.

Syntax

HRESULT SetCertificate(
  DWORD  dwFlags,
  BYTE*  pbAppCert,
  DWORD  dwCertLen,
  BYTE*  pbAppPVK,
  DWORD  dwPVKLen
);

Parameters

dwFlags

[in] Specifies the type of certificate being passed to this method. It must be set to SAC_CERT_V1.

pbAppCert

[in] Pointer to the first byte of the certificate of the SAC client.

dwCertLen

[in] DWORD specifying the length of the certificate to which pbAppCert points.

pbAppPVK

[in] Pointer to the first byte of the private key of the SAC client.

dwPVKLen

[in] DWORD specifying the length of the private key to which pbAppPVK points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Call the SetCertificate method immediately after creating the CsecureChannelClient object, as in the following Example Code.

You can specify the following dummy values for pbAppCert and pbAppPVK to will allow basic functionality:

BYTE abPVK[] = {0x00};
BYTE abCert[] = {0x00};

You can request a key and certificate from Microsoft as described in Tools for Development.

Example Code

The following C++ code authenticates the Windows Media Device Manager session and acquires the root object.

// Authenticates the WMDM, and acquires an interface to the top-level object.
HRESULT MyClass::Authenticate()
{
    HRESULT hr;
    CComPtr<IComponentAuthenticate> pAuth;

    // Create the WMDM object and acquire
    // its authentication interface.
    hr = CoCreateInstance(
        __uuidof(MediaDevMgr),
        NULL,
        CLSCTX_INPROC_SERVER,
        __uuidof(IComponentAuthenticate),
        (void**)&pAuth);

    if (hr != S_OK)
        return hr;

    // Create the secure channel client class needed to authenticate the application.
    // We'll use a global member variable to hold the secure channel client
    // in case we need to handle encryption, decryption, or MAC verification
    // during this session.
    m_pSAC = new CSecureChannelClient;
    if (m_pSAC == NULL)
        return E_FAIL;

    // Send the application's transfer certificate and the associated
    // private key to the secure channel client.
    hr = m_pSAC->SetCertificate(
        SAC_CERT_V1,
        (BYTE *)abCert, sizeof(abCert),
        (BYTE *)abPVK,  sizeof(abPVK));
    if (hr != S_OK)
        return hr;

    // Send the authentication interface we created to the secure channel
    // client and try authenticating the application with the V1 protocol.
    m_pSAC->SetInterface(pAuth);
    hr = m_pSAC->Authenticate(SAC_PROTOCOL_V1);
    if (hr != S_OK)
        return hr;

    // Authenticated succeeded, so we can use the WMDM.
    // Acquire an interface to the top-level WMDM interface.
    hr = pAuth->QueryInterface(__uuidof(IWMDeviceManager), (void**)&m_IWMDeviceMgr);

    return hr;
}

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Using Secure Authenticated Channels
  • Authenticating the Application
  • CSecureChannelServer::SetCertificate
  • CSecureChannelClient Class


CSecureChannelClient::SetInterface (deprecated)

The SetInterface method is used by applications to set the IComponentAuthenticate interface to use for Secure Authenticated Channel (SAC) operations.

Syntax

void SetInterface(
  IComponentAuthenticate*  pComponentAuth
);

Parameters

pComponentAuth

[in] Pointer to an IComponentAuthenticate interface. The caller is responsible for calling Release on the retrieved interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pComponentAuth parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The SAC interface is the IComponentAuthenticate interface. Applications use the IComponentAuthenticate interface provided in Windows Media Device Manager. Service providers and secure content providers must implement their own IComponentAuthenticate interface.

CoCreateInstance must be called first to acquire the IComponentAuthenticate interface.

Example Code

The following C++ code authenticates the Windows Media Device Manager session and acquires the root object.

// Authenticates the WMDM, and acquires an interface to the top-level object.
HRESULT MyClass::Authenticate()
{
    HRESULT hr;
    CComPtr<IComponentAuthenticate> pAuth;

    // Create the WMDM object and acquire
    // its authentication interface.
    hr = CoCreateInstance(
        __uuidof(MediaDevMgr),
        NULL,
        CLSCTX_INPROC_SERVER,
        __uuidof(IComponentAuthenticate),
        (void**)&pAuth);

    if (hr != S_OK)
        return hr;

    // Create the secure channel client class needed to authenticate the application.
    // We'll use a global member variable to hold the secure channel client
    // in case we need to handle encryption, decryption, or MAC verification
    // during this session.
    m_pSAC = new CSecureChannelClient;
    if (m_pSAC == NULL)
        return E_FAIL;

    // Send the application's transfer certificate and the associated
    // private key to the secure channel client.
    hr = m_pSAC->SetCertificate(
        SAC_CERT_V1,
        (BYTE *)abCert, sizeof(abCert),
        (BYTE *)abPVK,  sizeof(abPVK));
    if (hr != S_OK)
        return hr;

    // Send the authentication interface we created to the secure channel
    // client and try authenticating the application with the V1 protocol.
    m_pSAC->SetInterface(pAuth);
    hr = m_pSAC->Authenticate(SAC_PROTOCOL_V1);
    if (hr != S_OK)
        return hr;

    // Authenticated succeeded, so we can use the WMDM.
    // Acquire an interface to the top-level WMDM interface.
    hr = pAuth->QueryInterface(__uuidof(IWMDeviceManager), (void**)&m_IWMDeviceMgr);

    return hr;
}

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Using Secure Authenticated Channels
  • Authenticating the Application
  • IComponentAuthenticate Interface
  • CSecureChannelClient Class


CSecureChannelClient::SetSessionKey (deprecated)

The SetSessionKey method sets the key for this session that is used to communicate with another component. This method is not used by applications.

Syntax

HRESULT SetSessionKey(
  BYTE*  pbSPSessionKey
);

Parameters

pbSPSessionKey

[in] Pointer to the first byte of the session key that is to be set.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pbSPSessionKey parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Include scclient.h.

Library: mssachlp.lib

See Also

  • Using Secure Authenticated Channels
  • CSecureChannelClient::GetSessionKey
  • CSecureChannelClient Class


IWMDeviceManager Interface (deprecated)

The IWMDeviceManager interface is the top level Windows Media Device Manager interface for applications. This is the first interface accessed by an application, and is used to acquire the IWMDMEnumDevice interface used to enumerate the connected devices. This interface is obtained by calling QueryInterface on the authenticated IComponentAuthenticate interface. If the device supports it, use IWMDeviceManager2 interface, which offers superior device enumeration capabilities.

In addition to the methods inherited from IUnknown, the IWMDeviceManager interface exposes the following methods.

Method | Description
EnumDevices | Retrieves a pointer to the IWMDMEnumDevice interface that can be used to enumerate portable devices connected to the computer.
GetDeviceCount | Retrieves the number of portable devices that are currently connected to the computer.
GetRevision | Retrieves the version number of Windows Media Device Manager currently in use.

See Also

  • IWMDeviceManager2 Interface
  • Interfaces for Applications


IWMDeviceManager::EnumDevices (deprecated)

The EnumDevices method retrieves a pointer to the IWMDMEnumDevice interface that can be used to enumerate portable devices connected to the computer.

Syntax

HRESULT EnumDevices(
  IWMDMEnumDevice**  ppEnumDevice
);

Parameters

ppEnumDevice

[out] Pointer to a pointer to an IWMDMEnumDevice interface used to enumerate devices. The caller must release this interface when done with it.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumDevice parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method returns devices based on earlier versions of Windows Media Device Manager. To get all devices, including newer devices (such as MTP devices), call IWMDMDeviceManager2::EnumDevices2.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IWMDeviceManager Interface
  • IWMDeviceManager2::EnumDevices2
  • IWMDMEnumDevice Interface


IWMDeviceManager::GetDeviceCount (deprecated)

The GetDeviceCount method retrieves the number of portable devices that are currently connected to the computer.

Syntax

HRESULT GetDeviceCount(
  DWORD*  pdwCount
);

Parameters

pdwCount

[out] Pointer to a DWORD specifying the count of known devices.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwCount parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Example Code

The following C++ code retrieves a count of devices from a global IWMDeviceManager interface.

HRESULT hr = S_OK;

// Print number of devices.
DWORD iDevices = 0;
hr = m_IWMDeviceMgr->GetDeviceCount(&iDevices);
if (hr == S_OK)
{
    // TODO: Display the count of devices.
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IWMDeviceManager Interface


IWMDeviceManager::GetRevision (deprecated)

The GetRevision method retrieves the version number of Windows Media Device Manager currently in use.

Syntax

HRESULT GetRevision(
  DWORD*  pdwRevision
);

Parameters

pdwRevision

[out] Pointer to a DWORD specifying the Windows Media Device Manager version number. Windows Media Device Manager 10 returns 0x00080000.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwRevision parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Example Code

The following C++ code retrieves the revision from the global IWMDMDeviceManager interface, and displays it in hexadecimal using a custom macro.

DWORD revision = 0;
hr = m_IWMDeviceMgr->GetRevision(&revision);
CHECK_HR(hr, "Revision of WMDM: " << hex << revision << dec, "Couldn't get the WMDM revision number.");

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDeviceManager Interface


IWMDeviceManager2 Interface (deprecated)

The IWMDeviceManager2 interface extends IWMDeviceManager interface. It provides a way of enumerating devices that takes advantage of the Plug and Play (PnP) system that results in better performance and lower memory use. It also enables the application to query for a specific device based on the canonical name of the device.

In addition to the methods inherited from IWMDeviceManager, the IWMDeviceManager2 interface exposes the following methods.

Method | Description
GetDeviceFromCanonicalName | Retrieves an IWMDMDevice interface for a device with a specified canonical name.
EnumDevices2 | Retrieves an enumeration interface that is used to enumerate portable devices connected to the computer.
Reinitialize | Forces Windows Media Device Manager to rediscover all the Windows Media Device Manager devices

See Also

  • Interfaces for Applications


IWMDeviceManager2::GetDeviceFromCanonicalName (deprecated)

The GetDeviceFromCanonicalName method retrieves an IWMDMDevice interface for a device with a specified canonical name. You can retrieve a device's canonical name by calling IWMDMDevice2::GetCanonicalName.

Syntax

HRESULT GetDeviceFromCanonicalName(
  LPCWSTR  pwszCanonicalName,
  IWMDMDevice**  ppDevice
);

Parameters

pwszCanonicalName

[in] A wide-character, null-terminated string specifying the canonical name of the device.

ppDeviceArray

[out] Pointer to a pointer to the IWMDMDevice interface of the device object with the specified canonical name. The caller must release this interface when done with it.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Value | Description
E_INVALIDARG | The pwszCanonicalName or ppDeviceArray parameter is an invalid or NULL pointer.
S_FALSE | There is no connected device found with canonical name pwszCanonicalName.

Remarks

This method can be useful if an application implements IWMDMNotification, which sends a canonical name notification when a device connects or disconnects from the computer.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice2 Interface
  • IWMDeviceManager2 Interface


IWMDeviceManager2::EnumDevices2 (deprecated)

The EnumDevices2 method retrieves an enumeration interface that is used to enumerate portable devices connected to the computer.

Microsoft strongly recommends that applications use the EnumDevices2 method instead of IWMDeviceManager::EnumDevices.

Syntax

HRESULT EnumDevices2(
  IWMDMEnumDevice**  ppEnumDevice
);

Parameters

ppEnumDevice

[out] Pointer to a pointer to an IWMDMEnumDevice interface. The caller is responsible for calling Release on the retrieved interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumDevice parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method returns an enumerator that takes advantage of the Plug and Play (PnP) system for a faster enumeration and lower memory use. For PnP-complaint service providers, it loads in memory only those service providers that have a device currently connected to the computer, and requests only those service providers to create device objects.

This method returns a snapshot of the devices connected when the underlying object was first created. To ensure that the device list is up to date, call Reinitialize before calling this method.

Example Code

The following C++ code loops through all the devices and retrieves the display name of each.

// Enumerate through the devices using the faster EnumDevices2 Plug-and-Play method.
// IWMDevMgr2 is a global IWMDeviceManager2 pointer.
CComPtr<IWMDMEnumDevice> pEnumDevice;
hr = pIWMDevMgr2->EnumDevices2(&pEnumDevice);
if (hr == S_OK)
{
    // Length of all the strings we'll send in.
    const UINT MAX_CHARS = 100;
    WCHAR name[MAX_CHARS];

    // Enumerate through devices using a dummy loop.
    while(TRUE)
    {
        // Get a device handle.
        IWMDMDevice* pDevice;
        ULONG ulFetched = 0;
        hr = pEnumDevice->Next(1, &pDevice, &ulFetched);
        CComQIPtr<IWMDMDevice2> pDevice2(pDevice);

        if (hr != S_OK || ulFetched != 1)
        {
            break;
        }
        ZeroMemory(name, MAX_CHARS);
        hr = pDevice2->GetName(name, MAX_CHARS);
    }
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IWMDeviceManager2 Interface
  • IWMDMEnumDevice Interface


IWMDeviceManager2::Reinitialize (deprecated)

The Reinitialize method forces Windows Media Device Manager to rediscover all the Windows Media Device Manager devices.

Syntax

HRESULT Reinitialize();

Parameters

This method takes no parameters.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

Windows Media Device Manager monitors Plug and Play (PnP) notifications to keep track of connected devices which are controlled by a PnP-compliant service provider. If a non-compliant device is plugged in or some other changes are made to a device for which the device does not generate PnP notifications (for example, insertion or removal of a storage card), the application should call this method before calling IWMDeviceManager2::EnumDevices2. The application would typically do this on a refresh request from the user.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDeviceManager2 Interface
  • IWMDeviceManager2::EnumDevices2


IWMDeviceManager3 Interface (deprecated)

The IWMDeviceManager3 interface extends the IWMDeviceManager2 interface by providing a method that sets the device enumeration preferences.

In addition to the methods inherited from IWMDeviceManager2, the IWMDeviceManager3 interface exposes the following method.

Method | Description
SetDeviceEnumPreference | Sets the device enumeration preferences.

See Also

  • Interfaces for Applications
  • IWMDeviceManager2 Interface


IWMDeviceManager3::SetDeviceEnumPreference (deprecated)

The SetDeviceEnumPreference method sets the device enumeration preferences.

Syntax

HRESULT SetDeviceEnumPreference(
  UINT  fuPrefs
);

Parameters

fuPrefs

[in] Specifies a bitwise OR combination of one or more of the following bit values that specify enumeration preference. Each set bit enables the corresponding extended behavior, whereas the absence of that bit disables the extended behavior and specifies the default, backward-compatible enumeration behavior. The possible values for fuPrefs are provided in the following table.

Value | Description
DO_NOT_VIRTUALIZE_STORAGES_AS_DEVICES | By default, for devices containing multiple storage media (for example, multiple flash memory cards), each of these storages enumerates as a separate pseudo-device. However, when this flag is set, storages are not visible as devices, and only devices are visible as devices. See Remarks for more information.
ALLOW_OUTOFBAND_NOTIFICATION | When this flag is set, the service provider can send device arrival and removal by an additional mechanism, such as by using a window message, as well as the default mechanism of calling any application-implemented IWMDMNotification interfaces.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Value | Description
S_OK | The method succeeded.
E_INVALIDARG | The fuPrefs parameter specifies an unsupported bit value.
WMDM_E_CALL_OUT_OF_SEQUENCE | The method was called after an enumeration operation; it must be called before the enumeration operation.

Remarks

This method provides clients the ability to override the default device enumeration behavior of Windows Media Device Manager. In order to override the default behavior, the client application must call this method immediately after creating the device manager object by querying for the IWMDMDeviceManager3 interface from Media Device Manager. The call must be made before any enumeration occurs, either explicitly or implicitly as a result of another operation.

After a preference flag is set, it cannot be changed for the lifetime of the application (not just the lifetime of the Windows Media Device Manager object). Attempting to change a preference flag will result in an error. Calling this method again with the same flag settings does not return an error, and also does have any effect on enumeration.

The service provider may not honor the DO_NOT_VIRTUALIZE_STORAGES_AS_DEVICES flag. A more robust way to determine if storages are hosted by the same device is to call IWMDMDevice2::GetCanonicalName. Storages from the same device will return identical values, except for the final digit after the last "$" character.

Requirements

Header: Defined in mswmdm.h.

See Also

  • IWMDeviceManager3 Interface


IWMDMDevice Interface (deprecated)

The IWMDMDevice interface provides methods to examine and explore a single portable device. The interface can be used to get information about a device and enumerate its storages. IWMDMDevice2 extends the capabilities of this interface.

In addition to the methods inherited from IUnknown, the IWMDMDevice interface exposes the following methods.

Method | Description
EnumStorage | Retrieves an IWMDMEnumStorage interface to enumerate the storages on a device.
GetDeviceIcon | Retrieves a handle to the icon that the device manufacturer wants to display when the device is connected.
GetFormatSupport | Retrieves all the formats supported by the device, including codecs and file formats.
GetManufacturer | Retrieves the name of the manufacturer of the device.
GetName | Retrieves the human-readable name of the device.
GetPowerSource | Retrieves information about the power source and the percentage of power remaining for the device.
GetSerialNumber | Retrieves a serial number that uniquely identifies the device.
GetStatus | Retrieves device status information.
GetType | Retrieves the operations supported by the device.
GetVersion | Retrieves the manufacturer-defined version number of the device.
SendOpaqueCommand | Sends a device-specific command to the device through Windows Media Device Manager.

See Also

  • Interfaces for Applications
  • IWMDMDevice2 Interface
  • IWMDMDevice3 Interface


IWMDMDevice::EnumStorage (deprecated)

The EnumStorage method retrieves an IWMDMEnumStorage interface to enumerate the storages on a device.

Syntax

HRESULT EnumStorage(
  IWMDMEnumStorage**  ppEnumStorage
);

Parameters

ppEnumStorage

[out] Pointer to a pointer to an IWMDMEnumStorage interface to enumerate the storages on a device. This points to the root storage on the device. The caller is responsible for calling Release on the retrieved interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumStorage parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
E_OUTOFMEMORY | The storage enumerator object could not be created because not enough memory is available.

Example Code

The following two C++ functions recursively explore a device. The first one is a kickoff function that obtains the IWMDMEnumStorage interface of the root device storage. It passes this to the second, recursive function that examines all the nested functions.

// Kickoff function to explore a device.
void ExploreDevice(IWMDMDevice* pDevice)
{
    HRESULT hr = S_OK;

    // Get a root enumerator.
    CComPtr<IWMDMEnumStorage> pEnumStorage;
    hr = pDevice->EnumStorage(&pEnumStorage);

    // Explore the rest of the device recursively.
    RecursiveExploreStorage(pEnumStorage);

    HANDLE_HR(hr, "Got a root storage in ExploreDevice.","Couldn't get a root storage in ExploreDevice.");

e_Exit:
    return;
}

// Recursive function to explore all storages on the device.
void RecursiveExploreStorage(IWMDMEnumStorage* pEnumStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage> pStorage;
    ULONG numRetrieved = 0;
    // Loop through all storages in the current storage
    while(pEnumStorage->Next(1, &pStorage, &numRetrieved) == S_OK && numRetrieved == 1)
    {
        // Get the name of the object. The first time this is called on a device, it will
        // retrieve '\' as the root folder name.
        const UINT MAX_LEN = 255;
        WCHAR name[MAX_LEN];
        hr = pStorage->GetName((LPWSTR)&name, MAX_LEN);
        // TODO: Display the storage name.

        // Get metadata for the storage.
        if (SUCCEEDED(hr))
            GetMetadata(pStorage);

        // Find out something about the item.
        DWORD attributes = 0;
        _WAVEFORMATEX audioFormat;
        hr = pStorage->GetAttributes(&attributes, &audioFormat);
        HANDLE_HR(hr, "Got storage attributes in RecursivelyExploreStorage.","Couldn't get storage attributes in RecursivelyExploreStorage.");

        // If this is a folder, recurse into it.
        if (attributes & WMDM_FILE_ATTR_FILE)
            // TODO: Display a message indicating that this is a file.
        if (attributes & WMDM_FILE_ATTR_FOLDER)
        {
            // TODO: Display a message indicating that this is a folder.
            CComPtr<IWMDMEnumStorage> pEnumSubStorage;
            hr = pStorage->EnumStorage(&pEnumSubStorage);
            RecursiveExploreStorage(pEnumSubStorage);
        }

        // Some other useful attributes to check include:
        // WMDM_FILE_ATTR_CANDELETE and WMDM_FILE_ATTR_CANPLAY and others to determine what can be done with a storage.
        // WMDM_FILE_ATTR_HIDDEN and other attributes to determine display characteristics,
        // WMDM_STORAGE_IS_DEFAULT to see if this is the default save location for new files.
        pStorage.Release();
    } // Get the next storage pointer.

e_Exit:
    return;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Exploring a Device
  • IWMDMDevice Interface
  • IWMDMEnumStorage Interface


IWMDMDevice::GetDeviceIcon (deprecated)

The GetDeviceIcon method retrieves a handle to the icon that the device manufacturer wants to display when the device is connected.

Syntax

HRESULT GetDeviceIcon(
  ULONG*  hIcon
);

Parameters

hIcon

[out] Handle to an icon object.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The hIcon parameter is either an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

When the application is finished with the icon, it must call the Win32 DestroyIcon function to free the memory.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface


IWMDMDevice::GetFormatSupport (deprecated)

The GetFormatSupport method retrieves all the formats supported by the device, including codecs and file formats.

Syntax

HRESULT GetFormatSupport(
  _WAVEFORMATEX**  ppFormatEx,
  UINT*  pnFormatCount,
  LPWSTR**  pppwszMimeType,
  UINT*  pnMimeTypeCount
);

Parameters

ppFormatEx

[out] Pointer to an array of _WAVEFORMATEX structures specifying information about codecs and bit rates supported by the device. Windows Media Device Manager allocates the memory for this parameter; the caller must free it using CoTaskMemFree.

pnFormatCount

[out] Pointer to the number of elements in the ppFormatEx array.

pppwszMimeType

[out] Pointer to an array describing file formats and digital rights management schemes supported by the device. Windows Media Device Manager allocates the memory for this parameter; the caller must free it using CoTaskMemFree.

pnMimeTypeCount

[out] Pointer to the number of elements in the pppwszMimeType array.

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.

Return code | Description
S_OK | The method succeeded.
E_OUTOFMEMORY | Insufficient memory resources to allocate memory for ppFormatEx or pppwszMimeType.
E_INVALIDARG | A parameter is invalid or a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The recommended way to retrieve device-supported formats is IWMDMDevice3::GetFormatCapability.

Example Code

The following C++ function retrieves various device capabilities.

// Function to print out device caps for a device that supports
// only IWMDMDevice.
void GetCaps(IWMDMDevice* pDevice)
{
    HRESULT hr = S_OK;

    // Get all capabilities for audio and mime support.
    _WAVEFORMATEX* pAudioFormats;
    LPWSTR* pMimeFormats;
    UINT numAudioFormats = 0;
    UINT numMimeFormats = 0;
    hr = pDevice->GetFormatSupport(
        &pAudioFormats,
        &numAudioFormats,
        &pMimeFormats,
        &numMimeFormats);

    HANDLE_HR(hr, "Got audio and mime formats in GetCaps IWMDMDevice", "Couldn't get audio and mime formats in GetCaps IWMDMDevice");

    // Print out audio format data.
    if (numAudioFormats > 0)
    {
        / /TODO: Display a banner to precede the supported formats.
    }
    else
    {
        // TODO: Display a message indicating that no formats are supported.
    }
    for(int i = 0; i < numAudioFormats; i++)
    {
        // TODO: Display a configuration value.
        PrintWaveFormatGuid(pAudioFormats[i].wFormatTag);
        // TODO: Display a max channel value.
        // TODO: Display a max samples/second value.
        // TODO: Display the max bytes/second value.
        // TODO: Display the block alignment value.
        // TODo: Display the max bits/sample value.
    }

    // Print out MIME formats.
    if (numMimeFormats > 0)
        // TODO: Display a banner for the MIME format listing.
    else
        / /TODO: Display a message indicating that no MIME formats are supported.
    for(i = 0; i < numMimeFormats; i++)
    {
        // TODO: Display each individual MIME format.
    }

e_Exit:
    return;

}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • Discovering Device Format Capabilities
  • IWMDMDevice Interface
  • IWMDMDevice3::GetFormatCapability


IWMDMDevice::GetManufacturer (deprecated)

The GetManufacturer method retrieves the name of the manufacturer of the device.

Syntax

HRESULT GetManufacturer(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to a wide-character, null-terminated string specifying the manufacturer's name. The buffer must be allocated and released by the caller.

nMaxChars

[in] Integer specifying the maximum number of characters that can be copied to pwszName, including the termination character.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pwszName parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not have a manufacturer's name.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the return string. Check nMaxChars for the required buffer size.
E_FAIL | An unspecified error occurred.

Example Code

The following C++ code retrieves the device manufacturer.

// Print the device manufacturer.
const UINT MAX_CHARS = 100;
rWCHAR manufacturer[MAX_CHARS];
hr = pIWMDMDevice->GetManufacturer((LPWSTR)&manufacturer, MAX_CHARS);
if (hr == S_OK)
    // TODO: Display the manufacturer string.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Exploring a Device
  • IWMDMDevice Interface


IWMDMDevice::GetName (deprecated)

The GetName method retrieves the human-readable name of the media device.

Syntax

HRESULT GetName(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to a (Unicode) wide-character, null-terminated string specifying the device name. The buffer is allocated and released by the caller.

nMaxChars

[in] Integer specifying the maximum number of characters that can be placed in pwszName, including the termination character.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pwszName parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not have a name.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the return string. Check nMaxChars for the required buffer size.
E_FAIL | An unspecified error occurred.

Example Code

The following C++ code retrieves the device display name.

// Get the device name.
const UINT MAX_CHARS = 100;
WCHAR name[MAX_CHARS];
hr = pIWMDMDevice->GetName((LPWSTR)&name, MAX_CHARS);
if (hr == S_OK)
// TODO: Display the retrieved name.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Exploring a Device
  • IWMDMDevice Interface
  • IWMDMDevice::GetType


IWMDMDevice::GetPowerSource (deprecated)

The GetPowerSource method retrieves information about the power source and the percentage of power remaining for the device.

Syntax

HRESULT GetPowerSource(
  DWORD*  pdwPowerSource,
  DWORD*  pdwPercentRemaining
);

Parameters

pdwPowerSource

[out] Pointer to a DWORD specifying information about the power source of the device.

The possible returned values are a bitwise OR of one or more of the following values.

Flag | Description
WMDM_POWER_CAP_BATTERY | The media device can run on batteries.
WMDM_POWER_CAP_EXTERNAL | The media device can run on external power.
WMDM_POWER_IS_BATTERY | The media device is currently running on batteries.
WMDM_POWER_IS_EXTERNAL | The media device is currently running on external power.
WMDM_POWER_PERCENT_AVAILABLE | The percentage of power remaining was returned in pdwPercentRemaining.

pdwPercentRemaining

[out] If pdwPowerSource contains WMDM_POWER_PERCENT_AVAILABLE, a pointer to a DWORD specifying the percentage of power remaining in the device.

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.

Return code | Description
E_INVALIDARG | One of the parameters is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device cannot provide this information.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface


IWMDMDevice::GetSerialNumber (deprecated)

The GetSerialNumber method retrieves a serial number that uniquely identifies the device.

Syntax

HRESULT GetSerialNumber(
  PWMDMID  pSerialNumber,
  BYTE[WMDM_MAC_LENGTH]  abMac
);

Parameters

pSerialNumber

[out] Pointer to a WMDMID structure specifying the serial number information. The WMDID structure is allocated and released by the application.

abMac

[in, out] Array of bytes specifying the message authentication code for the parameter data of this method.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pSerialNumber parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not support serial numbers.
E_FAIL | An unspecified error occurred.

Remarks

Not all devices support serial numbers. To determine whether the device supports serial numbers, the caller must always check the return code when calling this function. If a media device supports serial numbers, the serial number of the media device is guaranteed to be unique for that device.

After calling this method, an application can verify that the serial has not been modified during transport by using the abMAC parameter. For example code on this, see Using Secure Authenticated Channels.

Example Code

The following C++ code retrieves the device serial number and verifies the MAC.

//
// Get and verify the serial number.
//
WMDMID serialNumber;
BYTE receivedMAC[WMDM_MAC_LENGTH];
hr = pIWMDMDevice->GetSerialNumber(&serialNumber, receivedMAC);

// Check the MAC to guarantee the serial number has not been tampered with.
if (hr == S_OK)
{
    // Initialize a MAC handle,
    // next add all parameters to the MAC,
    // and finally retrieve the calculated MAC value.
    HMAC hMAC;
    BYTE calculatedMAC[WMDM_MAC_LENGTH];
    hr = m_pSAC->MACInit(&hMAC);
    hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(&serialNumber), sizeof(serialNumber));
    hr = m_pSAC->MACFinal(hMAC, (BYTE*)calculatedMAC);
    if (memcmp(calculatedMAC, receivedMAC, sizeof(calculatedMAC)) == 0)
    {
        // MAC is authentic. Print the serial number.
        CHAR* serialNumberBuffer = new CHAR[serialNumber.SerialNumberLength + 1];
        ZeroMemory(serialNumberBuffer, (serialNumber.SerialNumberLength + 1) * sizeof(CHAR));
        memcpy(serialNumberBuffer, serialNumber.pID, serialNumber.SerialNumberLength * sizeof(CHAR));
        // TODO: Display the serial number.
        delete serialNumberBuffer;
    }
    else
        // TODO: Display a message indicating that the serial number MAC does not match in EnumDevices
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface
  • Using Secure Authenticated Channels


IWMDMDevice::GetStatus (deprecated)

The GetStatus method retrieves device status information.

Syntax

HRESULT GetStatus(
  DWORD*  pdwStatus
);

Parameters

pdwStatus

[out] Pointer to a DWORD specifying the device status. The possible values returned in pdwStatus are provided in the following table.

Status | Description
WMDM_STATUS_READY | Windows Media Device Manager and its subcomponents are in a ready state.
WMDM_STATUS_BUSY | An operation is ongoing. Evaluate status values to determine the operation.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwStatus parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface


IWMDMDevice::GetType (deprecated)

The GetType method retrieves the operations supported by the device.

Syntax

HRESULT GetType(
  DWORD*  pdwType
);

Parameters

pdwType

[out] Pointer to a DWORD specifying the device type attributes. The possible values returned in pdwType are defined in the following table. Microsoft recommends setting both WMDM_DEVICE_TYPE_SDMI and WMDM_DEVICE_TYPE_NONSDMI flags.

Device type | Description
WMDM_DEVICE_TYPE_PLAYBACK | The media device supports audio playback.
WMDM_DEVICE_TYPE_RECORD | The media device supports audio recording.
WMDM_DEVICE_TYPE_DECODE | The media device supports audio format decoding.
WMDM_DEVICE_TYPE_ENCODE | The media device supports audio format encoding.
WMDM_DEVICE_TYPE_STORAGE | The media device has on-board storage for media files.
WMDM_DEVICE_TYPE_VIRTUAL | The media device is not a physical device.
WMDM_DEVICE_TYPE_SDMI | The media device can accept SDMI-protected content.
WMDM_DEVICE_TYPE_NONSDMI | The media device can accept non-SDMI content.
WMDM_DEVICE_TYPE_NONREENTRANT | The media device must synchronize access to Windows Media Device Manager services.
WMDM_DEVICE_TYPE_FILELISTRESYNC | The media device allows the file list to be resynchronized.
WMDM_DEVICE_TYPE_VIEW_PREF_METADATAVIEW | The media device prefers metadata views while its storages are enumerated.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwType parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The current Microsoft service providers may not provide reliable information about devices, except WMDM_DEVICE_TYPE_NONSDMI or WMDM_DEVICE_TYPE_SDMI. All devices will be reported as supporting the former; devices that support serial numbers also return the latter.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface
  • IWMDMDevice::GetName


IWMDMDevice::GetVersion (deprecated)

The GetVersion method retrieves the manufacturer-defined version number of the device.

Syntax

HRESULT GetVersion(
  DWORD*  pdwVersion
);

Parameters

pdwVersion

[out] Pointer to a DWORD specifying the version number.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwVersion parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not support version numbers.
E_FAIL | An unspecified error occurred.

Remarks

The format of the version number is determined by the manufacturer.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface


IWMDMDevice::SendOpaqueCommand (deprecated)

The SendOpaqueCommand method sends a device-specific command to the device through Windows Media Device Manager. Windows Media Device Manager does not attempt to read the command.

Syntax

HRESULT SendOpaqueCommand(
  OPAQUECOMMAND*  pCommand
);

Parameters

pCommand

[in, out] Pointer to an OPAQUECOMMAND structure specifying the information required to execute the command. If the device returns data, it is returned through the pData member of pCommand.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is intended for device commands that do not affect the operation of Windows Media Device Manager and are passed through unchanged.

Example Code

The following code performs a simplified extended authentication procedure with a device. This procedure is specific to a device.

// Call opaque command to exchange extended authentication information.
    //
    {
        HMAC           hMAC;
        OPAQUECOMMAND  Command;
        CERTINFOEX    *pCertInfoEx;
        DWORD          cbData_App   = sizeof(bCertInfoEx_App)/sizeof(bCertInfoEx_App[0]);
        DWORD          cbData_SP    = sizeof(bCertInfoEx_SP)/sizeof(bCertInfoEx_SP[0]);
        DWORD          cbData_Send  = sizeof(CERTINFOEX) + cbData_App;

        // Fill out opaque command structure.
        memcpy(&(Command.guidCommand), &guidCertInfoEx, sizeof(GUID));

        Command.pData = (BYTE *)CoTaskMemAlloc(cbData_Send);
        if (!Command.pData)
        {
            ExitOnFail(hr = E_OUTOFMEMORY);
        }
        Command.dwDataLen = cbData_Send;

        // Map the data in the opaque command to a CERTINFOEX structure, and
        // fill in the certificate info to send.
        pCertInfoEx = (CERTINFOEX *)Command.pData;

        pCertInfoEx->hr     = S_OK;
        pCertInfoEx->cbCert = cbData_App;
        memcpy(pCertInfoEx->pbCert, bCertInfoEx_App, cbData_App);

        // Compute the MAC to send.
        g_cWmdm.m_pSAC->MACInit(&hMAC);
        g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.guidCommand)), sizeof(GUID));
        g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.dwDataLen)), sizeof(Command.dwDataLen));
        if (Command.pData)
        {
            g_cWmdm.m_pSAC->MACUpdate(hMAC, Command.pData, Command.dwDataLen);
        }
        g_cWmdm.m_pSAC->MACFinal(hMAC, Command.abMAC);

        // Send the command.
        hr = pDevice->SendOpaqueCommand(&Command);
        if (SUCCEEDED(hr))
        {
            BYTE abMACVerify2[ WMDM_MAC_LENGTH ];

            // Compute retrieved MAC for verification.
            g_cWmdm.m_pSAC->MACInit(&hMAC);
            g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.guidCommand)), sizeof(GUID));
            g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.dwDataLen)), sizeof(Command.dwDataLen));
            if (Command.pData)
            {
                g_cWmdm.m_pSAC->MACUpdate(hMAC, Command.pData, Command.dwDataLen);
            }
            g_cWmdm.m_pSAC->MACFinal(hMAC, abMACVerify2);

            // Verify the MAC matches.
            //
            if (memcmp(abMACVerify2, Command.abMAC, WMDM_MAC_LENGTH) == 0)
            {
                // Cast the data in the opaque command to a CERTINFOEX structure.
                //
                pCertInfoEx = (CERTINFOEX *)Command.pData;

                // In this simple extended authentication scheme, the callee must
                // provide the exact certificate info.
                //
                if ((pCertInfoEx->cbCert != cbData_SP) ||
                    (memcmp(pCertInfoEx->pbCert, bCertInfoEx_SP, cbData_SP) == 0))
                {
                    m_fExtraCertified = TRUE;
                }
            }
        }

        if (Command.pData)
        {
            CoTaskMemFree(Command.pData);
        }
    }

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice Interface


IWMDMDevice2 Interface (deprecated)

The IWMDMDevice2 interface extends IWMDMDevice by making it possible to get the video formats supported by a device, find storage from its name, and use property pages.

In addition to the methods inherited from IWMDMDevice, the IWMDMDevice2 interface exposes the following methods.

Method | Description
GetCanonicalName | Retrieves the canonical name of the device.
GetFormatSupport2 | Retrieves the formats supported by the device, including audio and video codecs, and MIME file formats
GetSpecifyPropertyPages | Retrieves the property page for the device.
GetStorage | Searches the immediate children of the root storage for a storage with the given name.

See Also

  • Interfaces for Applications
  • IWMDMDevice Interface
  • IWMDMDevice3 Interface


IWMDMDevice2::GetCanonicalName (deprecated)

The GetCanonicalName method retrieves the canonical name of the device.

Syntax

HRESULT GetCanonicalName(
  LPWSTR  pwszPnPName,
  UINT  nMaxChars
);

Parameters

pwszPnPName

[out] Wide-character buffer for the canonical names. This buffer must be allocated and released by the caller.

nMaxChars

[in] Integer specifying the maximum number of characters that can be placed in pwszPnPName, including the termination character.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
E_INVALIDARG | The pwszPnPName parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not support a canonical name.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the canonical name.
E_FAIL | An unspecified error occurred.

Remarks

The application can use the retrieved canonical name to call IWMDeviceManager2::GetDeviceFromCanonicalName to find this device again.

The returned canonical name is in the format <PnP Device Path>$<index>, where index is a zero-based index into the device objects returned by the service provider for the specified PnP device path.

The format of canonical name is subject to change in future releases of Windows Media Device Manager.

Example Code

The following C++ code retrieves a device canonical name.

// Obtain an IWMDMDevice2 interface and call
// some methods.
const UINT MAX_CHARS = 100;
CComQIPtr<IWMDMDevice2> pIWMDMDevice2(pIWMDMDevice);
if (pIWMDMDevice2 != NULL)
{
    // Get the canonical name.
    WCHAR canonicalName[MAX_CHARS];
    hr = pIWMDMDevice2->GetCanonicalName(canonicalName, MAX_CHARS);
    if (hr == S_OK)
    {
        // TODO: Retrieve the canonical name.
    }

    // Find out the driver.
    myGetDriverName(pIWMDMDevice2);
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDeviceManager2::GetDeviceFromCanonicalName
  • IWMDMDevice2 Interface


IWMDMDevice2::GetFormatSupport2 (deprecated)

The GetFormatSupport2 method retrieves the formats supported by the device, including audio and video codecs, and MIME file formats.

Syntax

HRESULT GetFormatSupport2(
  DWORD  dwFlags,
  _WAVEFORMATEX**  ppAudioFormatEx,
  UINT*  pnAudioFormatCount,
  _VIDEOINFOHEADER**  ppVideoFormatEx,
  UINT*  pnVideoFormatCount,
  WMFILECAPABILITIES**  ppFileType,
  UINT*  pnFileTypeCount
);

Parameters

dwFlags

[in] DWORD specifying audio formats, video formats, and MIME types. This flag specifies what the application is requesting the service provider to fill in. The caller can set one or more of the following three values.

Value | Description
WMDM_GET_FORMAT_SUPPORT_AUDIO | Service provider should fill in audio parameters.
WMDM_GET_FORMAT_SUPPORT_VIDEO | Service provider should fill in video parameters.
WMDM_GET_FORMAT_SUPPORT_FILE | Service provider should fill in file parameters.

ppAudioFormatEx

[out] Pointer to an array of _WAVEFORMATEX structures specifying information about audio codecs and bit rates supported by the device. The memory for this parameter is allocated by Windows Media Device Manager, and must be released by the caller with the Win32 function CoTaskMemFree.

pnAudioFormatCount

[out] Pointer to an integer specifying the audio format count.

ppVideoFormatEx

[out] Pointer to an array of _VIDEOFORMATEX structures specifying information about video codes and formats supported by the device. The memory for this parameter is allocated by Windows Media Device Manager, and must be released by the caller with the Win32 function CoTaskMemFree.

pnVideoFormatCount

[out] Pointer to an integer specifying the video format count.

ppFileType

[out] Pointer to an array of WMFILECAPABILITIES file-type objects. The memory for this parameter is allocated by Windows Media Device Manager, and must be released by the caller with the Win32 function CoTaskMemFree.

pnFileTypeCount

[out] Pointer to an integer specifying the file-type count.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

This method extends IWMDMDevice::GetFormatSupport to handle video formats. The recommended method for getting format support, however, is IWMDMDevice3::GetFormatCapability. If GetFormatCapability isn't supported, the device will probably not support video, and GetFormatSupport is probably sufficient.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Discovering Device Format Capabilities
  • IWMDMDevice2 Interface
  • IWMDMDevice3::GetFormatCapability


IWMDMDevice2::GetSpecifyPropertyPages (deprecated)

The GetSpecifyPropertyPages method retrieves the property page for the device. Property pages can be used to report device-specific properties and branding information.

Syntax

HRESULT GetSpecifyPropertyPages(
  ISpecifyPropertyPages**  ppSpecifyPropPages,
  IUnknown***  pppUnknowns,
  ULONG*  pcUnks
);

Parameters

ppSpecifyPropPages

[out] Pointer to a pointer to an ISpecifyPropertyPages interface. ISpecifyPropertyPages is documented in the COM area of the Platform SDK. The caller must release this interface when done with it.

pppUnknowns

[out] Specifies an array of IUnknown interface pointers. These interfaces are passed to the property page and can be used to pass information between the property page and the service provider. The array is allocated by Windows Media Device Manager, but the caller must call Release on each interface retrieved, and CoTaskMemFree on the retrieved array.

pcUnks

[out] Retrieves the size of the pppUnknowns array.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice2 Interface


IWMDMDevice2::GetStorage (deprecated)

The GetStorage method searches the immediate children of the root storage for a storage with the given name.

Syntax

HRESULT GetStorage(
  LPCWSTR  pszStorageName,
  IWMDMStorage**  ppStorage
);

Parameters

pszStorageName

[in] Pointer to a null-terminated string specifying the name of the storage to find. This parameter does not support wildcard characters.

ppStorage

[out] Pointer to the IWMDMStorage interface of the storage specified by the pszStorageName parameter. The caller must release this interface when done with it.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The storage cannot be found.

Remarks

This function is not recursive; it only searches the immediate children of the device root storage. For a recursive search version of this function, use IWMDMDevice3::FindStorage.

Example Code

The following C++ function searches for a storage recursively. It uses GetStorage to search the immediate children; if the requested storage is not found, it then loops through all the children and recursively searches folders.

HRESULT myFindStorageRecursively(LPCWSTR storageName, IWMDMStorage* pCurrentStorage, IWMDMStorage** ppFoundStorage)
{
    HRESULT hr = S_OK;

    // Start with a quick check of all storages inside the storage.
    // If we found it, stop now and return.
    CComQIPtr<IWMDMStorage2> pStorage2(pCurrentStorage);
    hr = pStorage2->GetStorage(storageName, ppFoundStorage);
    if (*ppFoundStorage != NULL)
        return hr;

    //
    // Otherwise, enumerate through and dive into all child folders.
    //

    // First get enumerator.
    CComPtr<IWMDMEnumStorage> pEnumStorage;
    hr = pCurrentStorage->EnumStorage(&pEnumStorage);
    if (hr != S_OK && pEnumStorage != NULL)
        return hr;

    // Now enumerate all folders until found the right item, or out of folders.
    CComPtr<IWMDMStorage> pThisStorage;
    DWORD numRetrieved = 0;
    DWORD attr = 0;
    while(pEnumStorage->Next(1, &pThisStorage, &numRetrieved) == S_OK)
    {
        pThisStorage->GetAttributes(&attr, NULL);
        if (attr & WMDM_FILE_ATTR_FOLDER)
        {
            hr = myFindStorageRecursively(storageName, pThisStorage, ppFoundStorage);
            if (*ppFoundStorage != NULL)
                return hr;
        }
        pThisStorage.Release();
    }

    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice2 Interface


IWMDMDevice3 Interface (deprecated)

The IWMDMDevice3 interface extends IWMDMDevice2 by providing methods to query a device for properties, send device I/O controle codes, and also providing upgraded methods to search for storages and retrieve device format capabilities.

In addition to the methods inherited from IWMDMDevice2, the IWMDMDevice3 interface exposes the following methods.

Method | Description
DeviceIoControl | Sends a Device I/O Control (IOCTL) code to the device.
FindStorage | Finds a storage by its persistent unique identifier.
GetFormatCapability | Retrieves device support for files of a specified format.
GetProperty | Retrieves a specific device metadata property.
SetProperty | Sets a specific device property, if it is writable.

See Also

  • Interfaces for Applications
  • IWMDMDevice Interface
  • IWMDMDevice2 Interface


IWMDMDevice3::DeviceIoControl (deprecated)

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(
  DWORD  dwIoControlCode,
  BYTE*  lpInBuffer,
  DWORD  nInBufferSize,
  BYTE*  lpOutBuffer,
  LPDWORD  pnOutBufferSize
);

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, you can use the macro SIZEOF_REQUIRED_COMMAND_DATA_OUT defined in MtpExt.h to specify the size.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.
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

  • IWMDMDevice::SendOpaqueCommand
  • IWMDMDevice3 Interface


IWMDMDevice3::FindStorage (deprecated)

The FindStorage method finds a storage by its persistent unique identifier. Unlike other methods, this method can search recursively from the root storage.

Syntax

HRESULT FindStorage(
  WMDM_FIND_SCOPE  findScope,
  LPCWSTR  pwszUniqueID,
  IWMDMStorage**  ppStorage
);

Parameters

findScope

[in] A WMDM_FIND_SCOPE enumeration specifying the scope of the find operation.

pwszUniqueID

[in] A wide character, null-terminated string representing a persistent unique identifier of the storage, which can be retrieved by querying for the g_wszWMDMPersistentUniqueID property of the storage.

ppStorage

[out] Pointer to the returned storage. The caller must release this interface when done with it.

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 | The findScope parameter is invalid, or pwszUniqueID or ppStorage is NULL.
E_NOTIMPL | Legacy devices and non-MTP devices do not implement this method.
E_PROP_ID_UNSUPPORTED (0x80070490) | The storage was not found.

Remarks

A persistent unique identifier is used to uniquely identify content stored on a particular device. It does not represent a content-specific globally unique identifier that remains identical across all devices. Thus, the same content stored in different storages will have different persistent unique identifiers. Similarly, different content can have same persistent unique identifier when it is stored on different devices. Using the analogy of content on a device being similar to rows in a database, this property serves the same purpose as the identity column serves in a database.

Because it is generated by the device, the format of the persistent unique identifier is device-dependent. The application should get the persistent unique identifier by querying the g_wszWMDMPersistentUniqueID property of the storage. An application can use the GetSpecifiedMetadata or GetMetadata methods to query this property.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice3 Interface
  • IWMDMStorage3::GetMetadata
  • IWMDMStorage4::FindStorage
  • IWMDMStorage4::GetSpecifiedMetadata
  • Metadata Constants
  • WMDM_FIND_SCOPE


IWMDMDevice3::GetFormatCapability (deprecated)

The GetFormatCapability method retrieves device support for files of a specified format. The capabilities are expressed as supported properties and their allowed values.

Syntax

HRESULT GetFormatCapability(
  WMDM_FORMATCODE  format,
  WMDM_FORMAT_CAPABILITY*  pFormatSupport
);

Parameters

format

[in] Value from the WMDM_FORMATCODE enumeration representing the queried format.

pFormatSupport

[out] Pointer to the returned WMDM_FORMAT_CAPABILITY structure containing supported properties and their allowed values. These values must be released by the application as described in Getting Format Capabilities on Devices That Support IWMDMDevice3.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pFormatSupport parameter is NULL or the format is invalid.
WMDM_E_NOTSUPPORTED | The device does not support this method or the format specified.

Remarks

The client can obtain the list of supported formats by using the IWMDMDevice3::GetProperty method to query the g_wszWMDMFormatsSupported device property.

For a particular format, a client can call this function to obtain the supported properties and get information about configurations of supported properties (for example, combinations of bit rate and sample rate). This information is expressed as a format capability.

Example Code

The following function is passed a device pointer and a format code, and retrieves the device's format capabilities for that format. The function uses a custom function to clear the retrieved values. This custom function is shown in Getting Format Capabilities on Devices That Support IWMDMDevice3.

// Each format configuration is described by an WMDM_FORMAT_CAPABILITY enum, and
// has a WMDM_FORMAT_CAPABILITY structure describing the device capabilities for that format.
//        Each WMDM_FORMAT_CAPABILITY structure has a WMDM_PROP_CONFIG structure listing configurations.
//            Each WMDM_PROP_CONFIG has a WMDM_PROP_DESC describing a specific format configuration.
//                Each WMDM_PROP_DESC holds specific values as a range, a set, or a flag meaning all values are accepted.
HRESULT myGetFormatCaps(WMDM_FORMATCODE formatCode, IWMDMDevice3* pDevice)
{
    HRESULT hr = S_OK;

    // Get a list of supported configurations for the format.
    WMDM_FORMAT_CAPABILITY formatCapList;
    hr = pDevice->GetFormatCapability(formatCode, &formatCapList);
    HANDLE_HR(hr, "Got a WMDM_FORMATCODE structure in GetCaps","Couldn't get a WMDM_FORMATCODE structure in GetCaps");

    // Print out the format name.
    // TODO: Display a banner for device formats.
    PrintWMDM_FORMATCODE(formatCode); // Custom function to print out the format code.

    // Loop through the configurations and examine each one.
    for(UINT iConfig = 0; iConfig < formatCapList.nPropConfig; iConfig++)
    {
        WMDM_PROP_CONFIG formatConfig = formatCapList.pConfigs[iConfig];

        // Preference level for this configuration (lower number means more preferred).
        // TODO: Display a banner for the preference-level output.

        // Loop through all properties for this configuration and get supported
        // values for the property. Values can be a single value, a range,
        // or a list of enumerated values.
        for(UINT iDesc = 0; iDesc < formatConfig.nPropDesc; iDesc++)
        {
            WMDM_PROP_DESC propDesc = formatConfig.pPropDesc[iDesc];
            // TODO: Display the property name.

            // Three ways a value can be represented: any, a range, or a list.
            switch (propDesc.ValidValuesForm)
            {
                case WMDM_ENUM_PROP_VALID_VALUES_ANY:
                    // TODO: Display a message indicating that all values are valid.
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
                    {
                        // List these in the docs as the propvariants set.
                        WMDM_PROP_VALUES_RANGE rng = propDesc.ValidValues.ValidValuesRange;
                        // TODO: Display a banner for the values to follow
                        // TODO: Display the max value.
                        // TODO: Display the min value.
                        // TODO: Display the step value.
                    }
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
                    {
                        // TODO: Display a banner for the values to follow.
                        WMDM_PROP_VALUES_ENUM list = propDesc.ValidValues.EnumeratedValidValues;
                        PROPVARIANT pVal;
                        for(UINT iValue = 0; iValue < list.cEnumValues; iValue++)
                        {
                            pVal = list.pValues[iValue];
                            // TODO: Display the current value.
                            PropVariantClear(&pVal);
                            PropVariantInit(&pVal);
                        }
                    }

                    break;
                default:
                    HANDLE_HR(E_FAIL, "Undefined configuration type in GetCaps" << endl, "");
                    break;
            }
        }
    }
    // Now clear the memory used by WMDM_FORMAT_CAPABILITY.
    FreeFormatCapability(formatCapList);

e_Exit:
    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Discovering Device Format Capabilities
  • IWMDMDevice3 Interface


IWMDMDevice3::GetProperty (deprecated)

The GetProperty method retrieves a specific device metadata property.

Syntax

HRESULT GetProperty(
  LPCWSTR  pwszPropName,
  PROPVARIANT*  pValue
);

Parameters

pwszPropName

[in] A wide character, null-terminated string name of the property to retrieve. A list of standard property name constants is given in Metadata Constants.

pValue

[out] Returned value for the property. The application must free this memory using PropVariantClear.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | One or both parameters are NULL.
WMDM_E_NOTSUPPORTED | The property is not supported by the device or the device returned an error.

Remarks

To obtain the list of supported device properties, the client call this function and specify g_wszWMDMSupportedDeviceProperties. For the list of standard device property names, see Metadata Constants.

The client should pass in a pointer to an empty PROPVARIANT in the pValue parameter. On return, pValue will contain the value of the property.

This method is similar to the GetMetadata and GetSpecifiedMetadata methods for storages, but this method can get only one property at a time.

Sample Code

The following C++ code queries for the g_wszWMDMFormatsSupported property, which returns a SAFEARRAY list of formats supported by a device.

// Query a device for supported configurations for each media or format type.
HRESULT GetCaps(IWMDMDevice3* pDevice)
{
    HRESULT hr = S_OK;

    // Request the "formats supported" property to get a list of supported formats.
    PROPVARIANT pvFormatsSupported;
    PropVariantInit(&pvFormatsSupported);
    hr = pDevice->GetProperty(g_wszWMDMFormatsSupported, &pvFormatsSupported);
    HANDLE_HR(hr, "Got a property list in GetCaps", "Couldn't get a property list in GetCaps.");

    // Loop through the retrieved format list.
    // For each format, get a list of format configurations.
    SAFEARRAY* formatList = pvFormatsSupported.parray;
    WMDM_FORMATCODE formatCode = WMDM_FORMATCODE_NOTUSED;
    for(LONG iCap = 0; iCap < formatList->rgsabound[0].cElements; iCap++)
    {
        // Get a format from the SAFEARRAY of retrieved formats.
        SafeArrayGetElement(formatList, &iCap, &formatCode);

        // Call a custom function to see the specifics of device support for
       // each format.
        if (formatCode != WMDM_FORMATCODE_NOTUSED)
            myGetFormatCaps(formatCode, pDevice);
    }

e_Exit:
    // Clear out the memory we used.
    PropVariantClear(&pvFormatsSupported);
    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • Setting Metadata on a File
  • IWMDMDevice3::SetProperty
  • IWMDMStorage3::GetMetadata
  • IWMDMStorage4::GetSpecifiedMetadata
  • IWMDMDevice3 Interface


IWMDMDevice3::SetProperty (deprecated)

The SetProperty method sets a specific device property, if it is writable.

Syntax

HRESULT SetProperty(
  LPCWSTR  pwszPropName,
  PROPVARIANT*  pValue
);

Parameters

pwszPropName

[in] A wide character, null-terminated string name of the property to set. This overwrites any existing property with the same name. Once the application has made this call, it should free any dynamic memory using PropVariantClear. A list of standard property name constants is given in Metadata Constants.

pValue

[in] Value of the property being set.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | One or both parameters are NULL.
WMDM_E_NOTSUPPORTED | The property is not supported by the device, or this property is not settable, or the device returned an error.

Remarks

This method sets the specified device property. To obtain the list of supported device properties, the client should query the IWMDMDevice3::GetProperty method for the g_wszWMDMSupportedDeviceProperties property.

For the list of device property names, see Metadata Constants.

This method is similar to the SetMetadata method for storages, but this method can set only one property at one time.

Not all properties of the device can be set.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IWMDMDevice3 Interface
  • IWMDMDevice3::GetProperty
  • IWMDMStorage3::SetMetadata
  • IWMDMStorage4::GetSpecifiedMetadata
  • Setting Metadata on a File


IWMDMDeviceControl Interface (deprecated)

The IWMDMDeviceControl interface provides methods for controlling playback on a device. Query an IWMDMDevice interface to get this interface. Playback parameters are controlled by the IWMDMObjectInfo interface.

The IWMDMDeviceControl interface methods support several modes of audio control, depending on the context in which they are used. That context is defined by the IWMDMDeviceControl::Seek method. The IWMDMDeviceControl::GetCapabilities method is used to determine what kinds of operations can be performed by the device.

In addition to the methods inherited from IUnknown, the IWMDMDeviceControl interface exposes the following methods.

Method | Description
GetCapabilities | Retrieves the device capabilities to determine what operations the device can perform.
GetStatus | Retrieves the control status of the device.
Pause | Pauses the current play or record operation.
Play | Begins playing at the current seek position.
Record | Begins recording from the device's external record input at the current seek position.
Resume | Resumes the current play or record operation from the file position saved during the call to Pause.
Seek | Seeks to a position that is used as the starting point by the Play or Record methods.
Stop | Stops the current record or play operation.

See Also

  • Interfaces for Applications


IWMDMDeviceControl::GetCapabilities (deprecated)

The GetCapabilities method retrieves the device capabilities to determine what operations the device can perform. The capabilities describe the methods of the device control that are supported by the media device.

Syntax

HRESULT GetCapabilities(
  DWORD*  pdwCapabilitiesMask
);

Parameters

pdwCapabilitiesMask

[out] Pointer to a DWORD specifying the capabilities of the device. The following flags can be returned in this variable.

Flag | Description
WMDM_DEVICECAP_CANPLAY | The media device can play MP3 audio.
WMDM_DEVICECAP_CANSTREAMPLAY | The media device can play streaming audio directly from the host computer.
WMDM_DEVICECAP_CANRECORD | The media device can record audio.
WMDM_DEVICECAP_CANSTREAMRECORD | The media device can record streaming audio directly to the host computer.
WMDM_DEVICECAP_CANPAUSE | The media device can pause during play or record operations.
WMDM_DEVICECAP_CANRESUME | The media device can resume an operation that was paused.
WMDM_DEVICECAP_CANSTOP | The media device can stop playing before the end of a file.
WMDM_DEVICECAP_CANSEEK | The media device can seek to a position other than the beginning of a file.
WMDM_DEVICECAP_HASSECURECLOCK | The media device has a secure clock.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwCapabilitiesMask parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Currently, not many devices report their capabilities correctly.

Example Code

The following C++ code retrieves the device capabilities.

// Examine the device capabilities.
// Use some of these to enable or disable the application's
// user interface elements.
CComQIPtr<IWMDMDeviceControl> pDeviceControl(pIWMDMDevice);
if (pDeviceControl != NULL)
{
    DWORD caps = 0;
    hr = pDeviceControl->GetCapabilities(&caps);
    if (caps & WMDM_DEVICECAP_CANPLAY)
    {
        // TODO: Display a message indicating that the media device can play MP3 audio.
    }
    if (caps & WMDM_DEVICECAP_CANSTREAMPLAY)
    {
        // TODO: Display a message that the device can play audio directly from the host computer.
    }
    if (caps & WMDM_DEVICECAP_CANRECORD)
    {
        // TODO: Display a message that the device can record audio.
    }
    if (caps & WMDM_DEVICECAP_CANSTREAMRECORD)
    {
        // TODO: Display a message that the media device can record
        // streaming audio directly to the host computer.
    }
    if (caps & WMDM_DEVICECAP_CANPAUSE)
    {
        // TODO: Display a message that the device can pause during play or record operations.
    }
    if (caps & WMDM_DEVICECAP_CANRESUME)
    {
        // TODO: Display a message that the device can resume an operation that was paused.
    }
    if (caps & WMDM_DEVICECAP_CANSTOP)
    {
        // TODO: Display a message that the device can stop playing before the end of a file.
    }
    if (caps & WMDM_DEVICECAP_CANSEEK)
    {
        // TODO: Display a message that the device can seek to a position
        // other than the beginning of the file.
    }
    if (caps & WMDM_DEVICECAP_HASSECURECLOCK)
    {
        // TODO: Display a message indicating that the device has a secure clock.
    }
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface
  • IWMDMObjectInfo Interface


IWMDMDeviceControl::GetStatus (deprecated)

The GetStatus method retrieves the control status of the device.

Syntax

HRESULT GetStatus(
  DWORD*  pdwStatus
);

Parameters

pdwStatus

[out] Pointer to a DWORD that specifies the control status of the device. The control status value specifies one or more of the following flags.

Flag | Description
WMDM_STATUS_READY | Windows Media Device Manager and its subcomponents are in a ready state.
WMDM_STATUS_BUSY | An operation is currently being performed. Evaluate the other status values to determine which operation it is.
WMDM_STATUS_DEVICECONTROL_PLAYING | The device is currently playing.
WMDM_STATUS_DEVICECONTROL_RECORDING | The device is currently recording.
WMDM_STATUS_DEVICECONTROL_PAUSED | The device is currently paused.
WMDM_STATUS_DEVICECONTROL_REMOTE | The play or record operation of the device is being remotely controlled by the application.
WMDM_STATUS_DEVICECONTROL_STREAM | The play or record method is streaming data to or from the media device.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwStatus parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This call returns status values specific to the device control operations of this interface. The control status can provide information about the state of control-related activities of the device, such as playing, recording, and so on. However, it cannot provide information about the global status of the device, such as whether the device is downloading data or being accessed for some other reason. If the device is busy for any reason other than device control, you receive a busy code and must call the IWMDMDeviceControl::GetStatus method for more detailed information.

You must not attempt to call the Play, Record, Pause, Resume, or Stop methods of this interface if the status value WMDM_STATUS_BUSY is returned and the status value does not contain any other values from the table of status values.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface
  • IWMDMObjectInfo Interface


IWMDMDeviceControl::Pause (deprecated)

The Pause method pauses the current play or record session at the current position within the content.

Syntax

HRESULT Pause();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The device is already paused.
WMDM_E_NOTSUPPORTED | The pause function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

The current playback or record session is paused and the current file position is saved. A subsequent call to the Resume method restarts the play or record operation at the saved file position.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface
  • IWMDMObjectInfo Interface


IWMDMDeviceControl::Play (deprecated)

The Play method begins playing at the current seek position. If the IWMDMDeviceControl::Seek method has not been called, then playing begins at the beginning of the first file, and the play length is not defined.

Syntax

HRESULT Play();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The device is busy.
WMDM_E_NOTSUPPORTED | The play function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

This method is used to invoke both device playback (playing an audio track on a storage medium of the media device) and streaming audio playback (streaming audio data from the user's computer to the media device, where it is played). The Seek method determines the form of playback that occurs.

Some devices do not support either device playback or streaming audio playback. Before attempting to start playback of a particular type, the GetCapabilities method must be called. If unsupported playback is attempted, this method returns WMDM_E_NOTSUPPORTED.

To determine before invoking the play operation whether an audio format can be played by the media device, you can call the GetFormatSupport method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice::GetFormatSupport
  • IWMDMDeviceControl Interface
  • IWMDMDeviceControl::GetCapabilities
  • IWMDMDeviceControl::Seek
  • IWMDMObjectInfo Interface


IWMDMDeviceControl::Record (deprecated)

The Record method begins recording from the device's external record input at the current seek position. The IWMDMDeviceControl::Seek method must be called first.

Syntax

HRESULT Record(
  _WAVEFORMATEX*  pFormat
);

Parameters

pFormat

[in] Pointer to a _WAVEFORMATEX structure specifying the format in which the data must be recorded.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The device is already performing an operation.
WMDM_E_NOTSUPPORTED | The record function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

This method is used to invoke both device recording (recording of an audio track to be stored on the media device) and streaming audio data from the media device to be recorded on the computer. The Seek method determines which form of recording occurs.

Some devices do not support either type of recording. The GetCapabilities method must be called before you start recording. If an unsupported type of recording is attempted, this method returns WMDM_E_NOTSUPPORTED.

An argument can be supplied for the pFormat parameter to specify an audio format for recording. To determine the formats supported by the device, see GetFormatSupport. If the pFormat parameter is set to NULL, the device records audio data in the default format.

When you use device recording, you must enumerate the storage medium contents to find the new object after the record operation is finished.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • IWMDMDevice::GetFormatSupport
  • IWMDMDeviceControl Interface
  • IWMDMDeviceControl::GetCapabilities
  • IWMDMDeviceControl::Seek
  • IWMDMObjectInfo Interface


IWMDMDeviceControl::Resume (deprecated)

The Resume method resumes the current play or record operation from the file position saved during the call to Pause.

Syntax

HRESULT Resume();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The device is not paused.
WMDM_E_NOTSUPPORTED | The resume function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface
  • IWMDMDeviceControl::Pause
  • IWMDMObjectInfo Interface


IWMDMDeviceControl::Seek (deprecated)

The Seek method seeks to a position that is used as the starting point by the Play or Record methods.

Syntax

HRESULT Seek(
  UINT  fuMode,
  int  nOffset
);

Parameters

fuMode

[in] Mode for the seek operation being performed. The fuMode parameter must be one of the following modes.

Mode | Description
WMDM_SEEK_BEGIN | Seek to a position that is nOffset units after the beginning of the file.
WMDM_SEEK_CURRENT | Seek to a position that is nOffset units from the current position.
WMDM_SEEK_END | Seek to a position that is nOffset units before the end of the file.
WMDM_SEEK_REMOTECONTROL | Seek the removable control.
WMDM_SEEK_STREAMINGAUDIO | Seek the streaming audio.

nOffset

[in] Number of units by which the seek operation moves the starting position away from the origin specified by fuMode. The units of nOffset are defined by the content. They can be milliseconds for music, pages for electronic books, and so on.

A positive value for nOffset indicates seeking forward through the file. A negative value indicates seeking backward through the file. Any combination of nOffset and fuMode that indicates seeking to a position before the beginning of the file or after the end of the file is not valid, and causes the method to return E_INVALIDARG.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | One or more parameters are invalid.
WMDM_E_NOTSUPPORTED | Seek is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

The seek position is defined by passing either an IWMDMStorage interface pointing to a location on a storage medium of the device, or an IWMDMOperation interface that has been implemented to support streaming audio. The IWMDMObjectInfo interface can also be passed to describe some point within the object to which the specified interface points.

For device playback, if Seek is not called before Play, then playback starts at the first audio track on the first storage medium on the media device.

For device recording, if Seek is not called before Record, the record operation fails. The recording length can be limited by calling the IWMDMObjectInfo::SetPlayLength method after returning from the Seek call.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface
  • IWMDMObjectInfo Interface
  • IWMDMOperation Interface
  • IWMDMStorage Interface


IWMDMDeviceControl::Stop (deprecated)

The Stop method stops the current record or play operation.

Syntax

HRESULT Stop();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The device is busy.
WMDM_E_NOTSUPPORTED | The stop function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface
  • IWMDMObjectInfo Interface


IWMDMDeviceSession Interface (deprecated)

The IWMDMDeviceSession interface improves the efficiency of device operations by bundling multiple operations into one session. Using a single session allows Windows Media Device Manager to handle various operations, such as acquiring a device certificate, once over several operations.

In addition to the methods inherited from IUnknown, the IWMDMDeviceSession interface exposes the following methods.

Method | Description
BeginSession | Begins a device session.
EndSession | Ends a device session.

See Also

  • Interfaces for Applications


IWMDMDeviceSession::BeginSession (deprecated)

The BeginSession method begins a device session.

Syntax

HRESULT BeginSession(
  WMDM_SESSION_TYPE  type,
  BYTE*  pCtx,
  DWORD  dwSizeCtx
);

Parameters

type

[in] A WMDM_SESSION_TYPE describing the type of session to begin. This is a bitwise OR of any values except WMDM_SESSION_NONE. The same type (or combination of types) must be specified during EndSession.

pCtx

[in] Optional pointer to a caller-allocated session context buffer for private communication between the application and the service provider. Applications having knowledge of the underlying service provider can use this buffer to pass context-specific data to it. Windows Media Device Manager does not do anything with this context. The caller is responsible for freeing this buffer.

dwSizeCtx

[in] Size of the context buffer, in bytes. If the size is 0, pCtx is ignored. If the size is non-zero, pCtx must be a valid pointer.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | Attempted to begin an invalid session type. For example, WMDM_SESSION_NONE is not a valid session type, and a session is not valid if pCtx is NULL when dwSizeCtx is non-zero.
WMDM_E_TOO_MANY_SESSIONS | Attempted to begin a new session before the previous session was ended. Only one open session is allowed per device.

Remarks

Bundling several operations into a session does not cause all actions to be postponed and performed in a group; all actions (such as a call to Insert) will still be performed synchronously as called. Rather, using a session allows Windows Media Device Manager components (such as the secure content provider and service provider) to perform some of the operations only once per session, which provides performance improvements. For example, during file transfer to a device, the secure content provider can acquire the device certificate once at the beginning of the session instead of once for every file transfer.

Applications can call BeginSession on a Windows Media Device Manager device object before doing a set of operations and EndSession when they are done.

The application typically calls BeginSession during multiple file transfers or deletions. In response to that, Windows Media Device Manager calls BeginSession or EndSession on the secure content provider and the service provider. In response, the secure content provider and the service provider can perform once-per-session operations. If opening the session fails on any of these components, Windows Media Device Manager returns a failure returned by the component.

Sessions are implemented on a per-device basis. Sessions on different devices do not interfere with each other.

The following restrictions apply to sessions:

  1. Only one session can be active at a time for a particular device. Attempting to open more than one session on a device will result in an error.
  2. Session types can be combined. The same set of flags must be specified during BeginSession and EndSession. Therefore, it is not possible to end only part of the session.

    For example, if BeginSession is called with

    WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

    Then EndSession should also be called with

    WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

    Otherwise Windows Media Device Manager will return E_INVALIDARG.

  3. Windows Media Device Manager sessions are simply a bracketing mechanism for optimizations and do not have any implications regarding locking or ownership of the device. Service provider or the lower level device driver will still need to synchronize device access that may result from different Windows Media Device Manager applications.

Example Code

The following C++ code demonstrates using a session to bundle an Insert3 call on a device. The code loops through a number of files stored in a vector and sends them to the device.

// Get the session interface.
CComQIPtr<IWMDMDeviceSession> pSession(pDevice);
if (pDevice == NULL)
{
    // TODO: Display a message that the application couldn't get an
    // IWMDMDeviceSession interface.
    return E_NOINTERFACE;
}

// Start the session. We don't use a custom buffer.
hr = pSession->BeginSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
if (hr != S_OK)
{
    // TODO: Display a message indicating that the session failed to start.
    return hr;
}
else
{
    // TODO: Display a message that the session started.
}

// Insert files. These calls happen synchronously.
UINT flags = WMDM_MODE_BLOCK | WMDM_STORAGECONTROL_INSERTINTO | WMDM_FILE_CREATE_OVERWRITE | WMDM_CONTENT_FILE;
CComPtr<IWMDMStorage> pNewStorage;
for(int i = 0; i < sourceFiles.size(); i++)
{
    hr = pStorageControl3->Insert3(
        flags,
        WMDM_FILE_ATTR_FOLDER,
        sourceFiles[i],
        NULL, // Use default name.
        NULL, // Don't specify IWMDMOperation.
        NULL, // Don't specify IWMDMProgress.
        NULL, // Don't specify metadata.
        NULL, // Nothing to send to the SCP.
        &pNewStorage);

    if (pNewStorage != NULL)
        pNewStorage.Release();
    CHECK_HR(hr, "Sent file " << sourceFiles[i] << " to the device.", "Couldn't send file " << sourceFiles[i] << " to the device");
}

// Close the session.
hr = pSession->EndSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
CHECK_HR(hr,"Closed the session.","Couldn't close the session.");

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceSession Interface
  • IWMDMDeviceSession::EndSession
  • WMDM_SESSION_TYPE


IWMDMDeviceSession::EndSession (deprecated)

The EndSession method ends a device session.

Syntax

HRESULT EndSession(
  WMDM_SESSION_TYPE  type,
  BYTE*  pCtx,
  DWORD  dwSizeCtx
);

Parameters

type

[in] A WMDM_SESSION_TYPE describing the type of session to end. This must be the same bitwise OR of the values specified in BeginSession.

pCtx

[in] Optional pointer to a caller-allocated session context buffer for private communication between the application and the service provider. Applications having knowledge of the underlying service provider can use this buffer to pass context-specific data to it. Windows Media Device Manager does not do anything with this context. The caller is responsible for freeing this buffer.

dwSizeCtx

[in] Size of the context buffer, in bytes. If the size is 0, pCtx is ignored. If the size is non-zero, pCtx must be a valid pointer

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.

Return code | Description
S_OK | The method succeeded
E_INVALIDARG | The session type to end does not match the current session type.
WMDM_E_CALL_OUT_OF_SEQUENCE | Attempted to call EndSession before BeginSession.

Remarks

A session brackets a group of operations to a device, allowing Windows Media Device Manager components to optimize performance by performing common setup and shutdown functions only once, rather than with each individual transfer. For details see BeginSession.

In response to an EndSession call, Windows Media Device Manager calls EndSession on the secure content provider and the service provider. If either of them fails the call, Windows Media Device Manager returns an error. In that case, it is possible that EndSession succeeded for one of the components.

Example Code

The following C++ code demonstrates using a session to bundle an Insert3 call on a device. The code loops through a number of files stored in a vector and sends them to the device.

// Get the session interface.
CComQIPtr<IWMDMDeviceSession> pSession(pDevice);
if (pDevice == NULL)
{
    // TODO: Display a message that the app wasn't able to retrieve the IWMDMDeviceSession interface.
    return E_NOINTERFACE;
}

// Start the session. We don't use a custom buffer.
hr = pSession->BeginSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
if (hr != S_OK)
{
    / /TODO: Display a message indicating that the session failed to start.
    return hr;
}
else
{
    // TODO: Display a message indicating that the session started.
}

// Insert files. These calls happen synchronously.
UINT flags = WMDM_MODE_BLOCK | WMDM_STORAGECONTROL_INSERTINTO | WMDM_FILE_CREATE_OVERWRITE | WMDM_CONTENT_FILE;
CComPtr<IWMDMStorage> pNewStorage;
for(int i = 0; i < sourceFiles.size(); i++)
{
    hr = pStorageControl3->Insert3(
        flags,
        WMDM_FILE_ATTR_FOLDER,
        sourceFiles[i],
        NULL, // Use default name.
        NULL, // Don't specify IWMDMOperation
        NULL, // Don't specify IWMDMProgress
        NULL, // Don't specify metadata
        NULL, // Nothing to send to the SCP.
        &pNewStorage);

    if (pNewStorage != NULL)
        pNewStorage.Release();
    CHECK_HR(hr, "Sent file " << sourceFiles[i] << " to the device.", "Couldn't send file " << sourceFiles[i] << " to the device");
}

// Close the session.
hr = pSession->EndSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
CHECK_HR(hr,"Closed the session.","Couldn't close the session.");

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceSession Interface
  • IWMDMDeviceSession::BeginSession
  • WMDM_SESSION_TYPE


IWMDMEnumDevice Interface (deprecated)

The IWMDMEnumDevice interface enumerates portable devices attached to a computer. To obtain this interface, call IWMDeviceManager::EnumDevices.

In addition to the methods inherited from IUnknown, the IWMDMEnumDevice interface exposes the following methods.

Method | Description
Clone | Returns a copy of the IWMDMEnumDevice interface.
Next | Returns a pointer to the next device.
Reset | Resets the enumeration so that Next returns a pointer to the first device.
Skip | Skips over a specified number of devices in the enumeration sequence.

See Also

  • Enumerating Devices
  • Interfaces for Applications


IWMDMEnumDevice::Clone (deprecated)

The Clone method returns a copy of the IWMDMEnumDevice interface. The new enumerator specifies the same enumeration state as the current enumerator.

Syntax

HRESULT Clone(
  IWMDMEnumDevice**  ppEnumDevice
);

Parameters

ppEnumDevice

[out] Address of a pointer to an IWMDMEnumDevice interface. The caller must release this interface when done with it.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumDevice parameter is an invalid or NULL pointer.
E_OUTOFMEMORY | There is not enough memory to replicate the original interface.

Remarks

Using this method, a client can record a particular point in the enumeration sequence and return to that point later. The new enumerator supports the same interface as the original one.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumDevice Interface


IWMDMEnumDevice::Next (deprecated)

The Next method returns a pointer to the next device, represented by an IWMDMDevice interface.

Syntax

HRESULT Next(
  ULONG  celt,
  IWMDMDevice**  ppDevice,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of devices requested.

ppDevice

[out] Pointer to caller-allocated array of IWMDMDevice interface pointers. The size of this array must be IWMDMDevice*[celt]. The caller must release these interfaces when done with them. To avoid allocating a whole array, simply pass in the address of a pointer to an IWMDMDevice interface, as shown in Remarks.

pceltFetched

[out] Pointer to a variable that receives the number of devices (interfaces) returned.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | Fewer than celt devices were retrieved.
E_FAIL | An unspecified error occurred.

Remarks

The returned device interface(s) are based on a cached list of devices. If a Plug and Play device is attached or removed, the current enumerator will not reflect that, and therefore, Next will return devices based on the cached list. Applications should obtain a new enumerator object by calling IWMDeviceManager::EnumDevices to get a refreshed list of devices.

If you only want to retrieve a single interface at a time, you do not need to allocate an array for this method, as shown in the following code:

// Get a device enumerator to examine each device.
CComPtr<IWMDeviceManager2> pIWMDevMgr2;
hr = m_IWMDeviceMgr->QueryInterface (__uuidof(IWMDeviceManager2), (void**) &pIWMDevMgr2);
if (hr == S_OK)
{
    // TODO: Display a message that the application retrieved IWMDeviceManager2.
}
else
{
    // TODO: Display a message that the application was not able to
    // retrieve IWMDeviceManager2 in EnumDevices.
    return hr;
}

// Enumerate through the devices using the faster EnumDevices2 plug-and-play method.
CComPtr<IWMDMEnumDevice> pEnumDevice;
hr = pIWMDevMgr2->EnumDevices2(&pEnumDevice);
if (hr != S_OK)
{
    //.TODO: Display a message that an error occurred in calling EnumDevices2.
    return hr;
}

// Enumerate through devices.
IWMDMDevice *pIWMDMDevice;
ULONG ulFetched = 0;
while(pEnumDevice->Next(1, &pIWMDMDevice, &ulFetched) == S_OK)
{
    if (ulFetched != 1)
    {
        return E_FAIL;
    }
    // Do some stuff here....
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IWMDeviceManager::EnumDevices
  • IWMDMEnumDevice Interface


IWMDMEnumDevice::Reset (deprecated)

The Reset method resets the enumeration so that Next returns a pointer to the first device.

Syntax

HRESULT Reset();

Parameters

This method takes no parameters.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumDevice Interface


IWMDMEnumDevice::Skip (deprecated)

The Skip method skips over a specified number of devices in the enumeration sequence.

Syntax

HRESULT Skip(
  ULONG  celt,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of devices to skip.

pceltFetched

[out] Number of devices actually skipped.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The number of elements specified was not skipped.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

If the requested number of devices to skip is greater than the remaining devices, the return value from Skip is S_FALSE. At this point, pceltFetched must be used to determine the number of interfaces skipped. If you skip to the end of the device array, a subsequent call to Next also returns S_FALSE. For more information about the standard enumerator Skip method, see the Microsoft COM documentation, available at the Microsoft Web site.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumDevice Interface


IWMDMEnumStorage Interface (deprecated)

The IWMDMEnumStorage interface enumerates storages on a device. Obtain this interface the first time by calling IWMDMDevice::EnumStorage on a device, and afterward by calling IWMDMStorage::EnumStorage. This interface only enumerates the immediate children of the parent storage that was used to obtain this interface. (If IWMDMDevice::EnumStorage was used, the parent storage is the device's root storage.)

In addition to the methods inherited from IUnknown, the IWMDMEnumStorage interface exposes the following methods.

Method | Description
Clone | Creates another enumerator with the same enumeration state as the current enumerator.
Next | Retrieves a pointer to the next sibling storage
Reset | Sets the enumeration sequence back to the beginning.
Skip | Skips over the specified number of storage devices or separate items of content in the enumeration sequence.

See Also

  • Exploring a Device
  • Interfaces for Applications
  • IWMDMStorage::EnumStorage


IWMDMEnumStorage::Clone (deprecated)

The Clone method creates another enumerator with the same enumeration state as the current enumerator.

Syntax

HRESULT Clone(
  IWMDMEnumStorage**  ppEnumStorage
);

Parameters

ppEnumStorage

[out] An IWMDMEnumStorage interface of the cloned enumerator. The caller must release this interface when done with it.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The parameter is invalid.
E_OUTOFMEMORY | There is not enough memory to replicate this interface.

Remarks

Using this function, a client can record a particular point in the enumeration sequence and return to that point later. The new enumerator supports the same interface as the original enumerator.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumStorage Interface


IWMDMEnumStorage::Next (deprecated)

The Next method retrieves a pointer to the next sibling storage.

Syntax

HRESULT Next(
  ULONG  celt,
  IWMDMStorage**  ppStorage,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of storages requested.

ppStorage

[out] Pointer to caller-allocated array of IWMDMStorage interface pointers. The size of this array must be IWMDMStorage*[celt]. The caller must release these interfaces when done with them. To avoid allocating a whole array, simply pass in the address of a pointer to an IWMDMStorage interface, as shown in Remarks.

pceltFetched

[out] Number of storages enumerated.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | Fewer than celt devices were retrieved.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Windows Media Device Manager delegates the storage enumeration to the corresponding service provider. For information on service provider storage enumeration, see the IMDSPEnumStorage interface.

The storage enumerator may not reflect the effect of media insertion and removal. In that case, the application should obtain a new storage enumerator object by calling IWMDMDevice::EnumStorage to get the refreshed list.If you only want to retrieve a single interface at a time, you do not need to allocate an array for this method, as shown in the following code.

Example Code

The following two C++ functions recursively explore a device. The first one is a kickoff functio that obtains the IWMDMEnumStorage interface of the root device storage. It passes this to the recursive function which examines all the nested functions.

// Kickoff function to explore a device.
void ExploreDevice(IWMDMDevice* pDevice)
{
    HRESULT hr = S_OK;

    // Get a root enumerator.
    CComPtr<IWMDMEnumStorage> pEnumStorage;
    hr = pDevice->EnumStorage(&pEnumStorage);
    RecursiveExploreStorage(pEnumStorage);

    HANDLE_HR(hr, "Got a root storage in ExploreDevice.","Couldn't get a root storage in ExploreDevice.");

e_Exit:
    return;
}

void RecursiveExploreStorage(IWMDMEnumStorage* pEnumStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage> pStorage;
    ULONG numRetrieved = 0;
    // Loop through all storages in the current storage.
    // We don't need to allocate an array to retrieve one
    // interface at a time.
    while(pEnumStorage->Next(1, &pStorage, &numRetrieved) == S_OK && numRetrieved == 1)
    {
        // Get the name of the object. The first time this is called on a
        // device, it will retrieve '\' as the root folder name.
        const UINT MAX_LEN = 255;
        WCHAR name[MAX_LEN];
        hr = pStorage->GetName((LPWSTR)&name, MAX_LEN);
        // TODO: Display the storage name.

        // Get metadata for the storage.
        if (SUCCEEDED(hr))
            GetMetadata(pStorage);

        // Find out something about the item.
        DWORD attributes = 0;
        _WAVEFORMATEX audioFormat;
        hr = pStorage->GetAttributes(&attributes, &audioFormat);
        HANDLE_HR(hr, "Got storage attributes in RecursivelyExploreStorage.","Couldn't get storage attributes in RecursivelyExploreStorage.");

        // If this is a folder, recurse into it.
        if (attributes & WMDM_FILE_ATTR_FILE)
            // TODO: Display a message indicating that this is a file.
        if (attributes & WMDM_FILE_ATTR_FOLDER)
        {
            // TODO: Display a message indicating that this is a folder.
            CComPtr<IWMDMEnumStorage> pEnumSubStorage;
            hr = pStorage->EnumStorage(&pEnumSubStorage);
            RecursiveExploreStorage(pEnumSubStorage);
        }

        // Some other useful attributes to check include:
        // WMDM_FILE_ATTR_CANDELETE and WMDM_FILE_ATTR_CANPLAY and others to determine what can be done with a storage.
        // WMDM_FILE_ATTR_HIDDEN and other attributes to determine display characteristics,
        // WMDM_STORAGE_IS_DEFAULT to see if this is the default save location for new files.
        pStorage.Release();
    } // Get the next storage pointer.

e_Exit:
    return;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Exploring a Device
  • IWMDMDevice::EnumStorage
  • IWMDMEnumStorage Interface


IWMDMEnumStorage::Reset (deprecated)

The Reset method sets the enumeration sequence back to the beginning.

Syntax

HRESULT Reset();

Parameters

This method takes no parameters.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumStorage Interface


IWMDMEnumStorage::Skip (deprecated)

The Skip method skips over the specified number of storages in the enumeration sequence.

Syntax

HRESULT Skip(
  ULONG  celt,
  ULONG*  pceltFetched
);

Parameters

celt

[in] The number of storages to skip.

pceltFetched

[out] The number of storages skipped.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The number of elements specified was not skipped.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

If the number of devices specified in celt is greater than the actual number of storage interfaces remaining in the enumeration sequence, this function will return S_FALSE. When this happens, pceltFetched must be queried to determine how many interfaces were actually skipped. If you skip to the end of the array of storage interfaces, a subsequent call to Next returns S_FALSE.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumStorage Interface


IWMDMMetaData Interface (deprecated)

The IWMDMMetaData interface sets and retrieves metadata properties (such as artist, album, genre, and so on) of a storage. Metadata properties are stored as name-value pairs.

To create a new, empty instance of this interface, call IWMDMStorage3::CreateEmptyMetadataObject. To retrieve this interface (with values), call IWMDMStorage3::GetMetadata or IWMDMStorage4::GetSpecifiedMetadata.

In addition to the methods inherited from IUnknown, the IWMDMMetaData interface exposes the following methods.

Method | Description
AddItem | Adds a metadata property to the interface.
GetItemCount | Retrieves the total number of properties held by the interface.
QueryByIndex | Retrieves the value of a property specified by index.
QueryByName | Retrieves the value of a property specified by name.

See Also

  • Interfaces for Applications
  • Metadata Constants
  • Setting Metadata on a File


IWMDMMetaData::AddItem (deprecated)

The AddItem method adds a metadata property to the interface.

Syntax

HRESULT AddItem(
  WMDM_TAG_DATATYPE  Type,
  LPCWSTR  pwszTagName,
  BYTE*  pValue,
  UINT  iLength
);

Parameters

Type

[in] An WMDM_TAG_DATATYPE enumerated value specifying the type of metadata being saved.

pwszTagName

[in] Pointer to a wide-character, null-terminated string specifying the name of the property to set. A list of standard property name constants is given in Metadata Constants.

pValue

[in] Pointer to a byte array specifying the value to assign to the property. The submitted value is copied, so the memory can be freed after calling AddItem.

iLength

[in] Integer specifying the size of pValue, in bytes.

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.

Value | Description
S_OK | The method succeeded.
E_OUTOFMEMORY | There is not enough memory to allocate the item.
E_INVALIDARG | One or more parameters are invalid.

Example Code

The following code adds an author metadata value to an IWMDMMetaData interface (pMetadata), and checks for returned errors with a custom macro.

WCHAR* author = L"Gudmundur Axel Hansen";
UINT numBytes = (wcslen(author) + 1) * sizeof(WCHAR); // WCHAR string is length + 1 for termination character.
hr = pMetadata->AddItem(WMDM_TYPE_STRING, g_wszWMDMAuthor, (BYTE*)author, numBytes) ;
BREAK_HR(hr,"Created an IWMDMMetaData interface in mySendFile.","Couldn't create an IWMDMMetaData interface in mySendFile.");

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • Metadata Constants
  • Setting Metadata on a File


IWMDMMetaData::GetItemCount (deprecated)

The GetItemCount method retrieves the total number of properties held by the interface.

Syntax

HRESULT GetItemCount(
  UINT*  iCount
);

Parameters

iCount

[out] Pointer to an integer that receives the total number of metadata properties stored by the interface.

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.

Value | Description
S_OK | The method succeeded.
E_INVALIDARG | One or more parameters are invalid.

Remarks

This method could be used along with QueryByIndex to enumerate all properties on a storage or device.

Example Code

The following code retrieves the count of properties in an IWMDMMetaData interface (pMetadata) and tries to retrieve them all by index and print them. It uses a custom error handling macro BREAK_HR.

        //
        // Loop through all metadata properties, and print out the value of each.
        //
        BYTE* value;
        WMDM_TAG_DATATYPE type;
        UINT len = 0;
        UINT count = 0;
        WCHAR* name;
        // Get the number of metadata items.
        hr = pMetadata->GetItemCount(&count);

        BREAK_HR(hr, "Got a metadata count in GetMetadata.", "Couldn't get a metadata count in GetMetadata.");
        for(;count > 0; count--)
        {
            // Get the metadata property by index.
            WCHAR* name;
            hr = pMetadata->QueryByIndex(count-1, &name, &type, &value, &len);
            if (SUCCEEDED(hr))
            {
                // TODO: Display the property name.
                CoTaskMemFree(name);

                // Print out the value of the property, according to the value type.
                switch (type)
                {
                case WMDM_TYPE_QWORD:
                case WMDM_TYPE_DWORD:
                case WMDM_TYPE_WORD:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_STRING:
                    // TODO: Display the value.
                    // Release the method-allocated property value memory.
                    if (SUCCEEDED(hr))
                        CoTaskMemFree(value);
                    break;
                case WMDM_TYPE_BOOL:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_BINARY:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_DATE:
                    {
                        WMDMDATETIME *val = (WMDMDATETIME*)value;
                        / /TODO: Display the month, day, and year.
                    }
                    break;
                case WMDM_TYPE_GUID:
                    {
                        WCHAR strGuid[64];
                        StringFromGUID2(reinterpret_cast<GUID&>(value),(LPOLESTR)strGuid, 64);
                        / /TODO: Display the GUID.
                    }
                    break;
                default:
                    // TODO: Display a message indicating that the
                    // application could not understand the returned value type.
                }
            }
            else // Couldn't get the metadata property at index count - 1.
                // TODO: Display a message indicating that the
                // application couldn't retrieve a value for the index.
        // Clear the WMDM-allocated memory.
        if (value)
            CoTaskMemFree(value);
        }

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • Metadata Constants
  • QueryByIndex
  • Setting Metadata on a File


IWMDMMetaData::QueryByIndex (deprecated)

The QueryByIndex method retrieves the value of a property specified by index.

Syntax

HRESULT QueryByIndex(
  UINT  iIndex,
  WCHAR**  ppwszName,
  WMDM_TAG_DATATYPE*  pType,
  BYTE**  ppValue,
  UINT*  pcbLength
);

Parameters

iIndex

[in] Integer specifying the zero-based index of the property. The number of items is obtained through the GetItemCount call.

ppwszName

[out] Name of the property. Windows Media Device Manager allocates this memory, and the caller must free it using CoTaskMemFree.

pType

[out] An WMDM_TAG_DATATYPE enumerated value describing the type of data returned in ppValue.

ppValue

[out] Pointer to a pointer to a byte array that receives the content of the value if the method succeeds. This memory is allocated by Windows Media Device Manager, and the caller must free it using CoTaskMemFree.

pcbLength

[out] Pointer to the size, in bytes, of the byte array ppValue. If the value is a string, this includes the termination character.

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.

Value | Description
S_OK | The method succeeded.
E_OUTOFMEMORY | There is not enough memory to allocate the item.
E_INVALIDARG | One or more parameters are invalid.

Example Code

The following code retrieves the count of properties in an IWMDMMetaData interface (pMetadata) and tries to retrieve them all by index and print them.

        //
        // Loop through all metadata properties, and print out the value of each.
        //
        BYTE* value;
        WMDM_TAG_DATATYPE type;
        UINT len = 0;
        UINT count = 0;
        WCHAR* name;
        // Get the number of metadata items.
        hr = pMetadata->GetItemCount(&count);

        BREAK_HR(hr, "Got a metadata count in GetMetadata.", "Couldn't get a metadata count in GetMetadata.");
        for(;count > 0; count--)
        {
            // Get the metadata property by index.
            WCHAR* name;
            hr = pMetadata->QueryByIndex(count-1, &name, &type, &value, &len);
            if (SUCCEEDED(hr))
            {
                // TODO: Display the property name.
                CoTaskMemFree(name);

                // Print out the value of the property, according to the value type.
                switch (type)
                {
                case WMDM_TYPE_QWORD:
                case WMDM_TYPE_DWORD:
                case WMDM_TYPE_WORD:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_STRING:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_BOOL:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_BINARY:
                    // TODO: Display the value.
                    break;
                case WMDM_TYPE_DATE:
                    {
                        WMDMDATETIME *val = (WMDMDATETIME*)value;
                        // Display the month, day, and year.
                    }
                    break;
                case WMDM_TYPE_GUID:
                    {
                        WCHAR strGuid[64];
                        StringFromGUID2(reinterpret_cast<GUID&>(value),(LPOLESTR)strGuid, 64);
                        // TODO: Display the GUID
                    }
                    break;
                default:
                    // TODO: Display a message indicating that the app could not understand the returned value type.
                }
            }
            else // Couldn't get the metadata property at index count - 1.
                // TODO: Display a message indicating that the application couldn't get a value for index in GetMetadata
        // Clear the WMDM-allocated memory.
        if (value)
            CoTaskMemFree(value);
        }

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • GetItemCount
  • IWMDMMetaData Interface
  • QueryByName
  • Setting Metadata on a File


IWMDMMetaData::QueryByName (deprecated)

The QueryByName method retrieves the value of a property specified by name.

Syntax

HRESULT QueryByName(
  LPCWSTR  pwszTagName,
  WMDM_TAG_DATATYPE*  pType,
  BYTE**  pValue,
  UINT*  pcbLength
);

Parameters

pwszTagName

[in] Pointer to a wide-character null-terminated string specifying the property name. A list of standard property name constants is given in Metadata Constants.

pType

[out] An WMDM_TAG_DATATYPE enumerated value describing the type of data retrieved by pValue.

pValue

[out] Pointer to a pointer to a byte array that receives the content of the value if the method succeeds. Windows Media Device Manager allocates this memory and the caller must free it using CoTaskMemFree.

pcbLength

[out] Pointer to the size, in bytes, of the byte array ppValue. If the value is a string, this includes the termination character.

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.

Value | Description
S_OK | The method succeeded.
E_OUTOFMEMORY | There is not enough memory to allocate the item.
E_INVALIDARG | One or more parameters are invalid. This value is returned if the parameter specified by name is not supported by the service provider.

Example Code

The following C++ code queries for a file name and size.

HRESULT CWMDMController::myGetSpecifiedMetadata(IWMDMStorage* pStorage)
{
    HRESULT hr = S_OK;

    // Get an IWMDMStorage4 interface, which is required to specify metadata by name.
    CComPtr<IWMDMStorage4> pStorage4;
    hr = pStorage->QueryInterface(__uuidof(IWMDMStorage4), (void**)&pStorage4);
    CHECK_HR(hr, "Storage supports IWMDMStorage4 in myGetSpecifiedMetadata","Storage doesn't support IWMDMStorage4 in myGetSpecifiedMetadata");

    // Specify Add values to request. We will request the object name and size.
    LPCWSTR props[] = {g_wszWMDMFileName, g_wszWMDMFileSize};
    CComPtr<IWMDMMetaData> pMetadata;
    hr = pStorage4->GetSpecifiedMetadata(2, props, &pMetadata);
    CHECK_HR(hr, "GetSpecifiedMetadata succeeded in myGetSpecifiedMetadata","GetSpecifiedMetadata failed in myGetSpecifiedMetadata");

    // Now query for each value.
    BYTE* pVal = NULL;
    UINT len = 0;
    WMDM_TAG_DATATYPE datatype;
    hr = pMetadata->QueryByName(g_wszWMDMFileName, &datatype, &pVal, &len);
    if(FAILED(hr))
    {
        // TODO: Display a message that the item doesn't support the file name metadata value.
    }
    else
    {
        // TODO: Display the object name and the length of the string (including termination character).
        CoTaskMemFree(pVal);
        pVal = NULL;
    }

    hr = pMetadata->QueryByName(g_wszWMDMFileSize, &datatype, &pVal, &len);
    if(FAILED(hr))
    {
        // TODO: Display a message indicating that the item doesn't support the file size metadata value.
    }
    else
    {
        DWORD size = (*pVal) >> 10;
        // TODO: Display an message containing the object size in Mb
        // and the number of bytes returned.
        CoTaskMemFree(pVal);
    }

    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • Metadata Constants
  • QueryByIndex
  • Setting Metadata on a File


IWMDMNotification Interface (deprecated)

The optional, application-implemented IWMDMNotification interface allows applications and service providers to receive notifications when either devices or memory storages (such as RAM cards) are connected or disconnected from the computer.

Note This method will be called only for registered Plug and Play devices. Other device arrivals or departures will not cause this interface to be called.

This interface GUID is not properly defined in mssachlp.lib; therefore, you must #include both mswmdm.h and mswmdm_i.c (from wmdm.idl) if implementing this interface, to get the proper definitions.

In addition to the methods inherited from IUnknown, the IWMDMNotification interface exposes the following methods.

Method | Description
WMDMMessage | Called by Windows Media Device Manager when a device or storage medium is connected or removed.

See Also

  • Enabling Notifications
  • Interfaces for Applications


IWMDMNotification::WMDMMessage (deprecated)

The WMDMMessage method is a callback method implemented by a client, and called by Windows Media Device Manager when a Plug and Play compliant device or storage medium is connected or removed.

Syntax

HRESULT WMDMMessage(
  DWORD  dwMessageType,
  LPCWSTR  pwszCanonicalName
);

Parameters

dwMessageType

[in] A DWORD specifying the message type.

The possible values for the event types are the following:

Message type | Description
WMDM_MSG_DEVICE_ARRIVAL | A device has been connected.
WMDM_MSG_DEVICE_REMOVAL | A device has been removed.
WMDM_MSG_MEDIA_ARRIVAL | A storage medium has been inserted in a connected device.
WMDM_MSG_MEDIA_REMOVAL | A storage medium has been removed from a connected device.

pwszCanonicalName

[in] Pointer to a wide-character, null-terminated string specifying the canonical name of the device for which this event is generated. The application does not release this value.

Return Values

The return value is an HRESULT in which application can return results of its processing of the message. The return value is ignored by WMDM.

Remarks

To learn how an application subscribes to receive notifications through this method, see Enabling Notifications.

Example Code

The following C++ code implements the WMDMMessage method, and prints out a device or storage arrival or departure notification message.

HRESULT WMDMMessage(DWORD  dwMessageType, LPCWSTR  pwszCanonicalName)
{
    switch(dwMessageType)
    {
    case WMDM_MSG_DEVICE_ARRIVAL:
        // TODO: Display a message indicating that a new device has been detected and display the device name.
        break;
    case WMDM_MSG_DEVICE_REMOVAL:
        // TODO: Display a message that the device has been removed and display the device name.
        break;
    case WMDM_MSG_MEDIA_ARRIVAL:
        // TODO: Display a message indicating that storage media has been added to the device and display the device name.
        break;
    case WMDM_MSG_MEDIA_REMOVAL:
        // TODO: Display a message that storage media has been removed from the device and display the device name.
        break;
    default:
        // TODO: Display a message indicating that an unidentified message has been received.
        break;
    }
    return S_OK; // Return value is ignored, and not returned to the application.
}

Requirements

Header: Defined in mswmdm.h and mswmdm_i.c; the application must include both of these.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMNotification Interface


IWMDMObjectInfo Interface (deprecated)

The IWMDMObjectInfo interface gets and sets information that controls how playable files on device are handled by the IWMDMDeviceControl interface.

This interface is not intended for non-playable files. If the IWMDMObjectInfo interface is acquired from an IWMDMStorage interface that represents a non-playable file, or a folder or a root file system containing no playable files, E_INVALIDTYPE is returned from all of the methods.

In addition to the methods inherited from IUnknown, the IWMDMObjectInfo interface exposes the following methods.

Method | Description
GetLastPlayPosition | Retrieves the last play position of the object.
GetLongestPlayPosition | Retrieves the longest play position of the object.
GetPlayLength | Retrieves the play length of the object in units pertinent to the object.
GetPlayOffset | Retrieves the play offset of the object, in units pertinent to the object.
GetTotalLength | Retrieves the total play length of the object in units pertinent to the object.
SetPlayLength | Sets the play length of the object, in units pertinent to the object.
SetPlayOffset | Sets the play offset of the object, in units pertinent to the object.

See Also

  • Interfaces for Applications
  • IWMDMStorage Interface


IWMDMObjectInfo::GetLastPlayPosition (deprecated)

The GetLastPlayPosition method retrieves the last play position of the object. The object must be an audio file on the media device.

Syntax

HRESULT GetLastPlayPosition(
  DWORD*  pdwLastPos
);

Parameters

pdwLastPos

[out] Pointer to a DWORD specifying the last play position of the object, in milliseconds.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report last play position.
E_INVALIDTYPE | The object is not a valid playable file.
E_FAIL | An unspecified error occurred.

Remarks

The object must be an audio data file. For all other object types, this function returns E_INVALIDTYPE.

The last play position changes when either the user starts playing a file on the media device or when an application invokes the IWMDMDeviceControl::Play method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMObjectInfo Interface
  • Play


IWMDMObjectInfo::GetLongestPlayPosition (deprecated)

The GetLongestPlayPosition method retrieves the longest play position of the file. The file must be an audio file on the media device.

Syntax

HRESULT GetLongestPlayPosition(
  DWORD*  pdwLongestPos
);

Parameters

pdwLongestPos

[out] Pointer to a DWORD specifying the longest play position of the object, in milliseconds.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report longest play position.
E_INVALIDTYPE | The object is not a valid playable file.
E_FAIL | An unspecified error occurred.

Remarks

The object must be an audio data file. For all other object types, this function returns E_INVALIDTYPE.

The last play position changes when either the user starts playing a file on the media device, or when an application invokes the IWMDMDeviceControl::Play method and that play exceeds the position of the last longest play position.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMObjectInfo Interface
  • Play


IWMDMObjectInfo::GetPlayLength (deprecated)

The GetPlayLength method retrieves the play length of the object in units appropriate to the format. This is the remaining length that the file can play, not its total length.

Syntax

HRESULT GetPlayLength(
  DWORD*  pdwLength
);

Parameters

pdwLength

[out] Pointer to a DWORD specifying the remaining play length of the file, in milliseconds.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report the remaining play length.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

The value of the play length retrieved is either the total length of the object minus the current play position (if the SetPlayLength method has not been called), or the value set by SetPlayLength clipped to be no greater than the total play length of the object minus the current play position.

The play length information can change either when the user starts playing a file on the media device or when an application invokes the Play method.

For folders or file systems containing playable files, the value returned is in tracks or numbers of playable files in that folder or in the root of that file system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMObjectInfo Interface
  • Play
  • SetPlayLength


IWMDMObjectInfo::GetPlayOffset (deprecated)

The GetPlayOffset method retrieves the play offset of the object, in units appropriate to the format. This is the starting point for the next invocation of Play.

Syntax

HRESULT GetPlayOffset(
  DWORD*  pdwOffset
);

Parameters

pdwOffset

[out] Pointer to a DWORD specifying the play offset of the object, in units appropriate to the format.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report the play offset.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

The value retrieved is either zero (if the SetPlayOffset method has not been called) or the value set by SetPlayOffset clipped to be no greater than the total play length of the object minus one unit.

For playable files, the value returned is specified in milliseconds. The play offset value does not change when the user starts playing a file on the media device or when an application invokes the IWMDMDeviceControl::Play method.

For folders or file systems containing playable files, the value returned indicates the first track that is played when an application invokes the IWMDMDeviceControl::Play method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMObjectInfo Interface
  • Play
  • SetPlayOffset


IWMDMObjectInfo::GetTotalLength (deprecated)

The GetTotalLength method retrieves the total play length of the object, in units appropriate to the format. The value returned is the total length regardless of the current settings of the play length and offset.

Syntax

HRESULT GetTotalLength(
  DWORD*  pdwLength
);

Parameters

pdwLength

[out] Pointer to a DWORD specifying the total length of the file, in units appropriate to the format.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report total play length.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

For playable files, the total length is specified in milliseconds.

For folders or file systems containing playable files, the value returned indicates the total number of playable files in a folder or in the root of a file system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMObjectInfo Interface


IWMDMObjectInfo::SetPlayLength (deprecated)

The SetPlayLength method sets the play length of the object, in units appropriate to the format. This is the maximum length that the object plays regardless of its actual length.

Syntax

HRESULT SetPlayLength(
  DWORD  dwLength
);

Parameters

dwLength

[in] DWORD specifying the play length, in units appropriate to the format.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This device does not support setting play lengths.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

If the value passed in is greater than the total length of the object, it is clipped to the length of the object minus the object's current play position minus one unit.

For playable files, the value to set is specified in milliseconds. The value is clipped to no more than the total length of the file minus the object's current play offset position. The play position information can change either when the user starts playing a file on the media device or when an application invokes the IWMDMDeviceControl::Play method.

For folders or file systems containing playable files, the value passed is the number of playable files in that folder or in the root of that file system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • GetPlayLength
  • IWMDMObjectInfo Interface


IWMDMObjectInfo::SetPlayOffset (deprecated)

The SetPlayOffset method sets the play offset of the object, in the units appropriate to the format. This specifies the starting point for the next invocation of Play.

Syntax

HRESULT SetPlayOffset(
  DWORD  dwOffset
);

Parameters

dwOffset

[in] DWORD specifying the play offset, in units appropriate to the format.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This device does not support setting play lengths.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

If the value passed is greater than the total length of the object minus the current play length, it is clipped to the length of the object minus the play length.

For playable files, the value is specified in milliseconds. The play offset position value does not change when the user starts playing a file on the media device or when an application invokes the IWMDMDeviceControl::Play method.

For folders or file systems containing playable files, the value indicates the first track that is played when an application invokes the IWMDMDeviceControl::Play method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • GetPlayOffset
  • IWMDMObjectInfo Interface


IWMDMOperation Interface (deprecated)

This optional, application-implemented IWMDMOperation interface allows the application to control how data is read from or written to the computer during a file transfer.

In addition to the methods inherited from IUnknown, the IWMDMOperation interface exposes the following methods.

Method | Description
BeginRead | Indicates that a "read from device" action is beginning.
BeginWrite | Indicates that a "write to device" action is beginning.
End | Indicates that a read or write operation is finished.
GetObjectAttributes | Allows the application to specify attributes for an object being written to a device.
GetObjectName | Allows the application to specify the name of an object being written to the device.
GetObjectTotalSize | Retrieves the total size of an object, in bytes.
SetObjectAttributes | Assigns the content attributes. This method is currently not called by Windows Media Device Manager.
SetObjectName | Assigns a name to the content being read or written. This method is currently not called by Windows Media Device Manager.
SetObjectTotalSize | Assigns the total size of an object, in bytes. This method is currently not called by Windows Media Device Manager.
TransferObjectData | Transfers a block of data to or from the computer.

See Also

  • Handling File Transfers Manually
  • Interfaces for Applications
  • IWMDMOperation2 Interface
  • IWMDMOperation3 Interface


IWMDMOperation::BeginRead (deprecated)

The BeginRead method indicates that a "read from device" action is beginning. Windows Media Device Manager only calls this method if the application calls IWMDMStorageControl::Read and passes in this IWMDMOperation interface.

Syntax

HRESULT BeginRead();

Parameters

This method takes no parameters.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED, the Windows Media Device Manager will call the End method to indicate that the process has been terminated. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

This method is called just before the Windows Media Device Manager calls IWMDMOperation::TransferObjectData.

Example Code

The following C++ code example implements the BeginRead method and outputs a message when a read-from-device action is beginning.

HRESULT BeginRead()
{
    // TODO: Display the message: "IWMDMOperation event--BeginRead."

    // If the global handle of the source file is uninitialized, fail.
    if (m_File == INVALID_HANDLE_VALUE)
        return E_FAIL;

    // Global status to let TransferObjectData know what kind of
    // operation is happening.
    m_OperationStatus = OPERATION_READ;
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::BeginWrite


IWMDMOperation::BeginWrite (deprecated)

The BeginWrite method indicates that a "write to device" action is beginning. Windows Media Device Manager only calls this method if the application calls IWMDMStorageControl/2/3::Insert/2/3 and passes in this interface.

Syntax

HRESULT BeginWrite();

Parameters

This method takes no parameters.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED, Windows Media Device Manager will call the End method to indicate that termination is finished. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

This method is called just before the Windows Media Device Manager calls IWMDMOperation::TransferObjectData to begin writing data to the device.

Example Code

The following C++ code example implements the BeginWrite method and outputs a message when a write-to-device action is beginning.

HRESULT BeginWrite()
{
    // TODO: Display the message: "IWMDMOperation event--BeginWrite."

    // If the global handle of the destination file is uninitialized, fail.
    if (m_File == INVALID_HANDLE_VALUE)
        return E_FAIL;

    // Global status to let TransferObjectData know what kind of
    // operation is happening.
    m_OperationStatus = OPERATION_WRITE;
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::BeginRead


IWMDMOperation::End (deprecated)

The End method indicates that a read or write operation is finished, whether successful or not, and it returns a completion code.

Syntax

HRESULT End(
  HRESULT*  phCompletionCode,
  IUnknown*  pNewObject
);

Parameters

phCompletionCode

[in] Completion code for the operation.

pNewObject

[in] When sending to a device, a pointer to a new IWMDMStorage object representing the new object that has been sent to the device. When reading from a device, a pointer to the IWMDMStorage object that was read from the device.

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.

Windows Media Device Manager ignores any return code returned by the End method because the current operation is finished or terminated before this method is called.

Remarks

The End method is called whether or not the transfer was successful, and is the last IWMDMOperation method called. This method can be used to signal the application to close all file handles and other objects required by the read or write operation.

Example Code

The following C++ code closes a global file handle after a read or write action, and outputs a message.

HRESULT End(HRESULT* phCompletionCode, IUnknown* pNewObject)
{
    // TODO: Display the message: "IWMDMOperation event--End."

    // Close the file handle now that we're done with it.
    if (m_File != INVALID_HANDLE_VALUE)
        if (!CloseHandle(m_File))
            // TODO: Display the message: "Couldn't close the file."

    // Reset global status flag.
    m_OperationStatus = OPERATION_UNINITIALIZED;
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface


IWMDMOperation::GetObjectAttributes (deprecated)

The GetObjectAttributes method allows the application to specify attributes for an object being written to a device. Windows Media Device Manager calls this method before a file is written to the device in order to learn the file's attributes.

Syntax

HRESULT GetObjectAttributes(
  DWORD*  pdwAttributes,
  _WAVEFORMATEX*  pFormat
);

Parameters

pdwAttributes

[out] Pointer to a DWORD that specifies the attributes defined in the IWMDMStorage::GetAttributes method.

pFormat

[out] Pointer to a _WAVEFORMATEX structure that specifies the audio format for files with audio data attributes.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED, the operation is cancelled and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

When transferring data to the device, you should provide object attributes for optimal transferrence.

Example Code

The following C++ code implements the GetObjectAttributes method. It tries to determine if the file being read (m_File) is a file or folder, and set the returned attributes accordingly.

HRESULT GetObjectAttributes(DWORD* pdwAttributes, _WAVEFORMATEX* pFormat)
{
    // TODO: Display the message: IWMDMOperation event--GetObjectAttributes.
    *pdwAttributes = WMDM_FILE_ATTR_FILE |
        WMDM_STORAGE_ATTR_REMOVABLE |
        WMDM_FILE_ATTR_AUDIO;

    BY_HANDLE_FILE_INFORMATION fileInformation;
    if (GetFileInformationByHandle(m_File, &fileInformation))
    {
        if (fileInformation.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY)
            *pdwAttributes |= WMDM_FILE_ATTR_FOLDER;
        else
            *pdwAttributes |= WMDM_FILE_ATTR_FILE;

        if (fileInformation.dwFileAttributes & FILE_ATTRIBUTE_READONLY)
            *pdwAttributes |= FILE_ATTRIBUTE_READONLY;
    }

    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::SetObjectAttributes


IWMDMOperation::GetObjectName (deprecated)

Windows Media Device Manager calls GetObjectName before an object is written to the device in order to know what it should be named on the device.

Syntax

HRESULT GetObjectName(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to a wide-character null-terminated string that specifies the object name. The name should include a file extension, if required. Windows Media Device Manager allocates and releases this buffer. nMaxChars specifies the maximum number of characters, including the terminating null character.

nMaxChars

[in] Integer specifying the number of characters in pwszName, including the terminating null character.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED is returned from this call, the operation is cancelled and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

This method is only called if the application did not specify the name as a parameter in the Insert method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::SetObjectName


IWMDMOperation::GetObjectTotalSize (deprecated)

Windows Media Device Manager calls GetObjectTotalSize before a file is written to the device in order to retrieve the total size of the object, in bytes.

Syntax

HRESULT GetObjectTotalSize(
  DWORD*  pdwSize,
  DWORD*  pdwSizeHigh
);

Parameters

pdwSize

[out] Pointer to a DWORD that, on return, specifies the low-order bits of the object size in bytes.

pdwSizeHigh

[out] Pointer to a DWORD that, on return, specifies the high-order bits of the object size in bytes.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED, the operation is cancelled and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return this same error to the application.

Remarks

This method is called after the GetObjectAttributes method has been called. When transferring, the object implementing this interface is passed the total size of the content being sent.

Example Code

The following C++ code implements GetObjectTotalSize. It uses the Win32 function GetFileInformationByHandle to retrieve the file size of the file about to be written to the device (m_File), and returns the values.

// About to start writing to the device.
HRESULT GetObjectTotalSize(DWORD*  pdwSize,    DWORD*  pdwSizeHigh)
{
    BY_HANDLE_FILE_INFORMATION fileInfo;
    GetFileInformationByHandle(
        m_File,
        &fileInfo);

    *pdwSize = fileInfo.nFileSizeLow;
    *pdwSizeHigh = fileInfo.nFileSizeHigh;
    // TODO: Display the message: "IWMDMOperation event--GetObjectTotalSize."
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • SetObjectTotalSize


IWMDMOperation::SetObjectAttributes (deprecated)

The SetObjectAttributes method specifies the file attributes. This method is currently not called by Windows Media Device Manager.

Syntax

HRESULT SetObjectAttributes(
  DWORD  dwAttributes,
  _WAVEFORMATEX*  pFormat
);

Parameters

dwAttributes

[in] DWORD specifying the object attributes as defined in the IWMDMStorage::SetAttributes method.

pFormat

[in] Pointer to a _WAVEFORMATEX structure specifying the format for files with audio data attributes. If the file contains audio data, this parameter should be filled.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED, the operation is terminated and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

Audio attributes include the number of samples per second, the number of bytes per sample, and so on.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::GetObjectAttributes


IWMDMOperation::SetObjectName (deprecated)

The SetObjectName method assigns a name to the content being read or written. This method is currently not called by Windows Media Device Manager.

Syntax

HRESULT SetObjectName(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[in] Pointer to a wide-character null-terminated string specifying the object name.

nMaxChars

[in] Integer specifying the maximum number of characters that this string can hold.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If either E_FAIL or WMDM_E_USER_CANCELLED is returned from this call, the operation is cancelled and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

This method is called after BeginRead is called.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::GetObjectName


IWMDMOperation::SetObjectTotalSize (deprecated)

The SetObjectTotalSize method assigns the total size in bytes of an object. This method is currently not called by Windows Media Device Manager.

Syntax

HRESULT SetObjectTotalSize(
  DWORD  dwSize,
  DWORD  dwSizeHigh
);

Parameters

dwSize

[in] DWORD specifying the low-order bits of the object size, in bytes.

dwSizeHigh

[in] DWORD specifying the high-order bits of the object size, in bytes.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns E_FAIL or WMDM_E_USER_CANCELLED, the operation is cancelled and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

This method is called after SetObjectAttributes.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • IWMDMOperation::GetObjectTotalSize


IWMDMOperation::TransferObjectData (deprecated)

The TransferObjectData method is called to allow the application to transfer a block of data to or from the computer.

Syntax

HRESULT TransferObjectData(
  BYTE*  pData,
  DWORD*  pdwSize,
  BYTE[WMDM_MAC_LENGTH]  abMac
);

Parameters

The details of these parameters differ, depending on whether this is a read-from-device or write-to-device operation, as indicated by the prior reception of a BeginRead or BeginWrite call.

pData

Pointer to a buffer containing the data. This buffer is always allocated and freed by Windows Media Device Manager. Your application should never allocate or free this buffer.

BeginRead [in] During a read from device, incoming data that must be decrypted using the CSecureChannelClient::DecryptParam method. The application does not need to deallocate the buffer.

BeginWrite [in, out] During a write to device, on input is a memory buffer pdwSize bytes long, allocated by Windows Media Device Manager. The application should fill this buffer with data that has been encrypted using the CSecureChannelClient::EncryptParam method.

pdwSize

Pointer to a DWORD that specifies the transfer buffer size.

BeginRead [in, out] On input, the size of the incoming data in pData. On output, the amount of data the application has actually actually read.

BeginWrite[in, out] On input, the size of the pData buffer. On output, the actual size of the data sent out.

abMac

Array of bytes specifying the message authentication code for the parameter data of this method.

BeginRead [in] A MAC generated from pData and pdwSize that the application should check after pData is decrypted, to verify that the data has not been modified.

BeginWrite [out] A MAC generated from pData and pdwSize before pData is encrypted.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

If the application returns either E_FAIL or WMDM_E_USER_CANCELLED from this call, the operation is cancelled and the End method is called. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return that error to the application.

Remarks

The application can determine whether data is being read from or written to the device by monitoring whether BeginRead or BeginWrite was called just before this method was called.

Example Code

The following C++ code demonstrates how an application might implement TransferObjectData to handle file transfer itself. The code shown handles both reading data from and writing data to the device. The direction of data flow is indicated by a member variable m_OperationStatus, set in a prior call to BeginRead or BeginWrite.

HRESULT TransferObjectData(BYTE* pData, DWORD* pdwSize, BYTE* pMac)
{
    HRESULT hr = S_OK;

    // Verify parameters.
    if (pData == NULL || pdwSize == NULL || pMac == NULL || m_File == INVALID_HANDLE_VALUE)
    {
        // TODO: Display the message: "Invalid argument in SetObjectTotalSize."
        return E_INVALIDARG;
    }
    if ((m_OperationStatus != OPERATION_READ) && (m_OperationStatus != OPERATION_WRITE))
    {
        // TODO: Display the message: "Unable to determine direction of data transfer."
        return E_FAIL;
    }

    //////////////////////////////////////////////////////////////////////////
// Sending data to the device.
//////////////////////////////////////////////////////////////////////////
    if (m_OperationStatus == OPERATION_WRITE)
    {
        DWORD   dwReadLen;
        // The SAC is used to encrypt the data sent to the device.
        if (m_pSAC == NULL)
        {
               // TODO: Display the message: "SAC not initialized in TransferObjectData."
            return E_FAIL;
        }

        // Read pdwSize bytes from the file into pData.
        dwReadLen = *pdwSize;
        if (ReadFile(m_File, pData, dwReadLen, pdwSize, NULL) == FALSE)
        {
               // TODO: Display the message: "Couldn't read the file in TransferObjectData."
            return E_FAIL;
        }

        // If there is no more data, terminate the transfer.
        if (*pdwSize == 0)
        {
            return S_FALSE;
        }

        // Create the MAC to return to Windows Media Device Manager.
        HMAC hMAC;
        hr = m_pSAC->MACInit(&hMAC);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pData), *pdwSize);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(DWORD));
        hr = m_pSAC->MACFinal(hMAC, (BYTE*)pMac);
        if (hr != S_OK) return E_FAIL;

        // Encrypt the data to send to the service provider/device.
        hr = m_pSAC->EncryptParam((BYTE*)(pData), *pdwSize);
        if (hr != S_OK)
        {
            return E_FAIL;
        }
    }
    //////////////////////////////////////////////////////////////////////////
// Receiving data from the device.
//////////////////////////////////////////////////////////////////////////
    else
    {
        // Copy the data to a temporary file for decryption.
        BYTE *pTmpData = new BYTE [*pdwSize];
        if (pTmpData == NULL)
        {
            return E_OUTOFMEMORY;
        }
        memcpy(pTmpData, pData, *pdwSize);

        // Decrypt the pData Parameter
        hr = m_pSAC->DecryptParam(pTmpData, *pdwSize);

        // Verify the MAC of the decrypted data.
        HMAC hMAC;
        BYTE pTestMac[WMDM_MAC_LENGTH];
        hr = m_pSAC->MACInit(&hMAC);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pTmpData), *pdwSize);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(*pdwSize));
        hr = m_pSAC->MACFinal(hMAC, pTestMac);
        if ((memcmp(pMac, pTestMac, WMDM_MAC_LENGTH) != 0) || (hr != S_OK))
        {
            delete [] pTmpData;
            return WMDM_E_MAC_CHECK_FAILED;
        }

        // Write the data to file, and record the amount of data written.
        DWORD dwWritten = 0;
        if (WriteFile(m_File,pTmpData,*pdwSize,&dwWritten,NULL))
        {
            hr = S_OK;
            *pdwSize = dwWritten;
        }
        else
        {
            hr = HRESULT_FROM_WIN32(GetLastError());
        }
        if (pTmpData)
        {
            delete [] pTmpData;
        }
    }
    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Encryption and Decryption
  • Handling File Transfers Manually
  • IWMDMOperation Interface
  • Using Secure Authenticated Channels


IWMDMOperation2 Interface (deprecated)

The optional, application-implemented IWMDMOperation2 interface extends IWMDMOperation by providing methods to get and set extended attributes.

In addition to the methods inherited from IWMDMOperation, the IWMDMOperation2 interface exposes the following methods.

Method | Description
GetObjectAttributes2 | Allows the application to specify attributes for an object being written to a device.
SetObjectAttributes2 | Sets attributes of files or storages. This method is currently not called by Windows Media Device Manager.

See Also

  • Handling File Transfers Manually
  • Interfaces for Applications
  • IWMDMOperation Interface
  • IWMDMOperation3 Interface


IWMDMOperation2::GetObjectAttributes2 (deprecated)

Windows Media Device Manager calls GetObjectAttributes when a file is written to the device in order to learn the attributes of the file.

Syntax

HRESULT GetObjectAttributes2(
  DWORD*  pdwAttributes,
  DWORD*  pdwAttributesEx,
  _WAVEFORMATEX*  pAudioFormat,
  _VIDEOINFOHEADER*  pVideoFormat
);

Parameters

pdwAttributes

[out] Pointer to a DWORD specifying the storage attributes defined in the IWMDMStorage::GetAttributes method.

pdwAttributesEx

[out] Pointer to a DWORD specifying extended attributes. There are currently no extended attributes defined.

pAudioFormat

[out] Optional pointer to a _WAVEFORMATEX structure that specifies audio file attributes.

pVideoFormat

[out] Optional pointer to a _VIDEOINFOHEADER structure that specifies video object attributes.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMOperation2 Interface
  • SetObjectAttributes2


IWMDMOperation2::SetObjectAttributes2 (deprecated)

The SetObjectAttributes2 method sets attributes of files or storages. This method is currently not called by Windows Media Device Manager.

Syntax

HRESULT SetObjectAttributes2(
  DWORD  dwAttributes,
  DWORD  dwAttributesEx,
  _WAVEFORMATEX*  pFormat,
  _VIDEOINFOHEADER*  pVideoFormat
);

Parameters

dwAttributes

[in] Pointer to a DWORD specifying the attributes as defined by the IWMDMStorage::SetAttributes method.

dwAttributesEx

[in] DWORD specifying the extended attributes. No extended attributes are currently defined.

pFormat

[in] Optional pointer to a _WAVEFORMATEX structure that specifies audio information about the object.

pVideoFormat

[in] Optional pointer to a _VIDEOINFOHEADER structure that specifies video information about the object.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • GetObjectAttributes2
  • IWMDMOperation2 Interface


IWMDMOperation3 Interface (deprecated)

The optional, application-implemented IWMDMOperation3 interface extends IWMDMOperation by providing a new method for transferring data unencrypted for added efficiency.

In addition to the methods inherited from IWMDMOperation, the IWMDMOperation3 interface exposes the following methods.

Method | Description
TransferObjectDataOnClearChannel | Transfers a block of data to or from the device more efficiently than IWMDMOperation::TransferObjectData.

See Also

  • Handling File Transfers Manually
  • Interfaces for Applications
  • IWMDMOperation Interface
  • IWMDMOperation2 Interface


IWMDMOperation3::TransferObjectDataOnClearChannel (deprecated)

The TransferObjectDataOnClearChannel method is a more efficient implementation of IWMDMOperation::TransferObjectData.

Syntax

HRESULT TransferObjectDataOnClearChannel(
  BYTE*  pData,
  DWORD*  pdwSize
);

Parameters

pData

[in, out] Pointer to an unencrypted byte buffer.

pdwSize

[in, out] Pointer to a DWORD specifying the buffer size.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The read operation should continue.
WMDM_E_USER_CANCELLED | The read operation should be cancelled without finishing.
E_FAIL | An unspecified error occurred, and the read operation should be cancelled without finishing.

Remarks

See TransferObjectData to learn about the basics of this function. The difference between this method and TransferObjectData is that this method does not require the sender or receiver to encrypt or decrypt data, which requires extra processing time. Licensed content can still be sent using this method, since the content is always encrypted during transport anyway.

If the application supports this method, it is called in preference to the TransferObjectData.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMOperation3 Interface


IWMDMProgress Interface (deprecated)

The optional, application-implemented IWMDMProgress allows an application to track the progress of operations, such as formatting media or file transfers. This interface is submitted to, and called by, the IWMDMStorageGlobals and IWMDMStorageControl interfaces.

These methods do not provide a way for the application to know which operation is being tracked. However, the IWMDMProgress3 methods do provide a means to identify the operation; if possible, you should implement that interface instead.

In addition to the methods inherited from IUnknown, the IWMDMProgress interface exposes the following methods.

Method | Description
Begin | Indicates that an operation is beginning. An estimate of the duration of the operation is provided when possible.
End | Indicates that an operation is finished.
Progress | Indicates that an operation is still in progress.

See Also

  • Enabling Notifications
  • Interfaces for Applications
  • IWMDMProgress2 Interface
  • IWMDMProgress3 Interface
  • IWMDMStorageControl Interface
  • IWMDMStorageGlobals Interface


IWMDMProgress::Begin (deprecated)

The Begin method indicates that an operation is beginning. An estimate of the duration of the operation is provided when possible.

Syntax

HRESULT Begin(
  DWORD  dwEstimatedTicks
);

Parameters

dwEstimatedTicks

[in] DWORD specifying the estimated number of ticks that are needed for the operation to complete.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The operation should continue.
WMDM_E_USER_CANCELLED | Windows Media Device Manager should cancel the current operation without waiting for it to finish. If the application is using block mode, then Windows Media Device Manager will return this error to the application.

Remarks

This operation is called by various methods to indicate that an operation is beginning. The number of ticks passed in dwEstimatedTicks is an estimate of how many ticks are needed for the operation to complete. During the course of the operation, the Progress method is called to indicate how many ticks have transpired. Applications can use the estimate to configure display mechanisms that show progress.

The IWMDMProgress3::Begin3 method provides more information about what action is occurring.

Example Code

The following C++ code is an implementation of the Begin method.

HRESULT Begin(DWORD  dwEstimatedTicks)
{
    // TODO: Display the message: "IWMDMProgress::Begin called.: "
    // followed by the dwEstimatedTicks value.
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress Interface
  • IWMDMProgress3::Begin3


IWMDMProgress::End (deprecated)

The End method indicates that an operation is finished.

Syntax

HRESULT End();

Parameters

This method takes no parameters.

Return Values

The return value from the method is ignored by Windows Media Device Manager.

Remarks

This method is called by various interfaces to indicate that an operation is ending. Windows Media Device Manager ignores any return code returned by the End method because the operation is completed or terminated before this method is called.

Example Code

The following C++ code is an implementation of the End method

HRESULT End()
{
    // TODO: Display the message: "IWMDMProgress::End called."
    return S_OK; // Unnecessary, since this is ignored.
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress Interface
  • IWMDMProgress2::End2
  • IWMDMProgress3::End3


IWMDMProgress::Progress (deprecated)

The Progress method indicates that an operation is still in progress.

Syntax

HRESULT Progress(
  DWORD  dwTranspiredTicks
);

Parameters

dwTranspiredTicks

[in] DWORD specifying the number of ticks that have transpired so far.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The operation should continue.
WMDM_E_USER_CANCELLED | Windows Media Device Manager should cancel the current operation without waiting for it to finish. If the application is using block mode, then Windows Media Device Manager will return this error to the application.

Remarks

This method is called by all other Windows Media Device Manager methods. The intention is that Progress will be called once per estimated tick. However, the dwTranspiredTicks parameter must be checked on each call because the operation being performed may not guarantee a call once for each estimated tick.

The application returns S_OK to the calling method to indicate that the operation should continue. The application returns WMDM_E_USER_CANCELLED to indicate that the operation should be cancelled. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return this same error to the application.

Example Code

The following C++ code is a simple implementation of the Progress method.

HRESULT Progress(DWORD  dwTranspiredTicks)
{
    // TODO: Display the message: "IWMDMProgress::Progress called"
    // followed by the dwTranspiredTicks value.
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress Interface
  • IWMDMProgress3::Progress3


IWMDMProgress2 Interface (deprecated)

The optional, application-implemented IWMDMProgress2 interface extends the IWMDMProgress::End method by providing a status indicator.

In addition to the methods inherited from IWMDMProgress, the IWMDMProgress2 interface exposes the following method.

Method | Description
End2 | Extends IWMDMProgress::End by providing a completion status indicator.

See Also

  • Enabling Notifications
  • Interfaces for Applications
  • IWMDMProgress Interface
  • IWMDMProgress3 Interface


IWMDMProgress2::End2 (deprecated)

The End2 method extends IWMDMProgress::End by providing a completion status indicator.

Syntax

HRESULT End2(
  HRESULT  hrCompletionCode
);

Parameters

hrCompletionCode

[in] The return value of the operation that ended.

Return Values

The return value from the method is ignored by Windows Media Device Manager.

Remarks

IWMDMProgress2 is a callback interface provided by the application to Windows Media Device Manager for a particular operation. End2 is called when that operation is completed. The hrCompletionCode parameter is the completion status of the operation that was in progress. For example, an application can provide an IWMDMProgress2 interface pointer to the Insert2 method. When the file transfer done by Insert2 is completed, End2 is called on the IWMDMProgress2 interface pointer with the completion status of the file transfer as the hrCompletion parameter.

IWMDMProgress3::End3 provides more information, and should be implemented instead of this method.

Example Code

The following C++ code is a simple implementation of the Progress2 method.

HRESULT Progress(DWORD  dwTranspiredTicks)
{
    // TODO: Display the message: "IWMDMProgress::Progress called."
    // followed by the dwTranspiredTicks value.
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress2 Interface
  • IWMDMProgress3::End3


IWMDMProgress3 Interface (deprecated)

The optional, application-implemented IWMDMProgress3 interface extends IWMDMProgress2 by providing additional input parameters to specify which event is being monitored, and to allow for context-specific information.

Applications that implement this callback interface should provide an implementation for methods corresponding to IWMDMProgress and IWMDMProgress2 for backward compatibility, in addition to the new methods.

In addition to the methods inherited from IWMDMProgress and IWMDMProgress2, the IWMDMProgress3 interface exposes the following methods.

Method | Description
Begin3 | Indicates that an operation is about to begin.
End3 | Indicates that an operation is finished.
Progress3 | Indicates the status of an action in progress.

See Also

  • Enabling Notifications
  • Interfaces for Applications
  • IWMDMProgress Interface
  • IWMDMProgress2 Interface


IWMDMProgress3::Begin3 (deprecated)

The Begin3 method is called by Windows Media Device Manager to indicate that an operation is about to begin. An estimate of the duration of the operation is provided when possible. This method extends IWMDMProgress::Begin by providing additional input parameters for the identification (ID) of the event and for a pointer to the optional context of the commands. The operation is identified by an event ID. The method allows the caller to pass an opaque data structure to the application.

Syntax

HRESULT Begin3(
  GUID  EventId,
  DWORD  dwEstimatedTicks,
  OPAQUECOMMAND*  pContext
);

Parameters

EventId

[in] A GUID identifying the operation that will begin. Possible values are shown in the following table.

Event | Description
SCP_EVENTID_ACQSECURECLOCK | Windows Media Device Manager is acquiring a secure clock from server.
SCP_EVENTID_NEEDTOINDIV | The device is being individualized. This is not currently used.
SCP_EVENTID_DRMINFO | This event ID is used to notify the application with the version DRM header found in the content for each file. The OPAQUECOMMAND structure returned has the guidCommand member set to SCP_PARAMID_DRMVERSION. In addition, the OPAQUECOMMAND specifies one of the following flags: WMDM_SCP_DRMINFO_NOT_DRMPROTECTED WMDM_SCP_DRMINFO_V1HEADER WMDM_SCP_DRMINFO_V2HEADER
EVENT_WMDM_CONTENT_TRANSFER | Content is being transferred to or from the device.

dwEstimatedTicks

[in] DWORD specifying the estimated number of ticks that are needed for the operation to complete. The number of ticks passed in dwEstimatedTicks is an estimate of how many ticks are needed for the operation to complete. During the course of the operation, the Progress3 method is called to indicate how many ticks have transpired. Applications can use the estimate to configure display mechanisms that show progress.

pContext

[in, out] Pointer to an OPAQUECOMMAND structure containing a command sent to the device without being handled by Windows Media Device Manager. This parameter is optional and can be NULL.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The operation should continue.
WMDM_E_USER_CANCELLED | Windows Media Device Manager should cancel the current operation without waiting for it to finish. If the application is using block mode, then Windows Media Device Manager will return this error to the application.

Remarks

The application returns S_OK to indicate that an operation should be continued and WMDM_E_USER_CANCELLED to indicate that the operation should be cancelled. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return this same error to the application.

Example Code

The following C++ code shows an example implementation of Begin3.

HRESULT Begin3(GUID  EventId, DWORD  dwEstimatedTicks, OPAQUECOMMAND*  pContext)
{
    WCHAR strGuid[64];
    StringFromGUID2(reinterpret_cast<GUID&>(EventId),(LPOLESTR)strGuid, 64);
    // TODO: Display the message "IWMDMProgress3::Begin3 called."
    // followed by the strGuid value.
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress::Begin
  • IWMDMProgress3 Interface


IWMDMProgress3::End3 (deprecated)

The End3 method is called by Windows Media Device Manager to indicate that an operation has finished. This method extends IWMDMProgress2::End2 by providing additional input parameters for the identification (ID) of the event and for a pointer to the context of the commands.

Syntax

HRESULT End3(
  GUID  EventId,
  HRESULT  hrCompletionCode,
  OPAQUECOMMAND*  pContext
);

Parameters

EventId

[in] A GUID specifying the event that is ending. Possible values are shown in the following table.

Event | Description
SCP_EVENTID_ACQSECURECLOCK | Windows Media Device Manager is acquiring a secure clock from server.
SCP_EVENTID_NEEDTOINDIV | The device is being individualized. This is not currently used.
SCP_EVENTID_DRMINFO | This event ID is used to notify the application with the version DRM header found in the content for each file. The OPAQUECOMMAND structure returned has the guidCommand member set to SCP_PARAMID_DRMVERSION. In addition, the data specifies one of the following flags: WMDM_SCP_DRMINFO_NOT_DRMPROTECTED WMDM_SCP_DRMINFO_V1HEADER WMDM_SCP_DRMINFO_V2HEADER
EVENT_WMDM_CONTENT_TRANSFER | Content is being transferred to or from the device.

hrCompletionCode

[in] HRESULT specifying the completion code of the operation that was in progress. The hrCompletionCode parameter is the return code of the operation that ended. This parameter can be any HRESULT, including standard COM error codes, Win32 error codes converted to HRESULT, or Windows Media Device Manager error codes.

pContext

[in, out] Pointer to an OPAQUECOMMAND structure containing a command sent directly to the device without being handled by Windows Media Device Manager. This parameter is optional and can be NULL. The context structure is a way for the component to send any relevant data with the event to the application. The component sending this structure should define how the application can interpret this data structure.

Return Values

Windows Media Device Manager ignores any return code returned by the End3 method because the current operation is finished or cancelled before this method is called.

Remarks

The interface that owns the method that is implementing an operation calls End3 when the operation defined by the method is completed.

Example Code

The following C++ code shows an example implementation of End3.

HRESULT End3(GUID  EventId, HRESULT  hrCompletionCode, OPAQUECOMMAND*  pContext)
{
    // TODO: Display the message "IWMDMProgress3::End3 called."
    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress::End
  • IWMDMProgress3 Interface


IWMDMProgress3::Progress3 (deprecated)

The Progress3 method is called by Windows Media Device Manager to indicate the status of an action in progress. This method extends IWMDMProgress::Progress by providing additional input parameters for the identification (ID) of the event and for a pointer to the context of the commands.

Syntax

HRESULT Progress3(
  GUID  EventId,
  DWORD  dwTranspiredTicks,
  OPAQUECOMMAND*  pContext
);

Parameters

EventId

[in] GUID specifying the event ID for which progress notifications are being sent. Possible values are shown in the following table.

Event | Description
SCP_EVENTID_ACQSECURECLOCK | Windows Media Device Manager is acquiring a secure clock from server.
SCP_EVENTID_NEEDTOINDIV | The device is being individualized. This is not currently used.
SCP_EVENTID_DRMINFO | This event ID is used to notify the application with the version DRM header found in the content for each file. The OPAQUECOMMAND structure returned has the guidCommand parameter set to SCP_PARAMID_DRMVERSION. In addition, the data specifies one of the following flags: WMDM_SCP_DRMINFO_NOT_DRMPROTECTED WMDM_SCP_DRMINFO_V1HEADER WMDM_SCP_DRMINFO_V2HEADER
EVENT_WMDM_CONTENT_TRANSFER | Content is being transferred to or from the device.

dwTranspiredTicks

[in] DWORD specifying the number of ticks that have transpired so far.

pContext

[in, out] Pointer to an OPAQUECOMMAND structure containing a command sent directly to the device without being handled by Windows Media Device Manager. This parameter is optional and can be NULL. If the event is SCP_EVENTID_DRMINFO, the data in this parameter will have the SCP_PARAMID_DRMVERSION GUID.

Return Values

The application should return one of the following HRESULT values.

Return code | Description
S_OK | The operation should continue.
WMDM_E_USER_CANCELLED | Windows Media Device Manager should cancel the current operation without waiting for it to finish. If the application is using block mode, then Windows Media Device Manager will return this error to the application.

Remarks

The interface that owns the method that is implementing an operation calls the Progress3 method as the operation defined by the method is carried out. The intention is that Progress3 will be called once per estimated tick. However, the dwTranspiredTicks parameter must be checked on each call because the operation being performed may not guarantee one call for each estimated tick.

The application returns S_OK to the calling method to indicate that the operation should continue. The application returns WMDM_E_USER_CANCELLED to indicate that the operation should be canceled. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return this same error to the application.

Example Code

The following C++ code shows an example implementation of Progress3.

HRESULT Progress3(GUID  EventId, DWORD  dwTranspiredTicks, OPAQUECOMMAND*  pContext)
{
    WCHAR strGuid[64];
    ZeroMemory(strGuid, 64);
    StringFromGUID2(reinterpret_cast<GUID&>(EventId),(LPOLESTR)strGuid, 64);
    // TODO: Display the message: "Progress3 called. GUID value: "
    // followed by the strGUID value.
    // TODO: Display the message: "Progress3 dwTranspiredTicks: "
    // followed by the dwTranspiredTicks value.

    return S_OK;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Notifications
  • IWMDMProgress::Progress
  • IWMDMProgress3 Interface


IWMDMRevoked Interface (deprecated)

The IWMDMRevoked interface retrieves the URL from which updated components can be downloaded, if a transfer fails with a revocation error. The secured content provider determines whether or not to allow a transfer, based on the application certificates of the components involved. You can access the IWMDMRevoked interface by calling QueryInterface on the IWMDMStorageControl interface.

In addition to the methods inherited from IUnknown, the IWMDMRevoked interface exposes the following method.

Method | Description
GetRevocationURL | Retrieves the URL from which updated components can be downloaded.

See Also

  • Interfaces for Applications
  • IWMDMStorageControl Interface


IWMDMRevoked::GetRevocationURL (deprecated)

The GetRevocationURL method retrieves the URL from which updated components can be downloaded.

Syntax

HRESULT GetRevocationURL(
  LPWSTR*  ppwszRevocationURL,
  DWORD*  pdwBufferLen,
  DWORD*  pdwRevokedBitFlag
);

Parameters

ppwszRevocationURL

[in, out] Pointer to a string containing a revocation URL. This buffer is created and freed by the caller.

pdwBufferLen

[in, out] Size of the buffer holding the revocation URL.

pdwRevokedBitFlag

[out] Pointer to a DWORD specifying information on what component(s) have been revoked. This should be one or more of the following values, combined using a bitwise OR.

Flag | Description
WMDM_WMDM_REVOKED | Windows Media Device Manager itself has been revoked.
WMDM_APP_REVOKED | The application has been revoked and needs to be updated before any DRM-protected content can be transferred.
WMDM_SP_REVOKED | The service provider has been revoked and needs to be updated before any DRM-protected content can be transferred to it.
WMDM_SCP_REVOKED | The secured content provider has been revoked and needs to be updated before any DRM-protected content can be transferred.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDTYPE | The object with which this interface is associated is not a playable file or folder.
WMDM_E_NOTSUPPORTED | This device does not support setting play lengths.
E_FAIL | An unspecified error occurred.

Remarks

This method retrieves the URL from which updated components can be downloaded. If this method is not implemented by the revoked component, a default Microsoft URL is used. This location is maintained by Microsoft and contains any updates to components revoked by the Microsoft digital rights management system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMRevoked Interface


IWMDMStorage Interface (deprecated)

An instance of the IWMDMStorage interface provides methods to examine and explore a storage (a generic name for a data or collection object, such as a file, folder, or playlist) on a device. Note that storages cannot be used to refer to objects on the computer, only on the device. IWMDMStorage can contain nested objects, and can represent the root object (the entire storage medium) or any child object, such as a folder or file, on that medium. The IWMDMStorage2 interface extends this interface by making it possible to get a storage pointer from a storage name and to get and set extended attributes. IWMDMStorage3 extends this interface by supporting metadata.

To obtain a root storage object which can be queried for all other objects on a device, you must call IWMDMDevice::EnumStorage, as described in Exploring a Device.

In addition to the methods inherited from IUnknown, the IWMDMStorage interface exposes the following methods.

Method | Description
EnumStorage | Retrieves an IWMDMEnumStorage interface to enumerate the immediate child storages of the current storage.
GetAttributes | Retrieves the attributes of the storage.
GetDate | Retrieves the date on which the storage was most recently modified.
GetName | Retrieves the display name of the storage.
GetRights | Retrieves the rights information for a licensed storage.
GetSize | Retrieves the size of the storage, in bytes.
GetStorageGlobals | Retrieves the IWMDMStorageGlobals interface to provide access to global information about a storage medium.
SendOpaqueCommand | Sends a command to the storage through Windows Media Device Manager.
SetAttributes | Sets the attributes of the storage.

See Also

  • Interfaces for Applications
  • IWMDMEnumStorage Interface
  • IWMDMStorage2 Interface
  • IWMDMStorage3 Interface
  • IWMDMStorage4 Interface
  • IWMDMStorageGlobals Interface


IWMDMStorage::EnumStorage (deprecated)

The EnumStorage method retrieves an IWMDMEnumStorage interface to enumerate the immediate child storages of the current storage.

Syntax

HRESULT EnumStorage(
  IWMDMEnumStorage**  pEnumStorage
);

Parameters

pEnumStorage

[out] Pointer to an IWMDMEnumStorage interface. The caller must release this interface when done with it.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pEnumStorage parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The IWMDMEnumStorage interface that is retrieved will enumerate the immediate chilren of this object. This method allows an application to navigate the contents of a device recursively.

Sample Code

The following two functions explore all the storages on a device passed into the kickoff function, ExploreDevice.

// Kickoff function to explore a device.
void ExploreDevice(IWMDMDevice* pDevice)
{
    HRESULT hr = S_OK;

    // Get a root enumerator.
    CComPtr<IWMDMEnumStorage> pEnumStorage;
    hr = pDevice->EnumStorage(&pEnumStorage);
    RecursiveExploreStorage(pEnumStorage);

    HANDLE_HR(hr, "Got a root storage in ExploreDevice.","Couldn't get a root storage in ExploreDevice.");

e_Exit:
    return;
}

void RecursiveExploreStorage(IWMDMEnumStorage* pEnumStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage> pStorage;
    ULONG numRetrieved = 0;
    // Loop through all storages in the current storage
    while(pEnumStorage->Next(1, &pStorage, &numRetrieved) == S_OK && numRetrieved == 1)
    {
        // Get the name of the object. The first time this is called on a device, it will
        // retrieve '\' as the root folder name.
        const UINT MAX_LEN = 255;
        WCHAR name[MAX_LEN];
        hr = pStorage->GetName((LPWSTR)&name, MAX_LEN);
        // TODO: Display the storage name.

        // Get metadata for the storage.
        if (SUCCEEDED(hr))
            GetMetadata(pStorage);

        // Find out something about the item.
        DWORD attributes = 0;
        _WAVEFORMATEX audioFormat;
        hr = pStorage->GetAttributes(&attributes, &audioFormat);
        HANDLE_HR(hr, "Got storage attributes in RecursivelyExploreStorage.","Couldn't get storage attributes in RecursivelyExploreStorage.");

        // If this is a folder, recurse into it.
        if (attributes & WMDM_FILE_ATTR_FILE)
            // TODO: Display a message indicating that this is a file.
        if (attributes & WMDM_FILE_ATTR_FOLDER)
        {
            // TODO: Display a message indicating that this is a folder.
            CComPtr<IWMDMEnumStorage> pEnumSubStorage;
            hr = pStorage->EnumStorage(&pEnumSubStorage);
            RecursiveExploreStorage(pEnumSubStorage);
        }

        // Some other useful attributes to check include:
        // WMDM_FILE_ATTR_CANDELETE and WMDM_FILE_ATTR_CANPLAY and others to determine what can be done with a storage.
        // WMDM_FILE_ATTR_HIDDEN and other attributes to determine display characteristics,
        // WMDM_STORAGE_IS_DEFAULT to see if this is the default save location for new files.
        pStorage.Release();
    } // Get the next storage pointer.

e_Exit:
    return;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Exploring a Device
  • IWMDMDevice::EnumStorage
  • IWMDMEnumStorage Interface
  • IWMDMStorage Interface


IWMDMStorage::GetAttributes (deprecated)

The GetAttributes method retrieves the attributes of the storage.

Syntax

HRESULT GetAttributes(
  DWORD*  pdwAttributes,
  _WAVEFORMATEX*  pFormat
);

Parameters

pdwAttributes

[out] Pointer to a DWORD specifying one or more of the following attributes, combined with a bitwise OR.

Attribute | Description
WMDM_STORAGE_ATTR_FILESYSTEM | This object is the top-level storage medium, for example, a storage card or some other type of on-board storage.
WMDM_STORAGE_ATTR_REMOVABLE | The global storage medium is removable.
WMDM_STORAGE_ATTR_NONREMOVABLE | The global storage medium is not removable.
WMDM_STORAGE_ATTR_FOLDERS | The global storage medium supports folders and file hierarchy.
WMDM_STORAGE_ATTR_HAS_FILES | This storage object contains at least one file as an immediate child.
WMDM_STORAGE_ATTR_HAS_FOLDERS | This storage object contains at least one folder as an immediate child.
WMDM_STORAGE_ATTR_CANEDITMETADATA | This storage can edit metadata.
WMDM_FILE_ATTR_FILE | This is a file on the storage medium.
WMDM_FILE_ATTR_FOLDER | This is a folder on the storage medium.
WMDM_FILE_ATTR_LINK | This is a link that creates an association between multiple files.
WMDM_FILE_ATTR_AUDIO | This file contains audio data.
WMDM_FILE_ATTR_DATA | This file contains non-audio data.
WMDM_FILE_ATTR_CANPLAY | This audio file can be played by the device.
WMDM_FILE_ATTR_CANDELETE | This file can be deleted.
WMDM_FILE_ATTR_CANMOVE | This file or folder can be moved around on the storage medium.
WMDM_FILE_ATTR_CANRENAME | This file or folder can be renamed.
WMDM_FILE_ATTR_CANREAD | This file can be read by the host computer.
WMDM_FILE_ATTR_MUSIC | This audio file contains music.
WMDM_FILE_ATTR_AUDIOBOOK | This is an audio book file.
WMDM_FILE_ATTR_VIDEO | This file contains video data.
WMDM_FILE_ATTR_HIDDEN | This file is hidden on the file system
WMDM_FILE_ATTR_SYSTEM | This is a system file
WMDM_FILE_ATTR_READONLY | This is a read-only file.
WMDM_STORAGE_ATTR_VIRTUAL | This storage is virtual and does not correspond to an actual storage on the file system of the device. (Folders created based on metadata are one example of virtual storage.)
WMDM_STORAGE_IS_DEFAULT | This storage is the default location for putting new digital media on the device.
WMDM_STORAGE_CONTAINS_DEFAULT | This storage contains the default storage where new digital media should be placed.

pFormat

[out] Optional pointer to a _WAVEFORMATEX structure that specifies the object's audio attributes.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwAttributes parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Example Code

The following C++ function recursively explores a storage if it is a folder with child files or folders.

void RecursiveExploreStorage(IWMDMEnumStorage* pEnumStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage> pStorage;
    ULONG numRetrieved = 0;
    // Loop through all storages in the current storage.
    while(pEnumStorage->Next(1, &pStorage, &numRetrieved) == S_OK && numRetrieved == 1)
    {
        // Get the name of the object. The first time this is called on a device, it will
        // retrieve '\' as the root folder name.
        const UINT MAX_LEN = 255;
        WCHAR name[MAX_LEN];
        hr = pStorage->GetName((LPWSTR)&name, MAX_LEN);
        // TODO: Display the storage name.

        // Get metadata for the storage.
        if (SUCCEEDED(hr))
            GetMetadata(pStorage);

        // Find out something about the item.
        DWORD attributes = 0;
        _WAVEFORMATEX audioFormat;
        hr = pStorage->GetAttributes(&attributes, &audioFormat);
        HANDLE_HR(hr, "Got storage attributes in RecursivelyExploreStorage.","Couldn't get storage attributes in RecursivelyExploreStorage.");

        // If this is a folder, recurse into it.
        if (attributes & WMDM_FILE_ATTR_FILE)
            // TODO: Display a message indicating that this is a file.
        else if ( (attributes & WMDM_FILE_ATTR_FOLDER) &&
                  ((attributes & WMDM_STORAGE_ATTR_HAS_FILES) ||
                  (attributes & WMDM_STORAGE_ATTR_HAS_FOLDERS)) )
        {
            // TODO: Display a message indicating that this is a folder with children.
            CComPtr<IWMDMEnumStorage> pEnumSubStorage;
            hr = pStorage->EnumStorage(&pEnumSubStorage);
            RecursiveExploreStorage(pEnumSubStorage);
        }

        // Some other useful attributes to check include:
        // WMDM_FILE_ATTR_CANDELETE and WMDM_FILE_ATTR_CANPLAY and others to determine what can be done with a storage.
        // WMDM_FILE_ATTR_HIDDEN and other attributes to determine display characteristics,
        // WMDM_STORAGE_IS_DEFAULT to see if this is the default save location for new files.
        pStorage.Release();
    } // Get the next storage pointer.

e_Exit:
    return;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • Exploring a Device
  • IWMDMEnumStorage Interface
  • IWMDMStorage Interface
  • IWMDMStorage::EnumStorage
  • IWMDMStorage::SetAttributes


IWMDMStorage::GetDate (deprecated)

The GetDate method retrieves the date when the storage was last modified.

Syntax

HRESULT GetDate(
  PWMDMDATETIME  pDateTimeUTC
);

Parameters

pDateTimeUTC

[out] Pointer to a WMDMDATETIME structure specifying the date on which the storage object (file or folder) was last modified.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The time is specified in coordinated universal time.

Example Code

The following C++ code gets the "last modified" value from a storage passed in.

// Get the "Last Modified" date
WMDMDATETIME lastModified;
hr = pStorage->GetDate(&lastModified);
// TODO: Display the last modified month, day, and year.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage Interface


IWMDMStorage::GetName (deprecated)

The GetName method retrieves the display name of the storage.

Syntax

HRESULT GetName(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to a wide-character null-terminated string specifying the storage name. This is the display name of the object is the file name without path information. The caller allocates and releases this buffer.

nMaxChars

[in] Integer specifying the maximum number of characters that can be copied to the name string.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pwszName parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Example Code

The following code retrieves the display name of a storage (pStorage).

// Get the name of the object. The first time this is called on a device, it will
// retrieve '\' as the root folder name.
const UINT MAX_LEN = 255;
WCHAR name[MAX_LEN];
hr = pStorage->GetName((LPWSTR)&name, MAX_LEN);
// TODO: Display the storage name.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage Interface


IWMDMStorage::GetRights (deprecated)

The GetRights method retrieves rights information for a licensed storage.

Syntax

HRESULT GetRights(
  PWMDMRIGHTS*  ppRights,
  UINT*  pnRightsCount,
  BYTE[WMDM_MAC_LENGTH]  abMac
);

Parameters

ppRights

[out] Pointer to an array of WMDMRIGHTS structures that contain the storage rights. This parameter is included in the message authentication code. Windows Media Device Manager allocates this memory, and the application must release it with CoTaskMemFree.

pnRightsCount

[out] Pointer to the number of WMDMRIGHTS structures in the ppRights array. This parameter is included in the message authentication code.

abMac

[in, out] Array of bytes containing the message authentication code (MAC) for the parameter data of this method.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The file has no associated rights, or is not licensed.
E_INVALIDARG | The ppRights or pnRightsCount parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | Rights are not supported for this object.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller has not been certified using the secure authenticated channel client class, or object is not licensed.
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

Object rights describe the usage permissions for digital media content. For example, the WMDMRIGHTS structure can contain information concerning how many times a file can be played and who can play it. This method will fail if this is not a licensed file.

The ppRights array is allocated by this method, and must be freed by the application using CoTaskMemFree, a standard Win32 function.

To receive progress events for this call, use IWMDMStorage4::GetRightsWithProgress.

After calling this method, an application can calculate the message authentication code (MAC) values of parameters and compare them with output MAC values to ensure that the parameters have not been tampered with. The following example code shows one way to do this.

Example Code

CSecureChannelClient  *pSCClient;
IWMDMStorage  *pStorgae;

HMAC  hMAC;
BYTE  abMAC[WMDM_MAC_LENGTH];
BYTE  abMACVerify[WMDM_MAC_LENGTH];

hr = pStorage->GetRights(&pRights, &nRightsCount, abMAC);
if (SUCCEEDED(hr))
{
    //
    // First verify the integrity of the retrieved rights.
    //
    pSCClient->MACInit(&hMAC);
    pSCClient->MACUpdate(hMAC, (BYTE*)(pRights),
                    sizeof(WMDMRIGHTS) * nRightsCount);
    pSCClient->MACUpdate(hMAC, (BYTE*)(&nRightsCount),
                                 sizeof(nRightsCount));
    pSCClient->MACFinal(hMAC, (BYTE*)abMACVerify);
    if (memcmp(abMACVerify, abMAC, sizeof(abMAC)) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
    }
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage Interface
  • Using Secure Authenticated Channels
  • WMDMRIGHTS


IWMDMStorage::GetSize (deprecated)

The GetSize method retrieves the size of the storage, in bytes.

Syntax

HRESULT GetSize(
  DWORD*  pdwSizeLow,
  DWORD*  pdwSizeHigh
);

Parameters

pdwSizeLow

[out] Pointer to a DWORD specifying the low-order part of the storage object size, in bytes.

pdwSizeHigh

[out] Pointer to a DWORD specifying the high-order part of the storage object size, in bytes.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

For folders or abstract objects (such as abstract playlists), the size is zero.

Example Code

The following C++ code retrieves the size of a file, in kilobytes.

// Get size of file in kilobytes.
DWORD lowSize = 0;
DWORD highSize = 0;
hr = pStorage->GetSize(&lowSize, &highSize);
//TODO: Display the file size.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage Interface
  • IWMDMStorage::GetDate
  • IWMDMStorage::GetName


IWMDMStorage::GetStorageGlobals (deprecated)

The GetStorageGlobals method retrieves the IWMDMStorageGlobals interface of the root storage of this storage.

Syntax

HRESULT GetStorageGlobals(
  IWMDMStorageGlobals**  ppStorageGlobals
);

Parameters

ppStorageGlobals

[out] Pointer to an IWMDMStorageGlobals interface, which provides information about the device such as serial number, capabilities, and so on. The caller must release this interface when finished with it.

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.

Return code | Description
E_INVALIDARG | The ppStorageGlobals parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

The IWMDMStorageGlobals interface returned provides methods for accessing global information about the root storage of the current storage. Because this interface exposes global device information, an application only needs to call this method once, on any storage within a single memory container.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals Interface
  • IWMDMStorage Interface


IWMDMStorage::SendOpaqueCommand (deprecated)

The SendOpaqueCommand method sends a command to the storage through Windows Media Device Manager, without processing it.

Syntax

HRESULT SendOpaqueCommand(
  OPAQUECOMMAND*  pCommand
);

Parameters

pCommand

[in, out] Pointer to an OPAQUECOMMAND structure containing the command to execute. Data can be passed two ways—from the application to the device, and from the device back to the application when the call finishes.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or a NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

This method is intended for storage media commands that do not affect the operation of Windows Media Device Manager and should be passed through unchanged.

Example Code

The following C++ code calls SendOpaqueCommand to perform a simple custom authentication step with a device. The caller sends its certificate and MAC to the device, which sends back its own certificate and MAC. The application compares the retrieved certificate with the one it has stored, and if they match (and the MAC is correct), it sets bExtraCertified to TRUE.

    // Call SendOpaqueCommand to exchange extended authentication information.
    {
        HMAC           hMAC;
        OPAQUECOMMAND  Command;
        CERTINFOEX    *pCertInfoEx;
        DWORD          cbData_App   = sizeof(bCertInfoEx_App)/sizeof(bCertInfoEx_App[0]);
        DWORD          cbData_SP    = sizeof(bCertInfoEx_SP)/sizeof(bCertInfoEx_SP[0]);
        DWORD          cbData_Send  = sizeof(CERTINFOEX) + cbData_App;

        // Fill opaque command structure with the application's certificate.
        memcpy(&(Command.guidCommand), &guidCertInfoEx, sizeof(GUID));

        Command.pData = (BYTE *)CoTaskMemAlloc(cbData_Send);
        if (!Command.pData)
        {
            ExitOnFail(hr = E_OUTOFMEMORY);
        }
        Command.dwDataLen = cbData_Send;

        // Map the data in the opaque command to a CERTINFOEX structure, and
        // fill in the cert info to send.
        pCertInfoEx = (CERTINFOEX *)Command.pData;
        pCertInfoEx->hr     = S_OK;
        pCertInfoEx->cbCert = cbData_App;
        memcpy(pCertInfoEx->pbCert, bCertInfoEx_App, cbData_App);

        // Compute MAC on the data, and add to the OPAQUECOMMAND struct.
        g_cWmdm.m_pSAC->MACInit(&hMAC);
        g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.guidCommand)), sizeof(GUID));
        g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.dwDataLen)), sizeof(Command.dwDataLen));
        if (Command.pData)
        {
            g_cWmdm.m_pSAC->MACUpdate(hMAC, Command.pData, Command.dwDataLen);
        }
        g_cWmdm.m_pSAC->MACFinal(hMAC, Command.abMAC);

        // Send the opaque command.
        hr = pDevice->SendOpaqueCommand(&Command);
        if (SUCCEEDED(hr))
        {
            // Now verify the retrieved MAC.
            BYTE abMACVerify2[ WMDM_MAC_LENGTH ];
            g_cWmdm.m_pSAC->MACInit(&hMAC);
            g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.guidCommand)), sizeof(GUID));
            g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.dwDataLen)), sizeof(Command.dwDataLen));
            if (Command.pData)
            {
                g_cWmdm.m_pSAC->MACUpdate(hMAC, Command.pData, Command.dwDataLen);
            }
            g_cWmdm.m_pSAC->MACFinal(hMAC, abMACVerify2);

            // Verify MAC matches.
            if (memcmp(abMACVerify2, Command.abMAC, WMDM_MAC_LENGTH) == 0)
            {
                 // They match; verify the retrieved certificate.
                // Map the data in the opaque command to a CERTINFOEX structure
                //
                pCertInfoEx = (CERTINFOEX *)Command.pData;

                // In this simple extended authentication scheme, the callee must
                // provide the exact certificate information.
                //
                if ((pCertInfoEx->cbCert != cbData_SP) &&
                    (memcmp(pCertInfoEx->pbCert, bCertInfoEx_SP, cbData_SP) == 0))
                {
                    bExtraCertified = TRUE;
                }
            }
        }

        if (Command.pData)
        {
            CoTaskMemFree(Command.pData);
        }
    }

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage Interface


IWMDMStorage::SetAttributes (deprecated)

The SetAttributes method sets the attributes of the storage.

Syntax

HRESULT SetAttributes(
  DWORD  dwAttributes,
  _WAVEFORMATEX*  pFormat
);

Parameters

dwAttributes

[in] DWORD specifying the attributes to be set. The following table lists the attributes that can be set by this parameter.

Attribute | Description
WMDM_FILE_ATTR_AUDIO | This file contains audio data.
WMDM_FILE_ATTR_DATA | This file contains non-audio data.
WMDM_FILE_ATTR_CANPLAY | This audio file can be played by the device.
WMDM_FILE_ATTR_CANDELETE | This file can be deleted.
WMDM_FILE_ATTR_CANMOVE | This file or folder can be moved around on the storage medium.
WMDM_FILE_ATTR_CANRENAME | This file or folder can be renamed.
WMDM_FILE_ATTR_CANREAD | This file can be read by the host computer.
WMDM_FILE_ATTR_MUSIC | This audio file contains music.
WMDM_FILE_ATTR_AUDIOBOOK | This is an audio book file.
WMDM_FILE_ATTR_HIDDEN | This file is hidden on the file system
WMDM_FILE_ATTR_SYSTEM | This is a system file
WMDM_FILE_ATTR_READONLY | This is a read-only file.

pFormat

[in] Optional pointer to a _WAVEFORMATEX structure that specifies audio information about the object.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

Many of the attributes listed for GetAttributes cannot be set, and so are not listed in the attribute table for SetAttributes.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage Interface
  • IWMDMStorage::GetAttributes


IWMDMStorage2 Interface (deprecated)

The IWMDMStorage2 interface extends IWMDMStorage by making it possible to get a child storage by name, and to get and set extended attributes. IWMDMStorage3 interface extends this interface by supporting metadata.

In addition to the methods inherited from IWMDMStorage, the IWMDMStorage2 interface exposes the following methods.

Method | Description
GetAttributes2 | Retrieves extended attributes of the storage.
GetStorage | Retrieves a child storage by name.
SetAttributes2 | Sets extended attributes of the storage.

See Also

  • Interfaces for Applications
  • IWMDMStorage Interface
  • IWMDMStorage3 Interface
  • IWMDMStorage4 Interface


IWMDMStorage2::GetAttributes2 (deprecated)

The GetAttributes2 method retrieves extended attributes of the storage.

Syntax

HRESULT GetAttributes2(
  DWORD*  pdwAttributes,
  DWORD*  pdwAttributesEx,
  _WAVEFORMATEX*  pAudioFormat,
  _VIDEOINFOHEADER*  pVideoFormat
);

Parameters

pdwAttributes

[out] Pointer to a DWORD specifying one or more attributes defined in the IWMDMStorage::GetAttributes method, combined with a bitwise OR.

pdwAttributesEx

[out] Pointer to a DWORD specifying the extended attributes. Currently, no extended attributes are defined.

pAudioFormat

[out] Optional pointer to a _WAVEFORMATEX structure that specifies audio information about the object. This parameter is ignored if the file is not audio.

pVideoFormat

[out] Optional pointer to a _VIDEOINFOHEADER structure that specifies video information about the object. This parameter is ignored if the file is not video.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

Evaluation of attributes is a crucial step when exposing the contents of the media device. Some devices do not support hierarchical storage of data on storage media. The GetAttributes2 method is used to infer the support and format of the file system by discovering its structure through object attributes.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMEnumStorage Interface
  • IWMDMStorage::EnumStorage
  • IWMDMStorage2 Interface
  • IWMDMStorage2::SetAttributes2


IWMDMStorage2::GetStorage (deprecated)

The GetStorage method retrieves a child storage by name directly from the current storage without having to enumerate through all the children.

Syntax

HRESULT GetStorage(
  LPWSTR  pszStorageName,
  IWMDMStorage**  ppStorage
);

Parameters

pszStorageName

[in] Pointer to a null-terminated string specifying the storage name. This is the name retrieved by IWMDMStorage::GetName.

ppStorage

[out] Pointer to the retrieved storage object, or NULL if no storage was found. The caller must release this interface when done with it.

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 it fails with an error, it returns a standard error code.

Return code | Description
S_OK | The method succeeded.
S_FALSE | No errors occurred, but the file was not found.

Remarks

IWMDMStorage2::GetStorage does not support wildcard characters. It is not recursive; that is, it will only find storages that are immediate children of the current storage. To find a storage more than one level deep, try IWMDMDevice3::FindStorage.

Example Code

The following C++ function searches for a storage recursively. It uses GetStorage to search the immediate children; if the requested storage is not found, it then loops through all the children and recursively searches folders.

HRESULT myFindStorageRecursively(LPCWSTR storageName, IWMDMStorage* pCurrentStorage, IWMDMStorage** ppFoundStorage)
{
    HRESULT hr = S_OK;

    // Start with a quick check of all storages inside the storage.
    // If we found it, stop now and return.
    CComQIPtr<IWMDMStorage2> pStorage2(pCurrentStorage);
    hr = pStorage2->GetStorage(storageName, ppFoundStorage);
    if (*ppFoundStorage != NULL)
        return hr;

    //
    // Otherwise, enumerate through and dive into all child folders.
    //

    // First get enumerator.
    CComPtr<IWMDMEnumStorage> pEnumStorage;
    hr = pCurrentStorage->EnumStorage(&pEnumStorage);
    if (hr != S_OK && pEnumStorage != NULL)
        return hr;

    // Now enumerate all folders until found the right item, or out of folders.
    CComPtr<IWMDMStorage> pThisStorage;
    DWORD numRetrieved = 0;
    DWORD attr = 0;
    while(pEnumStorage->Next(1, &pThisStorage, &numRetrieved) == S_OK)
    {
        pThisStorage->GetAttributes(&attr, NULL);
        if (attr & WMDM_FILE_ATTR_FOLDER)
        {
            hr = myFindStorageRecursively(storageName, pThisStorage, ppFoundStorage);
            if (*ppFoundStorage != NULL)
                return hr;
        }
        pThisStorage.Release();
    }

    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage2 Interface


IWMDMStorage2::SetAttributes2 (deprecated)

The SetAttributes2 method sets extended attributes of the storage.

Syntax

HRESULT SetAttributes2(
  DWORD  dwAttributes,
  DWORD  dwAttributesEx,
  _WAVEFORMATEX*  pFormat,
  _VIDEOINFOHEADER*  pVideoFormat
);

Parameters

dwAttributes

[in] DWORD specifying the base attributes defined in the IWMDMStorage::SetAttributes method.

dwAttributesEx

[in] DWORD specifying extended attributes. Currently, no extended attributes are defined.

pFormat

[out] Optional pointer to a _WAVEFORMATEX structure that specifies audio information about the object. This parameter is ignored if the file is not audio.

pVideoFormat

[in] Optional pointer to a _VIDEOINFOHEADER structure that specifies video information about the object. This parameter is ignored if the file is not video.

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.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage2 Interface
  • IWMDMStorage2::GetAttributes2


IWMDMStorage3 Interface (deprecated)

The IWMDMStorage3 interface extends IWMDMStorage2 by exposing metadata.

In addition to the methods inherited from IWMDMStorage2, the IWMDMStorage3 interface exposes the following methods.

Method | Description
CreateEmptyMetadataObject | Creates an object that supports the IWMDMMetaData interface.
GetMetadata | Retrieves the metadata associated with the storage.
SetEnumPreference | Sets the preferred enumeration mode for the storage.
SetMetadata | Sets metadata on the storage object.

See Also

  • Interfaces for Applications
  • IWMDMMetaData Interface
  • IWMDMStorage Interface
  • IWMDMStorage2 Interface


IWMDMStorage3::CreateEmptyMetadataObject (deprecated)

The CreateEmptyMetadataObject method creates a new IWMDMMetaData interface. This interface is used to set or retrieve metadata properties of a storage.

Syntax

HRESULT CreateEmptyMetadataObject(
  IWMDMMetaData**  ppMetadata
);

Parameters

ppMetadata

[out] Receives the new IWMDMMetaData interface. The caller must release this interface when done with it.

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.

Value | Description
S_OK | The method succeeded.

Remarks

The metadata interface created is not implicitly connected to the storage that created it; it is merely an empty metadata container. You must submit the interface to a method to set or retrieve metadata values.

Example Code

The following C++ function sends a file to a device. As part of the transfer, it must add metadata to the storage to specify the new storage type.

HRESULT mySendFile(LPCWSTR pwszFileName, IWMDMStorage* pStorage, IWMDMOperation* pOperation)
{
   HRESULT hr = S_OK;

   // A dummy loop to handle unrecoverable errors. When we hit an error we
   // can't handle or don't like, we just use a 'break' statement.
   // The custom BREAK_HR macro checks for failed HRESULT values and does this.
   do
   {
      if (pwszFileName == NULL || pStorage == NULL)
      {
         BREAK_HR(E_POINTER,"","Bad pointer passed in.");
         return E_POINTER;
      }

      // Make sure the destination is a folder.
      DWORD attributes = 0;
      _WAVEFORMATEX format;
      hr = pStorage->GetAttributes(&attributes, &format);
      if (!(attributes | WMDM_FILE_ATTR_FOLDER))
      {
         BREAK_HR(E_FAIL, "", "Storage submitted to mySendFile is not a folder.");
         return E_FAIL;
      }

      // Transcode the file
      hr = myTranscodeMethod(pwszFileName);
      BREAK_HR(hr, "Couldn't transcode the file in mySendFile.", "Transcoded the file in mySendFile.");
      //
      // Let's set some metadata in the storage.
      //
      CComPtr<IWMDMStorage3> pStorage3;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorage3), (void**)(&pStorage3));
      BREAK_HR(hr, "Got an IWMDMStorage3 interface in mySendFile.","Couldn't get an IWMDMStorage3 in mySendFile.");

      // First create the IWMDMMetaData interface.
      IWMDMMetaData* pMetadata;
      hr = pStorage3->CreateEmptyMetadataObject(&pMetadata);
      BREAK_HR(hr,"Created an IWMDMMetaData interface in mySendFile.","Couldn't create an IWMDMMetaData interface in mySendFile.");

      //
      // Set the file format.
      //
      WMDM_FORMATCODE fileFormat = myGetWMDM_FORMATCODE(pwszFileName);
      hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMFormatCode, (BYTE*)&fileFormat, sizeof(WMDM_TYPE_DWORD));

      //
      // Get the proper interface and transfer the file.
      //
      CComPtr<IWMDMStorageControl3> pStgCtl3;
      CComPtr<IWMDMStorage> pNewStorage;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorageControl3),(void**)(&pStgCtl3));

      // Get the simple file name to use for the destination file.
      wstring destFile = pwszFileName;
      destFile = destFile.substr(destFile.find_last_of(L"\\") + 1);

      // Get a progress indicator.
      CComQIPtr<IWMDMProgress> pProgress(this);

      // Set the flags for the operation
      UINT flags = WMDM_MODE_BLOCK | // Synchronous call.
         WMDM_STORAGECONTROL_INSERTINTO | // Insert it into the destination folder.
         WMDM_CONTENT_FILE | // We're inserting a file.
         WMDM_FILE_CREATE_OVERWRITE; // Overwrite existing files.
      if (pOperation != NULL)
         flags |= WMDM_CONTENT_OPERATIONINTERFACE;

      // Send the file and metadata.
      hr = pStgCtl3->Insert3(
         flags,
         WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
         const_cast<WCHAR*>(pwszFileName), // Source file.
         NULL, // Destination file name.
         pOperation, // Null to allow WMDM to read the file; non-null to present raw data bytes to WMDM.
         pProgress, // Interface to send simple progress notifications.
         pMetadata, // IWMDMMetaData interface previously created and filled.
         NULL,
         &pNewStorage);
      if (FAILED(hr))
         m_pLogger->LogDword(WMDM_LOG_SEV_ERROR, NULL, "Error calling Insert3 in mySendFile: %lX", hr);
      BREAK_HR(hr, "Wrote a file to the device in mySendFile", "Couldn't write to the device in mySendFile.");

   } while (FALSE); // End of dummy loop

   return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • IWMDMStorage3 Interface
  • IWMDMStorageControl3::Insert3
  • Setting Metadata on a File


IWMDMStorage3::GetMetadata (deprecated)

The GetMetadata method retrieves the metadata associated with the storage.

Syntax

HRESULT GetMetadata(
  IWMDMMetaData**  ppMetadata
);

Parameters

ppMetadata

[out] Pointer to an IWMDMMetaData pointer associated with a storage. The caller is responsible for calling Release on this interface and all the allocated values when finished with it, as described under "Clearing allocated memory" in Discovering Device Format Capabilities.

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 it fails with an error, it returns a standard error code.

Return code | Description
S_OK | The method succeeded.
WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED | Not all the requested properties could be retrieved by the device.

Remarks

This method retrieves all metadata associated with the storage. If an application is seeking specific metadata, it might be more efficient to call IWMDMStorage4::GetSpecifiedMetadata.

When retrieving data from a Windows Portable Devices (WPD) device, the data is returned in binary form. The application should de-serialize this data to obtain the actual property values.

Example Code

The following C++ function retrieves all the metadata associated with a storage.

// Function to print out all the metadata associated with a storage.
HRESULT CWMDMController::GetMetadata(IWMDMStorage *pStorage)
{
   HRESULT hr = S_OK;

   // A dummy loop to handle unrecoverable errors. When we hit an error we
   // can't handle or don't like, we just use a 'break' statement.
   // The custom BREAK_HR macro checks for failed HRESULT values and does this.
   do
   {
      CComPtr<IWMDMStorage3> pStorage3;
      CComPtr<IWMDMMetaData> pMetadata;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorage3), (void**)&pStorage3);
      BREAK_HR(hr, "Got an IWMDMStorage3 interface in GetMetadata.", "Couldn't get an IWMDMStorage3 interface in GetMetadata.");

      hr = pStorage3->GetMetadata(&pMetadata);
      BREAK_HR(hr, "Got an IWMDMMetaData interface in GetMetadata.", "Couldn't get an IWMDMMetaData interface in GetMetadata.");

      //
      // Loop through all metadata properties, and print out the value of each.
      //
      BYTE* value;
      WMDM_TAG_DATATYPE type;
      UINT len = 0;
      UINT count = 0;
      WCHAR* name;
      // Get the number of metadata items.
      hr = pMetadata->GetItemCount(&count);

      BREAK_HR(hr, "Got a metadata count in GetMetadata.", "Couldn't get a metadata count in GetMetadata.");
      for(;count > 0; count--)
      {
         // Get the metadata property by index.
         WCHAR* name;
         hr = pMetadata->QueryByIndex(count-1, &name, &type, &value, &len);
         if (SUCCEEDED(hr))
         {
            // TODO: Display the property name.
            CoTaskMemFree(name);

            // Print out the value of the property, according to the value type.
            switch (type)
            {
            case WMDM_TYPE_QWORD:
            case WMDM_TYPE_DWORD:
            case WMDM_TYPE_WORD:
               // TODO: Display the value.
               break;
            case WMDM_TYPE_STRING:
               // TODO: Display the value.
               // Release the method-allocated property value memory.
                    if (SUCCEEDED(hr))
                        CoTaskMemFree(value);
               break;
            case WMDM_TYPE_BOOL:
               // TODO: Display the value.
               break;
            case WMDM_TYPE_BINARY:
               // TODO: Display the value.
               break;
            case WMDM_TYPE_DATE:
               {
                  WMDMDATETIME *val = (WMDMDATETIME*)value;
                        // TODO: Display the month, day, and year.
               }
               break;
            case WMDM_TYPE_GUID:
               {
                  WCHAR strGuid[64];
                  StringFromGUID2(reinterpret_cast<GUID&>(value),(LPOLESTR)strGuid, 64);
                  // TODO: Display the GUID value.
               }
               break;
            default:
               // TODO: Display the message: "Could not understand the returned value type
            }
         }
         else // Couldn't get the metadata property at index count - 1.
            // TODO: Display the message:
            // "Couldn't get a value for index "
            // followed by the current index value.
      }

      // Now get a specific property by name.
      // If this property isn't supported, the method returns E_INVALIDARG.
      hr = pMetadata->QueryByName(g_wszWMDMFileName, &type, &value, &len);
      if (hr == S_OK)
      {
         wstring wstr((wchar_t*)value, len / 2); // Create a string from the name.
            // TODO: Display the file name.
            CoTaskMemFree(value);
      }

      // See if file is DRM-protected.
      hr = pMetadata->QueryByName(g_wszWMDMIsProtected, &type, &value, &len);
      if (hr == S_OK)
      {
         // TODO: Display a message that the object is DRM protected.
      }

   }while(FALSE);// End of dummy loop.

   // Clean up and return.
   return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • IWMDMStorage3 Interface
  • IWMDMStorage3::SetMetadata
  • IWMDMStorage4::GetSpecifiedMetadata


IWMDMStorage3::SetEnumPreference (deprecated)

The SetEnumPreference method sets the preferred view mode for the storage.

Syntax

HRESULT SetEnumPreference(
  WMDM_STORAGE_ENUM_MODE*  pMode,
  DWORD  nViews,
  WMDMMetadataView*  ppViews
);

Parameters

pMode

[in, out] Desired mode of the storage enumerator. For more details on the mode, see WMDM_STORAGE_ENUM_MODE. If the value of pMode is set to ENUM_MODE_USE_DEVICE_PREF, then upon return it is set to ENUM_MODE_RAW or ENUM_MODE_METADATA_VIEWS, based on the device preference.

nViews

[in] Number of view definitions provided.

This parameter is ignored if the value of pMode is ENUM_MODE_RAW or if the value of pMode is ENUM_MODE_USE_DEVICE_PREF and the device does not prefer metadata views.

If the value of pMode is ENUM_MODE_METADATA_VIEWS or if the value of pMode is ENUM_MODE_USE_DEVICE_PREF and the device prefers metadata views, this parameter can still be 0. In this case, Windows Media Device Manager uses its default metadata views.

If the value of nViews is 0, ppViews must be NULL. If the value of nViews is not 0, ppViews must point to an array of WMDMMetadataView structures with nViews elements.

ppViews

[in] Array of view definitions. The length of the array must be equal to nViews.

This parameter is ignored if the value of pMode is ENUM_MODE_RAW or if the value of pMode is ENUM_MODE_USE_DEVICE_PREF and the device does not prefer metadata views.

If the value of pMode is ENUM_MODE_METADATA_VIEWS or if the value of pMode is ENUM_MODE_USE_DEVICE_PREF and the device prefers metadata views, this parameter can still be NULL. In this case Windows Media Device Manager uses its default metadata views.

The value of this parameter must be NULL if the value of nViews is 0. If the value of nViews is not 0, ppViews must point to an array of WMDMMetadataView structures with nViews elements.

Return Values

The method returns an HRESULT. The following table lists all possible values.

Return code | Description
S_OK | The method succeeded.
E_OUTOFMEMORY | There is not enough memory to allocate the item.
E_INVALIDARG | One or more parameters are invalid.
WMDM_E_NOT_CERTIFIED | The caller does not have the rights to execute this operation.
WMDM_E_NOTSUPPORTED | The object does not support this method.
E_FAIL | An unspecified error occurred.

Remarks

Windows Media Device Manager can present metadata views of the content on the device. It walks through all the content on a top-level storage (such as internal memory or a storage card) and returns a storage enumerator that presents the content organized by the metadata of the content. The definition of a metadata view is provided through a WMDMMetadataView structure.

This behavior is controlled by the pMode parameter. If the pMode is set to ENUM_MODE_RAW, Windows Media Device Manager returns an enumerator that mirrors the hierarchy of the file system on the storage of the device. If the pMode is set to ENUM_MODE_METADATA_VIEWS, Windows Media Device Manager generates metadata views.

Devices indicate their preference by setting the device parameter UseMetadataViews at the time the device is installed. For more information about UseMetadataViews, see Device Parameters. If the application will let the device decide on the kind of storage enumerator returned, it should set pMode to ENUM_MODE_USE_DEVICE_PREF.

After this method is called, later calls to IWMDMStorage::EnumStorage will behave according to the storage enumeration preference set by this method. This method can be called again to change the behavior of subsequent IWMDMStorage::EnumStorage calls.

This method should typically be called on the top-level storage. If this method is called on any of the storages in metadata view, it will return WMDM_E_NOTSUPPORTED.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • IWMDMStorage Interface
  • IWMDMStorage::EnumStorage
  • WMDMMetadataView


IWMDMStorage3::SetMetadata (deprecated)

The SetMetadata method sets metadata on the storage.

Syntax

HRESULT SetMetadata(
  IWMDMMetaData*  pMetadata
);

Parameters

pMetadata

[in] An IWMDMMetaData pointer containing metadata to set on the object. To create this interface, call CreateEmptyMetadataObject.

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 it fails with an error, it returns a standard error code.

Return code | Description
S_OK | The method succeeded.
WMDM_S_NOT_ALL_PROPERTIES_APPLIED | Not all the requested properties could be applied.

Remarks

Existing properties in the storage with the same name are overwritten. All other existing properties are not modified or lost.

To set properties for a Windows Portable Devices (WPD) device, an application would create an IPortableDeviceValues object and set each property into this collection. Then, the application would serialize the collection to a binary large object (BLOB). Once the data is serialized, the application would add it to the IWMDMMetaData referenced by the pMetadata argument using the g_wszWPDPassthroughPropertyValues metadata constant.

Example Code

The following C++ code adds a subtitle as metadata to a storage (pStorage3) using the IWMDMMetaData interface retrieved from the storage previously (not shown).

// Set metadata values on a storage.
WCHAR* station = L"Mysubtitle";
UINT numBytes = (wcslen(station) + 1) * sizeof(WCHAR); // WCHAR string is 2 * length of characters long
                                                       // plus the terminating null character.
hr = pMetadata->AddItem(WMDM_TYPE_STRING, g_wszWMDMMediaStationName, (BYTE*)station, numBytes) ;
BREAK_HR(hr, "Added a metadata value to the interface in TestUpdateMetadata.", "Couldn't add a metadata value to the interface in TestUpdateMetadata.");

// Add the metadata to the storage.
hr = pStorage3->SetMetadata(pMetadata);
BREAK_HR(hr, "Set metadata on the storage in TestUpdateMetadata.", "Couldn't set metadata on the storage in TestUpdateMetadata: " << hex << hr << dec);

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMMetaData Interface
  • IWMDMStorage3 Interface
  • IWMDMStorage3::GetMetadata
  • Setting Metadata on a File


IWMDMStorage4 Interface (deprecated)

The IWMDMStorage4 interface extends IWMDMStorage3 by providing methods for retrieving a subset of available metadata for a storage, and for setting and retrieving a list of references to other storages.

In addition to the methods inherited from IWMDMStorage3, the IWMDMStorage4 interface exposes the following methods.

Method | Description
FindStorage | Retrieves a storage in the current root storage by its unique identification (ID).
GetParent | Retrieves the parent of the storage.
GetReferences | Retrieves an array of pointers to IWMDMStorage pointed to by this storage.
GetRightsWithProgress | Retrieves the rights information for the storage object, providing a callback mechanism for monitoring progress.
GetSpecifiedMetadata | Retrieves one or more specific metadata properties from the storage.
SetReferences | Sets the references contained in a storage that has references (such as a playlist or album), overwriting any previously existing references held by the storage.

See Also

  • IWMDMStorage Interface
  • IWMDMStorage2 Interface
  • IWMDMStorage3 Interface
  • Interfaces for Applications


IWMDMStorage4::FindStorage (deprecated)

The FindStorage method retrieves a storage in the current root storage, based on its persistent unique identifier.

Syntax

HRESULT FindStorage(
  WMDM_FIND_SCOPE  findScope,
  LPCWSTR  pwszUniqueID,
  IWMDMStorage**  ppStorage
);

Parameters

findScope

[in] A WMDM_FIND_SCOPE enumeration specifying the scope to search.

pwszUniqueID

[in] Persistent unique identifier of the storage to be found. The persistent unique identifier of the storage is described by the g_wszWMDMPersistentUniqueID metadata property of the storage.

ppStorage

[out] Pointer to the retrieved storage, if found. The caller must release this interface when done with it.

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 and storage matching the persistent unique identifier was found.
E_INVALIDARG | The findScope is not valid, or pwszUniqueID or ppStorage is NULL.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND) | No storage found with the specified persistent unique identifier.

Remarks

This method only searches a single memory object (flash card or hard disc) on the device.

A persistent unique identifier identifies content stored on a particular device. It does not represent a content-specific globally unique identifier that remains identical across all devices. Thus, the same content stored in different storages will have different persistent unique identifiers. Similarly, different content may have the same persistent unique identifier when stored on different devices.

The format of the persistent unique identifier depends on the device. The application must have obtained the persistent unique identifier previously by obtaining a storage and querying it for its WMDM/PersistentUniqueID property. Use the GetSpecifiedMetadata or GetMetadata methods to request this property.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::FindStorage
  • IWMDMStorage3::GetMetadata
  • IWMDMStorage4 Interface
  • IWMDMStorage4::GetSpecifiedMetadata
  • WMDM_FIND_SCOPE


IWMDMStorage4::GetParent (deprecated)

The GetParent method retrieves the parent of the storage.

Syntax

HRESULT GetParent(
  IWMDMStorage**  ppStorage
);

Parameters

ppStorage

[out] Pointer to the IWMDMStorage interface of the parent storage. The caller must release this interface when finished with it.

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 and ppStorage holds the IWMDMStorage pointer to the parent object.
S_FALSE | Current storage is the root storage and therefore has no parent. In this case, ppStorage is set to NULL.

Remarks

The application can navigate up the storage hierarchy by calling GetParent recursively. After the root storage is reached, GetParent returns S_FALSE and sets ppStorage to NULL.

Example Code

The following C++ function traverses up to the root parent of a storage.

HRESULT BubbleUp(IWMDMStorage *pIStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage4> pStorage4;

    hr = pIStorage->QueryInterface (__uuidof(IWMDMStorage4), reinterpret_cast<void**>(&pStorage4));
    if (SUCCEEDED(hr))
    {
        while ((pStorage4 != NULL))
        {
            CComPtr<IWMDMStorage> pParent;
            hr = pStorage4->GetParent(&pParent);
            if (FAILED(hr))
            {
                break;
            }

            //
            // Do something with pParent....
            //

            if (S_FALSE != hr)
            {
                hr = pParent->QueryInterface (__uuidof(IMDSPStorage4), reinterpret_cast<void**>(&pStorage4));
                if (FAILED(hr))
                {
                    break;
                }
            }
        } // Loop up to next parent.
    }

    return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage4 Interface


IWMDMStorage4::GetReferences (deprecated)

The GetReferences method retrieves an array of pointers to IWMDMStorage objects pointed to by this storage. An abstract album or playlist is typically stored as a collection of references on an MTP device.

Syntax

HRESULT GetReferences(
  DWORD*  pdwRefs,
  IWMDMStorage***  pppIWMDMStorage
);

Parameters

pdwRefs

[out] Pointer to the count of values retrieved by pppIWMDMStorage. If the object has no references, this will return zero, and the function will return S_OK.

pppIWMDMStorage

[out] Pointer to a pointer to the array of IWMDMStorage interface pointers that represent references in a storage. Such references can, for example, represent items in a playlist or album. The retrieved array is in the same order as they appear in the object itself. Memory for this array is allocated by Windows Media Device Manager. When the calling application has finished accessing this array, it must first call Release on all of the interface pointers, and then free the array memory using CoTaskMemFree.

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.
S_FALSE | The method succeeded. However, one or more items referenced by the storage on the device side have been deleted since the last call to SetReferences.
E_INVALIDARG | Either pointer pdwRefs or pppIWMDMStorage is NULL.
E_OUTOFMEMORY | Method could not be completed due to insufficient memory.
WMDM_E_INTERFACEDEAD | The storage interface represented by this IWMDMStorage4 interface has been deleted.

Remarks

Windows Media Device Manager delegates to the underlying service provider the task of adding and removing the references on a storage. Objects with references refers to abstract objects such as abstract playlists or albums; folders are not considered as having references.

There are two types of asynchronous deletions that can occur and cause errors in this method. If a reference to a storage has been deleted since the application retrieved it, and the application tries to use the reference, the method call will return WMDM_E_INTERFACEDEAD. If the file the reference refers to has been deleted, S_FALSE is returned.

Example Code

The following C++ code queries for the references of a storage (pStorage).

// Get references.
CComQIPtr<IWMDMStorage4> pStorage4(pStorage);
if (pStorage4 != NULL)
{
    WCHAR name[100];
    DWORD numRefs = 0;
    IWMDMStorage** parrReferences;
    hr = pStorage4->GetReferences(&numRefs, &parrReferences);
    for(int i = 0; i < numRefs; i++)
    {
        ZeroMemory(name, sizeof(name));
        hr = parrReferences[i]->GetName(name, (sizeof(name) / sizeof(WCHAR)) - 1);
        if (hr == S_OK)
            // TODO: Display the name.
        parrReferences[i]->Release();
    }
    // Free the memory.
    if (parrReferences != NULL)
        CoTaskMemFree(parrReferences);
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Creating a Playlist on the Device
  • IWMDMStorage4 Interface
  • IWMDMStorage4::SetReferences


IWMDMStorage4::GetRightsWithProgress (deprecated)

The GetRightsWithProgress method retrieves the rights information for the storage object, providing a callback mechanism for monitoring progress.

Syntax

HRESULT GetRightsWithProgress(
  IWMDMProgress3*  pIProgressCallback,
  PWMDMRIGHTS*  ppRights,
  UINT*  pnRightsCount
);

Parameters

pIProgressCallback

[in] Optional pointer to an IWMDMProgress3 interface to be used by Windows Media Device Manager to report progress back to the application.

ppRights

[out] Pointer to an array of WMDMRIGHTS structures that contain the storage object rights information. Memory for this array is allocated by Windows Media Device Manager. When the calling application has finished accessing this array, the memory must be freed by using CoTaskMemFree.

pnRightsCount

[out] Pointer to the number of WMDMRIGHTS structures in the ppRights array.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | Either ppRights or pnRightsCount is NULL.
WMDM_E_NOTSUPPORTED | Rights are not supported for this object.
WMDM_E_NOTCERTIFIED | The caller is not certified.
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

Object rights describe the usage permissions for digital media content. For example, the WMDMRIGHTS structure can contain information concerning how many times a file can be played and who can play it.

Retrieving rights from a licensed file can sometimes be a lengthy request; this function allows a rights request to be performed asynchronously.

The secure content provider can generate event notifications on the callback pIProgressCallback in addition to the progress notifications. Examples of such events include acquiring a secure clock, initializing DRM, and so on. These events are described in IWMDMProgress3::Progress3.

This method is identical to IWMDMStorage::GetRights, except it returns progress, and does not provide a MAC for parameter verification.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorage4 Interface


IWMDMStorage4::GetSpecifiedMetadata (deprecated)

The GetSpecifiedMetadata method retrieves one or more specific metadata properties from the storage.

Syntax

HRESULT GetSpecifiedMetadata(
  DWORD  cProperties,
  LPCWSTR*  ppwszPropNames,
  IWMDMMetaData**  ppMetadata
);

Parameters

cProperties

[in] Count of properties to retrieve.

ppwszPropNames

[in] Array of property names to retrieve. The length of this array should be equal to cProperties. The application should free this memory using CoTaskMemFree.

ppMetadata

[out] Pointer to the returned IWMDMMetaData interface pointer, containing the retrieved values. The caller must release this interface when finished with it.

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.
WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED | The method succeeded but only some of the requested properties were retuned.
E_INVALIDARG | This value is returned if either of the following is true: i) One of cProperties and ppwszPropNames is zero while the other is non-zero. ii) None of the properties requested are supported by the storage.
WMDM_E_NOTSUPPORTED | None of the properties was returned by the device. It is possible that one or more properties are supported by the device but could not be returned at this time.

Remarks

This method gives the client control over which properties are retrieved. This can be more efficient than IWMDMStorage3::GetMetadata, and is recommended when the client needs only a subset of properties supported by the storage.

If this method is used to retrieve data from a Windows Portable Devices (WPD) device, the data is returned in binary form in an IPortableDeviceValues object. The application should de-serialize this data in order to obtain the actual property values.

The method succeeds and returns WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED even if some of the specified properties could not be retrieved (but at least one property was retrieved). The method fails and returns WMDM_E_NOTSUPPORTED if none of the specified properties could be retrieved.

Requesting a single property is a special case of this method. If the client requests a single property, the possible return codes are S_OK, E_INVALIDARG, and WMDM_E_NOTSUPPORTED. Thus, in the case of a single property, the method succeeds only if the property is successfully retrieved.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Creating a Playlist on the Device
  • IWMDMMetaData Interface
  • IWMDMStorage3::GetMetadata
  • IWMDMStorage4 Interface
  • Metadata Constants


IWMDMStorage4::SetReferences (deprecated)

The SetReferences method sets the references contained in a storage that has references (such as a playlist or album), overwriting any previously existing references held by the storage.

Syntax

HRESULT SetReferences(
  DWORD  dwRefs,
  IWMDMStorage**  ppIWMDMStorage
);

Parameters

dwRefs

[in] Count of IWMDMStorage interface pointers in ppIWMDMStorage. Zero is an acceptable value and clears all references from the storage. The storage itself is not deleted in this case.

ppIWMDMStorage

[in] Pointer to an array of IWMDMStorage interface pointers to be referenced by the storage. This order is preserved by the storage. NULL is an acceptable value if dwRefs is also zero. The caller is responsible for allocating and releasing this array.

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 | The dwRefs is non-zero and ppIWMDMStorage is NULL.
E_OUTOFMEMORY | Method could not be completed due to insufficient memory.
WMDM_E_INTERFACEDEAD | The object represented by this interface has been deleted.
E_NOINTERFACE | The device does not support metadata.

Remarks

This method is used to set references in objects that are composed of references, such as playlists or albums. If a device does not support metadata, this method will probably not be supported.

Any valid IWMDMStorage object can be contained in the ppIWMDMStorage array. This includes folders and other storages specifying references themselves (creating, for example, a playlist of playlists). The device itself determines how any particular case of referent object is handled. Windows Media Device Manager does not enforce any rules beyond that of IWMDMStorage validity. Consider the case of a playlist containing nested playlist references. On one device, this is disallowed and SetReferences fails. On another device, this is allowed; playback simply traverses the entire set of contained references in depth-first order.

The situation may arise where an IWMDMStorage4 interface pointer corresponds to a storage that no longer exists on the device. WMDM_E_INTERFACEDEAD is returned in this case.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Creating a Playlist on the Device
  • IWMDMStorage4 Interface
  • IWMDMStorage4::GetReferences


IWMDMStorageControl Interface (deprecated)

The IWMDMStorageControl interface is used to insert, delete, or move files within a storage, a device, or between a device and the computer.

In addition to the methods inherited from IUnknown, the IWMDMStorageControl interface exposes the following methods.

Method | Description
Delete | Permanently deletes this storage.
Insert | Puts content into the storage on the device.
Move | Moves the storage to a new location on the device.
Read | Copies the current storage to the computer.
Rename | Renames the current storage.

See Also

  • Interfaces for Applications
  • IWMDMStorageControl2 Interface
  • IWMDMStorageControl3 Interface


IWMDMStorageControl::Delete (deprecated)

The Delete method permanently deletes this storage.

Syntax

HRESULT Delete(
  UINT  fuMode,
  IWMDMProgress*  pProgress
);

Parameters

fuMode

[in] One or two of the following flags, combined with a bitwise OR. Specify exactly one of the first two modes; the third mode is optional.

Mode | Description
WMDM_MODE_BLOCK | The operation is performed using block mode (synchronous) processing. The call will not return until the operation is finished.
WMDM_MODE_THREAD | The operation is performed using thread mode (asynchronous) processing. The call will return immediately, and the operation is performed in a background thread.
WMDM_MODE_RECURSIVE | If the storage object is a folder, it and its contents, and all subfolders and their contents are deleted.

pProgress

[in] Optional pointer to an IWMDMProgress interface to be used by Windows Media Device Manager to report progress back to the application.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

When the Delete operation is finished, all references to the deleted object become invalid. The application must release these interfaces and any other interfaces or resources associated with the object.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the delete operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice::GetStatus
  • IWMDMStorage Interface
  • IWMDMStorageControl Interface
  • IWMDMStorageGlobals::GetStatus


IWMDMStorageControl::Insert (deprecated)

The Insert method puts content into the storage on the device.

Syntax

HRESULT Insert(
  UINT  fuMode,
  LPWSTR  pwszFile,
  IWMDMOperation*  pOperation,
  IWMDMProgress* pProgress,
  IWMDMStorage**  ppNewObject
);

Parameters

fuMode

[in] A bitwise OR of the following values. The following table lists the processing modes that can be specified in the fuMode parameter. You must specify exactly one of the first two modes, exactly one of the STORAGECONTROL modes, and exactly one of the CONTENT modes. If both WMDM_MODE_BLOCK and WMDM_MODE_THREAD are specified, block mode is used.

Combinations | Mode | Description
Exactly one of: | WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
 | WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call will return immediately, and the operation is performed in a background thread.
Exactly one of: | WMDM_STORAGECONTROL_INSERTBEFORE | The object is inserted before the current object.
 | WMDM_STORAGECONTROL_INSERTAFTER | The object is inserted after the current object.
 | WMDM_STORAGECONTROL_INSERTINTO | The object is inserted into the current object. This will only work if the current object is a folder.
Exactly one of: | WMDM_CONTENT_FILE | The content being inserted is a file.
 | WMDM_CONTENT_FOLDER | The content being inserted is a folder. This will not transfer the contents of the folder.
 | WMDM_CONTENT_OPERATIONINTERFACE | The content being inserted is an operation interface. The data for the content should be written to the application-implemented IWMDMOperation interface.
Zero or more of: | WMDM_FILE_CREATE_OVERWRITE | The object will replace the current object.
 | WMDM_MODE_QUERY | A test is performed to determine whether the insert operation could succeed, but the insert will not be performed.
 | WMDM_MODE_PROGRESS | The method should return progress notifications through pProgress.
Zero or one of: | WMDM_MODE_TRANSFER_PROTECTED | The insertion is in protected transfer mode.
 | WMDM_MODE_TRANSFER_UNPROTECTED | The insertion is in unprotected transfer mode.

pwszFile

[in] Pointer to a wide-character null-terminated string indicating where to find the content for the insert operation. This parameter must be NULL if WMDM_CONTENT_OPERATIONINTERFACE is specified in fuMode.

pOperation

[in] Optional pointer to an IWMDMOperation interface, to control the transfer of content to a media device. If specified, fuMode must include the WMDM_CONTENT_OPERATIONINTERFACE flag. This parameter must be NULL if WMDM_CONTENT_FILE or WMDM_CONTENT_FOLDER is specified in fuMode.

pProgress

[in] Optional pointer to an IWMDMProgress interface to be used by Windows Media Device Manager to report progress back to the application. If this is used, fuMode should include WMDM_MODE_PROGRESS.

ppNewObject

[out] Pointer to an IWMDMStorage interface that will contain the new content. The caller must release this interface when finished with it.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | Some of the input parameters are invalid or NULL.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

If the device supports IWMDMStorageControl3::Insert3, that is the preferred method to use.

The name and extension of the object saved on the device will be the same as the name and extension of the source file (if pOperation is NULL).

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

The Insert method does not guarantee that the device supports ordered file insertion, but it provides the flags WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERTAFTER in case it does. If the file system does not support ordering (for instance, FAT32), WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERTAFTER will simply insert the new storage object at the same level as the current object in the file system hierarchy.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the insert operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageControl Interface
  • IWMDMStorageControl::Read
  • IWMDMStorageControl2::Insert2
  • IWMDMStorageControl3::Insert3
  • Writing Files to the Device


IWMDMStorageControl::Move (deprecated)

The Move method moves the current storage to a new location on the device.

Syntax

HRESULT Move(
  UINT  fuMode,
  IWMDMStorage*  pTargetObject,
  IWMDMProgress*  pProgress
);

Parameters

fuMode

[in] Processing mode by which to invoke the Move operation and the type of move to make. Specify exactly one of the following two modes. If both modes are specified, block mode is used.

Mode | Description
WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call will return immediately, and the operation is performed in a background thread.

The following table lists flags that indicate where the object is moved to. One value from this table is combined with one value from the preceding Mode table using a bitwise OR.

Flag | Description
WMDM_STORAGECONTROL_INSERTBEFORE | The object is inserted before the target object.
WMDM_STORAGECONTROL_INSERTINTO | The object is inserted into the target object.
WMDM_STORAGECONTROL_INSERTAFTER | The object is inserted after the target object.

pTargetObject

[in] Pointer to the object before or after which you want to put the current object.

pProgress

[in] Optional pointer to an IWMDMProgress interface that has been implemented by the application to track the progress of an ongoing operation.

Return Values

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:

Return code | Description
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | Some of the input parameters are invalid or NULL.

Remarks

A file or directory can be moved only within the same root storage.

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the move operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice::GetStatus
  • IWMDMProgress Interface
  • IWMDMStorage Interface
  • IWMDMStorageControl Interface


IWMDMStorageControl::Read (deprecated)

The Read method copies the current storage to the computer.

Syntax

HRESULT Read(
  UINT  fuMode,
  LPWSTR  pwszFilename,
  IWMDMProgress*  pProgress,
  IWMDMOperation*  pOperation
);

Parameters

fuMode

[in] Processing mode used for the Read operation. The following table lists the processing modes that can be specified in the fuMode parameter. You must specify exactly one of the first two modes, and exactly one of the last three (WMDM_CONTENT) modes. If both WMDM_MODE_BLOCK and WMDM_MODE_THREAD are specified, block mode is used.

Mode | Description
WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call will return immediately, and the operation is performed in a background thread.
WMDM_CONTENT_FILE | The caller requests that Windows Media Device Manager read the file from the portable device into a file on the hard disk. The caller should indicate, in the pwszFileName parameter, the full path and name of the file.
WMDM_CONTENT_FOLDER | The caller requests that Windows Media Device Manager read the specified folder, the contents, of the folder and the contents of any subfolders from the portable device onto the hard disk. The caller should indicate the full path of the target directory on the hard disk in the pwszFileName parameter. This is not currently supported by any Microsoft-provided service providers.
WMDM_CONTENT_OPERATIONINTERFACE | The application-implemented IWMDMOperation interface is being used to read data, instead of passing in a file name.

pwszFilename

[in] Pointer to a fully-qualified file name on the computer to which the content from the portable device is copied. The file name should include an extension; the extension from the current storage on the device will not be used. If WMDM_CONTENT_OPERATIONINTERFACE is specified in fuMode, this parameter is ignored.

pProgress

[in] Optional pointer to a IWMDMProgress interface that has been implemented by the application to track the progress of ongoing operations.

pOperation

[in] Optional pointer to an IWMDMOperation interface, an optional set of methods used to enhance the transfer of content from a media device. This parameter must be NULL if WMDM_CONTENT_FILE or WMDM_CONTENT_FOLDER is specified in fuMode.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | One or more parameters are invalid or NULL.
E_NOTCERTIFIED | Permission to read has been denied.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

This method will automatically overwrite existing files specified by pwszFilename. It can succeed even if

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the read operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice::GetStatus
  • IWMDMOperation Interface
  • IWMDMProgress Interface
  • IWMDMStorageControl Interface
  • IWMDMStorageControl::Insert


IWMDMStorageControl::Rename (deprecated)

The Rename method renames the current storage.

Syntax

HRESULT Rename(
  UINT  fuMode,
  LPWSTR  pwszNewName,
  IWMDMProgress*  pProgress
);

Parameters

fuMode

[in] Processing mode used for the Rename operation. Specify exactly one of the following two modes. If both modes are specified, block mode is used.

Mode | Description
WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call will return immediately, and the operation is performed in a background thread.

pwszNewName

[in] Pointer to a wide-character null-terminated string specifying the new name.

pProgress

[in] Optional pointer to an IWMDMProgress interface that has been implemented by the application to track the progress of the action.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | Renaming is not supported for this storage medium.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | One or more parameters is invalid or NULL.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified

Remarks

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the read operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice::GetStatus
  • IWMDMProgress Interface
  • IWMDMStorage Interface
  • IWMDMStorage::GetName
  • IWMDMStorageControl Interface


IWMDMStorageControl2 Interface (deprecated)

The IWMDMStorageControl2 interface extends IWMDMStorageControl by making it possible to set the name of the destination file when inserting content into a storage.

In addition to the methods inherited from IWMDMStorageControl, the IWMDMStorageControl2 interface exposes the following method.

Method | Description
Insert2 | Puts content into/next to the storage on the device.

See Also

  • Interfaces for Applications
  • IWMDMStorageControl Interface
  • IWMDMStorageControl3 Interface


IWMDMStorageControl2::Insert2 (deprecated)

The Insert2 method puts content into/next to the storage. This method extends IWMDMStorageControl::Insert by allowing the application to specify a new destination name, and provide a pointer to a custom COM object.

Syntax

HRESULT Insert2(
  UINT    fuMode,
  LPWSTR  pwszFileSource,
  LPWSTR  pwszFileDest,
  IWMDMOperation* pOperation,
  IWMDMProgress*  pProgress,
  IUnknown*       pUnknown,
  IWMDMStorage**  ppNewObject
);

Parameters

fuMode

[in] Processing mode used for the Insert2 operation. The following table lists the processing modes that can be specified in the fuMode parameter. You must specify exactly one of the first two modes, exactly one of the STORAGECONTROL modes, and exactly one of the CONTENT modes. If both WMDM_MODE_BLOCK and WMDM_MODE_THREAD are specified, block mode is used.

Combinations | Mode | Description
Exactly one of: | WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
- | WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call will return immediately, and the operation is performed in a background thread.
Optional | WMDM_MODE_QUERY | A test is performed to determine whether the insert operation could succeed, but the insert will not be performed.
Exactly one of: | WMDM_STORAGECONTROL_INSERTBEFORE | The object is inserted before the target object.
- | WMDM_STORAGECONTROL_INSERTAFTER | The object is inserted after the target object.
- | WMDM_STORAGECONTROL_INSERTINTO | The object is inserted into the current object. This will only work if the current object is a folder.
Optional | WMDM_FILE_CREATE_OVERWRITE | The object will replace the target object.
Exactly one of: | WMDM_CONTENT_FILE | The content being inserted is a file.
- | WMDM_CONTENT_FOLDER | The content being inserted is a folder. This will not transfer the contents of the folder.
Optional | WMDM_CONTENT_OPERATIONINTERFACE | The content being inserted is an operation interface. The data for the content should be written to the application-implemented IWMDMOperation interface.
Optional | WMDM_MODE_PROGRESS | Progress notifications should be sent through the pProgress parameter.
Optional one of: | WMDM_MODE_TRANSFER_PROTECTED | The insertion is in protected transfer mode.
- | WMDM_MODE_TRANSFER_UNPROTECTED | The insertion is in unprotected transfer mode.

pwszFileSource

[in] Pointer to a wide-character, null-terminated string indicating the full name and path of the object to send to the device. This parameter must be NULL if WMDM_CONTENT_OPERATIONINTERFACE is specified in fuMode.

pwszFileDest

[in] Optional name of file on the device. If not specified and the application passes an IWMDMOperation pointer to pOperation, Windows Media Device Manager will request a destination name by calling IWMDMOperation::GetObjectName. If not specified and the application does not use pOperation, the original file name and extension are used (without the path).

pOperation

[in] Optional pointer to an IWMDMOperation interface, to control the transfer of content to a media device. If specified, fuMode must include the WMDM_CONTENT_OPERATIONINTERFACE flag. This parameter must be NULL if WMDM_CONTENT_FILE or WMDM_CONTENT_FOLDER is specified in fuMode.

pProgress

[in] Optional pointer to an IWMDMProgress interface to report action progress back to the application. If specified, fuMode should include WMDM_MODE_PROGRESS.

pUnknown

[in] Optional IUnknown pointer of any custom COM object to be passed to the secure content provider. This makes it possible to pass custom information to a secure content provider if the application has sufficient information about the secure content provider.

ppNewObject

[out] Pointer to an IWMDMStorage interface that will contain the new content. The caller must release this interface when finished with it.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | Some of the input parameters are invalid or NULL.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

If the device supports IWMDMStorageControl3::Insert3, that is the preferred method to use.

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the insert operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice::GetStatus
  • IWMDMOperation Interface
  • IWMDMProgress Interface
  • IWMDMStorage Interface
  • IWMDMStorageControl2 Interface
  • IWMDMStorageControl3::Insert3


IWMDMStorageControl3 Interface (deprecated)

The IWMDMStorageControl3 interface extends IWMDMStorageControl2 by providing an Insert method that accepts an IWMDMMetaData interface pointer.

In addition to the methods inherited from IWMDMStorageControl2, the IWMDMStorageControl3 interface exposes the following method.

Method | Description
Insert3 | Puts content into/next to the storage. Extends IWMDMStorageControl2::Insert2 method by allowing the application to pass in an IWMDMMetaData interface pointer.

See Also

  • Interfaces for Applications
  • IWMDMStorageControl Interface
  • IWMDMStorageControl2 Interface


IWMDMStorageControl3::Insert3 (deprecated)

The Insert3 method puts content into/next to the storage. This method extends IWMDMStorageControl2::Insert2 by allowing the application to explicitly specify the metadata and type of the object being sent.

Syntax

HRESULT Insert3(
  UINT  fuMode,
  UINT  fuType,
  LPWSTR  pwszFileSource,
  LPWSTR  pwszFileDest,
  IWMDMOperation*  pOperation,
  IWMDMProgress*  pProgress,
  IWMDMMetaData*  pMetaData,
  IUnknown*  pUnknown,
  IWMDMStorage**  ppNewObject
);

Parameters

fuMode

[in] Processing mode used for the Insert3 operation. The following table lists the processing modes that can be specified in the fuMode parameter. You must specify exactly one of the first two modes, exactly one of the STORAGECONTROL modes, and exactly one of the CONTENT modes. If both WMDM_MODE_BLOCK and WMDM_MODE_THREAD are specified, block mode is used. Specifying the WMDM_FILE_ATTR* flags in this function is more efficient than calling this function first, then setting these attributes on the file after it has been created or sent.

Combinations | Mode | Description
Exactly one of: | WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
- | WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call will return immediately, and the operation is performed in a background thread.
Optional | WMDM_MODE_QUERY | A test is performed to determine whether the insert operation could succeed, but the insert will not be performed.
Exactly one of: | WMDM_STORAGECONTROL_INSERTBEFORE | The object is inserted before the target object.
- | WMDM_STORAGECONTROL_INSERTAFTER | The object is inserted after the target object.
- | WMDM_STORAGECONTROL_INSERTINTO | The object is inserted into the current object. This will only work if the current object is a folder.
Optional | WMDM_FILE_CREATE_OVERWRITE | The object will replace the target object.
Exactly one of: | WMDM_CONTENT_FILE | The content being inserted is a file.
- | WMDM_CONTENT_FOLDER | The content being inserted is a folder. This will not transfer the contents of the folder.
Optional | WMDM_CONTENT_OPERATIONINTERFACE | The application is passing in an IWMDMOperation interface to control data transfer.
Zero or more of: | WMDM_FILE_ATTR_READONLY | The storage should be set to read-only on the device.
- | WMDM_FILE_ATTR_HIDDEN | The storage should be set to hidden on the device.
- | WMDM_FILE_ATTR_SYSTEM | The storage should be set to system on the device.
Optional | WMDM_MODE_PROGRESS | The insertion is in progress.
Optional one of: | WMDM_MODE_TRANSFER_PROTECTED | The insertion is in protected transfer mode.
- | WMDM_MODE_TRANSFER_UNPROTECTED | The insertion is in unprotected transfer mode.

fuType

[in] One of the following types, specifying the current storage.

Value | Description
WMDM_FILE_ATTR_FILE | The current storage is a file.
WMDM_FILE_ATTR_FOLDER | The current storage is a folder.

pwszFileSource

[in] Pointer to a wide-character, null-terminated string indicating where to find the content for the insert operation. This parameter must be NULL if WMDM_CONTENT_OPERATIONINTERFACE is specified in fuMode. This parameter can be NULL if a playlist or album is being created.

pwszFileDest

[in] Optional name of file on the device. If not specified and the application passes an IWMDMOperation pointer to pOperation, Windows Media Device Manager will request a destination name by calling IWMDMOperation::GetObjectName. If not specified and the application does not use pOperation, the original file name and extension are used (without the path).

pOperation

[in] Optional pointer to an IWMDMOperation interface, to control the transfer of content to a media device. If specified, fuMode must include the WMDM_CONTENT_OPERATIONINTERFACE flag. This parameter must be NULL if WMDM_CONTENT_FILE or WMDM_CONTENT_FOLDER is specified in fuMode.

pProgress

[in] Optional pointer to an IWMDMProgress interface to report action progress back to the application. This parameter can be NULL.

pMetaData

[in] Optional pointer to a metadata object. Create a new metadata object by calling IWMDMStorage3::CreateEmptyMetadataObject. This parameter allows an application to specify metadata (including format) to set on the device during object creation on the device, which is more efficient than setting metadata afterward. You must set the file format (specified by g_wszWMDMFormatCode). If you do not specify the format code of a file when using this method, an MTP device will not show the file as present in its user interface, and non-MTP devices will behave unpredictably.

pUnknown

[in] Optional IUnknown pointer of any custom COM object to be passed to the secure content provider. This makes it possible to pass custom information to a secure content provider if the application has sufficient information about the secure content provider.

ppNewObject

[out] Pointer to an IWMDMStorage interface that will contain the new content. The caller must release this interface when finished with it.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | Some of the input parameters are invalid or NULL.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.
WMDM_E_INCORRECT_APPSEC | The application does not have the proper security level for some reason: for example, the application's transfer certificate does not have high enough permissions.

Remarks

Although you can set metadata on a storage after sending it to the device, it is more efficient to set this information in the pMetaData parameter of this method. Doing so provides additional information to the device to enable it to transfer and handle the file appropriately (for example, by storing it in the correct place) or display useful information (such as a user-written description of a picture).

To set properties for a Windows Portable Devices (WPD) device, an application would create an IPortableDeviceValues object and set each property into this collection. Then, the application would serialize the collection to a binary large object (BLOB). Once the data is serialized, the application would add it to the IWMDMMetaData referenced by the pMetadata argument using the g_wszWPDPassthroughPropertyValues metadata constant.

If the WMDM_MODE_THREAD flag is specified, you should obtain completion status by calling either IWMDMProgress2::End2 or IWMDMProgress3::End3. These methods will ensure that the operation is complete and will also return an HRESULT with success or failure information.

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the read operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an end notification. Failure to do this will result in access violations.

When creating a playlist or other reference object, the object being "inserted" actually contains no data but is simply stored on the device as a group of metadata references to other objects (such as music files). Creating such an "abstract" object on the playlist is described in Creating a Playlist on the Device.

Example Code

The following C++ function sends a file to a device. As part of the transfer, it must add metadata to the storage to specify the new storage type.

HRESULT mySendFile(LPCWSTR pwszFileName, IWMDMStorage* pStorage, IWMDMOperation* pOperation)
{
   HRESULT hr = S_OK;

   // A dummy loop to handle unrecoverable errors. When we hit an error we
   // can't handle or don't like, we just use a 'break' statement.
   // The custom BREAK_HR macro checks for failed HRESULT values and does this.
   do
   {
      if (pwszFileName == NULL || pStorage == NULL)
      {
         BREAK_HR(E_POINTER,"","Bad pointer passed in.");
         return E_POINTER;
      }

      // Make sure the destination is a folder.
      DWORD attributes = 0;
      _WAVEFORMATEX format;
      hr = pStorage->GetAttributes(&attributes, &format);
      if (!(attributes | WMDM_FILE_ATTR_FOLDER))
      {
         BREAK_HR(E_FAIL, "", "Storage submitted to mySendFile is not a folder.");
         return E_FAIL;
      }

      // Transcode the file
      hr = myTranscodeMethod(pwszFileName);
      BREAK_HR(hr, "Couldn't transcode the file in mySendFile.", "Transcoded the file in mySendFile.");
      //
      // Let's set some metadata in the storage.
      //
      CComPtr<IWMDMStorage3> pStorage3;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorage3), (void**)(&pStorage3));
      BREAK_HR(hr, "Got an IWMDMStorage3 interface in mySendFile.","Couldn't get an IWMDMStorage3 in mySendFile.");

      // First create the IWMDMMetaData interface.
      IWMDMMetaData* pMetadata;
      hr = pStorage3->CreateEmptyMetadataObject(&pMetadata);
      BREAK_HR(hr,"Created an IWMDMMetaData interface in mySendFile.","Couldn't create an IWMDMMetaData interface in mySendFile.");

      //
      // Set the file format.
      //
      WMDM_FORMATCODE fileFormat = myGetWMDM_FORMATCODE(pwszFileName);
      hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMFormatCode, (BYTE*)&fileFormat, sizeof(WMDM_TYPE_DWORD));

      //
      // Get the proper interface and transfer the file.
      //
      CComPtr<IWMDMStorageControl3> pStgCtl3;
      CComPtr<IWMDMStorage> pNewStorage;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorageControl3),(void**)(&pStgCtl3));

      // Get the simple file name to use for the destination file.
      wstring destFile = pwszFileName;
      destFile = destFile.substr(destFile.find_last_of(L"\\") + 1);

      // Get a progress indicator.
      CComQIPtr<IWMDMProgress> pProgress(this);

      // Set the flags for the operation.
      UINT flags = WMDM_MODE_BLOCK | // Synchronous call.
         WMDM_STORAGECONTROL_INSERTINTO | // Insert it into the destination folder.
         WMDM_CONTENT_FILE | // We're inserting a file.
         WMDM_FILE_CREATE_OVERWRITE; // Overwrite existing files.
      if (pOperation != NULL)
         flags |= WMDM_CONTENT_OPERATIONINTERFACE;

      // Send the file and metadata.
      hr = pStgCtl3->Insert3(
         flags,
         WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
         const_cast<WCHAR*>(pwszFileName), // Source file.
         NULL, // Destination file name.
         pOperation, // Null to allow Windows Media Device Manager to read
                     // the file; non-null to present raw data bytes to
                     // Windows Media Device Manager.
         pProgress, // Interface to send simple progress notifications.
         pMetadata, // IWMDMMetaData interface previously created and filled.
         NULL,
         &pNewStorage);
      if (FAILED(hr))
         m_pLogger->LogDword(WMDM_LOG_SEV_ERROR, NULL, "Error calling Insert3 in mySendFile: %lX", hr);
      BREAK_HR(hr, "Wrote a file to the device in mySendFile", "Couldn't write to the device in mySendFile.");

   } while (FALSE); // End of dummy loop

   return hr;
}

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Creating a Playlist on the Device
  • IWMDMDevice::GetStatus
  • IWMDMMetaData Interface
  • IWMDMOperation Interface
  • IWMDMProgress Interface
  • IWMDMStorage Interface
  • IWMDMStorageControl2::Insert2
  • IWMDMStorageControl3 Interface
  • Writing Files to the Device


IWMDMStorageGlobals Interface (deprecated)

The IWMDMStorageGlobals interface provides methods for retrieving global information about a storage medium (such as a flash ROM card) on a device. This can include the amount of free space, the total number of files, and so on. The values returned by this interface apply to the root storage of the current storage. Note that this is not necessarily equivalent to a device, since a device may have more than one storage (each flash card is considered a separate storage, for instance).

This interface is acquired by calling IWMDMStorage::GetStorageGlobals.

In addition to the methods inherited from IUnknown, the IWMDMStorageGlobals interface exposes the following methods.

Method | Description
GetCapabilities | Retrieves the capabilities of the storage medium.
GetSerialNumber | Retrieves a serial number that uniquely identifies the storage medium.
GetStatus | Retrieves the current status of the storage medium.
GetTotalBad | Retrieves the total amount of unusable space on the storage medium, in bytes.
GetTotalFree | Retrieves the total free space on the storage medium, in bytes.
GetTotalSize | Retrieves the total size of the storage medium, in bytes.
Initialize | Formats the storage medium.

See Also

  • Interfaces for Applications
  • IWMDMStorage Interface


IWMDMStorageGlobals::GetCapabilities (deprecated)

The GetCapabilities method retrieves the capabilities of the root storage medium.

Syntax

HRESULT GetCapabilities(
  DWORD*  pdwCapabilities
);

Parameters

pdwCapabilities

[out] Pointer to a DWORD containing a bitwise OR of zero or more of the following values.

Capability code | Description
WMDM_STORAGECAP_FOLDERSINROOT | The medium supports folders in the root of storage.
WMDM_STORAGECAP_FILESINROOT | The medium supports files in the root of storage.
WMDM_STORAGECAP_FOLDERSINFOLDERS | The medium supports nested folders.
WMDM_STORAGECAP_FILESINFOLDERS | The medium supports files in folders.
WMDM_STORAGECAP_FOLDERLIMITEXISTS | There is an arbitrary count limit for the number of folders allowed per the form of folder support by the medium.
WMDM_STORAGECAP_FILELIMITEXISTS | There is an arbitrary count limit for the number of files allowed per the form of file support by the medium.
WMDM_STORAGECAP_NOT_INITIALIZABLE | The medium can not be initialized. The top-level storage can be formatted by default.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwCapabilities parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOT_CERTIFIED | The caller is not certified.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals Interface


IWMDMStorageGlobals::GetSerialNumber (deprecated)

The GetSerialNumber method retrieves a serial number that uniquely identifies the storage medium.

Syntax

HRESULT GetSerialNumber(
  PWMDMID  pSerialNum,
  BYTE[WMDM_MAC_LENGTH]  abMac
);

Parameters

pSerialNum

[out] Pointer to a WMDMID structure specifying the serial number information.

abMac

[in, out] Array of bytes specifying the message authentication code for the parameter data of this method. This memory is allocated and freed by the caller.

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.

Return code | Description
E_INVALIDARG | The pSerialNum parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not support serial numbers.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.
WMDM_E_MAC_CHECK_FAILED | The message authentication check failed.

Remarks

Not all storage media support serial numbers, but a serial number is required to support Microsoft digital rights management. If the storage medium cannot report a unique serial number, content protected by Microsoft digital rights management cannot be transferred to this storage medium. The return code should be checked to determine whether the storage medium provides this support.

Example Code

The following C++ code retrieves the serial number of the root storage object, and verifies the MAC.

    hr = m_pStorageGlobals->GetSerialNumber(&m_SerialNumber, (BYTE*)abMAC);
    if (SUCCEEDED(hr))
    {
        // Verify the MAC using the CSecureChannelClient member.
        m_pSAC->MACInit(&hMAC);
        m_pSAC->MACUpdate(hMAC, (BYTE*)(&m_SerialNumber), sizeof(m_SerialNumber));
        m_pSAC->MACFinal(hMAC, (BYTE*)abMACVerify);
        if (memcmp(abMACVerify, abMAC, sizeof(abMAC)) != 0)
        {
            hr = E_FAIL;
        }
    }

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals Interface
  • Using Secure Authenticated Channels


IWMDMStorageGlobals::GetStatus (deprecated)

The GetStatus method retrieves the current status of a storage medium.

Syntax

HRESULT GetStatus(
  DWORD*  pdwStatus
);

Parameters

pdwStatus

[out] Pointer to a DWORD to receive the status information when the method returns. The following values can be returned in the pdwStatus parameter.

Status | Description
WMDM_STATUS_READY | The medium is in an idle or ready state.
WMDM_STATUS_BUSY | An operation is ongoing. Evaluate status values to determine the ongoing operation.
WMDM_STATUS_STORAGE_NOTPRESENT | The storage medium is not present. For devices with more than one medium supported, this value is only reported from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGE_INITIALIZING | The device is currently busy formatting a storage medium on a device.
WMDM_STATUS_STORAGE_BROKEN | The storage medium is broken. For devices with more than one medium supported, this value is only reported from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGE_NOTSUPPORTED | The storage medium is not supported by the device. For devices with more than one medium supported, this value is only returned from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGE_UNFORMATTED | The storage medium is not formatted. For devices with more than one medium supported, this value is only reported from the IWMDMStorageGlobals interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwStatus parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

This method must always be called before the caller attempts to interact with a storage medium. The status value retrieved is WMDM_STATUS_BUSY if some other interface has invoked an ongoing operation. You can evaluate the value retrieved from this call to determine whether an ongoing operation has been invoked from the IWMDMStorageGlobals interface.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals Interface


IWMDMStorageGlobals::GetTotalBad (deprecated)

The GetTotalBad method retrieves the total amount of unusable space on the storage medium, in bytes.

Syntax

HRESULT GetTotalBad(
  DWORD*  pdwBadLow,
  DWORD*  pdwBadHigh
);

Parameters

pdwBadLow

[out] Pointer to a DWORD that receives the low-order bytes of unusable space.

pdwBadHigh

[out] Pointer to a DWORD that receives the high-order bytes of unusable space.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

To determine the amount of storage space in use by the medium for file management, subtract the number of bad bytes retrieved using GetTotalBad from the number of free bytes retrieved using GetTotalFree.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals::GetTotalFree
  • IWMDMStorageGlobals Interface


IWMDMStorageGlobals::GetTotalFree (deprecated)

The GetTotalFree method retrieves the total amount of free space on the storage medium, in bytes.

Syntax

HRESULT GetTotalFree(
  DWORD*  pdwFreeLow,
  DWORD*  pdwFreeHigh
);

Parameters

pdwFreeLow

[out] Pointer to a DWORD that receives the low-order part of the free space value.

pdwFreeHigh

[out] Pointer to a DWORD that receives the high-order part of the free space value.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified

Remarks

To determine the amount of storage space in use by the medium for file management, subtract the number of bad bytes retrieved using GetTotalBad from the number of free bytes retrieved using GetTotalFree.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals Interface
  • IWMDMStorageGlobals::GetTotalBad
  • IWMDMStorageGlobals::GetTotalSize


IWMDMStorageGlobals::GetTotalSize (deprecated)

The GetTotalSize method retrieves the total size in bytes of the storage medium associated with the IWMDMStorageGlobals interface.

Syntax

HRESULT GetTotalSize(
  DWORD*  pdwTotalSizeLow,
  DWORD*  pdwTotalSizeHigh
);

Parameters

pdwTotalSizeLow

[out] Pointer to a DWORD that receives the low-order value of the total size of the medium.

pdwTotalSizeHigh

[out] Pointer to a DWORD that receives the high-order value of the total size of the medium.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device is not capable of retrieving the total amount of space on the storage medium.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMStorageGlobals Interface
  • IWMDMStorageGlobals::GetTotalFree


IWMDMStorageGlobals::Initialize (deprecated)

The Initialize method formats the storage medium.

Syntax

HRESULT Initialize(
  UINT  fuMode,
  IWMDMProgress*  pProgress
);

Parameters

fuMode

[in] Mode used to initialize the medium. Specify exactly one of the following two modes. If both modes are specified, block mode is used.

Mode | Description
WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call will not return until the operation is finished.
WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call returns immediately, and the operation is performed in a background thread.

pProgress

[in] Pointer to an IWMDMProgress interface implemented by an application to track the progress of the formatting operation.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | The media device does not support initializing.
E_BUSY | The media device is performing an operation.
E_INVALIDARG | The mode specified in the fuMode parameter is not valid.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

If an application uses WMDM_MODE_THREAD and passes a non-null pProgress parameter, the application must ensure that the object to which pProgress belongs is not destroyed until the read operation completes, because Windows Media Device Manager will send progress notifications to this object. This object can be destroyed only after it receives an End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMProgress Interface
  • IWMDMStorageGlobals Interface


IWMDRMDeviceApp Interface (deprecated)

The IWMDRMDeviceApp interface enables an application to meter, synchronize licenses, and update a device's DRM components. This interface will only work with devices that support Windows Media DRM 10 for Portable Devices.

To get this interface, call CoCreateInstance, passing in CLSID_WMDRMDeviceApp.

Note This interface is defined in the header file built from WMDRMDeviceApp.idl. This header #includes "wmdm.h". You might need to change this file name to match the header built from WMDM.idl.

In addition to the methods inherited from IUnknown, the IWMDRMDeviceApp interface exposes the following methods.

Method | Description
AcquireDeviceData | Initializes or resets a device secure clock
GenerateMeterChallenge | Acquires metering data from a device.
ProcessMeterResponse | Resets some or all of the metering counts on a device, after data from the device has been sent to and processed by the server.
QueryDeviceStatus | Queries a device for its current DRM status and capabilities.
SynchronizeLicenses | Updates licenses on a device when they are close to expiring.

Note Microsoft recommends that you notify end users if you will be collecting metering data.

See Also

  • Handling Protected Content in the Application
  • Interfaces for Applications
  • Metering Content Usage


IWMDRMDeviceApp::AcquireDeviceData (deprecated)

The AcquireDeviceData method initializes or resets a device secure clock.

Syntax

HRESULT AcquireDeviceData(
  IWMDMDevice*  pDevice,
  IWMDMProgress3*  pProgressCallback,
  DWORD  dwFlags,
  DWORD*  pdwStatus
);

Parameters

pDevice

[in] Pointer to an IWMDMDevice interface for the device that will report metering data.

pProgressCallback

[in] Progress callback through which the application can track the progress of the event, or cancel the event. The progress is identified by the EventId parameter of IWMDMProgress3 methods.

dwFlags

[in] A logical OR of one or both of the following flags, specifying what action to perform. This value is retrieved from the pdwStatus parameter of IWMDRMDeviceApp::QueryDeviceStatus or IWMDRMDeviceApp2::QueryDeviceStatus2. You can use the pdwStatus flag directly.

Flag | Description
WMDRM_DEVICE_NEEDCLOCK | Acquire a clock from a secure clock server.
WMDRM_DEVICE_REFRESHCLOCK | Refresh the clock from a secure clock server.

pdwStatus

[out] One of the following DWORD values specifying the status returned by the device.

Status | Description
0 | The action is not supported.
1 | The device secure clock could not be acquired from the service.
2 | The device's secure clock could not be set.
3 | The device's secure clock was set.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
DRM_E_INVALIDARG | One or more arguments are not valid.
NS_E_DEVICE_NOT_WMDRM_DEVICE | The specified device is not a Windows Media DRM–compatible device.
NS_E_DRM_UNABLE_TO_GET_SECURE_CLOCK | Failed to retrieve secure clock challenge from the device or unable to retrieve the secure clock URL from the challenge.
NS_E_DRM_UNABLE_TO_GET_SECURE_CLOCK_FROM_SERVER | Failed to retrieve the secure clock response from the secure clock server.
NS_E_DRM_UNABLE_TO_SET_SECURE_CLOCK | Failed to send the secure clock challenge to the device, or the device failed to set the clock.

Remarks

This is an asynchronous method; the device must await the IWMDMProgress::End callback for this operation before attempting to play any licensed content.

An application can learn if the device must have its clock reset or updated by calling IWMDRMDeviceApp::QueryDeviceStatus or IWMDRMDeviceApp2::QueryDeviceStatus2.

Your application must have an Internet connection to enable it to acquire or reset a secure clock.

Requirements

Header: Requires both WMDRMDeviceApp.h and wmdrmdeviceapp_i.c (built from WMDRMDeviceApp.idl).

Library: mssachlp.lib

See Also

  • Handling Protected Content in the Application
  • IWMDMDevice Interface
  • IWMDMProgress3 Interface
  • IWMDRMDeviceApp Interface


IWMDRMDeviceApp::GenerateMeterChallenge (deprecated)

The GenerateMeterChallenge method acquires metering data from a device.

Syntax

HRESULT GenerateMeterChallenge(
  IWMDMDevice*  pDevice,
  BSTR  bstrMeterCert,
  BSTR*  pbstrMeterURL,
  BSTR*  pbstrMeterData
);

Parameters

pDevice

[in] Pointer to an IWMDMDevice interface. If the application passes in NULL, metering information stored on the computer is used instead of metering information from a connected device.

bstrMeterCert

[in] The application's metering certificate, as a BSTR. This is a signed certificate received from Microsoft.

pbstrMeterURL

[out] The URL where metering data should be sent. This is allocated by Windows Media Device Manager, and must be free by the caller using SysFreeString.

pbstrMeterData

[out] Metering data to send to the metering service. This is allocated by Windows Media Device Manager, and must be free by the caller using SysFreeString.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
DRM_E_INVALIDARG | One or more arguments are not valid.
DRM_E_INVALIDXMLTAG | XML is improperly formed.
DRM_E_NOXMLCLOSETAG | XML is improperly formed.
DRM_E_NOXMLOPENTAG | XML is improperly formed.
DRM_E_XMLNOTFOUND | Failed to find a required XML tag.
Errors from the device | Any of a number of device errors.
Errors from the DRM Client | Any of a number of internal DRM client errors.
NS_E_DEVICE_NOT_WMDRM_DEVICE | The specified device is not a Windows Media DRM–compatible device.

Remarks

Before calling this method, the application should call IWMDRMDeviceApp::QueryDeviceStatus or IWMDRMDeviceApp2::QueryDeviceStatus2 to verify that all the device's DRM components are up to date. This method can only be called on a device that supports Windows Media DRM 10 for Portable Devices.

The retrieved data pbstrMeterData should be sent to the URL specified by pbstrMeterURL. Be sure to URL-encode the retrieved data so that it does not get modified during transfer.

See Handling Protected Content in the Application for more information.

Example Code

The following C++ code example creates a WMDRMDeviceApp object, verifies that the device is a Windows Media DRM 10 device, that its clock is accurate, and then requests the metering data.

HRESULT hr = S_OK;
// Create the WMDRMDeviceApp object.
CComPtr<IWMDRMDeviceApp> pDRM;
hr = pDRM.CoCreateInstance(CLSID_WMDRMDeviceApp, 0, CLSCTX_ALL);

// Find out first if the device is a WMDRM 10 device, and if it requires
// any clock updates.
DWORD status = 0;
hr = pDRM->QueryDeviceStatus(pDevice, &status);

if (!(WMDRM_DEVICE_ISWMDRM & status)) // Device is not WMDRM 10. Nothing can be updated,
    return E_FAIL;                   // and metering cannot be performed.
else if (status & WMDRM_DEVICE_REVOKED) // Device is revoked.
    return E_FAIL;
else if (status & WMDRM_DEVICE_NEEDCLOCK ||
    status & WMDRM_CLIENT_NEEDINDIV ||
    status & WMDRM_DEVICE_REFRESHCLOCK)
{
    // Need to update device clock.
    // Using custom function, which is synchronous.
    hr = myAcquireDeviceData(pDRM, pDevice, this, status, &result);
    if (hr != S_OK || result != 0)    // Couldn't perform the updates.
        return E_FAIL;
}

// Any updates have been performed. Now get the metering information from the device.
CComBSTR meterCert(METERCERT);
CComBSTR URL;
CComBSTR rawdata;
CComBSTR data;
hr = pDRM->GenerateMeterChallenge(pDevice, meterCert, &URL, &rawdata);
if (hr == S_OK)
    ..... Send to URL...

Requirements

Header: Requires both WMDRMDeviceApp.h and wmdrmdeviceapp_i.c (built from WMDRMDeviceApp.idl).

Library: mssachlp.lib

See Also

  • Handling Protected Content in the Application
  • IWMDMDevice Interface
  • IWMDRMDeviceApp Interface


IWMDRMDeviceApp::ProcessMeterResponse (deprecated)

The ProcessMeterResponse method resets some or all of the metering counts on a device, after data from the device has been sent to and processed by the server.

Syntax

HRESULT ProcessMeterResponse(
  IWMDMDevice*  pDevice,
  BYTE*  pbResponse,
  DWORD  cbResponse,
  DWORD*  pdwFlags
);

Parameters

pDevice

[in] Pointer to an IWMDMDevice object.

pbResponse

[in] Response received from a metering server, after sending data generated using GenerateMeterChallenge.

cbResponse

[in] Size of pbResponse, in bytes.

pdwFlags

[out] A DWORD from the following table indicating whether there is more metering data on the device that needs to be processed.

Flag | Description
WMDRM_METER_RESPONSE_ALL | All metering data has been processed.
WMDRM_METER_RESPONSE_PARTIAL | Additional metering data needs to be processed.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
DRM_E_INVALIDARG | One or more arguments are not valid.
Errors from the device | Any of a number of device errors.
Errors from the DRM Client | Any of a number of internal DRM client errors.
NS_E_DEVICE_NOT_WMDRM_DEVICE | The specified device is not a Windows Media DRM–compatible device.

Remarks

More information on metering, including code examples, can be found in the whitepaper Metering the Use of Digital Media Content with Windows Media DRM 10 on the MSDN Web site.

Requirements

Header: Requires both WMDRMDeviceApp.h and wmdrmdeviceapp_i.c (built from WMDRMDeviceApp.idl).

Library: mssachlp.lib

See Also

  • Handling Protected Content in the Application
  • IWMDMDevice Interface
  • IWMDRMDeviceApp Interface


IWMDRMDeviceApp::QueryDeviceStatus (deprecated)

The QueryDeviceStatus method queries a device for its current DRM status and capabilities.

Syntax

HRESULT QueryDeviceStatus(
  IWMDMDevice*  pDevice,
  DWORD*  pdwStatus
);

Parameters

pDevice

[in] Pointer to an IWMDMDevice object.

pdwStatus

[out] Zero or more of the following DWORD values describing the DRM aspects of the device, combined with a bitwise OR. See Remarks.

Status | Description
WMDRM_DEVICE_ISWMDRM | The device supports Windows Media DRM.
WMDRM_DEVICE_NEEDCLOCK | The device does not have a secure clock.
WMDRM_DEVICE_REVOKED | The device has been revoked.
WMDRM_CLIENT_NEEDINDIV | The DRM security needs to be individualized.
WMDRM_DEVICE_REFRESHCLOCK | The clock needs to be refreshed.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
DRM_E_INVALIDARG | The input argument is not valid.
NS_E_DRM_INVALID_CERTIFICATE | The device certificate retrieved from the device is not valid.
NS_E_DRM_UNABLE_TO_GET_DEVICE_CERT | Failed to retrieve the device certificate from the device.

Remarks

This method should be called before performing any restricted actions on DRM content, such as transferring DRM content to the device, or acquiring metering information. If the values retrieved by pdwStatus indicate that some action needs to be performed (such as individualization for the desktop or acquiring a clock for the device), the application should call AcquireDeviceData and pass the retrieved pdwStatus value from this function to the dwFlags parameter in AcquireDeviceData. If zero is returned, the device does not support Windows Media DRM 10 for Portable Devices, and no actions need be taken. See Handling Protected Content in the Application for more information.

Example Code

The following C++ code example creates a WMDRMDeviceApp object, verifies that the device is a Windows Media DRM 10 device, that its clock is accurate, and then requests the metering data.

HRESULT hr = S_OK;
// Create the WMDRMDeviceApp object.
CComPtr<IWMDRMDeviceApp> pDRM;
hr = pDRM.CoCreateInstance(CLSID_WMDRMDeviceApp, 0, CLSCTX_ALL);

// Find out first if the device is a WMDRM 10 device, and if it requires
// any clock updates.
DWORD status = 0;
hr = pDRM->QueryDeviceStatus(pDevice, &status);

if (!(WMDRM_DEVICE_ISWMDRM & status)) // Device is not WMDRM 10. Nothing can be updated,
    return E_FAIL;                   // and metering cannot be performed.
else if (status & WMDRM_DEVICE_REVOKED) // Device is revoked.
    return E_FAIL;
else if (status & WMDRM_DEVICE_NEEDCLOCK ||
    status & WMDRM_CLIENT_NEEDINDIV ||
    status & WMDRM_DEVICE_REFRESHCLOCK)
{
    // Need to update device clock.
    // Using custom function, which is synchronous.
    hr = myAcquireDeviceData(pDRM, pDevice, this, status, &result);
    if (hr != S_OK || result != 0)    // Couldn't perform the updates.
        return E_FAIL;
}

Requirements

Header: Requires both WMDRMDeviceApp.h and wmdrmdeviceapp_i.c (built from WMDRMDeviceApp.idl).

Library: mssachlp.lib

See Also

  • Handling Protected Content in the Application
  • IWMDRMDeviceApp Interface
  • IWMDRMDeviceApp2::QueryDeviceStatus2


IWMDRMDeviceApp::SynchronizeLicenses (deprecated)

The SynchronizeLicenses method updates licenses on a device when they are close to expiring.

Syntax

HRESULT SynchronizeLicenses(
  IWMDMDevice*  pDevice,
  IWMDMProgress3*  pProgressCallback,
  DWORD  cMinCountThreshold,
  DWORD  cMinHoursThreshold
);

Parameters

pDevice

[in] Pointer to an IWMDMDevice object.

pProgressCallback

[in] Progress callback that will receive progress of any steps that it might need to carry out. The step is identified by the EventId parameter of the IWMDMProgress3 method called.

cMinCountThreshold

[in] Optional minimum remaining play count on a device license.

cMinHoursThreshold

[in] Optional minimum remaining hours on a device license.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
DRM_E_INVALIDARG | One or more arguments are not valid.
DRM_E_INVALIDXMLTAG | XML is improperly formed.
DRM_E_NOTIMPL | This functionality is not currently implemented. (SyncLicenses w/pDevice=NULL)
DRM_E_NOXMLCLOSETAG | The license XML was improperly formed.
DRM_E_NOXMLOPENTAG | The license XML was improperly formed.
DRM_E_OUTOFMEMORY | Out of memory.
DRM_E_XMLNOTFOUND | Failed to find a required XML tag in the license.
NS_E_DEVICE_NOT_WMDRM_DEVICE | The specified device is not a Windows Media DRM–compatible device.
NS_E_DRM_NEEDS_INDIVIDUALIZATION | The DRM requires an individualized black box to perform this function. In other words, the Windows Media Format SDK requires a security upgrade.

Remarks

This call can only be made on a device that supports Windows Media DRM 10 for Portable Devices. You must specify at least one threshold parameter.

Requirements

Header: Requires both WMDRMDeviceApp.h and wmdrmdeviceapp_i.c (built from WMDRMDeviceApp.idl).

Library: mssachlp.lib

See Also

  • Handling Protected Content in the Application
  • IWMDMProgress3 Interface
  • IWMDRMDeviceApp Interface


IWMDRMDeviceApp2 Interface (deprecated)

The IWMDRMDeviceApp2 interface extends IWMDRMDeviceApp by providing a new version of the QueryDeviceStatus method. QueryDeviceStatus2 enables the caller to query for a specific DRM requirement.

To get this interface, call CoCreateInstance and pass in CLSID_WMDRMDeviceApp.

Note This interface is defined in the header file built from WMDRMDeviceApp.idl. This header #includes "wmdm.h". You might need to change this file name to match the header built from WMDM.idl.

In addition, WMDRMDeviceApp.idl may not define the interface GUID in WMDRMDeviceApp.h, so you may need to include wmdrmdeviceapp_i.c as well.

In addition to the methods inherited from IWMDRMDeviceApp, the IWMDRMDeviceApp2 interface exposes the following method.

Method | Description
QueryDeviceStatus2 | Queries a device for a specific DRM status or capability.

See Also

  • Handling Protected Content in the Application
  • Interfaces for Applications
  • Metering Content Usage


IWMDRMDeviceApp2::QueryDeviceStatus2 (deprecated)

The QueryDeviceStatus2 method queries a device for a specific DRM status or capability.

Syntax

HRESULT QueryDeviceStatus2(
  IWMDMDevice*  pDevice,
  DWORD  dwFlags,
  DWORD*  pdwStatus
);

Parameters

pDevice

[in] Pointer to an IWMDMDevice object.

dwFlags

[in] One or more of the following DWORD values specifying which capabilities to request, combined with a bitwise OR.

Flag | Description
WMDRM_QUERY_CLIENT_INDIVSTATUS | Query whether the computer's DRM components need to be individualized.
WMDRM_QUERY_DEVICE_CLOCKSTATUS | Query whether the device's secure clock needs to be added or updated.
WMDRM_QUERY_DEVICE_ISREVOKED | Query whether the device is revoked.
WMDRM_QUERY_DEVICE_ISWMDRM | Query whether the device supports Windows Media DRM 10 for Portable Devices.

pdwStatus

[out] Zero or more of the following DWORD values specifying the requested device status, combined with a bitwise OR.

Status | Description
WMDRM_DEVICE_ISWMDRM | The device supports Windows Media DRM.
WMDRM_DEVICE_NEEDCLOCK | The device does not have a secure clock.
WMDRM_DEVICE_REVOKED | The device has been revoked.
WMDRM_CLIENT_NEEDINDIV | The computer's DRM components need to be individualized.
WMDRM_DEVICE_REFRESHCLOCK | The clock needs to be refreshed.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
DRM_E_INVALIDARG | One or more arguments are not valid.
NS_E_DRM_INVALID_CERTIFICATE | The device certificate retrieved from the device is not valid.
NS_E_DRM_UNABLE_TO_GET_DEVICE_CERT | Failed to retrieve the device certificate from the device.

Remarks

This method should be called before performing any restricted actions on DRM content, such as transferring DRM content to the device, or acquiring metering information. If the values retrieved by pdwStatus indicate that some action needs to be performed (such as individualization for the desktop or acquiring a clock for the device), the application should call IWMDRMDeviceApp::AcquireDeviceData and pass in the retrieved pdwStatus value from this function to the dwFlags parameter in AcquireDeviceData. If zero is returned, the device does not support Windows Media DRM 10 for Portable Devices, and no actions need be taken. See Handling Protected Content in the Application for more information.

Requirements

Header: Requires both WMDRMDeviceApp.h and wmdrmdeviceapp_i.c (built from WMDRMDeviceApp.idl).

Library: mssachlp.lib

See Also

  • Handling Protected Content in the Application
  • IWMDRMDeviceApp::QueryDeviceStatus
  • IWMDRMDeviceApp2 Interface


Interfaces for Service Providers

This section describes interfaces implemented by Windows Media Device Manager service providers. Service providers perform most of the actual work of communicating with a device, because they implement most of the Windows Media Device Manager SDK methods called by the application.

Service providers do not need to implement all of the interfaces listed in this section. For example, a media device that does not have on-board storage does not implement the interfaces that are used to control or expose content. Whether a method or interface is required is indicated on the appropriate reference page.

Interface or class | Description
CSecureChannelServer | A helper class that enables a service provider or secure content provider to authenticate an application and create MAC signatures for secure parameters.
IMDServiceProvider | Provides the client (usually Windows Media Device Manager) with a device enumerator for the devices that this service provider supports.
IMDServiceProvider2 | Extends IMDServiceProvider by providing a method for creating the device by using the device path.
IMDServiceProvider3 | Extends IMDServiceProvider2 by providing a method for setting the device enumeration preferences.
IMDSPDevice | Provides an instance-based association with a media device. Using this interface, the client can enumerate the storage media enumerators for the device, get information about the device, and send opaque (pass-through) commands to the device.
IMDSPDevice2 | Extends IMDSPDevice by providing methods for getting extended video formats, getting Plug and Play (PnP) device names, enabling the use of property pages, and making it possible to get a pointer to a storage medium from its name. This interface is optional for the service provider but is recommended.
IMDSPDevice3 | Extends IMDSPDevice2 by providing ability to query properties and capabilities of the device with regard to an object format.
IMDSPDeviceControl | Provides methods for controlling devices.
IMDSPDirectTransfer | Enables Windows Media Device Manager to delegate content transfer to the service provider. In this case Windows Media Device Manager does not do any processing of the content before sending it to the service provider. The service provider gets full control of the source.
IMDSPEnumDevice | Enumerates the media devices supported by this service provider.
IMDSPEnumStorage | Enumerates the storage media on a device and the contents on a storage medium.
IMDSPObject | Contains methods for data transfer operations on a storage object.
IMDSPObject2 | Extends IMDSPObject by providing more efficient transmission of DRM-enabled data.
IMDSPObjectInfo | Sets or gets play length, play position, play offset, or total length of playable objects on a storage medium.
IMDSPRevoked | Retrieves the URL from which updated components can be downloaded.
IMDSPStorage | Provides an instanced-based association with a storage medium on a device. This interface creates storage objects, retrieves information about them, and provides access to the IMDSPEnumStorage interface for enumerating subfolders nested within the current storage.
IMDSPStorage2 | Extends IMDSPStorage by getting and setting extended attributes and making it possible to get a pointer to storage from its name.
IMDSPStorage3 | Extends IMDSPStorage2 by supporting metadata.
IMDSPStorage4 | Extends IMDSPStorage3 by supporting playlist objects.
IMDSPStorageGlobals | Retrieves global information about a storage medium, such as the amount of free space and the total number of files.

The following diagram shows how to get the various interfaces implemented by a service provider. In this diagram, derived interfaces are displayed in the same tag for compactness, so IMDServiceProvider/2/3 would represent three interfaces: IMDServiceProvider, IMDServiceProvider2, and IMDServiceProvider3. Methods shown are extended by only one of these interfaces. Derived interfaces are obtained by calling QueryInterface on the base interface of the created object.

Diagram showing how Windows Media Device Manager expects to acquire interfaces from a service provider.

See Also

  • Programming Reference
  • Windows Media DRM-Implemented Interfaces


CSecureChannelServer Class (deprecated)

The CSecureChannelServer class is a helper class (not an interface) that enables a service provider or secure content provider to authenticate an application using the IComponentAuthenticate interface, to encrypt and decrypt data, and to create MAC signatures. The authentication process requires that the application create a CSecureChannelClient object and that the service provider create a CSecureChannelServer object. The CSecureChannelClient and CSecureChannelServer classes are declared in the static link library, Mssachlp.lib. All methods of Windows Media Device Manager, service provider, and secure content provider interfaces can return WMDM_E_NOTCERTIFIED to indicate that the caller has not authenticated successfully.

The CSecureChannelServer class exposes the following methods.

Method | Description
DecryptParam | Decrypts the data contained in a parameter.
EncryptParam | Encrypts the data contained in a parameter.
fIsAuthenticated | Verifies that a secure authentication channel has been successfully established.
GetAppSec | Retrieves the application security levels of the local and remote components.
GetSessionKey | Retrieves the current session key.
MACFinal | Releases the message authentication code (MAC) channel and retrieves a final MAC value.
MACInit | Acquires a message authentication code (MAC) channel.
MACUpdate | Updates the message authentication code (MAC) value with a parameter value.
SACAuth | Establishes a secure authenticated channel between components.
SACGetProtocols | Reports the protocols supported by a component.
SetCertificate | Specifies the certificate and private key of the secure authenticated channel (SAC) server.
SetSessionKey | Sets the session key that is used to communicate with another component.

See Also

  • CSecureChannelClient Class
  • IComponentAuthenticate Interface
  • Interfaces for Service Providers
  • Using Secure Authenticated Channels


CSecureChannelServer::DecryptParam (deprecated)

DecryptParam uses the session key of the secure authenticated channel to decrypt the data contained in a parameter.

Syntax

HRESULT DecryptParam(
  BYTE*  pbData,
  DWORD  dwDataLen
);

Parameters

pbData

[in, out] Pointer to the first byte of a data buffer containing the encrypted parameter that is to be decrypted.

dwDataLen

[in] Pointer to a DWORD specifying the length of the buffer to which pbData points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Components should copy the data to a temporary buffer before calling DecryptParam and then decrypt the temporary buffer. This method only needs to be called for encrypted parameters. See Using Secure Authenticated Channels for a table of methods that must use the message authentication code algorithm and encrypted parameters.

Example Code

The following code shows a service provider's implementation of the IMDSPObject::Write method, which requires a service provider to decrypt data sent to it.

HRESULT CMyStorage::Write(BYTE *pData, DWORD *pdwSize,
                                 BYTE abMac[WMDM_MAC_LENGTH])
{
    HRESULT  hr;
    DWORD    dwWritten = 0;
    BYTE    *pTmpData  = NULL;          // Temporary buffer to hold the
                                        // data during decryption.
    BYTE     pTempMac[WMDM_MAC_LENGTH]; // Temporary MAC that will be
                                        // copied into the abMac
                                        // out parameter.

    if( m_hFile == INVALID_HANDLE_VALUE )
    {
        return E_FAIL;
    }

    // Allocate the temporary buffer and copy the encrypted data into it.
    pTmpData = new BYTE [*pdwSize];
    if(!pTmpData)
        return E_OUTOFMEMORY;
    memcpy(pTmpData, pData, *pdwSize);

    // Decrypt the data.
    CHRg(g_pAppSCServer->DecryptParam(pTmpData, *pdwSize));

    // Check the MAC passed to the method. The MAC is built from
    // the data and data size parameters.
    // CORg is a macro that goes to the Error label on failure.
    HMAC hMAC;
    CORg(g_pAppSCServer->MACInit(&hMAC));
    CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pTmpData), *pdwSize));
    CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(*pdwSize)));
    CORg(g_pAppSCServer->MACFinal(hMAC, pTempMac));

    // If the MAC values don't match, return an error.
    if (memcmp(abMac, pTempMac, WMDM_MAC_LENGTH) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
        goto Error;
    }

    // The MAC values matched, so write the decrypted data to a local file.
    if( WriteFile(m_hFile,pTmpData,*pdwSize,&dwWritten,NULL) )
    {
        hr = S_OK;
    }
    else
    {
        hr = HRESULT_FROM_WIN32(GetLastError());
    }

    *pdwSize = dwWritten;

Error:

    if( pTmpData )
    {
        delete [] pTmpData;
    }

    return hr;
}

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelClient::DecryptParam
  • CSecureChannelClient::EncryptParam
  • CSecureChannelServer Class
  • CSecureChannelServer::EncryptParam


CSecureChannelServer::EncryptParam (deprecated)

The EncryptParam method uses the session key of the secure authenticated channel to encrypt the data contained in a parameter.

Syntax

HRESULT EncryptParam(
  BYTE*  pbData,
  DWORD  dwDataLen
);

Parameters

pbData

Pointer to the first byte of a data buffer containing the parameter that is to be encrypted.

dwDataLen

Pointer to a DWORD specifying the length of the buffer to which pbData points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Certain parameters, listed in the tables under Using Secure Authenticated Channels, must be included in the message authentication code (MAC) and must be encrypted before the call for data transfer in both directions. Call EncryptParam to encrypt the specified parameters. Do not encrypt any parameters that do not require it.

Example Code

The following code demonstrates a service provider's implementation of IMDSPObject::Read. This method creates the MAC key using the data to encrypt and the size of the data, and sends them both to the application.

HRESULT CMyStorage::Read(
    BYTE  *pData,
    DWORD *pdwSize,
    BYTE   abMac[WMDM_MAC_LENGTH])
{
    HRESULT  hr;
    DWORD    dwToRead;         // Bytes to read.
    DWORD    dwRead   = NULL;  // Bytes read.
    BYTE    *pTmpData = NULL;  // Temporary buffer to hold data before it
                               // is copied out to pData.

    // Use a global CSecureChannelServer member to verify that the client
    // is authenticated.
    if (!(g_pAppSCServer->fIsAuthenticated()))
    {
        return WMDM_E_NOTCERTIFIED;
    }

    // Verify that the handle to the file to read is valid.
    if(m_hFile == INVALID_HANDLE_VALUE)
    {
        return E_FAIL;
    }

    // Create a buffer to hold the data read.
    dwToRead = *pdwSize;
    pTmpData = new BYTE [dwToRead] ;
    if(!pTmpData)
        return E_OUTOFMEMORY;

    // Read data into the temporary buffer.
    if(ReadFile(m_hFile,(LPVOID)pTmpData,dwToRead,&dwRead,NULL))
    {
        *pdwSize = dwRead;

        if( dwRead )
        {
            // Create a MAC from all the parameters.
            // CORg is a macro that goes to Error label on failure.
            // MAC consists of data and size of data.
            HMAC hMAC;

            CORg(g_pAppSCServer->MACInit(&hMAC));
            CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pTmpData), dwRead));
            CORg(g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(DWORD)));
            CORg(g_pAppSCServer->MACFinal(hMAC, abMac));

            // Encrypt the data.
            CORg(g_pAppSCServer->EncryptParam(pTmpData, dwRead));

            // Copy the data from the temporary buffer into the out param.
            memcpy(pData, pTmpData, dwRead);
        }

        hr = S_OK;
    }
    else
    {
        *pdwSize = 0;

        hr = E_FAIL;
    }

Error:

    if(pTmpData)
    {
        delete [] pTmpData;
    }

    return hr;
}

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • CSecureChannelServer::DecryptParam


CSecureChannelServer::fIsAuthenticated (deprecated)

The fIsAuthenticated method verifies that a Secure Authenticated Channel has been successfully established.

Syntax

BOOL fIsAuthenticated( );

Parameters

This method takes no parameters.

Return Values

The method returns and 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.

Remarks

This method is used to ensure that a secure authenticated channel has been established between components before allowing certain operations. This includes calls by devices and storages prior to accessing and transferring data streams. You should confirm that this method returns TRUE before calling other top-level methods on the component.

Applications do not need to call the fIsAuthenticated method, but service providers do. They should call this method for all exposed APIs and return WMDM_E_NOTCERTIFIED if it returns FALSE.

Example Code

The following code shows a service provider's implementation of IMDSPDevice::GetVersion. This method verifies that a secure authenticated channel has been established before returning the version.

HRESULT CMyDevice::GetVersion(DWORD * pdwVersion)
{
    HRESULT hr = S_OK;

    if(g_pAppSCServer == NULL)
        return E_FAIL;

    if (!(g_pAppSCServer->fIsAuthenticated()))
    {
        return WMDM_E_NOTCERTIFIED;
    }
    *pdwVersion = 1;
    return hr;
}

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelClient::fIsAuthenticated
  • CSecureChannelServer Class


CSecureChannelServer::GetAppSec (deprecated)

The GetAppSec method retrieves the application security levels of the local and remote components. This method is published and available, but normally is used only by Windows Media Device Manager.

Syntax

HRESULT GetAppSec(
  DWORD*  pdwLocalAppSec,
  DWORD*  pdwRemoteAppSec
);

Parameters

pdwLocalAppSec

[out] Pointer to a DWORD specifying the application security level of the local component.

pdwRemoteAppSec

[out] Pointer to a DWORD specifying the application security level of the remote component.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class


CSecureChannelServer::GetSessionKey (deprecated)

The GetSessionKey method retrieves the current session key that is used for encryption and decryption. This method is published and available, but normally is used only by Windows Media Device Manager.

Syntax

HRESULT GetSessionKey(
  BYTE*  pbSPSessionKey
);

Parameters

pbSPSessionKey

[out] Pointer to the first byte of a buffer containing the session key.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pbSPSessionKey parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • CSecureChannelServer::SetSessionKey


CSecureChannelServer::MACFinal (deprecated)

The MACFinal method releases the message authentication code (MAC) channel and retrieves a final MAC value.

Syntax

HRESULT MACFinal(
  HMAC  hMAC,
  BYTE  abData[WMDM_MAC_LEN]
);

Parameters

hMAC

[in] Handle to the MAC for the current parameter data. The handle is returned from the MACInit method. The handle is no longer valid after this method call.

abData

[out] Pointer to an 8-byte buffer to receive the final MAC value for the current parameter data.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid.
E_FAIL | An unspecified error occurred.

Example Code

See the example code for MACInit.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • CSecureChannelServer::MACInit
  • CSecureChannelServer::MACUpdate
  • Message Authentication


CSecureChannelServer::MACInit (deprecated)

The MACInit method acquires a message authentication code (MAC) channel for use in calls to the MACUpdate and MACFinal methods.

Syntax

HRESULT MACInit(
  HMAC*  phMAC
);

Parameters

phMAC

[out] Pointer to a MAC handle.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The phMAC parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The MACInit method begins a message authentication code (MAC) session. This method must be called every time a (MAC) is required. MACUpdate and MACFinal must be called sequentially after MACInit. After MACFinal, MACInit must be called again to acquire a new handle.

Example Code

g_pAppSCServer = new CsecureChannelServer();
if( dwRead )
{
    // MAC the parameters.
    HMAC hMAC;

    g_pAppSCServer->MACInit(&hMAC);
    g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pTmpData), dwRead);
    g_pAppSCServer->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(DWORD));
    g_pAppSCServer->MACFinal(hMAC, abMac);

    g_pAppSCServer->EncryptParam(pTmpData, dwRead);

    memcpy(pData, pTmpData, dwRead);
    }

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • CSecureChannelServer::MACFinal
  • CSecureChannelServer::MACUpdate
  • Message Authentication


CSecureChannelServer::MACUpdate (deprecated)

The MACUpdate method updates the message authentication code (MAC) value with a parameter value.

Syntax

HRESULT MACUpdate(
  HMAC  hMAC,
  BYTE*  pbData,
  DWORD  dwDataLen
);

Parameters

hMAC

[in] Handle to the array containing the MAC for the current parameter data. The handle is returned by the MACInit method.

pbData

[in] Pointer to the data to be added to the MAC value for the current parameter data.

dwDataLen

DWORD specifying the length of the data to which pbData points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

MACUpdate must be called repeatedly with each piece of data to add to the message authentication code (MAC) . MACUpdate must be called after MACInit because MACInit acquires the MAC handle. MACFinal must be called after MACUpdate.

Example Code

See the example code for MACInit.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • CSecureChannelServer::MACInit
  • CSecureChannelServer::MACUpdate
  • Message Authentication


CSecureChannelServer::SACAuth (deprecated)

The SACAuth method establishes a secure authenticated channel between components.

Syntax

HRESULT SACAuth (
  DWORD  dwProtocolID,
  DWORD  dwPass,
  BYTE*  pbDataIn,
  DWORD  dwDataInLen,
  BYTE**  ppbDataOut,
  DWORD*  pdwDataOutLen
);

Parameters

dwProtocolID

DWORD specifying the protocol identifier. This parameter must be set to SAC_PROTOCOL_V1.

dwPass

DWORD containing the number of the current pass.

pbDataIn

[in] Pointer to the first byte of the input authentication data.

dwDataInLen

DWORD specifying the length of the data to which pbDataIn points.

ppbDataOut

[out] Pointer to a pointer to the output authentication data.

pdwDataOutLen

Pointer to a DWORD specifying the length of the data to which ppbDataOut points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is called one or more times as dictated by the protocol identifier. The structure of the data in pbDataIn and pbDataOut is determined by the values of dwProtocolID and dwPass. The dwPass parameter indicates the number of the communication pass that is under way.

This method is used by the service provider to implement the public IComponentAuthenticate::SACAuth method. For an example of calling this method, see that method's documentation.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • IComponentAuthenticate::SACAuth
  • Message Authentication


CSecureChannelServer::SACGetProtocols (deprecated)

The SACGetProtocols method reports the protocols supported by a component.

Syntax

HRESULT SACGetProtocols(
  DWORD**  ppdwProtocols,
  DWORD*  pdwProtocolCount
);

Parameters

ppdwProtocols

Pointer to a pointer to an array of DWORD values specifying the supported protocols.

pdwProtocolCount

Pointer to a DWORD specifying the number of protocols in the array to which ppdwProtocols points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is used by the service provider to implement the public IComponentAuthenticate::SACGetProtocols method. For an example of calling this method, see that method's documentation.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • IComponentAuthenticate::SACGetProtocols


CSecureChannelServer::SetCertificate (deprecated)

The SetCertificate method specifies the certificate and private key of the secure authenticated channel (SAC) server. Information about where to get this certificate is given in Tools for Development.

Syntax

HRESULT SetCertificate(
  DWORD  dwFlags,
  BYTE*  pbAppCert,
  DWORD  dwCertLen,
  BYTE*  pbAppPVK,
  DWORD  dwPVKLen
);

Parameters

dwFlags

[in] Specifies the type of certificate being passed to this method. Must be set to SAC_CERT_V1.

pbAppCert

[in] Pointer to the first byte of the certificate of the SAC client.

dwCertLen

[in] DWORD specifying the length of the certificate to which pbAppCert points.

pbAppPVK

[in] Pointer to the first byte of the private key of the SAC client.

dwPVKLen

[in] DWORD specifying the length of the private key to which pbAppPVK points.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method sends the component's authentication certificate to CSecureChannelClient. SetCertificate should be called immediately after creating the CSecureChannelServer object. If pbAppCert and/or pbAppPVK are NULL (or both zero) a default certificate and private key pair is used which will allow for basic functionality.

Example Code

The following code demonstrates creating a CSecureChannelServer object and setting its certificate. In this code, the variables pbAppCert and pbAppPVK are a matching certificate/key pair.

extern CSecureChannelServer *g_pSCWMDM;
g_pSCWMDM = new CSecureChannelServer();

// Select the certificate and the associated private key into the SAC.
if (g_pSCWMDM)
{
    g_pSCWMDM->SetCertificate( SAC_CERT_V1,
                               (BYTE*)g_abAppCert,
                               sizeof(g_abAppCert),
                               (BYTE*)g_abPriv,
                               sizeof(g_abPriv) );
}

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class


CSecureChannelServer::SetSessionKey (deprecated)

The SetSessionKey method sets the session key that is used to communicate with another component. This method is published and available, but normally is used only by Windows Media Device Manager.

Syntax

HRESULT SetSessionKey(
  BYTE*  pbSPSessionKey
);

Parameters

pbSPSessionKey

[in] Pointer to the first byte of the session key that is to be set. The key is used for encryption and decryption.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pbSPSessionKey parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Include scserver.h.

Library: mssachlp.lib

See Also

  • CSecureChannelServer Class
  • CSecureChannelServer::GetSessionKey


IMDServiceProvider Interface (deprecated)

The IMDServiceProvider interface is the initial interface that Windows Media Device Manager uses to connect to your service provider. Using this interface, Windows Media Device Manager can enumerate and communicate with the all media devices supported by a particular service provider. The IMDServiceProvider2 interface can be implemented to create devices by using the device path.

In addition to the methods inherited from IUnknown, the IMDServiceProvider interface exposes the following methods.

Method | Description
EnumDevices | Enumerates the installed physical or software devices that are currently attached and are known by the service provider.
GetDeviceCount | Retrieves the number of media devices that are currently attached and are known by the service provider.

See Also

  • IMDServiceProvider2 Interface
  • Interfaces for Service Providers


IMDServiceProvider::EnumDevices (deprecated)

The EnumDevices method enumerates the installed physical or software devices that are currently attached and are known by the service provider.

Syntax

HRESULT EnumDevices(
  IMDSPEnumDevice**  ppEnumDevice
);

Parameters

ppEnumDevice

[out] Pointer to an IMDSPEnumDevice interface. If the service provider implements IMDServiceProvider2::CreateDevice, this enumerator should only enumerate non-Plug and Play devices.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumDevice parameter is an invalid or NULL pointer.
WMDM_E_NOTCERTIFIED | The caller is not authorized, and calls to other service provider interfaces will also fail and return this code.

Remarks

This method is called on service providers that are not registered as Plug and Play aware (see Enabling PnP for Devices and Enumerating Devices for details). A service provider should return only the enumerator, which will enumerate only the devices that are currently attached to the computer and are supported by the service provider.

This method will be called only when an application starts, or when the application calls IWMDeviceManager2::Reinitialize.

At present, Windows Media Device Manager does not support returning installed devices.

The service provider cannot alert the application when devices connect or disconnect from the computer. If a Plug and Play device connects or disconnects and an application implements IWMDMNotification, then Windows Media Device Manager will send a notification to the application.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IMDServiceProvider Interface


IMDServiceProvider::GetDeviceCount (deprecated)

The GetDeviceCount method returns the number of installed physical or software devices that are currently attached and are known by the service provider.

Syntax

HRESULT GetDeviceCount(
  DWORD*  pdwCount
);

Parameters

pdwCount

[out] Pointer to a DWORD containing the count of known devices.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwCount parameter is an invalid or NULL pointer.

Remarks

The service provider should return only the number of supported devices that are currently attached to the computer.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDServiceProvider Interface


IMDServiceProvider2 Interface (deprecated)

The IMDServiceProvider2 interface extends the IMDServiceProvider interface by providing a way of obtaining IMDSPDevice object(s) for a given device path name. The device path name comes from the Plug and Play (PnP) subsystem.

In addition to the methods inherited from IMDServiceProvider, the IMDServiceProvider2 interface exposes the following method.

Method | Description
CreateDevice | Creates devices by using the device path.

See Also

  • IMDServiceProvider Interface
  • Interfaces for Service Providers


IMDServiceProvider2::CreateDevice (deprecated)

The CreateDevice method is called by the Windows Media Device Manager to get the IMDSPDevice object(s) corresponding to the canonical device obtained from the PnP subsystem. This method must be implemented for PnP and Windows Explorer support, but otherwise it is optional. For more information, see Mandatory and Optional Interfaces.

Syntax

HRESULT CreateDevice(
  LPCWSTR  pwszDevicePath,
  DWORD*  pdwCount,
  IMDSPDevice***  pppDeviceArray
);

Parameters

pwszDevicePath

[in] Pointer to a wide-character null-terminated string containing the device path of the device detected by Windows Media Device Manager. This name is obtained from the PnP subsystem, and is the canonical name plus "$#", where # is an auto-

incremented number. This name can be passed directly to functions such as CreateFile to gain access to the underlying kernel device object. The service provider should create a wrapper IMDSPDevice object(s) for this device.

pdwCount

[out] Pointer to a DWORD containing the number of IMDSPDevice objects that are created.

pppDeviceArray

[out] An array of IMDSPDevice interfaces representing the devices. Typically, there is only one array element, but a service provider can create more than one IMDSPDevice object corresponding to a device path name if it creates an IMDSPDevice object for each top-level storage. This is subject to change in the future, and the count may be restricted to 1.

Return Values

If the method succeeds it returns S_OK. If the method fails, it returns the Windows Media Device Manager error codes.

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

Remarks

Windows Media Device Manager calls this method when an application starts, or when a Plug and Play compliant device connects with the computer.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enumerating Devices
  • IMDServiceProvider2 Interface


IMDServiceProvider3 Interface (deprecated)

The IMDServiceProvider3 interface extends the IMDServiceProvider2 interface by providing a method for setting the device enumeration preferences.

In addition to the methods inherited from IMDServiceProvider2, the IMDServiceProvider3 interface exposes the following method.

Method | Description
SetDeviceEnumPreference | Sets the device enumeration preferences.

See Also

  • IMDServiceProvider2 Interface
  • Interfaces for Service Providers


IMDServiceProvider3::SetDeviceEnumPreference (deprecated)

The SetDeviceEnumPreference method sets the device enumeration preferences.

Syntax

HRESULT SetDeviceEnumPreference(
  DWORD  dwEnumPref
);

Parameters

dwEnumPref

[in] Contains a bitwise OR combination of one or more of the following bit values that specify enumeration preference. Each set bit enables the corresponding extended behavior, whereas the absence of that bit disables the extended behavior and specifies the default, backward-compatible enumeration behavior. The possible values for dwEnumPref are provided in the following table.

Value | Description
DO_NOT_VIRTUALIZE_STORAGES_AS_DEVICES | By default, for devices containing multiple storage media, each of these storages enumerates as a separate pseudo-device. However, when this bit is set, storages are not visible as devices, and only devices are visible as devices.
ALLOW_OUTOFBAND_NOTIFICATION | By default, the IWMDMNotification callback mechanism provides applications with device arrival and removal events. When this bit is set, the service provider is free to notify the application by a separate mechanism, such as by using a window message. This behavior is in addition to the Windows Media Device Manager notifications. This flag does not suppress Windows Media Device Manager notifications.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Value | Description
S_OK | The method succeeded.
E_INVALIDARG | The dwEnumPref parameter contains an unsupported bit value.
WMDM_E_CALL_OUT_OF_SEQUENCE | The method was called after an enumeration operation. It must be called before the enumeration operation.

Remarks

This API provides clients the ability to override the default device enumeration behavior of Windows Media Device Manager.

Client applications must call this method immediately after creating the device manager object by querying for the IWMDeviceManager interface from Windows Media Device Manager. The call must be made before any enumeration occurs, either explicitly or implicitly as a result of another operation.

After a preference flag is set, it cannot be changed for the lifetime of the application (not just the lifetime of the Windows Media Device Manager object). Attempting to change a preference flag will result in an error. Calling this API again with the same flag settings does not return an error, and also does have any effect on enumeration.

The DO_NOT_VIRTUALIZE_STORAGES_AS_DEVICES flag has to be honored by the service provider to take effect. It is possible that, despite this flag, some devices are enumerated as a device-per-storage.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDServiceProvider3 Interface


IMDSPDevice Interface (deprecated)

The IMDSPDevice interface provides an instance-based association with a media device. Using this interface, the client can get a storage media enumerator for the device, get information about the device, and send opaque (pass-through) commands to the device. IMDServiceProvider2 extends IMDSPDevice by providing methods for getting video formats, getting Plug and Play (PnP) device names, enabling the use of property pages, and making it possible to get a pointer to a storage medium from its name. This interface is optional for the service provider but is recommended.

In addition to the methods inherited from IUnknown, the IMDSPDevice interface exposes the following methods.

Method | Description
EnumStorage | Enumerates the top-level storage medium on the device. This method is mandatory.
GetDeviceIcon | Retrieves a HICON value that represents the icon that the device service provider indicates must be used to represent this device.
GetFormatSupport | Enumerates the formats supported by the device. This method is mandatory.
GetManufacturer | Retrieves the name of the manufacturer of the device.
GetName | Retrieves the name of the device.
GetPowerSource | Reports whether the device is capable of running on batteries, external power, or both, and on which type of power source it is currently running.
GetSerialNumber | Retrieves the serial number that uniquely identifies the device. This method is mandatory.
GetStatus | Retrieves the device status information. This method is mandatory.
GetType | Retrieves device type information. This method is mandatory.
GetVersion | Retrieves the version number of the device.
SendOpaqueCommand | Sends a command to a device through Windows Media Device Manager. Windows Media Device Manager transmits the command without acting on it.

See Also

  • IMDSPDevice2 Interface
  • IMDSPDevice3 Interface
  • Interfaces for Service Providers


IMDSPDevice::EnumStorage (deprecated)

The EnumStorage method retrieves a pointer to an IMDSPEnumStorage interface of an enumerator object that represents the top-level storage(s) on the device. Top level storage for a device is the root directory of the storage medium.

Syntax

HRESULT EnumStorage(
  IMDSPEnumStorage**  ppEnumStorage
);

Parameters

ppEnumStorage

[out] Pointer to an IMDSPEnumStorage object.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
WMDM_E_NOTCERTIFIED | The caller is not certified.
E_OUTOFMEMORY | Insufficient memory for allocating the enumerator object.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice::GetDeviceIcon (deprecated)

The GetDeviceIcon method returns a HICON that represents the icon that the device service provider indicates must be used to represent this device.

Syntax

HRESULT GetDeviceIcon(
  ULONG*  hIcon
);

Parameters

hIcon

[out] Handle to an Icon object that receives the icon for the device. Before using it, the caller must cast the value to a HICON*. When an application is finished with the icon, it should call DestroyIcon to free the resource. DestroyIcon is a standard Win32 function.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The hIcon parameter is an invalid or NULL pointer.
WMDM_E_NOTCERTIFIED | The caller is not certified.

Remarks

In addition to the values above, the HRESULT error code could be a Win32 error.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice::GetFormatSupport (deprecated)

The GetFormatSupport method retrieves all the formats supported by the device. The format information includes codecs, file formats, and digital rights management schemes.

Syntax

HRESULT GetFormatSupport(
  _WAVEFORMATEX**  pFormatEx,
  UINT*  pnFormatCount,
  LPWSTR**  pppwszMimeType,
  UINT*  pnMimeTypeCount
);

Parameters

pFormatEx

[out] Pointer to an array of _WAVEFORMATEX structures containing information about codecs and bit rates supported by the device.

pnFormatCount

[out] Pointer to the number of elements in the pFormatEx array.

pppwszMimeType

[out] Pointer to an array that describes file formats and digital rights management schemes supported by the device.

pnMimeTypeCount

[out] Pointer to the number of elements in the pppwszMimeType array.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
WMDM_E_NOTCERTIFIED | The caller is not certified.
E_OUTOFMEMORY | Insufficient memory for allocating format structures and MIME type strings.

Remarks

Memory for the pFormatEx and pppwszMimeType parameters is allocated by this method and must be freed by the caller using CoTaskMemFree, a standard Win32 function.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice::GetManufacturer (deprecated)

The GetManufacturer method retrieves the name of the manufacturer of the device.

Syntax

HRESULT GetManufacturer(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to a caller-allocated wide character array that receives the manufacturer name string.

nMaxChars

[in] Maximum number of characters to copy to the string, including the termination character.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the return string. Check nMaxChars for the required buffer size.
E_FAIL | An unspecified error occurred.

Remarks

The LPWSTR string type is a 16-bit Unicode character string and does not accept byte-sized characters. To convert a string of byte-sized characters (LPCSTR) to an LPWSTR string, use the MultiByteToWideChar function, as described in the Microsoft® Windows® Platform Software Development Kit documentation.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice::GetName (deprecated)

The GetName method retrieves the name of the device.

Syntax

HRESULT GetName(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to an array of 16-bit Unicode characters that receives the device name string.

nMaxChars

[in] Maximum number of characters to copy to the string.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the return string. Check nMaxChars for the required buffer size.
E_FAIL | An unspecified error occurred.

Remarks

The LPWSTR string type is a 16-bit Unicode character string and does not accept byte-sized characters. To convert a string of byte-sized characters (LPCSTR) to an LPWSTR string, use the MultiByteToWideChar function as described in Microsoft Windows documentation.

Device names must not contain trailing spaces.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface
  • IMDSPDevice::GetType


IMDSPDevice::GetPowerSource (deprecated)

The GetPowerSource method reports whether the device is capable of running on batteries, external power, or both, and on which type of power source it is currently running. If the device is running on batteries, this method also reports the percentage of total power remaining in the batteries.

Syntax

HRESULT GetPowerSource(
  DWORD*  pdwPowerSource,
  DWORD*  pdwPercentRemaining
);

Parameters

pdwPowerSource

[out] Pointer to a DWORD that receives a value indicating the current power source for the device. The value is one of the following flags.

Flag | Description
WMDM_POWER_CAP_BATTERY | The media device can run on batteries.
WMDM_POWER_CAP_EXTERNAL | The media device can run on external power.
WMDM_POWER_IS_BATTERY | The media device is currently running on batteries.
WMDM_POWER_IS_EXTERNAL | The media device is currently running on external power.
WMDM_POWER_PERCENT_AVAILABLE | The percentage of power remaining was returned in pdwPercentRemaining.

pdwPercentRemaining

[out] If the device is running on batteries, pdwPercentRemaining specifies a pointer to a DWORD containing the percentage of total battery power remaining.

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.

Return code | Description
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.
WMDM_E_NOTSUPPORTED | The device cannot report power capabilities.

Remarks

Only physical devices report power source capabilities and current power source. Software implementations of devices report no power capabilities or current power source.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice::GetSerialNumber (deprecated)

The GetSerialNumber method retrieves the serial number that uniquely identifies the device.

Syntax

HRESULT GetSerialNumber(
  PWMDMID  pSerialNumber,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pSerialNumber

[out] Pointer to a WMDMID structure that receives the serial number for the device. This parameter is included in the output message authentication code.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

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.

Return code | Description
E_INVALIDARG | The pSerialNumber parameter is an invalid or NULL pointer.
WMDM_E_NOTCERTIFIED | The caller is not authorized, and calls to other service provider interfaces will also fail and return this code.
WMDM_E_NOTSUPPORTED | This device does not support serial numbers.
E_FAIL | An unspecified error occurred.

Remarks

Not all media devices support serial numbers. To determine whether the device supports serial numbers, always check the return code when calling this method. If a media device does support serial numbers, the serial number of the media device is guaranteed to be unique.

This method is optional. When transferring protected content, Windows Media Device Manager uses IMDSPStorageGlobals::GetSerialNumber. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface
  • IMDSPStorageGlobals::GetSerialNumber


IMDSPDevice::GetStatus (deprecated)

The GetStatus method retrieves all the device status information that the device can provide.

Syntax

HRESULT GetStatus(
  DWORD*  pdwStatus
);

Parameters

pdwStatus

[out] Pointer to a DWORD that receives the current device status. These status values are defined in the following table.

Status | Description
WMDM_STATUS_READY | Windows Media Device Manager and its subcomponents are in a ready state.
WMDM_STATUS_BUSY | An operation is ongoing. Check other status values to determine which operation it is.
WMDM_STATUS_DEVICE_NOTPRESENT | The device is not connected to the computer.
WMDM_STATUS_STORAGE_NOTPRESENT | The medium is not present. For devices that support more than one medium, this value is reported only from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGE_INITIALIZING | The device is currently busy formatting media on the device.
WMDM_STATUS_STORAGE_BROKEN | The medium is not working. For devices that support more than one medium, this value is reported only from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGE_NOTSUPPORTED | The medium is not supported by the device. For devices that support more than one medium, this value is returned only from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGE_UNFORMATTED | The medium is not formatted. For devices that support more than one medium, this value is returned only from the IWMDMStorageGlobals interface.
WMDM_STATUS_STORAGECONTROL_INSERTING | The IWMDMStorageControl::Insert method is currently running.
WMDM_STATUS_STORAGECONTROL_DELETING | The IWMDMStorageControl::Delete method is currently running.
WMDM_STATUS_STORAGECONTROL_MOVING | The IWMDMStorageControl::Move method is currently running.
WMDM_STATUS_STORAGECONTROL_READING | The IWMDMStorageControl::Read method is currently running.

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.

Return code | Description
E_INVALIDARG | The pdwStatus parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

One or more status values can be returned from this call. All the status values of all the interfaces of the media device are reported through this call. For example, if a storage operation, such as writing a file to a media device is ongoing, a call to this method reports the busy status of that operation. For any ongoing operation, the status value WMDM_STATUS_BUSY is always present.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface
  • IWMDMStorageControl Interface
  • IWMDMStorageGlobals Interface


IMDSPDevice::GetType (deprecated)

The GetType method retrieves device type information.

Syntax

HRESULT GetType(
  DWORD*  pdwType
);

Parameters

pdwType

[out] Pointer to a DWORD that receives the type attributes of the device. The following table shows the types received.

Device type | Description
WMDM_DEVICE_TYPE_PLAYBACK | The media device supports audio playback.
WMDM_DEVICE_TYPE_RECORD | The media device supports audio recording.
WMDM_DEVICE_TYPE_DECODE | The media device supports audio format decoding.
WMDM_DEVICE_TYPE_ENCODE | The media device supports audio format encoding.
WMDM_DEVICE_TYPE_STORAGE | The media device has on-board storage for media files.
WMDM_DEVICE_TYPE_SDMI | The media device is SDMI compliant.
WMDM_DEVICE_TYPE_NONSDMI | The media device is not SDMI compliant.
WMDM_DEVICE_TYPE_VIRTUAL | The media device is not a physical device.
WMDM_DEVICE_TYPE_NONREENTRANT | The media device must synchronize access to the service provider services.
WMDM_DEVICE_TYPE_FILELISTRESYNC | The media device allows the file list to be resynchronized.
WMDM_DEVICE_TYPE_VIEW_PREF_METADATAVIEW | The media device prefers metadata views while its storages are enumerated.

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.

Return code | Description
E_INVALIDARG | The pdwType parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface
  • IMDSPDevice::GetName


IMDSPDevice::GetVersion (deprecated)

The GetVersion method retrieves the version number of the device.

Syntax

HRESULT GetVersion(
  DWORD*  pdwVersion
);

Parameters

pdwVersion

[out] Pointer to a DWORD to receive the version number of the device.

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.

Return code | Description
E_INVALIDARG | The pdwVersion parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | This device does not support version numbers.
E_FAIL | An unspecified error occurred.

Remarks

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice::SendOpaqueCommand (deprecated)

The SendOpaqueCommand method sends a command through Windows Media Device Manager. Without acting on it, Windows Media Device Manager passes the command through to a device.

Syntax

HRESULT SendOpaqueCommand(
  OPAQUECOMMAND*  pCommand
);

Parameters

pCommand

[in, out] Pointer to an OPAQUECOMMAND structure containing the information required to execute the command.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pCommand parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is used with device commands that do not affect Windows Media Device Manager, and are passed through unchanged. A more efficient way to call commands on a device is to call IMDSPDevice3::DeviceIoControl.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface


IMDSPDevice2 Interface (deprecated)

The IMDSPDevice2 interface extends IMDSPDevice by getting extended formats, getting Plug and Play (PnP) device names, enabling the use of property pages, and making it possible to get a pointer to a storage medium from its name.

In addition to the methods inherited from IMDSPDevice, the IMDSPDevice2 interface exposes the following methods.

Method | Description
GetCanonicalName | Gets the name of a Plug and Play device. This method can return E_NOTIMPL.
GetFormatSupport2 | Gets the formats supported by a device, including audio and video formats, codecs, and MIME file formats.
GetSpecifyPropertyPages | Gets property pages of the portable device.
GetStorage | Returns a storage object from a storage name.

See Also

  • IMDSPDevice Interface
  • IMDSPDevice3 Interface
  • Interfaces for Service Providers


IMDSPDevice2::GetCanonicalName (deprecated)

The GetCanonicalPName method gets the canonical name of a device.

Syntax

HRESULT GetCanonicalName(
  LPWSTR  pwszPnPName,
  UINT  nMaxChars
);

Parameters

pwszPnPName

[out] A wide character, null-terminated buffer holding the canonical name. The caller allocates and releases this buffer.

nMaxChars

[in] Integer containing the maximum number of characters that can be placed in pwszCanonicalName, including the termination character.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Possible values include, but are not limited to, those in the following table.

Return code | Description
E_INVALIDARG | The pwszCanonicalName parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not support a canonical name.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the canonical name.
E_FAIL | An unspecified error occurred.

Remarks

This method returns a canonical name for the device. The service provider should return the device path name of the device as its canonical name. The service provider is passed the device path name in the CreateDevice method on the IMDServiceProvider2 interface.

This is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDServiceProvider2 Interface
  • IMDServiceProvider2::CreateDevice
  • IMDSPDevice2 Interface


IMDSPDevice2::GetFormatSupport2 (deprecated)

The GetFormatSupport2 method gets the formats supported by a device, including audio and video codecs, and MIME file formats.

Syntax

HRESULT GetFormatSupport2(
  DWORD  dwFlags,
  _WAVEFORMATEX**  ppAudioFormatEx,
  UINT*  pnAudioFormatCount,
  _VIDEOINFOHEADER**  ppVideoFormatEx,
  UINT*  pnVideoFormatCount,
  WMFILECAPABILITIES**  ppFileType,
  UINT*  pnFileTypeCount
);

Parameters

dwFlags

[in] DWORD containing audio formats, video formats, and MIME types. This flag specifies what the application is requesting the service provider to fill in. The caller can set one or more of the following three values.

Value | Description
WMDM_GET_FORMAT_SUPPORT_AUDIO | Service provider should fill in audio parameters.
WMDM_GET_FORMAT_SUPPORT_VIDEO | Service provider should fill in video parameters.
WMDM_GET_FORMAT_SUPPORT_FILE | Service provider should fill in file parameters.

ppAudioFormatEx

[out] Pointer to an array of _WAVEFORMATEX structures containing information about audio codecs and bit rates supported by the device.

pnAudioFormatCount

[out] Pointer to an integer containing the audio format count.

ppVideoFormatEx

[out] Pointer to an array of _VIDEOINFOHEADER structures containing information about video codecs and formats supported by the device.

pnVideoFormatCount

[out] Pointer to an integer containing the video format count.

ppFileType

[out] Pointer to an array of WMFILECAPABILITIES structures containing information about file types supported by the device.

pnFileTypeCount

[out] Pointer to an integer containing the file format count.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.
E_OUTOFMEMORY | Not enough memory to return the structures

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice2 Interface


IMDSPDevice2::GetSpecifyPropertyPages (deprecated)

The GetSpecifyPropertyPages method gets property pages describing non-standard capabilities of portable devices.

Syntax

HRESULT GetSpecifyPropertyPages(
  ISpecifyPropertyPages**  ppSpecifyPropPages,
  IUnknown***  pppUnknowns,
  ULONG*  pcUnks
);

Parameters

ppSpecifyPropPages

[out] Pointer to a Win32 ISpecifyPropertyPages interface pointer.

pppUnknowns

[out] Array of IUnknown interface pointers. These interfaces will be passed to the property page and can be used to pass information between the property page and the service provider.

pcUnks

[out] Size of the pppUnknowns array.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

Memory for the pppUnknowns array should be allocated by this method and must be freed by the caller using CoTaskMemFree, a standard Win32 function.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice2 Interface


IMDSPDevice2::GetStorage (deprecated)

The GetStorage method makes it possible to go directly to a storage based on its name instead of enumerating through all storages to find it.

Syntax

HRESULT GetStorage(
  LPCWSTR  pszStorageName,
  IMDSPStorage**  ppStorage
);

Parameters

pszStorageName

[in] Pointer to a null-terminated string containing the name of the storage to find.

ppStorage

[out] Pointer to the storage object specified by the pszStorageName parameter.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The storage cannot be found.
E_FAIL | An unspecified error occurred.
E_NOTIMPL | The method is not implemented.

Remarks

The GetStorage method does not support wildcard characters. It is not recursive, that is, it will only find storages in the root of the device.

If this method is not implemented, it should return E_NOTIMPL. (It should not return WMDM_E_NOT_SUPPORTED or any other codes indicating that this method is not implemented). This will ensure that Windows Media Device Manager will attempt to substitute this functionality itself by enumerating all storages to find a match based on the storage name passed in as pszStorageName.

It is strongly recommended that a service provider implement this method to efficiently return a storage object based on name.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice2 Interface


IMDSPDevice3 Interface (deprecated)

The IMDSPDevice3 interface must be supported for devices that expect to synchronize with Windows Media Player. For more information, see Enabling Synchronization with Windows Media Player.

The IMDSPDevice3 interface extends IMDSPDevice2 by providing ability to query properties and capabilities of the device with regard to an object format.

Note Unless the service provider has added the device parameter UseExtendedWmdm with a value of 1, Windows Media Device Manager will not call this interface. See Device Parameters for more information about this.

In addition to the methods inherited from IMDSPDevice2, the IMDSPDevice3 interface exposes the following methods.

Method | Description
DeviceIoControl | Calls the device I/O control.
FindStorage | Finds the storage through its unique identification (ID).
GetFormatCapability | Retrieves information from a device about the values or ranges of values supported by the device for each aspect of a particular object format.
GetProperty | Retrieves device-specific properties.
SetProperty | Sets device-specific properties that are writeable.

See Also

  • IMDSPDevice Interface
  • IMDSPDevice2 Interface
  • Interfaces for Service Providers


IMDSPDevice3::DeviceIoControl (deprecated)

The DeviceIoControl method calls the device I/O control.

Syntax

HRESULT DeviceIoControl(
  DWORD  dwIoControlCode,
  BYTE*  lpInBuffer,
  DWORD  nInBufferSize,
  BYTE*  lpOutBuffer,
  LPDWORD  pnOutBufferSize
);

Parameters

dwIoControlCode

[in] I/O control code being sent to the device.

lpInBuffer

[in] Input buffer supplied by the calling application. This can be NULL if nInBufferSize is zero.

nInBufferSize

[in] Size of lpInBuffer, in bytes.

lpOutBuffer

[out] Output buffer, supplied by the calling application.

pnOutBufferSize

[in] Size of lpOutBuffer, in bytes.

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.
S_FALSE | The method failed.
E_INVALIDARG | The parameters are invalid or NULL.
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 IMDSPDevice::SendOpaqueCommand, this method better aligns with the DeviceIoControl Windows API because the output buffer is supplied by the caller. Also, unlike IMDSPDevice::SendOpaqueCommand, this method does not involve any MAC check and is more efficient.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice::SendOpaqueCommand
  • IMDSPDevice3 Interface
  • IWMDMDevice3::DeviceIoControl


IMDSPDevice3::FindStorage (deprecated)

The FindStorage method finds a storage with the given persistent unique identifier. The persistent unique identifier of a storage is described by the g_wszWMDMPersistentUniqueID property of that storage.

Syntax

HRESULT FindStorage(
  WMDM_FIND_SCOPE  findScope,
  LPCWSTR  pwszUniqueID,
  IMDSPStorage**  ppStorage
);

Parameters

findScope

[in] Scope of the find operation. It must be one of the following values.

Value | Description
WMDM_FIND_SCOPE_GLOBAL | Search the whole device.
WMDM_FIND_SCOPE_IMMEDIATE_CHILDREN | Search only in the immediate children of the current storage.

pwszUniqueID

[in] Persistent unique identifier of the storage.

ppStorage

[out] Pointer to the returned storage specified by the pwszUniqueID parameter.

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 | The findScope parameter is invalid, or pwszUniqueID or ppStorage is NULL.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND) | No storage was found with the specified persistent unique identifier.

Remarks

The service provider returns a persistent unique identifier through the g_wszWMDMPersistentUniqueID property of the storage. For a specific storage, the persistent unique identifier supplied by service provider should be same across different device connect sessions.

The application may call FindStorage with this persistent unique identifier at a later point. In response, Windows Media Device Manager calls this method on the service provider (SP).

A persistent unique identifier is used to uniquely identify content stored on a particular device. It does not represent a content-specific globally unique identifier that remains identical across all devices. Thus, the same content stored in different storages will have different persistent unique identifiers.

Windows Media Device Manager calls this method only for devices that are registered to enable synchronization with Windows Media Player. For more information, see Enabling Synchronization with Windows Media Player.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Synchronization with Windows Media Player
  • IMDSPDevice3 Interface
  • IMDSPStorage3::GetMetadata
  • IMDSPStorage4::FindStorage
  • IMDSPStorage4::GetSpecifiedMetadata
  • Metadata Constants
  • WMDM_FIND_SCOPE


IMDSPDevice3::GetFormatCapability (deprecated)

The GetFormatCapability method retrieves information from a device about the values or ranges of values supported by the device for each aspect of a particular object format.

Syntax

HRESULT GetFormatCapability(
  WMDM_FORMATCODE  format,
  WMDM_FORMAT_CAPABILITY*  pFormatSupport
);

Parameters

format

[in] WMDM_FORMATCODE

Enumerated value representing inquired format.

pFormatSupport

[out] Returned WMDM_FORMAT_CAPABILITY structure containing the values or ranges of values supported for each aspect of a particular object format.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The device does not support this method or the format specified.

Remarks

This method can be called for any of the supported formats. The list of supported formats are represented by g_wszWMDMFormatsSupported device property.

For a particular format, this method should return all configurations of supported properties (for example, combinations of bit rate and sample rate). This information is expressed as a format capability. For detailed information, see WMDM_FORMAT_CAPABILITY.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice3 Interface
  • IMDSPDevice3::GetProperty
  • WMDM_ENUM_PROP_VALID_VALUES_FORM
  • WMDM_FORMAT_CAPABILITY
  • WMDM_PROP_CONFIG
  • WMDM_PROP_DESC
  • WMDM_PROP_VALUES_ENUM
  • WMDM_PROP_VALUES_RANGE


IMDSPDevice3::GetProperty (deprecated)

The GetProperty method retrieves a specific device property.

Syntax

HRESULT GetProperty(
  LPCWSTR  pwszPropName,
  PROPVARIANT*  pValue
);

Parameters

pwszPropName

[in] Name of property being retrieved from the device.

pValue

[out] Returned value for the property.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The property is not supported by the device or the device returned an error.

Remarks

The variant that pValue points to is set to an empty PROPVARIANT, that is, its VT is set to VT_EMPTY.

Service provider should set this variant to the appropriate property value for the property pwszPropName.

If pwszPropName is g_wszWMDMSupportedDeviceProperties, service provider should return an array of the supported device properties. In such case, the VT of variant should be VT_BSTR | VT_ARRAY.

For a list of standard device property names, see Metadata Constants.

This method is similar to the IMDSPStorage3::GetMetadata and IMDSPStorage4::GetSpecifiedMetadata methods for storages, but this method can get only one property at a time.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice3 Interface
  • IMDSPDevice3::SetProperty
  • IMDSPStorage3::GetMetadata
  • IMDSPStorage4::GetSpecifiedMetadata
  • Metadata Constants


IMDSPDevice3::SetProperty (deprecated)

The SetProperty method sets a specific device property that is writable.

Syntax

HRESULT SetProperty(
  LPCWSTR  pwszPropName,
  PROPVARIANT*  pValue
);

Parameters

pwszPropName

[in] Name of device property being set.

pValue

[in] Value of device property being set.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
WMDM_E_NOTSUPPORTED | The property is not supported by the device, or this property cannot be set, or the device returned an error.

Remarks

This method sets the specified device property.

For a list of device property names, see Metadata Constants.

This method is similar to the SetMetadata method for storages, but this method can set only one property at a time.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice3 Interface
  • IMDSPDevice3::GetProperty
  • IMDSPStorage3::SetMetadata
  • IMDSPStorage4::GetSpecifiedMetadata
  • Metadata Constants


IMDSPDeviceControl Interface (deprecated)

The IMDSPDeviceControl interface provides methods for controlling devices. After this interface is acquired from a specific instance of the IMDSPDevice interface, the control methods are used for remote control of streaming audio play, record, pause, stop, and seek operations on that device. Implementing this interface is optional. For more information, see Mandatory and Optional Interfaces.

The IMDSPDeviceControl interface methods support several modes of audio control, depending on the context in which they are used. That context is defined by the Seek method. The GetCapabilities method is used to determine what kinds of operations can be performed by the device.

In addition to the methods inherited from IUnknown, the IMDSPDeviceControl interface exposes the following methods.

Method | Description
GetCapabilities | Retrieves the device capabilities to determine what operations the device can perform.
GetDCStatus | Retrieves the control status of the device.
Pause | Pauses the current playback or record operation and saves the current file position.
Play | Begins playing at the current seek position.
Record | Begins recording from the device's external record input at the current seek position.
Resume | Resumes the current playback or record operation from the file position saved during the call to Pause.
Seek | Seeks to a position that is used as the starting point by the Play or Record methods.
Stop | Stops the current playback or record operation.

See Also

  • Interfaces for Service Providers


IMDSPDeviceControl::GetCapabilities (deprecated)

The GetCapabilities method retrieves the capabilities mask for the device with which this control interface is associated. The capabilities describe the methods of the device control that are supported by the media device.

Syntax

HRESULT GetCapabilities(
  DWORD*  pdwCapabilitiesMask
);

Parameters

pdwCapabilitiesMask

[out] Pointer to a DWORD containing the capabilities of the device. The following flags can be returned in this variable.

Flag | Description
MDM_DEVICECAP_CANPLAY | The media device can play MP3 audio.
MDM_DEVICECAP_CANSTREAMPLAY | The media device can play streaming audio directly from the host computer.
MDM_DEVICECAP_CANRECORD | The media device can record audio.
MDM_DEVICECAP_CANSTREAMRECORD | The media device can record streaming audio directly to the host computer.
MDM_DEVICECAP_CANPAUSE | The media device can pause during play or record operations.
MDM_DEVICECAP_CANRESUME | The media device can resume an operation from a pause command.
MDM_DEVICECAP_CANSTOP | The media device can stop playing before the end of a file.
MDM_DEVICECAP_CANSEEK | The media device can seek to a position other than the beginning of a file.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwCapabilitiesMask parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDeviceControl Interface


IMDSPDeviceControl::GetDCStatus (deprecated)

The GetDCStatus method retrieves the control status of the device.

Syntax

HRESULT GetDCStatus(
  DWORD*  pdwStatus
);

Parameters

pdwStatus

[out] Pointer to a DWORD that contains the control status of the device. The control status value contains one or more of the following flags.

Flag | Description
WMDM_STATUS_READY | Windows Media Device Manager and its subcomponents are in a ready state.
WMDM_STATUS_BUSY | An operation is currently being performed. Evaluate the other status values to determine which operation it is.
WMDM_STATUS_DEVICECONTROL_PLAYING | The device is currently playing.
WMDM_STATUS_DEVICECONTROL_RECORDING | The device is currently recording.
WMDM_STATUS_DEVICECONTROL_PAUSED | The device is currently paused.
WMDM_STATUS_DEVICECONTROL_REMOTE | The play or record operation of the device is being remotely controlled by the application.
WMDM_STATUS_DEVICECONTROL_STREAM | The play or record method is streaming data to or from the media device.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwStatus parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This call returns status values specific to the device control operations of this interface. The control status can provide information about the state of control-related activities of the device, such as playing, recording, and so on. However, it cannot provide information about the global status of the device, such as whether the device is downloading data or being accessed for some other reason. If the device is busy for any reason other than device control, you receive a busy code and must call the GetStatus method of the associated IMDSPDevice interface for more detailed information.

You must not attempt to call the Play, Record, Pause, Resume, or Stop methods of this interface if the status value WMDM_STATUS_BUSY is returned and the status value does not contain any other values from the table of status values.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDeviceControl Interface


IMDSPDeviceControl::Pause (deprecated)

The Pause method pauses the current play or record session at the current position within the content.

Syntax

HRESULT Pause();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The device is already paused.
WMDM_E_NOTSUPPORTED | The pause function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

The current play or record session is paused and the current file position is saved. A subsequent call to the Resume method restarts the play or record operation at the saved file position.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDeviceControl Interface


IMDSPDeviceControl::Play (deprecated)

The Play method begins playing at the current seek position. If the Seek method has not been called, then playing begins at the beginning of the first file, and the play length is not defined.

Syntax

HRESULT Play();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The device is busy.
WMDM_E_NOTSUPPORTED | The play function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

This method is used to invoke both device playback (playback of an audio track on a storage medium of the media device) and streaming audio playback (streaming audio data from the user's computer to the media device, where it is played). The Seek method determines the form of playback that occurs.

Some devices do not support either device playback or streaming audio playback. Before attempting to start playback of a particular type, the GetCapabilities method must be called. If unsupported playback is attempted, this method returns WMDM_E_NOTSUPPORTED.

To determine whether an audio format can be played by the media device before invoking the play operation, you can call the IMDSPDevice::GetFormatSupport method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice::GetFormatSupport
  • IMDSPDeviceControl Interface
  • IMDSPDeviceControl::GetCapabilities
  • IMDSPDeviceControl::Seek


IMDSPDeviceControl::Record (deprecated)

The Record method begins recording from the device's external record input at the current seek position. The Seek method must be called first.

Syntax

HRESULT Record(
  _WAVEFORMATEX*  pFormat
);

Parameters

pFormat

[in] Pointer to a _WAVEFORMATEX structure containing the format in which the data must be recorded.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The device is already performing an operation.
WMDM_E_NOTSUPPORTED | The record function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

This method is used to invoke both device recording (recording of an audio track to be stored on the media device) and streaming audio data from the media device to be recorded on the computer. The Seek method determines which form of recording occurs.

Some devices do not support either type of recording. The GetCapabilities method must be called before you start recording. If an unsupported type of recording is attempted, this method returns WMDM_E_NOTSUPPORTED.

An argument for the pFormat parameter can be supplied to specify an audio data format for recording. To determine the formats supported by the device, see IMDSPDevice::GetFormatSupport. If the pFormat parameter is set to NULL, the device records audio data in the default format.

When you use device recording, you must enumerate the storage medium contents to find the new object after the record operation is finished.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • IMDSPDevice::GetFormatSupport
  • IMDSPDeviceControl Interface
  • IMDSPDeviceControl::GetCapabilities
  • IMDSPDeviceControl::Seek


IMDSPDeviceControl::Resume (deprecated)

The Resume method resumes the current playback or record operation from the file position saved during the call to Pause.

Syntax

HRESULT Resume();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The device is not paused.
WMDM_E_NOTSUPPORTED | The resume function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDeviceControl Interface
  • IMDSPDeviceControl::Pause


IMDSPDeviceControl::Seek (deprecated)

The Seek method seeks to a position that is used as the starting point by the Play or Record methods.

Syntax

HRESULT Seek(
  UINT  fuMode,
  int  nOffset
);

Parameters

fuMode

[in] Mode for the seek operation being performed. The fuMode parameter must be one of the following modes.

Mode | Description
MDSP_SEEK_BOF | Seek to a position that is nOffset units after the beginning of the file.
MDSP_SEEK_CUR | Seek to a position that is nOffset units from the current position.
MDSP_SEEK_EOF | Seek to a position that is nOffset units before the end of the file.

nOffset

[in] Number of units by which the seek operation moves the starting position away from the origin specified by fuMode. The units of nOffset are defined by the content. They can be milliseconds for music, pages for electronic books, and so on.

A positive value for nOffset indicates seeking forward through the file. A negative value indicates seeking backward through the file. Any combination of nOffset and fuMode that indicates seeking to a position before the beginning of the file or after the end of the file is not valid, and causes the method to return E_INVALIDARG.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | One or more parameters are invalid.
WMDM_E_NOTSUPPORTED | Seek is not implemented on this device.
E_FAIL | An unspecified error occurred.

Remarks

The seek position is defined by passing either an IWMDMStorage interface pointing to a location on a storage medium of the device, or an IWMDMOperation interface that has been implemented to support streaming audio. The IMDSPObjectInfo interface can also be passed to describe some point within the object to which the specified interface points.

For device playback, if Seek is not called before Play, then playback starts at the first audio track on the first storage medium on the media device.

For device recording, if Seek is not called before Record, the record operation fails. After the Record method is called, subsequent calls to the IMDSPObjectInfo::GetLastPlayPosition method report the total play length at any time, and equal the value returned from IMDSPObjectInfo::GetTotalLength. The recording length can be limited by calling the IMDSPObjectInfo::SetPlayLength method after returning from the Seek call.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDeviceControl Interface
  • IMDSPObjectInfo Interface
  • IWMDMOperation Interface
  • IWMDMStorage Interface


IMDSPDeviceControl::Stop (deprecated)

The Stop method stops the current stream.

Syntax

HRESULT Stop();

Parameters

This method takes no parameters.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The device is busy.
WMDM_E_NOTSUPPORTED | The stop function is not implemented on this device.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IWMDMDeviceControl Interface


IMDSPDirectTransfer Interface (deprecated)

The IMDSPDirectTransfer interface enables Windows Media Device Manager to delegate content transfer to the service provider. In this case Windows Media Device Manager does not do any processing of the content before sending it to the service provider. The service provider gets full control of the source.

In addition to the methods inherited from IUnknown, the IMDSPDirectTransfer interface exposes the following method.

Method | Description
TransferToDevice | Called by Windows Media Device Manager to delegate content transfer to the service provider.

See Also

  • Interfaces for Service Providers


IMDSPDirectTransfer::TransferToDevice (deprecated)

The TransferToDevice method is called by Windows Media Device Manager to delegate content transfer content to the service provider. The source can be specified either as a file or as an operation interface.

Syntax

HRESULT TransferToDevice(
  LPWSTR  pwszSourceFileName,
  IWMDMOperation*  pSourceOperation,
  UINT  fuFlags,
  LPWSTR  pwszDestinationName,
  IWMDMMetaData*  pSourceMetaData,
  IWMDMProgress*  pTransferProgress,
  IMDSPStorage**  ppNewObject
);

Parameters

pwszSourceFileName

[in] Source file name. The value contained in this parameter should be ignored if WMDM_CONTENT_OPERATIONINTERFACE is specified.

pSourceOperation

[in] Operation interface pointer that serves as the source. The value contained in this parameter should be ignored unless WMDM_CONTENT_OPERATIONINTERFACE is specified.

fuFlags

[in] Flags that affect behavior of this method. The fuFlags parameter must be one of the following values.

Value | Description
WMDM_CONTENT_FILE | The source is a file.
WMDM_CONTENT_FOLDER | The source is a folder.
WMDM_FILE_CREATE_OVERWRITE | Overwrite the destination file if it already exists.

pwszDestinationName

[in] Content should be transferred to the device with this name. This parameter is required.

pSourceMetaData

[in] Metadata interface pointer. The metadata object contains the source properties. This parameter is optional.

pTransferProgress

[in] Progress callback interface. The service provider should update the information during the progress of the transfer. This parameter is optional.

ppNewObject

[out] Newly created storage object. This parameter is optional. This can be NULL if the caller does not need to have the new object returned.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | One of the following is true: 1) Both pwszSourceFileName and pSourceOperation are specified; 2) pwszDestinationName is not specified; 3) fuFlags is invalid.
HRESULT_FROM_WIN32(ERROR_DISK_FULL) | There is not enough space on the disk.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS) | The file already exists and WMDM_FILE_CREATE_OVERWRITE was not specified. If the device allows duplicate file names, this could be acceptable and this error does not need to be returned.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) | Transfer of the specified content is not supported on the device.

Remarks

Windows Media Device Manager queries for IMDSPDirectTransfer interface during every transfer.

If the service provider supports the IMDSPDirectTransfer interface, Windows Media Device Manager simply delegates content transfer to the service provider. In this case, Windows Media Device Manager does not do any processing of the content before sending it to the service provider. The service provider gets full control of the source.

If the service provider does not support the IMDSPDirectTransfer interface, Windows Media Device Manager processes the source files and sends byte packets to the service provider. In addition, for protected content, Windows Media Device Manager calls the secure content provider to process the content before sending it to the service provider.

If IMDSPDirectTransfer is supported, Windows Media Device Manager delegates handling of the content to the service provider. This provides flexibility to the service provider for handling the content. In this case, the service provider is responsible for handling the protected content.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDirectTransfer Interface
  • IMDSPObject::Close
  • IMDSPObject::Open
  • IMDSPObject::Write
  • IWMDMMetaData Interface
  • IWMDMOperation Interface
  • IWMDMProgress Interface
  • IWMDMStorageControl Interface


IMDSPEnumDevice Interface (deprecated)

The IMDSPEnumDevice interface is used to enumerate the media devices. For more information on enumeration, see the Microsoft COM documentation on the COM page at the Microsoft Web site. The IMDSPEnumDevice interface is implemented on the device enumerator object. The only valid way to create a device enumerator object is to call IMDServiceProvider::EnumDevices. If the device implements IMDServiceProvider2::CreateDevice, this enumerator should enumerate only non-Plug and Play devices. The device enumerator should enumerate only the devices that are attached to the computer and are supported by the service provider.

In addition to the methods inherited from IUnknown, the IMDSPEnumDevice interface exposes the following methods.

Method | Description
Clone | Creates another enumerator that contains the same enumeration state as the current one.
Next | Returns a pointer to the next IMDSPDevice interface.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over the next specified number of media device interface(s) in the enumeration sequence.

See Also

  • IMDServiceProvider::EnumDevices
  • IMDSPDevice Interface
  • Interfaces for Service Providers


IMDSPEnumDevice::Clone (deprecated)

The Clone method creates another enumerator that contains the same enumeration state as the current one.

Syntax

HRESULT Clone(
  IMDSPEnumDevice**  ppEnumDevice
);

Parameters

ppEnumDevice

[out] Pointer to an IMDSPEnumDevice interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumDevice parameter is an invalid or NULL pointer.
E_OUTOFMEMORY | There is not enough memory to replicate this interface.
E_UNEXPECTED | The interface was not retrieved from a valid origin.

Remarks

Using this function, a client can record a particular point in the enumeration sequence, and then return to that point later. The new enumerator supports the same interface as the original one.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumDevice Interface


IMDSPEnumDevice::Next (deprecated)

The Next method retrieves a pointer to the next celt IMDSPDevice interfaces.

Syntax

HRESULT Next(
  ULONG  celt,
  IMDSPDevice**  ppDevice,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of devices requested.

ppDevice

[out] Array of celt pointers IMDSPDevice allocated by the caller. Return NULL to indicate that no more devices exist or an error has occurred. If celt is more than 1, the caller must allocate enough memory to store celt number of interface pointers.

pceltFetched

[out] Pointer to a ULONG variable that receives the number of interfaces retrieved.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The number of elements retrieved is less than celt.
E_FAIL | An unspecified error occurred.
E_OUTOFMEMORY | Not enough memory to create device objects.

Remarks

When there are no more service provider interfaces for enumerated devices, or when there are fewer of these interfaces than requested by the celt parameter, the return value from Next is S_FALSE. When this happens, the pceltFetched parameter must be queried to determine how many interfaces, if any, were returned.

The device enumerator may not reflect the effect of device insertion and removal.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice Interface
  • IMDSPEnumDevice Interface


IMDSPEnumDevice::Reset (deprecated)

The Reset method resets the enumeration sequence to the beginning. A subsequent call to Next fetches the first Windows Media Device Manager interface in the enumeration sequence.

Syntax

HRESULT Reset();

Parameters

This method takes no parameters.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumDevice Interface


IMDSPEnumDevice::Skip (deprecated)

The Skip method skips over the next specified number of media device interface(s) in the enumeration sequence.

Syntax

HRESULT Skip(
  ULONG  celt,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of elements to skip.

pceltFetched

[out] Pointer to the number of elements that actually were skipped.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The number of elements skipped is less than celt.
E_FAIL | An unspecified error occurred.

Remarks

If the number specified in the celt parameter is greater than the actual number of interfaces remaining in the enumeration sequence, then the return value from Skip is S_FALSE. When this happens, the pceltFetched parameter must be queried to determine how many interfaces were skipped. If you skip to the end of the array of enumerated media device interfaces, a subsequent call to Next returns S_FALSE.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumDevice Interface


IMDSPEnumStorage Interface (deprecated)

The IMDSPEnumStorage interface is used to enumerate the storage media on a device. For more information on the standard implementation of enumeration interfaces, see the Microsoft COM documentation, available at the Microsoft Web site. The storage media on a device are organized in a hierarchical manner similar to disk drives on a computer.

When accessed from the IMDSPDevice::EnumStorage method, this interface enumerates the individual storage media on the device in the same way that you would see the individual disk drives on a computer.

When accessed from the IWMDMStorage::EnumStorage method, this interface enumerates the contents of the storage medium. EnumStorage can be called on the enumerated storage objects recursively, and thus the contents of a storage medium are returned in the hierarchical fashion in which they are stored on the storage medium. If the file system of the storage medium supports a notion of order among the content, the enumerator will return the contents in the same order.

The storage enumerator returns a snapshot of the state of storages. It may not reflect the effect of storage media insertion and removal and may not reflect the effects of subsequent Insert, Move and Delete methods. The client should obtain a new enumerator to get the new state of the storage media.

The Insert, Move, and Delete methods of the IWMDMStorageControl interface change the order of files. If these operations are invoked, then the order of objects as originally returned by the IMDSPEnumStorage interface can be changed.

If an application is going to display the order of content on a media device, the application programmer must take into account order changes that can occur as a result of IWMDMStorageControl operations. There are two ways to deal with this situation. One way is to simply re-enumerate whenever a change to content occurs. Another way is to maintain the order of IWMDMStorage objects programmatically.

No matter how this issue is handled, it must be handled by the application if the order of files is important to the application.

In addition to the methods inherited from IUnknown, the IMDSPEnumStorage interface exposes the following methods.

Method | Description
Clone | Creates another enumerator that contains the same enumeration state as the current one.
Next | Retrieves a pointer to the next IMDSPStorage interface.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over the next specified number of storage interface(s) in the enumeration sequence.

See Also

  • IMDSPDevice::EnumStorage
  • IMDSPStorage Interface
  • Interfaces for Service Providers
  • IWMDMStorage Interface
  • IWMDMStorage::EnumStorage
  • IWMDMStorageControl Interface


IMDSPEnumStorage::Clone (deprecated)

The Clone method creates another enumerator that contains the same enumeration state as the current one.

Syntax

HRESULT Clone(
  IMDSPEnumStorage**  ppEnumStorage
);

Parameters

ppEnumStorage

[out] Pointer to an IMDSPEnumStorage interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppEnumStorage parameter is an invalid or NULL pointer.
E_OUTOFMEMORY | There is not enough memory to replicate this interface.
E_UNEXPECTED | The interface was not retrieved from a valid origin.

Remarks

Using this function, a client can record a particular point in the enumeration sequence, and return to that point at a later time. The new enumerator supports the same interface as the original one.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumStorage Interface


IMDSPEnumStorage::Next (deprecated)

The Next method returns a pointer to the next celt IMDSPStorage interfaces.

Syntax

HRESULT Next(
  ULONG  celt,
  IMDSPStorage**  ppStorage,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of storage interfaces requested.

ppStorage

[out] Array of celt IMDSPStorage interface pointers allocated by the caller. Return NULL if no more storage media exist, or an error has occurred. If celt is more than 1, the caller must allocate enough memory to store celt number of interface pointers.

pceltFetched

[out] Pointer to a ULONG variable that receives the count of interfaces returned.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | Number of interfaces retrieved is fewer than requested.
E_FAIL | An unspecified error occurred.

Remarks

When there are no more storage interfaces, or when there are fewer storage interfaces than requested, the return value from Next is S_FALSE. When this happens, the pceltFetched parameter must be queried to determine how many interfaces, if any, were returned.

The storage enumerator may not reflect the effect of media insertion and removal. In such cases, the client should obtain a new enumerator object.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumStorage Interface
  • IMDSPStorage Interface
  • IWMDMStorage Interface


IMDSPEnumStorage::Reset (deprecated)

The Reset method resets the enumeration sequence to the beginning. A subsequent call to the Next method fetches the first storage interface in the enumeration sequence.

Syntax

HRESULT Reset();

Parameters

This method takes no parameters.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumStorage Interface


IMDSPEnumStorage::Skip (deprecated)

The Skip method skips over the next specified number of storage interface(s) in the enumeration sequence.

Syntax

HRESULT Skip(
  ULONG  celt,
  ULONG*  pceltFetched
);

Parameters

celt

[in] Number of elements to skip.

pceltFetched

[out] Pointer to the number of elements actually skipped.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The number of skipped elements is less than celt.
E_FAIL | An unspecified error occurred.

Remarks

If the number specified in the celt parameter is greater than the actual number of storage interfaces remaining in the enumeration sequence, the return value from Skip is S_FALSE. When this happens, the pceltFetched parameter must be queried to determine how many interfaces were skipped. If you skip to the end of the array of storage interfaces, a subsequent call to Next returns S_FALSE.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPEnumStorage Interface


IMDSPObject Interface (deprecated)

The IMDSPObject interface manages the transfer of data to and from storage media.

The Open, Read, Write, and Close methods are valid only if the storage object is a file. The client would typically call Open, perform a number of Read or Write operations and then call Close. This allows for a buffered mode read/write of the storage medium. The service provider should be able to handle any other calls on the device or storage interfaces (for example, enumerating content or getting global information about the storage medium) while the read or write operation is in progress.

The service provider should also be able to handle simultaneous read or write operations on multiple files. If the underlying file-system does not support opening of multiple files at the same time, service provider should gracefully return an error.

The Delete, Rename, and Move methods are valid for both files and folders.

In addition to the methods inherited from IUnknown, the IMDSPObject interface exposes the following methods.

Method | Description
Close | Closes a file on a storage medium of a media device.
Delete | Deletes an object from a storage medium on a media device. This object can be either a file or a folder.
Move | Moves an object on a media device. This object can be either a file or a folder.
Open | Opens the associated object and prepares it for other operations. This object must be a file.
Read | Reads data from the object at the current position. This object must be a file.
Rename | Renames the associated object. This object can be either a file or a folder.
Seek | Sets the current position within the object. This object must be a file.
Write | Writes data to the object at the current position within the object. This object must be a file.

See Also

  • IMDSPObject2 Interface
  • Interfaces for Service Providers


IMDSPObject::Close (deprecated)

The Close method closes a file on a storage medium of a media device.

Syntax

HRESULT Close();

Parameters

This method takes no parameters.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | The operation is not supported by the medium.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_CALL_OUT_OF_SEQUENCE | Open was not called before Close.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObject Interface
  • IMDSPObject::Open
  • IMDSPObject::Read
  • IMDSPObject::Write


IMDSPObject::Delete (deprecated)

The Delete method removes an object or objects from a storage medium on a media device.

Syntax

HRESULT Delete(
  UINT  fuMode,
  IWMDMProgress*  pProgress
);

Parameters

fuMode

[in] Flag that must always be set to WMDM_MODE_RECURSIVE by the client. If the object is a folder, it and its contents, and all subfolders and their contents are deleted. If the object is a file, this parameter is ignored.

pProgress

[in] Pointer to an application-implemented IWMDMProgress interface that enables the application to receive progress notifications for lengthy Delete operations.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
E_INVALIDARG | The mode specified is invalid.
E_FAIL | An unspecified error occurred.

Remarks

This method permanently removes the object(s) from the storage medium.

When using a CompactFlash card reader/writer with Windows Media Device Manager service provider, calling IMDSPObject::Delete immediately after IMDSPObject::Write sometimes fails. This happens because data written to a CompactFlash reader/writer is buffered by the driver of the card reader/writer. The service provider responds as if the write operations are finished, but the driver writes them out to the device according to its own schedule. IMDSPObject::Delete fails if the driver has not finished its writing operation.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObject Interface
  • IWMDMProgress Interface


IMDSPObject::Move (deprecated)

The Move method moves a file or folder on a media device.

Syntax

HRESULT Move(
  UINT  fuMode,
  IWMDMProgress*  pProgress,
  IMDSPStorage*  pTarget
);

Parameters

fuMode

[in] Processing mode by which to invoke the Move operation and the method by which to move. Specify exactly one of the following two modes. If both modes are specified, block mode is used.

Mode | Description
WMDM_MODE_BLOCK | The operation will be performed using block mode processing. The call will not return until the operation is finished.
WMDM_MODE_THREAD | The operation will be performed using thread mode processing. The call will return immediately, and the operation will be performed in a background thread.

The following table lists flags that indicate where the object will be moved to. One value from this table is combined with one value from the preceding Mode table by using a bitwise OR.

Method of move | Description
WMDM_STORAGECONTROL_INSERTBEFORE | The object will be inserted before the target object.
WMDM_STORAGECONTROL_INSERTINTO | The object will be inserted into the target object. The target object must be a folder. If the target object is a file, this method fails.
WMDM_STORAGECONTROL_INSERTAFTER | The object will be inserted after the target object.

pProgress

[in] Pointer to an IWMDMProgress interface that has been implemented by the application to track the progress of ongoing operations. This parameter is optional and should be set to NULL when not being used.

pTarget

[in] Pointer to the target object before or after which you want to put the current object.

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.

Return code | Description
S_OK | The method succeeded.
E_BUSY | The media device is already busy with another operation.
E_INVALIDARG | One or more of the input parameters are invalid or NULL.

Remarks

A file or directory can be moved only within the same root storage. The object on which this method is called must be updated to reflect its new location.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObject Interface
  • IWMDMProgress Interface
  • IWMDMStorage Interface


IMDSPObject::Open (deprecated)

The Open method opens the associated object and prepares it for Read or Write operations. This operation is valid only if the storage object represents a file.

Syntax

HRESULT Open(
  UINT  fuMode
);

Parameters

fuMode

[in] Mode in which the file must be opened. It must be one of the following two values.

Value | Description
MDSP_READ | Query whether a subsequent call to Read would be allowed.
MDSP_WRITE | Query whether a subsequent call to Insert would be allowed.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
ERROR_TOO_MANY_OPEN_FILES | Cannot open any more files.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
E_INVALIDARG | The fuMode parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

If the underlying file-system does not support opening of multiple files at the same time, the service provider should gracefully the return Win32 error code ERROR_TOO_MANY_OPEN_FILES, if the client attempts to open more than one file at a time.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObject Interface
  • IMDSPObject::Close
  • IMDSPObject::Read
  • IMDSPObject::Seek
  • IMDSPObject::Write


IMDSPObject::Read (deprecated)

The Read method reads data from the object at the current position. This operation is valid only if the storage object represents a file.

Syntax

HRESULT Read(
  BYTE*  pData,
  DWORD*  pdwSize,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pData

[out] Pointer to a buffer to receive the data read from the object. This parameter is included in the output message authentication code and must be encrypted using CSecureChannelServer::EncryptParam. See Remarks.

pdwSize

[in, out] Pointer to a DWORD specifying the number of bytes of data to read. Upon return, this parameter contains the actual amount of data read. This parameter must be included in the input message authentication code.

abMac[WMDM_MAC_LENGTH]

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_CALL_OUT_OF_SEQUENCE | Open was not called before calling Read.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The MAC used for encryption should include both pData and pdwSize in calls to CSecureChannelServer::MACUpdate.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Encryption and Decryption
  • IMDSPObject Interface
  • IMDSPObject::Close
  • IMDSPObject::Open
  • IMDSPObject::Seek
  • IMDSPObject::Write


IMDSPObject::Rename (deprecated)

The Rename method renames the associated object which can be a file or a folder.

Syntax

HRESULT Rename(
  LPWSTR  pwszNewName,
  IWMDMProgress*  pProgress
);

Parameters

pwszNewName

[in] Pointer to a wide-character null-terminated string to receive a new name for the object. For information on how to use the LPWSTR variable type, see the Windows documentation.

pProgress

[in] Pointer to an application-implemented IWMDMProgress interface that enables the application to receive progress notification for lengthy renaming operations.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_NOTSUPPORTED | Renaming is not supported by this storage device.
E_INVALIDARG | The pwszNewName parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObject Interface
  • IWMDMProgress Interface


IMDSPObject::Seek (deprecated)

The Seek method sets the current position within the object. This operation is valid only if the storage object represents a file.

Syntax

HRESULT Seek(
  UINT  fuFlags,
  DWORD  dwOffset
);

Parameters

fuFlags

[in] Mode in which the file must be opened. It must be one of the values in the following table.

Value | Description
MDSP_SEEK_BOF | Seek dwOffset bytes forward from the beginning of the file.
MDSP_SEEK_CUR | Seek dwOffset bytes forward from the current position.
MDSP_SEEK_EOF | Seek dwOffset bytes backward from the end of the file.

dwOffset

[in] DWORD containing the number of bytes to seek.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_NOTSUPPORTED | Seeking is not supported on this medium.
E_INVALIDARG | The mode specified in fuFlags is invalid.
E_FAIL | An unspecified error occurred.

Remarks

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObject Interface
  • IMDSPObject::Open
  • IMDSPObject::Read


IMDSPObject::Write (deprecated)

The Write method writes data to the object at the current position within the object. This operation is valid only if the storage object represents a file.

Syntax

HRESULT Write(
  BYTE*  pData,
  DWORD*  pdwSize,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pData

[in] Pointer to the buffer containing the data to write to the object. This parameter is encrypted and must be decrypted using CSecureChannelServer::DecryptParam with the MAC in abMac. See Remarks.

pdwSize

[in, out] DWORD containing the number of bytes of data to write. Upon return, this parameter contains the actual number of bytes written. This parameter must be included in both the input and output message authentication codes.

abMac[WMDM_MAC_LENGTH]

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_CALL_OUT_OF_SEQUENCE | Open was not called before calling Write.
E_INVALIDARG | One or more parameters is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.
HRESULT_FROM_WIN32 (ERROR_DISK_FULL) | Write failed because there is not enough space on the disk. Note: Use the macro HRESULT_FROM_WIN32 to convert the Windows error ERROR_DISK_FULL (defined in Winerror.h) to an HRESULT.

Remarks

The MAC used for encryption should include both pData and pdwSize in calls to CSecureChannelServer::MACUpdate.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Encryption and Decryption
  • IMDSPObject Interface
  • IMDSPObject::Close
  • IMDSPObject::Open
  • IMDSPObject::Read


IMDSPObject2 Interface (deprecated)

Windows Media Device Manager uses IMDSPObject2 to enable more efficient file reading and writing.

Note Unless the service provider has added the device parameter UseExtendedWmdm with a value of 1, Windows Media Device Manager will not call this interface. See Device Parameters for more information about this.

In addition to the methods inherited from IMDSPObject, the IMDSPObject2 interface exposes the following methods.

Method | Description
ReadOnClearChannel | Reads data from the object at the current position without secure authenticated channel (SAC).
WriteOnClearChannel | Writes data to the object at the current position without SAC.

See Also

  • IMDSPObject Interface
  • Interfaces for Service Providers


IMDSPObject2::ReadOnClearChannel (deprecated)

The ReadOnClearChannel method reads data from the object at the current position without using secure authenticated channels. This is still secure for use with DRM-protected content. This operation is valid only if the storage object represents a file. If IMDSPObject2 is supported, this method must be implemented. Windows Media Device Manager does not fall back to IMDSPObject::Read if this method fails.

Syntax

HRESULT ReadOnClearChannel(
  BYTE*  pData,
  DWORD*  pdwSize
);

Parameters

pData

[out] Pointer to a buffer to receive the data read from the object.

pdwSize

[in, out] Pointer to a DWORD specifying the number of bytes of data to read. Upon return, this parameter contains the actual amount of data read.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_CALL_OUT_OF_SEQUENCE | Open was not called before calling Read.
E_INVALIDARG | A parameter is an invalid or NULL pointer.

Remarks

This method can be used for DRM-protected content. This method is more efficient than IMDSPObject::Read because this method does not involve encrypting and decrypting parameters.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Synchronization with Windows Media Player
  • IMDSPObject::Read
  • IMDSPObject2 Interface
  • IMDSPObject2::WriteOnClearChannel


IMDSPObject2::WriteOnClearChannel (deprecated)

The WriteOnClearChannel method writes data to the object to the current position within the object, without using secure authenticated channels. This operation is valid only if the storage object represents a file. If IMDSPObject2 is supported, this method must be implemented. Windows Media Device Manager does not fall back to IMDSPObject::Write if this method fails.

Syntax

HRESULT WriteOnClearChannel(
  BYTE*  pData,
  DWORD*  pdwSize
);

Parameters

pData

[in] Pointer to the buffer containing the data to write to the object.

pdwSize

[in, out] Pointer to a DWORD containing the number of bytes of data to write. Upon return, this parameter contains the actual number of bytes written.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUSY | The media device is busy.
WMDM_E_INTERFACEDEAD | The file or folder was previously deleted.
WMDM_E_CALL_OUT_OF_SEQUENCE | Open was not called before calling Write.
E_INVALIDARG | One or more parameters is invalid or is a NULL pointer.
HRESULT_FROM_WIN32 (ERROR_DISK_FULL) | Write failed because there is not enough space on the disk. Note: Use the macro HRESULT_FROM_WIN32 to convert the Windows error ERROR_DISK_FULL (defined in Winerror.h) to an HRESULT.

Remarks

This method can be used with DRM-protected content. It is more efficient than IMDSPObject::Write because this method does not involve encrypting and decrypting parameters.

Unlike IMDSPObject::Write, this method does not need to decrypt the data before writing to a device, and is therefore more efficient.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Synchronization with Windows Media Player
  • IMDSPObject::Write
  • IMDSPObject2 Interface
  • IMDSPObject2::ReadOnClearChannel


IMDSPObjectInfo Interface (deprecated)

The IMDSPObjectInfo interface provides methods for getting and setting parameters that describe how playable objects on a storage medium are referenced or accessed by the IMDSPDeviceControl interface. Implementing this interface is optional. For more information, see Mandatory and Optional Interfaces.

The resolution of the method parameters depends on the associated storage object as follows:

  • If the storage object represents a playable audio file, then the relative storage units are milliseconds.
  • If the storage object represents a folder or the root of a storage medium containing playable files, then the relative storage units are tracks.

This interface is not intended for non-playable files. If the IMDSPObjectInfo interface is acquired from an IMDSPStorage interface that represents a non-playable file or a folder or a root file system containing no playable files, E_INVALIDTYPE is returned from all of the methods.

In addition to the methods inherited from IUnknown, the IMDSPObjectInfo interface exposes the following methods.

Method | Description
GetLastPlayPosition | Retrieves the last play position of the object. The object must be a music file on the media device.
GetLongestPlayPosition | Retrieves the longest play position of the object. The object must be a music file on the media device.
GetPlayLength | Retrieves the play length of the object in units pertinent to the object.
GetPlayOffset | Retrieves the play offset of the object, in units pertinent to the object.
GetTotalLength | Retrieves the total play length of the object in units pertinent to the object.
SetPlayLength | Sets the play length of the object, in units pertinent to the object.
SetPlayOffset | Sets the play offset of the object, in units pertinent to the object.

See Also

  • IMDSPStorage Interface
  • Interfaces for Service Providers


IMDSPObjectInfo::GetLastPlayPosition (deprecated)

The GetLastPlayPosition method retrieves the last play position of the object. The object must be a music file on the media device.

Syntax

HRESULT GetLastPlayPosition(
  DWORD*  pdwLastPos
);

Parameters

pdwLastPos

[out] Pointer to a DWORD containing the last play position of the object, in milliseconds.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report last play position.
E_INVALIDTYPE | The object is not a valid playable file.
E_FAIL | An unspecified error occurred.

Remarks

The object must be an audio data file. For all other object types, this function returns E_INVALIDTYPE.

The last play position changes when either the user starts playing a file on the media device or when an application invokes the IMDSPDeviceControl::Play method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface


IMDSPObjectInfo::GetLongestPlayPosition (deprecated)

The GetLongestPlayPosition method retrieves the longest play position of the object. The object must be a music file on the media device.

Syntax

HRESULT GetLongestPlayPosition(
  DWORD*  pdwLongestPos
);

Parameters

pdwLongestPos

[out] Pointer to a DWORD containing the longest play position of the object, in milliseconds.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report longest play position.
E_INVALIDTYPE | The object is not a valid playable file.
E_FAIL | An unspecified error occurred.

Remarks

The object must be an audio data file. For all other object types, this function returns E_INVALIDTYPE.

The last play position changes when either the user starts playing a file on the media device, or when an application invokes the IMDSPDeviceControl::Play method and that play exceeds the position of the last longest play position.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface


IMDSPObjectInfo::GetPlayLength (deprecated)

The GetPlayLength method retrieves the play length of the object in units pertinent to the object. This is the remaining length that the object can play, not its total length.

Syntax

HRESULT GetPlayLength(
  DWORD*  pdwLength
);

Parameters

pdwLength

[out] Pointer to a DWORD containing the remaining play length of the object.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report the remaining play length.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

The value of the play length retrieved is either the total length of the object minus the current play position (if the IMDSPObjectInfo::SetPlayLength method has not been called), or the value set by IMDSPObjectInfo::SetPlayLength clipped to be no greater than the total play length of the object minus the current play position.

For playable files, the value returned is specified in milliseconds. The play length information can change either when the user starts playing a file on the media device or when an application invokes the IMDSPDeviceControl::Play method.

For folders or file systems containing playable files, the value returned is in tracks or numbers of playable files in that folder or in the root of that file system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface
  • IMDSPObjectInfo::SetPlayLength


IMDSPObjectInfo::GetPlayOffset (deprecated)

The GetPlayOffset method retrieves the play offset of the object, in units pertinent to the object. This is the starting point for the next invocation of IMDSPDeviceControl::Play.

Syntax

HRESULT GetPlayOffset(
  DWORD*  pdwOffset
);

Parameters

pdwOffset

[out] Pointer to a DWORD containing the play offset of the object, in units pertinent to the object.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report the play offset.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

The value retrieved is either zero (if the SetPlayOffset method has not been called) or the value set by SetPlayOffset clipped to be no greater than the total play length of the object minus one unit.

For playable files, the value returned is specified in milliseconds. The play offset value does not change when the user starts playing a file on the media device or when an application invokes the IMDSPDeviceControl::Play method.

For folders or file systems containing playable files, the value returned indicates the first track that is played when an application invokes the IMDSPDeviceControl::Play method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface
  • IMDSPObjectInfo::SetPlayOffset


IMDSPObjectInfo::GetTotalLength (deprecated)

The GetTotalLength method retrieves the total play length of the object in units pertinent to the object. The value returned is the total length regardless of the current settings of the play length and offset.

Syntax

HRESULT GetTotalLength(
  DWORD*  pdwLength
);

Parameters

pdwLength

[out] Pointer to a DWORD containing the total length of the object, in units pertinent to the object.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This object cannot report total play length.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

The value returned in the pdwLength parameter is the total length of the object regardless of the current settings of the play length and play offsets.

For playable files, the total length is specified in milliseconds.

For folders or file systems containing playable files, the value returned indicates the total number of playable files in a folder or in the root of a file system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface


IMDSPObjectInfo::SetPlayLength (deprecated)

The SetPlayLength method sets the play length of the object, in units pertinent to the object. This is the maximum length that the object plays regardless of its actual length.

Syntax

HRESULT SetPlayLength(
  DWORD  dwLength
);

Parameters

dwLength

[in] DWORD containing the play length to set for the object, in units pertinent to the object.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This device does not support setting play lengths.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

If the value passed in is greater than the total length of the object, it is clipped to the length of the object minus the object's current play position minus one unit.

For playable files, the value to set is specified in milliseconds. The value is clipped to no more than the total length of the file minus the object's current play offset position. The play position information can change either when the user starts playing a file on the media device or when an application invokes the IMDSPDeviceControl::Play method.

For folders or file systems containing playable files, the value passed is the number of playable files in that folder or in the root of that file system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface
  • IMDSPObjectInfo::GetPlayLength


IMDSPObjectInfo::SetPlayOffset (deprecated)

The SetPlayOffset method sets the play offset of the object, in the units pertinent to the object. This specifies the starting point for the next invocation of IMDSPDeviceControl::Play.

Syntax

HRESULT SetPlayOffset(
  DWORD  dwOffset
);

Parameters

dwOffset

[in] DWORD containing the play offset to set for the object, in units pertinent to the object.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | This device does not support setting play lengths.
E_INVALIDTYPE | The object that this interface is associated with is not a valid playable file or a folder or file system containing playable files.
E_FAIL | An unspecified error occurred.

Remarks

If the value passed is greater than the total length of the object minus the current play length, it is clipped to the length of the object minus the play length.

For playable files, the value is specified in milliseconds. The play offset position value does not change when the user starts playing a file on the media device or when an application invokes the IMDSPDeviceControl::Play method.

For folders or file systems containing playable files, the value indicates the first track that is played when an application invokes the IMDSPDeviceControl::Play method.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPObjectInfo Interface
  • IMDSPObjectInfo::GetPlayOffset


IMDSPRevoked Interface (deprecated)

The IMDSPRevoked interface retrieves the URL from which updated components can be downloaded. Implementing this interface is optional. For more information, see Mandatory and Optional Interfaces.

In addition to the methods inherited from IUnknown, the IMDSPRevoked interface exposes the following method.

Method | Description
GetRevocationURL | Retrieves the URL from which updated components can be downloaded.

See Also

  • Interfaces for Service Providers


IMDSPRevoked::GetRevocationURL (deprecated)

The GetRevocationURL method retrieves the URL from which updated components can be downloaded.

Syntax

HRESULT GetRevocationURL(
  LPWSTR*  ppwszRevocationURL,
  DWORD*  pdwMaxChars
);

Parameters

ppwszRevocationURL

[in, out] Pointer to a Unicode string where the revocation URL should be written.

pdwMaxChars

[in, out] Number of WCHAR characters that the buffer supplied by the client can hold; on return it contains the required number of characters.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUFFERTOOSMALL | The buffer supplied by the client is too small. When the function returns, pdwMaxChars will contain the required number of characters.
E_FAIL | An unspecified error occurred.

Remarks

The IMDSPRevoked interface retrieves the URL from which updated components can be downloaded if the service provider is ever revoked by any digital rights management system. If this method is not implemented, a default Microsoft URL will be used. This location is maintained by Microsoft and contains updates to components revoked by the Microsoft digital rights management system.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPRevoked Interface


IMDSPStorage Interface (deprecated)

The IMDSPStorage interface provides an instanced-based association with a storage medium on a device. An IMDSPStorage interface can represent the entire storage medium, or can be further enumerated to represent any object, such as a folder or file, on that medium. This reiterative enumeration provides the mechanism for describing the organization of a hierarchically structured storage medium.

The methods of IMDSPStorage can be used to gather information about the object that the interface represents. The IMDSPStorage2 interface extends IMDSPStorage by getting and setting extended attributes and making it possible to get a pointer to a storage medium from its name.

In addition to the methods inherited from IUnknown, the IMDSPStorage interface exposes the following methods.

Method | Description
CreateStorage | Creates a new storage and returns a pointer to the IMDSPStorage interface on the newly created storage. The new storage can be created at the same level or can be inserted into the current storage.
EnumStorage | Retrieves the attributes of the storage object.
GetAttributes | Retrieves the date on which the storage object (file or folder) was most recently modified.
GetDate | Accesses the IMDSPEnumStorage interface to enumerate the individual storage media on a device
GetName | Retrieves the display name of the storage object.
GetRights | Retrieves the size of the storage object, in bytes.
GetSize | Retrieves the IMDSPStorageGlobals interface to provide access to global information about a storage medium.
GetStorageGlobals | Retrieves the rights information for the object.
SendOpaqueCommands | Sends commands through Windows Media Device Manager. Without acting on it, Windows Media Device Manager passes the command through to a device.
SetAttributes | Sets the attributes of the storage object.

See Also

  • IMDSPEnumStorage Interface
  • IMDSPStorage2 Interface
  • IMDSPStorage3 Interface
  • IMDSPStorage4 Interface
  • IMDSPStorageGlobals Interface
  • Interfaces for Service Providers


IMDSPStorage::CreateStorage (deprecated)

The CreateStorage method creates a new storage and returns a pointer to the IMDSPStorage interface on the newly created storage. This method is optional unless dwAttributes is WMDM_FILE_ATTR_FILE. In that case, this method must be implemented and must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Syntax

HRESULT CreateStorage(
  DWORD  dwAttributes,
  _WAVEFORMATEX*  pFormat,
  LPWSTR  pwszName,
  IMDSPStorage**  ppNewStorage
);

Parameters

dwAttributes

[in] DWORD containing the attributes for the new storage. The following table lists the available storage attributes.

Attribute | Description
WMDM_STORAGECONTROL_INSERTBEFORE | The new storage object will be created in front of the target object.
WMDM_STORAGECONTROL_INSERTAFTER | The new storage object will be created after the target object.
WMDM_STORAGECONTROL_INSERTINTO | The new storage object will be created in the target object folder.
WMDM_STORAGECONTROL_OVERWRITE | If storage with the same name already exists, it will be destroyed and a new storage created.
WMDM_STORAGE_ATTR_FILESYSTEM | This object is the top-level storage medium (for example, a storage card or some other on-board storage.)
WMDM_STORAGE_ATTR_REMOVABLE | This storage medium is removable.
WMDM_STORAGE_ATTR_CANEDITMETADATA | This storage can edit metadata.
WMDM_STORAGE_ATTR_FOLDERS | This storage medium supports folders and file hierarchy.
WMDM_FILE_ATTR_FOLDER | This is a folder on the storage medium.
WMDM_FILE_ATTR_LINK | This is a link that creates an association among multiple files.
WMDM_FILE_ATTR_FILE | This is a file on the storage medium.
WMDM_FILE_ATTR_AUDIO | This file is audio data.
WMDM_FILE_ATTR_DATA | This file is non-audio data.
WMDM_FILE_ATTR_CANPLAY | This audio file can be played by the device.
WMDM_FILE_ATTR_CANDELETE | This file can be deleted.
WMDM_FILE_ATTR_CANMOVE | This file or folder can be moved around on the storage medium.
WMDM_FILE_ATTR_CANRENAME | This file or folder can be renamed.
WMDM_FILE_ATTR_CANREAD | This file can be read by the host computer.
WMDM_FILE_ATTR_MUSIC | This audio file is music.
WMDM_FILE_ATTR_VIDEO | This file contains video data.
WMDM_FILE_ATTR_HIDDEN | This file is hidden on the file system
WMDM_FILE_ATTR_SYSTEM | This is a system file
WMDM_FILE_ATTR_READONLY | This is a read-only file.
WMDM_STORAGE_IS_DEFAULT | This storage is the default storage where new media should be placed.
WMDM_STORAGE_CONTAINS_DEFAULT | This storage contains the default storage where new media should be placed.

pFormat

[in] Pointer to a _WAVEFORMATEX structure that contains information about the object, if the object is an audio file.

pwszName

[in] Pointer to a wide-character null-terminated string containing the name for the new storage.

ppNewStorage

[out] Pointer to an IMDSPStorage pointer to receive the IMDSPStorage interface for the newly created storage.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

If both the WMDM_FILE_ATTR_FOLDER and WMDM_FILE_ATTR_FILE attributes are set, the folder attribute overrides the file attribute, and the new storage is created as a folder.

Only one of WMDM_STORAGECONTROL_INSERTBEFORE, WMDM_STORAGECONTROL_INSERTAFTER, and WMDM_STORAGECONTROL_INSERTINTO can be specified by the client.

The new storage can be created at the same level or can be inserted into the current storage provided that the current storage is a folder. This is controlled by the value of dwAttributes parameter. If it specifies WMDM_STORAGECONTROL_INSERTBEFORE or WMDM_STORAGECONTROL_INSERTAFTER, the new storage will be created at the same level as the current storage. If it specifies WMDM_STORAGECONTROL_INSERTINTO, the new storage will be inserted into the current storage.

WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERAFTER imply an ordering of content in the file system. If the file system does not support ordering (for example, FAT32) both the flags have the identical effect of inserting the new storage at the same level of the current storage. If the current storage represents the root of the storage medium, and one of these two flags is specified, the operation fails.

WMDM_STORAGECONTROL_INSERTINTO is valid only if the current storage is a folder. If the current storage is a file, and this flag is specified, the operation fails.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • IMDSPStorage Interface
  • IMDSPStorage2::CreateStorage2


IMDSPStorage::EnumStorage (deprecated)

The EnumStorage method accesses the IMDSPEnumStorage interface to enumerate the individual storage media on a device.

Syntax

HRESULT EnumStorage(
  IMDSPEnumStorage**  ppEnumStorage
);

Parameters

ppEnumStorage

[out] Pointer to an IMDSPEnumStorage interface.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

The IMDSPEnumStorage interface returned will enumerate the nested storages in the storage that IMDSPStorage corresponds to. Thus all the storage objects in a hierarchical structure can be retrieved recursively.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPDevice::EnumStorage
  • IMDSPEnumStorage Interface
  • IMDSPStorage Interface


IMDSPStorage::GetAttributes (deprecated)

The GetAttributes method retrieves the attributes of this storage object.

Syntax

HRESULT GetAttributes(
  DWORD*  pdwAttributes,
  _WAVEFORMATEX*  pFormat
);

Parameters

pdwAttributes

[out] Pointer to a DWORD containing the attributes as defined by in the IWMDMStorage::GetAttributes method.

pFormat

[out] Pointer to a _WAVEFORMATEX structure that is filled with attribute information about the object.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwAttributes parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Evaluation of attributes is a crucial step when exposing the contents of the media device. Devices may not support hierarchical storage of data on storage media. The GetAttributes method allows the application to infer the support and format of the file system by discovering its structure through object attributes.

For example, the attributes of a top-level IMDSPStorage interface indicate a storage medium, and IMDSPEnumStorage exposes the contents of the medium. For an .mp3 file, the attributes indicate a file whose type can be determined by further examination of both the attributes and the file name. In a hierarchical medium, the attributes can indicate a directory whose contents can be exposed by IMDSPStorage::EnumStorage.

The _WAVEFORMATEX parameter is optional. If you pass a valid _WAVEFORMATEX pointer to an audio file, GetAttributes passes descriptive information back into the structure. However, if the file is not audio, the _WAVEFORMATEX parameter is ignored.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • IMDSPEnumStorage Interface
  • IMDSPStorage Interface
  • IMDSPStorage::SetAttributes
  • IMDSPStorage2::GetAttributes2


IMDSPStorage::GetDate (deprecated)

The GetDate method retrieves the date on which the storage object (file or folder) was most recently modified.

Syntax

HRESULT GetDate(
  PWMDMDATETIME  pDateTimeUTC
);

Parameters

pDateTimeUTC

[out] Pointer to a WMDMDATETIME structure containing the date on which the file or folder was most recently modified.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pDisplayDate parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The time is specified in coordinated universal time.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • IMDSPStorage::GetName
  • IMDSPStorage::GetSize
  • WMDMDATETIME


IMDSPStorage::GetName (deprecated)

The GetName method retrieves the display name of the storage object.

Syntax

HRESULT GetName(
  LPWSTR  pwszName,
  UINT  nMaxChars
);

Parameters

pwszName

[out] Pointer to a (Unicode) wide-character null-terminated string containing the object name.

nMaxChars

[in] Integer containing the maximum number of characters that can be copied to the name string.

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_BUFFERTOOSMALL | The buffer specified is too small for the return string. Check nMaxChars for the required buffer size.
E_INVALIDARG | The pwszName parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The display name of the object is the file name without path information. In hierarchical media the display name would be concatenated with the ancestor instances of IMDSPStorage interfaces to create a full path-qualified name.

The LPWSTR string type is a 16-bit Unicode character string and does not accept byte-sized characters.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • IMDSPStorage::GetDate
  • IMDSPStorage::GetSize


IMDSPStorage::GetRights (deprecated)

The GetRights method retrieves the rights information for an object.

Syntax

HRESULT GetRights(
  PWMDMRIGHTS*  ppRights,
  UINT*  pnRightsCount,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

ppRights

[out] Pointer to an array of WMDMRIGHTS structures that contain the storage object rights information. This parameter is included in the output message authentication code.

pnRightsCount

[out] Pointer to the number of WMDMRIGHTS structures in the ppRights array. This parameter is included in the output message authentication code.

abMac[WMDM_MAC_LENGTH]

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | Rights are not supported for this object.
E_INVALIDARG | One or more parameters is not valid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Object rights describe the usage permissions for media content. For example, the WMDMRIGHTS structure can contain information concerning how many times a file can be played and who can play it.

The ppRights array is allocated by this method, and must be freed by the application using CoTaskMemFree, a standard Win32 function.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • WMDMRIGHTS


IMDSPStorage::GetSize (deprecated)

The GetSize method retrieves the size of the storage object, in bytes.

Syntax

HRESULT GetSize(
  DWORD*  pdwSizeLow,
  DWORD*  pdwSizeHigh
);

Parameters

pdwSizeLow

[out] Pointer to a DWORD containing the low-order part of the storage object size.

pdwSizeHigh

[out] Pointer to a DWORD containing the high-order part of the storage object size.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | One or more parameters is not valid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The object size is reported in bytes. The size is zero for folder objects.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • IMDSPStorage::GetDate
  • IMDSPStorage::GetName


IMDSPStorage::GetStorageGlobals (deprecated)

The GetStorageGlobals method retrieves the IMDSPStorageGlobals interface to provide access to global information about a storage medium.

Syntax

HRESULT GetStorageGlobals(
  IMDSPStorageGlobals**  ppStorageGlobals
);

Parameters

ppStorageGlobals

[out] Pointer to an IMDSPStorageGlobals interface that can provide access to global information about a storage medium.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

The IMDSPStorageGlobals interface provides methods for accessing global information about the medium regardless of the nesting level of the IMDSPStorage interface from which the global view is accessed. Any instance of IMDSPStorage can acquire an IMDSPStorageGlobals interface.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • IMDSPStorageGlobals Interface


IMDSPStorage::SendOpaqueCommands (deprecated)

The SendOpaqueCommands method sends a command through Windows Media Device Manager. Without acting on it, Windows Media Device Manager passes the command through to a device.

Syntax

HRESULT SendOpaqueCommands(
  OPAQUECOMMAND*  pCommand
);

Parameters

pCommand

[in, out] Pointer to an OPAQUECOMMAND structure containing the information required to execute the command.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pCommand parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is used with device commands that do not affect Windows Media Device Manager, and are passed through unchanged.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • OPAQUECOMMAND


IMDSPStorage::SetAttributes (deprecated)

The SetAttributes method sets the attributes of a storage object.

Syntax

HRESULT SetAttributes(
  DWORD  dwAttributes,
  _WAVEFORMATEX*  pFormat
);

Parameters

dwAttributes

[in] DWORD containing the attributes to be set as defined in the IWMDMStorage::SetAttributes method.

pFormat

[in] Pointer to a _WAVEFORMATEX structure that contains attribute information about the object. This parameter is optional and is ignored if the file is not audio.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An error occurred.

Remarks

Many of the attributes returned by GetAttributes (as listed in attribute table for IWMDMStorage::GetAttributes) cannot be set, so they are not listed in the attribute table for IWMDMStorage::SetAttributes.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • _WAVEFORMATEX
  • IMDSPEnumStorage Interface
  • IMDSPStorage Interface
  • IMDSPStorage::GetAttributes
  • IMDSPStorage2::SetAttributes2


IMDSPStorage2 Interface (deprecated)

The IMDSPStorage2 interface extends IMDSPStorage by providing methods for getting and setting extended attributes and making it possible to get a pointer to a storage medium from its name. This interface also extends the CreateStorage method of the IMDSPStorage interface.

In addition to the methods inherited from IMDSPStorage, the IMDSPStorage2 interface exposes the following methods.

Method | Description
CreateStorage2 | Creates storage for a file to be copied to a device.
GetAttributes2 | Gets attributes of files or storages.
GetStorage | Gets a storage pointer and a string containing the name.
SetAttributes2 | Sets storage attributes.

See Also

  • IMDSPStorage Interface
  • IMDSPStorage3 Interface
  • IMDSPStorage4 Interface
  • Interfaces for Service Providers


IMDSPStorage2::CreateStorage2 (deprecated)

The CreateStorage2 method creates a new storage with the specified name and returns a pointer to the IMDSPStorage interface on the newly created storage.

Syntax

HRESULT CreateStorage2(
  DWORD  dwAttributes,
  DWORD  dwAttributesEx,
  _WAVEFORMATEX*  pAudioFormat,
  _VIDEOINFOHEADER*  pVideoFormat,
  LPWSTR  pwszName,
  ULONGLONG  qwFileSize,
  IMDSPStorage**  ppNewStorage
);

Parameters

dwAttributes

[in] DWORD containing the attributes as described in the IMDSPStorage::CreateStorage method.

dwAttributesEx

[in] DWORD containing the extended attributes. There are currently no extended attributes defined.

pAudioFormat

[in] Pointer to a _WAVEFORMATEX structure that contains audio format information about the object. This parameter is optional and is ignored if the file is not audio.

pVideoFormat

[in] Pointer to a _VIDEOINFOHEADER structure that contains video format information about the object. This parameter is optional and is ignored if the file is not video.

pwszName

[in] Pointer to a wide-character null-terminated string containing the name for the new storage.

qwFileSize

[in] QWORD containing the size of the file to create. If the total size of the output file is not known at the time of creation, this value will be set to zero.

ppNewStorage

[out] Pointer to an IMDSPStorage pointer to receive the IMDSPStorage interface for the newly created storage.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

If both the WMDM_FILE_ATTR_FOLDER and WMDM_FILE_ATTR_FILE attributes are set, the folder attribute overrides the file attribute, and the new storage is created as a folder.

Only one of WMDM_STORAGECONTROL_INSERTBEFORE, WMDM_STORAGECONTROL_INSERTAFTER, and WMDM_STORAGECONTROL_INSERTINTO can be specified by the client.

The new storage can be created at the same level or can be inserted into the current storage, provided that the current storage is a folder. This is controlled by the value of the dwAttributes parameter. If it specifies WMDM_STORAGECONTROL_INSERTBEFORE or WMDM_STORAGECONTROL_INSERTAFTER, the new storage will be created at the same level as the current storage. If it specifies WMDM_STORAGECONTROL_INSERTINTO, the new storage will be inserted into the current storage.

WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERAFTER imply an ordering of content in the file system. If the file system does not support ordering (for example, FAT32) both the flags have the identical effect of inserting the new storage at the same level as the current storage. If the current storage represents the root of the storage medium, and one of these two flags is specified, the operation fails.

WMDM_STORAGECONTROL_INSERTINTO is valid only if the current storage is a folder. If the current storage is a file, and this flag is specified, the operation fails.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage::CreateStorage
  • IMDSPStorage2 Interface


IMDSPStorage2::GetAttributes2 (deprecated)

The GetAttributes2 method gets attributes of files or storages.

Syntax

HRESULT GetAttributes2(
  DWORD*  pdwAttributes,
  DWORD*  pdwAttributesEx,
  _WAVEFORMATEX*  pAudioFormat,
  _VIDEOINFOHEADER*  pVideoFormat
);

Parameters

pdwAttributes

[out] Pointer to a DWORD containing the base attributes as defined in the IWMDMStorage::GetAttributes method.

pdwAttributesEx

[out] Pointer to a DWORD containing the extended attributes. Currently no extended attributes are defined.

pAudioFormat

[out] Pointer to a _WAVEFORMATEX structure that contains audio format information about the object. This parameter is optional and is ignored if the file is not audio.

pVideoFormat

[out] Pointer to a _VIDEOINFOHEADER structure that contains video format information about the object. This parameter is optional and is ignored if the file is not video.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

See remarks for IWMDMStorage::GetAttributes.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage2 Interface
  • IMDSPStorage2::SetAttributes2


IMDSPStorage2::GetStorage (deprecated)

The GetStorage method makes it possible to go directly to a storage object from a storage name instead of enumerating through all storages to find it.

Syntax

HRESULT GetStorage(
  LPCWSTR  pszStorageName,
  IMDSPStorage**  ppStorage
);

Parameters

pszStorageName

[in] Pointer to a null-terminated string containing the storage name.

ppStorage

[out] Pointer to the storage object specified by pszStorageName, or NULL if no such storage was found.

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.

Return code | Description
S_OK | The method succeeded.
S_FALSE | The storage is not found.
E_FAIL | An unspecified error occurred.
E_NOTIMPL | The method is not implemented.

Remarks

The IMDSPStorage2::GetStorage interface extends the functionality of IMDSPStorage.

IMDSPStorage2::GetStorage does not support wildcard characters. It is not recursive, that is, it will only find storage objects in the current storage.

If this method is not implemented, it should return E_NOTIMPL. (It should not return WMDM_E_NOT_SUPPORTED or any other codes indicating that this method is not implemented). This will ensure that Windows Media Device Manager will attempt to substitute this functionality itself by enumerating all storages to find a match based on the storage name passed in as pszStorageName.

It is strongly recommended that a service provider implement this method to efficiently return a storage object based on name.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • IMDSPStorage2 Interface


IMDSPStorage2::SetAttributes2 (deprecated)

The SetAttributes2 method extends IMDSPStorage::SetAttributes by enabling you to set audio and video formats and extended attributes of a storage object.

Syntax

HRESULT SetAttributes2(
  DWORD  dwAttributes,
  DWORD  dwAttributesEx,
  _WAVEFORMATEX*  pAudioFormat,
  _VIDEOINFOHEADER*  pVideoFormat
);

Parameters

dwAttributes

[in] DWORD containing the attributes to be set as defined in the IWMDMStorage::SetAttributes method

dwAttributesEx

[in] DWORD containing the extended attributes. No extended attributes are currently defined.

pAudioFormat

[in] Pointer to a _WAVEFORMATEX structure that contains audio format information about the object. This parameter is optional and is ignored if the file is not audio.

pVideoFormat

[in] Pointer to a _VIDEOINFOHEADER structure that contains video format information about the object. This parameter is optional and is ignored if the file is not video.

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.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Remarks

See Remarks for IWMDMStorage::SetAttributes.

This method is optional. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage::SetAttributes
  • IMDSPStorage2 Interface
  • IMDSPStorage2::GetAttributes2
  • IWMDMStorage::SetAttributes


IMDSPStorage3 Interface (deprecated)

The IMDSPStorage3 interface extends IMDSPStorage2 by supporting metadata. This interface is optional. Service providers must implement this interface only if they are going to support metadata. If the device parameter UseMetadataViews is set to 1, this interface must be implemented and the GetMetadata method becomes mandatory, although SetMetadata is still optional. For more information, see Device Parameters.

In addition to the methods inherited from IMDSPStorage2, the IMDSPStorage3 interface exposes the following methods.

Method | Description
GetMetadata | Retrieves metadata from the service provider.
SetMetadata | Provides the metadata associated with a specified content.

See Also

  • IMDSPStorage Interface
  • IMDSPStorage2 Interface
  • IMDSPStorage4 Interface
  • Interfaces for Service Providers


IMDSPStorage3::GetMetadata (deprecated)

The GetMetadata method retrieves metadata from the service provider.

Syntax

HRESULT GetMetadata(
  IWMDMMetaData*  pMetadata
);

Parameters

pMetadata

[in] Pointer to an IWMDMMetaData interface.

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.

Return code | Description
S_OK | The method succeeded.

Remarks

The service provider calls IWMDMMetaData::AddItem for each of the metadata properties to be sent to the application. The service provider should use the predefined metadata name tags (g_wszWMDMTitle, g_wszAlbumTitle, g_dwBitrate, and so on) contained in the mswmdm.h file.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage3 Interface
  • IMDSPStorage3::SetMetadata
  • IWMDMMetaData Interface


IMDSPStorage3::SetMetadata (deprecated)

The SetMetadata method provides the metadata associated with a specified content.

Syntax

HRESULT SetMetadata(
  IWMDMMetaData*  pMetadata
);

Parameters

pMetadata

[in] Pointer to an IWMDMMetadata interface.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Value | Description
S_OK | The method succeeded, which indicates that SP has successfully processed the meta data.
WMDM_E_NOT_SUPPORTED | The device does not support setting metadata.

Remarks

A service provider calls IWMDMMetaData::QueryByName or IWMDMMetaData::QueryByIndex to retrieve the metadata.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage3 Interface
  • IMDSPStorage3::GetMetadata
  • IWMDMMetaData Interface
  • IWMDMMetaData::QueryByIndex
  • IWMDMMetaData::QueryByName


IMDSPStorage4 Interface (deprecated)

The IMDSPStorage4 interface extends IMDSPStorage3 for supporting virtual storages (such as playlists and albums) and metadata.

Note Unless the service provider has added the device parameter UseExtendedWmdm with a value of 1, Windows Media Device Manager will not call this interface. See Device Parameters for more information about this.

In addition to the methods inherited from IMDSPStorage3, the IMDSPStorage4 interface exposes the following methods.

Method | Description
CreateStorageWithMetadata | Creates a new storage supporting metadata, and returns a pointer to the IMDSPStorage interface on the newly created storage. The new storage can be created at the same level or can be inserted into the current storage.
FindStorage | Retrieves the storage through its unique identification (ID).
GetParent | Retrieves the parent storage object.
GetReferences | Retrieves references of an association object.
GetSpecifiedMetadata | Retrieves the specified metadata.
SetReferences | Sets references of an association object.

See Also

  • IMDSPStorage Interface
  • IMDSPStorage2 Interface
  • IMDSPStorage3 Interface
  • Interfaces for Service Providers


IMDSPStorage4::CreateStorageWithMetadata (deprecated)

The CreateStorageWithMetadata method creates a new storage, applying the given metadata to the new storage, and returns a pointer to the IMDSPStorage interface on the newly created storage. The new storage can be created at the same level or can be inserted into the current storage.

This method is useful if the device needs metadata at creation time. Depending upon the device it may also be more efficient to applying metadata at creation time as opposed to creating the storage and then setting metadata.

Syntax

HRESULT CreateStorageWithMetadata(
  DWORD  dwAttributes,
  LPCWSTR  pwszName,
  IWMDMMetaData*  pMetadata,
  ULONGLONG  qwFileSize,
  IMDSPStorage**  ppNewStorage
);

Parameters

dwAttributes

[in] DWORD containing attributes for the new storage. The following table lists the available storage attributes.

Attribute | Description
WMDM_STORAGECONTROL_INSERTBEFORE | The new storage object will be created in front of the target object.
WMDM_STORAGECONTROL_INSERTAFTER | The new storage object will be created after the target object.
WMDM_STORAGECONTROL_INSERTINTO | The new storage object will be created in the target object folder.
WMDM_STORAGECONTROL_OVERWRITE | If storage with the same name already exists, it will be destroyed and a new storage created.
WMDM_STORAGE_ATTR_FILESYSTEM | This object is the top-level storage medium (for example, a storage card or some other onboard storage.)
WMDM_STORAGE_ATTR_REMOVABLE | This storage medium is removable.
WMDM_STORAGE_ATTR_CANEDITMETADATA | This storage can edit metadata.
WMDM_STORAGE_ATTR_FOLDERS | This storage medium supports folders and file hierarchy.
WMDM_FILE_ATTR_FOLDER | This is a folder on the storage medium.
WMDM_FILE_ATTR_LINK | This is a link that creates an association among multiple files.
WMDM_FILE_ATTR_FILE | This is a file on the storage medium.
WMDM_FILE_ATTR_AUDIO | This file is audio data.
WMDM_FILE_ATTR_DATA | This file is non-audio data.
WMDM_FILE_ATTR_CANPLAY | This audio file can be played by the device.
WMDM_FILE_ATTR_CANDELETE | This file can be deleted.
WMDM_FILE_ATTR_CANMOVE | This file or folder can be moved on the storage medium.
WMDM_FILE_ATTR_CANRENAME | This file or folder can be renamed.
WMDM_FILE_ATTR_CANREAD | This file can be read by the host computer.
WMDM_FILE_ATTR_MUSIC | This audio file is music.
WMDM_FILE_ATTR_PLAYLIST | This is a playlist object.
WMDM_FILE_ATTR_VIDEO | This file contains video data.
WMDM_FILE_ATTR_HIDDEN | This file is hidden on the file system.
WMDM_FILE_ATTR_SYSTEM | This is a system file.
WMDM_FILE_ATTR_READONLY | This is a read-only file.
WMDM_STORAGE_IS_DEFAULT | This storage is the default storage where new media should be placed.
WMDM_STORAGE_CONTAINS_DEFAULT | This storage contains the default storage where new media should be placed.

pwszName

[in] Pointer to a wide-character, null-terminated string containing a name for the new storage.

pMetadata

[in] Pointer to an IWMDMMetaData interface.

qwFileSize

[in] Qword containing the file size.

ppNewStorage

[out] Pointer to an IMDSPStorage pointer to receive the IMDSPStorage interface for the newly created storage.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or a NULL pointer.

Remarks

This method is useful if metadata needs to be applied to storage at the creation time. In contrast, the IMDSPStorage2::CreateStorage2 and IMDSPStorage::CreateStorage methods do not provide a way for supplying metadata at creation time.

If service provider for a device that can synchronize with Windows Media Player supports this interface, Windows Media Device Manager calls this method during Insert /2/3operations.

If both the WMDM_FILE_ATTR_FOLDER and WMDM_FILE_ATTR_FILE attributes are set, the folder attribute overrides the file attribute, and the new storage is created as a folder.

Only one of WMDM_STORAGECONTROL_INSERTBEFORE, WMDM_STORAGECONTROL_INSERTAFTER, and WMDM_STORAGECONTROL_INSERTINTO can be specified by the client.

The new storage can be created at the same level or can be inserted into the current storage provided that the current storage is a folder. This is controlled by the value of dwAttributes parameter. If it specifies WMDM_STORAGECONTROL_INSERTBEFORE or WMDM_STORAGECONTROL_INSERTAFTER, the new storage will be created at the same level as the current storage. If it specifies WMDM_STORAGECONTROL_INSERTINTO, the new storage will be inserted into the current storage.

WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERAFTER imply an ordering of content in the file system. If the file system does not support ordering (for example, the FAT32 file system), both flags have the identical effect of inserting the new storage at the level of the current storage. If the current storage represents the root of the storage medium and one of these two flags is specified, the operation fails.

WMDM_STORAGECONTROL_INSERTINTO is valid only if the current storage is a folder. If the current storage is a file and this flag is specified, the operation fails.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Synchronization with Windows Media Player
  • IMDSPStorage::CreateStorage
  • IMDSPStorage2::CreateStorage2
  • IMDSPStorage4 Interface


IMDSPStorage4::FindStorage (deprecated)

The FindStorage method finds a storage with the given persistent unique identifier. The persistent unique identifier of a storage is described by the g_wszWMDMPersistentUniqueID property of that storage.

Syntax

HRESULT FindStorage(
  WMDM_FIND_SCOPE  findScope,
  LPCWSTR  pwszUniqueID,
  IMDSPStorage**  ppStorage
);

Parameters

findScope

[in] Scope of the find operation. It must be one of the following values.

Value | Description
WMDM_FIND_SCOPE_GLOBAL | Search the entire device.
WMDM_FIND_SCOPE_IMMEDIATE_CHILDREN | Search only in the immediate children of the current storage.

pwszUniqueID

[in] Persistent unique identifier of the storage.

ppStorage

[out] Pointer to the returned storage specified by the pwszUniqueID parameter.

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 | The findScope parameter is invalid, or pwszUniqueID or ppStorage is NULL.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND) | No storage was found with the specified persistent unique identifier.

Remarks

The service provider returns a persistent unique identifier through the g_wszWMDMPersistentUniqueID property of the storage. For a specific storage, the persistent unique identifier supplied by service provider should be the same across different device connect sessions.

The application may call FindStorage with this persistent unique identifier at a later point. In response, Windows Media Device Manager calls this method on the service provider.

A persistent unique identifier is used to uniquely identify content stored on a particular device. It does not represent a content-specific globally unique identifier that remains identical across all devices. Thus, the same content stored in different storages will have different persistent unique identifiers.

This method allows searching for a storage based on persistent unique identifier while IMDSPStorage2::GetStorage allows searching for a storage based on name.

Windows Media Device Manager calls this method only for devices that can be synchronized with Windows Media Player. See Enabling Synchronization with Windows Media Player for more information.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • Enabling Synchronization with Windows Media Player
  • IMDSPStorage2::GetStorage
  • IMDSPStorage4 Interface


IMDSPStorage4::GetParent (deprecated)

The GetParent method retrieves the parent of the current storage.

Syntax

HRESULT GetParent(
  IMDSPStorage**  ppStorage
);

Parameters

ppStorage

[out] Pointer to the returned parent storage object.

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 and ppStorage holds the IMDSPStorage pointer to the parent object.
S_FALSE | Current storage is the root storage and therefore has no parent. In this case, ppStorage is set to NULL.

Remarks

This method can be used to traverse the complete hierarchy of the current storage if used recursively.

When this method is called for root storage, this method should return S_FALSE and set ppStorage to NULL.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage4 Interface


IMDSPStorage4::GetReferences (deprecated)

The GetReferences method returns an array of pointers to IMDSPStorage objects comprising the references contained in an association storage, such as one representing playlist or album objects.

Syntax

HRESULT GetReferences(
  DWORD*  pdwRefs,
  IMDSPStorage***  pppISPStorage
);

Parameters

pdwRefs

[out] Pointer to the count of IWMDMStorage interface pointers being returned in pppIWMDMStorage.

pppISPStorage

[out] Pointer to a pointer to the array of IWMDMStorage interface pointers that represent references on a storage. Such references can, for example, represent items in a playlist or album. The ordering of references matches the ordering in this array. Memory for this array should be allocated by the service provider.

Return Values

The method returns an HRESULT. All of 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.
S_FALSE | The method succeeded. However, one or more items referenced by the storage on the device side have been deleted since the last call to SetReferences.
E_INVALIDARG | Either pointer pdwRefs or pppIWMDMStorage is NULL.
E_OUTOFMEMORY | The method could not be completed due to insufficient memory.
WMDM_E_INTERFACEDEAD | The storage represented by this IWMDMStorage4 interface has been deleted.

Remarks

Windows Media Device Manager uses this method for obtaining the references on an association storage such as a playlist or an album.

If the storage has references to one or more items that have been deleted from the device, the SP should not include these references in the references returned. The SP should indicate such condition by returning S_FALSE. The application might choose to refresh the association storage object by using the known-good references returned here. The SP can also refresh the references itself.

If the count of references is 0, service provider must return an array of references with 0 elements in it.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage4 Interface
  • IMDSPStorage4::SetReferences


IMDSPStorage4::GetSpecifiedMetadata (deprecated)

The GetSpecifiedMetadata method retrieves only the specified metadata object for a storage.

Syntax

HRESULT GetSpecifiedMetadata(
  DWORD  cProperties,
  LPCWSTR*  ppwszPropNames,
  IWMDMMetaData**  ppMetadata
);

Parameters

cProperties

[in] Count of properties to be retrieved.

ppwszPropNames

[in] Array that contains the property names to be retrieved. The size of this array should be equal to cProperties.

ppMetadata

[out] Pointer to the returned IWMDMMetaData interface pointer.

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 | This value is returned if any of the following is true: One of cProperties and ppwszPropNames is zero while the other is non-zero. None of the property names passed-in is valid for the storage.
WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED | The method succeeded, but only some of the requested properties were retuned.
WMDM_E_NOTSUPPORTED | None of the properties was returned by the device. It is possible that one or more properties are supported by the device, but could not be returned at this time.

Remarks

This method gives the client control over which properties are retrieved. The client can specify the property names for the properties that the client needs to retrieve.

In contrast, the GetMetadata method retrieves all the storage metadata (properties).

If none of the specified properties can be returned, the service provider should return WMDM_E_NOTSUPPORTED or any suitable error code.

If at least one property can be retrieved, the service provider should return that property and set the return code to a success code of WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage4 Interface


IMDSPStorage4::SetReferences (deprecated)

The SetReferences method sets the references contained in a storage that has references (such as playlist/album), overwriting any previously existing references contained in this storage.

Syntax

HRESULT SetReferences(
  DWORD  dwRefs,
  IMDSPStorage**  ppIMDSPStorage
);

Parameters

dwRefs

[in] Count of IMDSPStorage interface pointers contained in the passed-in array. Zero is an acceptable value and resets the storage to contain zero references. The storage itself is not deleted in this case.

ppIWMDMStorage

[in] Pointer to an array of IMDSPStorage interface pointers used to set references in a storage. The ordering of references matches the ordering of the corresponding IWMDMStorage interface pointers in this array. NULL is an acceptable value if dwRefs is also zero.

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 | The dwRefs is non-zero and ppIWMDMStorage is NULL.
E_OUTOFMEMORY | The method could not be completed due to insufficient memory.
WMDM_E_INTERFACEDEAD | The playlist object on the device represented by this IWMDMStorage4 interface has been deleted.

Remarks

Any valid IMDSPStorage object may be contained in the ppIMDSPStorage array. This includes folders and other storages containing references themselves (creating, for example, a playlist of playlists).

Depending upon the level of support in the device (whether it supports playlists or nested playlists), the service provider should handle this method appropriately. If the device does not have the level of supported needed for the passed-in reference array, the service provider should return WMDM_E_NOTSUPPORTED.

If the reference contains a deleted storage, WMDM_E_INTERFACEDEAD should be returned.

The SetReferences method follows a wipe-and-load model. The references passed include a complete set and should replace any existing references on the storage object completely.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage4 Interface
  • IMDSPStorage4::GetReferences


IMDSPStorageGlobals Interface (deprecated)

The IMDSPStorageGlobals interface, acquired from the IMDSPStorage interface, provides methods for retrieving global information about a storage medium. This might include the amount of free space, serial number of the medium, and so on.

In addition to the methods inherited from IUnknown, the IMDSPStorageGlobals interface exposes the following methods.

Method | Description
GetCapabilities | Retrieves the capabilities of the storage medium that an instance of this interface is associated with.
GetDevice | Retrieves a pointer to the device with which this interface is associated.
GetRootStorage | Retrieves a pointer to the IMDSPStorage interface for the root storage of the storage medium.
GetSerialNumber | Retrieves a serial number uniquely identifying the storage medium.
GetStatus | Retrieves the current status of the storage medium.
GetTotalBad | Retrieves the total amount of unusable space on the storage medium, in bytes.
GetTotalFree | Retrieves the total free space on the storage medium, in bytes.
GetTotalSize | Retrieves the total size of the storage medium, in bytes.
Initialize | Formats the storage medium.

See Also

  • IMDSPStorage Interface
  • Interfaces for Service Providers


IMDSPStorageGlobals::GetCapabilities (deprecated)

The GetCapabilities method retrieves the capabilities of the storage medium that an instance of this interface is associated with.

Syntax

HRESULT GetCapabilities(
  DWORD*  pdwCapabilities
);

Parameters

pdwCapabilities

[out] Pointer to a DWORD containing the capabilities of the storage medium.

The following flags can be returned in the pdwCapabilities parameter.

Flag | Description
WMDM_STORAGECAP_FOLDERSINROOT | The medium supports folders in the root of storage.
WMDM_STORAGECAP_FILESINROOT | The medium supports files in the root of storage.
WMDM_STORAGECAP_FOLDERSINFOLDERS | The medium supports folders in folders.
WMDM_STORAGECAP_FILESINFOLDERS | The medium supports files in folders.
WMDM_STORAGECAP_FOLDERLIMITEXISTS | There is an arbitrary count limit for the number of folders allowed per the form of folder support by the medium.
WMDM_STORAGECAP_FILELIMITEXISTS | There is an arbitrary count limit for the number of files allowed per the form of file support by the medium.
WMDM_STORAGECAP_NOT_INITIALIZABLE | The medium cannot be initialized. By default, the top-level storage can be initialized.

For secured device implementations, the following flags describing the rights capabilities of the medium can also be returned.

Flag | Description
WMDM_RIGHTS_PLAYBACKCOUNT | The medium supports playback count limiting for content.
WMDM_RIGHTS_EXPIRATIONDATE | The medium supports expiration date tracking for content.
WMDM_RIGHTS_FREESERIALIDS | The medium supports a free serial identifier for the file.
WMDM_RIGHTS_GROUPID | The medium supports a group identifier for the file.
WMDM_RIGHTS_NAMEDSERIALIDS | The medium supports a named serial identifier for the file.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwCapabilities parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Attempts to perform unsupported operations on the storage medium with the IMDSPObject interface return an error code. The GetCapabilities method can be called in order to determine whether an operation can be expected to succeed under normal circumstances.

If either the WMDM_STORAGECAP_FILELIMITEXISTS flag or the WMDM_STORAGECAP_FOLDERLIMITEXISTS flag is true, there are arbitrary limits on the number of files or folders that can be created. Operations through the IMDSPObject interface that exceed these limits will fail.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface


IMDSPStorageGlobals::GetDevice (deprecated)

The GetDevice method retrieves a pointer to the device on which the storage medium with which this interface is associated is mounted.

Syntax

HRESULT GetDevice(
  IMDSPDevice**  ppDevice
);

Parameters

ppDevice

[out] Pointer to a device identified by the IMDSPDevice interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppDevice parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface


IMDSPStorageGlobals::GetRootStorage (deprecated)

The GetRootStorage method retrieves a pointer to the IMDSPStorage interface for the root storage of the storage medium.

Syntax

HRESULT GetRootStorage(
  IMDSPStorage**  ppRoot
);

Parameters

ppRoot

[out] Pointer to an IMDSPStorage pointer that receives the root storage.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The ppRoot parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorage Interface
  • IMDSPStorageGlobals Interface
  • IWMDMStorage Interface


IMDSPStorageGlobals::GetSerialNumber (deprecated)

The GetSerialNumber method retrieves a serial number uniquely identifying the storage medium. This method must be implemented for protected content transfer, but otherwise it is optional. For more information, see Mandatory and Optional Interfaces.

.

Syntax

HRESULT GetSerialNumber(
  PWMDMID  pSerialNum,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pSerialNum

[out] Pointer to a WMDMID structure containing the serial number information. This parameter is included in the output message authentication code.

abMac[WMDM_MAC_LENGTH]

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | The device does not support serial numbers.
E_INVALIDARG | The pSerialNum parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Not all storage media support serial numbers. The return code must always be checked to determine whether the storage medium provides this support. If the storage medium does not support returning a unique serial number, protected content cannot be transferred to the medium. If the storage represented is removable media, the serial number returned must be the storage serial number, which should be distinct from the device serial number.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface
  • WMDMID


IMDSPStorageGlobals::GetStatus (deprecated)

The GetStatus method retrieves the current status of the storage medium.

Syntax

HRESULT GetStatus(
  DWORD*  pdwStatus
);

Parameters

pdwStatus

[out] Pointer to a DWORD containing the status information. The following status values can be returned by the pdwStatus parameter.

Status | Description
WMDM_STATUS_READY | The medium is in an idle ready state.
WMDM_STATUS_BUSY | An operation is ongoing. Evaluate status values to determine the ongoing operation.
WMDM_STATUS_STORAGE_NOTPRESENT | The medium is not present. For devices that support more than one medium, this value is only reported from the IMDSPStorageGlobals interface.
WMDM_STATUS_STORAGE_INITIALIZING | The device is currently busy formatting media on a device.
WMDM_STATUS_STORAGE_BROKEN | The medium is broken. For devices that support more than one medium, this value is only reported from the IMDSPStorageGlobals interface.
WMDM_STATUS_STORAGE_NOTSUPPORTED | The medium is not supported by the device. For devices that support more than one medium, this value is only returned from the IMDSPStorageGlobals interface.
WMDM_STATUS_STORAGE_UNFORMATTED | The medium is not formatted. For devices that support more than one medium, this value is only reported from the IMDSPStorageGlobals interface.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pdwStatus parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

You must always call this method before attempting to interact with a storage medium. The status value returned is WMDM_STATUS_BUSY if some other interface has invoked an ongoing operation. You can evaluate the value returned from this call to determine whether an ongoing operation has been invoked from the IMDSPStorageGlobals interface.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface


IMDSPStorageGlobals::GetTotalBad (deprecated)

The GetTotalBad method retrieves the total amount of unusable space on the storage medium, in bytes.

Syntax

HRESULT GetTotalBad(
  DWORD*  pdwBadLow,
  DWORD*  pdwBadHigh
);

Parameters

pdwBadLow

[out] Pointer to a DWORD containing the low-order bytes of the unusable space.

pdwBadHigh

[out] Pointer to a DWORD containing the high-order bytes of the unusable space.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | Either pdwBadLow or pdwBadHigh is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

To determine the amount of storage space in use by the medium for file management, subtract the number of bad bytes identified by using GetTotalBad from the number of free bytes identified by using GetTotalFree.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface


IMDSPStorageGlobals::GetTotalFree (deprecated)

The GetTotalFree method retrieves the total free space on the storage medium, in bytes.

Syntax

HRESULT GetTotalFree(
  DWORD*  pdwFreeLow,
  DWORD*  pdwFreeHigh
);

Parameters

pdwFreeLow

[out] Pointer to a DWORD containing the low-order bytes of the free space.

pdwFreeHigh

[out] Pointer to a DWORD containing the high-order bytes of the free space.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | Either pdwFreeLow or pdwFreeHigh is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

To determine the amount of storage space in use by the medium for file management, subtract the number of bad bytes identified by using GetTotalBad from the number of free bytes identified by using GetTotalFree.

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface
  • IMDSPStorageGlobals::GetTotalSize


IMDSPStorageGlobals::GetTotalSize (deprecated)

The GetTotalSize method retrieves the total size, in bytes, of the medium associated with this IMDSPStorageGlobals interface.

Syntax

HRESULT GetTotalSize(
  DWORD*  pdwTotalSizeLow,
  DWORD*  pdwTotalSizeHigh
);

Parameters

pdwTotalSizeLow

[out] Pointer to a DWORD containing the low-order bytes of the total size of the medium.

pdwTotalSizeHigh

[out] Pointer to a DWORD containing the high-order bytes of the total size of the medium.

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.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method must be implemented. It must not return WMDM_E_NOTSUPPORTED or E_NOTIMPL. For more information, see Mandatory and Optional Interfaces.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface
  • IMDSPStorageGlobals::GetTotalFree


IMDSPStorageGlobals::Initialize (deprecated)

The Initialize method formats the storage medium. This method is optional. However, this method should be implemented if the device supports this functionality. If this method is not implemented, IMDSPStorageGlobals::GetCapabilities must return WMDM_STORAGECAP_NOT_INITIALIZABLE in addition to any other flags. For more information, see Mandatory and Optional Interfaces.

Syntax

HRESULT Initialize(
  UINT  fuMode,
  IWMDMProgress*  pProgress
);

Parameters

fuMode

[in] Mode used to initialize the medium. Specify exactly one of the following two modes. If both modes are specified, block mode is used.

Mode | Description
WMDM_MODE_BLOCK | The operation is performed using block mode processing. The call is not returned until the operation is finished.
WMDM_MODE_THREAD | The operation is performed using thread mode processing. The call returns immediately and the operation is performed in a background thread.

pProgress

[in] Pointer to an IWMDMProgress interface implemented by an application to track the progress of the formatting operation. This parameter can 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.

Return code | Description
S_OK | The method succeeded.
WMDM_E_NOTSUPPORTED | The device is not capable of formatting the storage medium.
E_BUSY | The media device is performing an operation.
E_INVALIDARG | An invalid mode has been specified in the fuMode parameter.
E_FAIL | An unspecified error occurred.

Remarks

If WMDM_MODE_BLOCK is specified, Initialize does not return until formatting is finished. If the WMDM_MODE_THREAD is specified, the call returns immediately and the caller can use the IMDSPStorageGlobals::GetStatus method to track the initializing operation.

Requirements

Header: Defined in mswmdm.h.

Library: mssachlp.lib

See Also

  • IMDSPStorageGlobals Interface
  • IMDSPStorageGlobals::GetCapabilities
  • IMDSPStorageGlobals::GetStatus
  • IWMDMProgress Interface


Windows Media DRM-Implemented Interfaces

The following interfaces are not intended to be implemented by third-party service providers, but are implemented and called internally by the Windows Media DRM and Windows Media Device Manager. Implementing these interfaces will prevent DRM-protected content from being processed. They are documented merely for completeness.

  • IWMDRMDevice Interface
  • IWMDRMDevice2 Interface

See Also

  • Programming Reference


IWMDRMDevice Interface (deprecated)

This interface is not intended to be implemented by a service provider, but is provided for purposes of complete documentation.

The IWMDRMDevice interface enables a secure content provider to communicate with devices that use Windows Media DRM 10 for Portable Devices.

In addition to the methods inherited from IUnknown, the IWMDRMDevice interface exposes the following methods.

Method | Description
CleanDataStore | Starts the process of cleaning the DRM data store on the device.
GetDeviceCertificate | Retrieves the device certificate.
GetMeterChallenge | Retrieves the metering challenge.
GetSecureClock | Retrieves the secure clock.
GetSecureClockChallenge | Retrieves the secure clock challenge.
GetSyncList | Retrieves the license synchronization list.
IsWMDRMDevice | Determines whether the device supports Windows Media DRM 10 for Portable Devices.
SetLicenseResponse | Sets the license response.
SetMeterResponse | Sets the metering response.
SetSecureClockResponse | Sets the secure clock response.

Note Microsoft recommends that you notify end users if you will be collecting metering data.

See Also

  • Interfaces for Service Providers


IWMDRMDevice::CleanDataStore (deprecated)

The CleanDataStore method starts the process of cleaning the DRM data store on the device.

Syntax

HRESULT CleanDataStore(
  DWORD  dwFlags
);

Parameters

dwFlags

[in] Flags for store cleaning criteria.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::GetDeviceCertificate (deprecated)

The GetDeviceCertificate method retrieves the device certificate.

Syntax

HRESULT GetDeviceCertificate(
  BSTR*  pbstrDevCert
);

Parameters

pbstrDevCert

[out] Pointer to a BSTR containing the retrieved device certificate.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::GetMeterChallenge (deprecated)

The GetMeterChallenge method retrieves the metering challenge.

Syntax

HRESULT GetMeterChallenge(
  BSTR  bstrMeterCert,
  BYTE**  ppbMeterChallenge,
  DWORD*  pcbMeterChallenge
);

Parameters

bstrMeterCert

[in] Metering certificate that the content owner sends to the host computer for collecting the associated metering data on the device

ppbMeterChallenge

[out] Retrieved metering challenge result.

pcbMeterChallenge

[out] The size of the metering challenge, in bytes.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Remarks

Metering data is collected and stored in the DRM data store on the device for content with metering enabled. Actions such as play will be recorded. When this function is called, the device collects the metering data in the DRM data store in the form of an XML document and sends it to the hostcomputer. If there is too much data, it is sent in phases.

When the host computer receives the metering data, it sends the data over the Internet to the URL specified in the metering certificate.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::GetSecureClock (deprecated)

The GetSecureClock method retrieves the secure clock, so time-based licenses can be enforced.

Syntax

HRESULT GetSecureClock(
  BYTE**  ppbSecureClock,
  DWORD*  pcbSecureClock,
  DWORD*  pdwFlags
);

Parameters

ppbSecureClock

[out] Retrieved secure clock.

pcbSecureClock

[out] Size of the secure clock, in bytes.

pdwFlags

[out] Device status flags. This value must be one of the following flags.

Flag | Description
WMDRM_DEVICE_ISWMDRM | The device supports Windows Media DRM.
WMDRM_DEVICE_NEEDCLOCK | The device needs clock.
WMDRM_DEVICE_REVOKED | The device has been revoked.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • GetSecureClockChallenge
  • IWMDRMDevice Interface
  • SetSecureClockResponse


IWMDRMDevice::GetSecureClockChallenge (deprecated)

The GetSecureClockChallenge method retrieves the secure clock challenge result.

Syntax

HRESULT GetSecureClockChallenge(
  BYTE**  ppbChallenge,
  DWORD*  pcbChallenge
);

Parameters

ppbChallenge

[out] Retrieved challenge result.

pcbChallenge

[out] Size of the challenge result, in bytes.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • GetSecureClock
  • IWMDRMDevice Interface


IWMDRMDevice::GetSyncList (deprecated)

The GetSyncList method retrieves the license synchronization list on the device. License synchronization allows the host computer to transfer updated licenses to a device according to the specified criteria.

Syntax

HRESULT GetSyncList(
  DWORD  cMinCountThreshold,
  DWORD  cMinHoursThreshold,
  BYTE**  ppbSyncList,
  DWORD*  pcbSyncList
);

Parameters

cMinCountThreshold

[in] Minimum count threshold.

cMinHoursThreshold

[in] Minimum hours threshold.

ppbSyncList

[out] Retrieved license synchronization list.

pcbSyncList

[out] Size of the license synchronization list, in bytes.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::IsWMDRMDevice (deprecated)

The IsWMDRMDevice method determines whether the device supports Windows Media DRM 10 for Portable Devices.

Syntax

HRESULT IsWMDRMDevice(
  DWORD*  pdwVersion
);

Parameters

pdwVersion

[out] Version of Windows Media DRM 10 for Portable Devices, which has value of 0x00010000.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::SetLicenseResponse (deprecated)

The SetLicenseResponse method sets the license response.

Syntax

HRESULT SetLicenseResponse(
  BYTE*  pbResponse,
  DWORD  cbResponse
);

Parameters

pbResponse

[in] Specifies the response to be set.

cbResponse

[in] Size of the response, in bytes.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::SetMeterResponse (deprecated)

The SetMeterResponse method sets the metering response.

Syntax

HRESULT SetMeterResponse(
  BYTE*  pbMeterResponse,
  DWORD  cbMeterResponse,
  DWORD*  pdwFlags
);

Parameters

pbMeterResponse

[in] The metering response to be set.

cbMeterResponse

[in] Size of the metering response, in bytes.

pdwFlags

[out] Response flags. This value must be one of the following flags.

Flag | Description
WMDRM_METER_RESPONSE_ALL | All meter responses.
WMDRM_METER_RESPONSE_PARTIAL | Partial meter responses.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice Interface


IWMDRMDevice::SetSecureClockResponse (deprecated)

The SetSecureClockResponse method sets the secure clock response.

Syntax

HRESULT SetSecureClockResponse(
  BYTE*  pbResponse,
  DWORD  cbResponse
);

Parameters

pbResponse

[in] The secure clock response to be set.

cbResponse

[in] The specified size of the secure clock response, in bytes.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • GetSecureClock
  • IWMDRMDevice Interface


IWMDRMDevice2 Interface (deprecated)

This interface is not intended to be implemented by a service provider, but is provided for purposes of complete documentation.

The IWMDRMDevice2 interface extends IWMDRMDevice by providing methods to get the license state and a partial synchronization list.

In addition to the methods inherited from IWMDRMDevice, the IWMDRMDevice2 interface exposes the following methods.

Method | Description
GetLicenseState | Gets the license state.
GetPartialSyncList | Gets a partial synchronization list.

See Also

  • Interfaces for Service Providers
  • IWMDRMDevice Interface


IWMDRMDevice2::GetLicenseState (deprecated)

The GetLicenseState method gets the license state.

Syntax

HRESULT GetLicenseState(
  BYTE*  pbStateQueryData,
  DWORD  cbStateQueryData,
  DWORD*  pdwCategory,
  DWORD*  pcRemainingCounts,
  DWORD*  pcRemainingHours,
  DWORD*  pdwReserved
);

Parameters

pbStateQueryData

[in] Pointer to the queried data of the license state.

cbStateQueryData

[in] Count of the queried data.

pdwCategory

[out] Pointer to the category.

pcRemainingCounts

[out] Pointer to the remaining counts.

pcRemainingHours

[out] Pointer to the remaining hours.

pdwReserved

[out] Reserved for future use.

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeds.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice2 Interface


IWMDRMDevice2::GetPartialSyncList (deprecated)

The GetPartialSyncList method gets a partial synchronization list.

Syntax

HRESULT GetPartialSyncList(
  DWORD  cMinCountThreshold,
  DWORD  cMinHoursThreshold,
  DWORD  dwStartingIndex,
  DWORD  cItems,
  BYTE**  ppbSyncList,
  DWORD*  pcbSyncList,
  DWORD*  pdwNextStartingIndex,
  DWORD*  pcItemsProcessed
);

Parameters

cMinCountThreshold

[in] Minimum count threshold.

cMinHoursThreshold

[in] Minimum hours threshold.

dwStartingIndex

[in] Start position for indexing.

cItems

[in] Count of items to be indexed.

ppbSyncList

[out] Retrieved license synchronization list.

pcbSyncList

[out] Size of the license synchronization list, in bytes.

pdwNextStartingIndex

[out] Next start position for indexing.

pcItemsProcessed

[out] Count of items being processed.

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.

Return code | Description
S_OK | The method succeeded.

Requirements

Header: Defined in WMDDRMSP.idl.

Library: mssachlp.lib

See Also

  • IWMDRMDevice::GetSyncList
  • IWMDRMDevice2 Interface


Interfaces for Service Providers and Applications

The following interfaces can be used by both service providers and applications that use the Windows Media Device Manager SDK.

Interface | Description
IWMDMLogger | Logs entries in a common log file.
IComponentAuthenticate | Provides secure, encrypted communication between modules of Windows Media Device Manager.


IWMDMLogger Interface (deprecated)

The IWMDMLogger interface is used by Windows Media Device Manager applications and service providers to log entries in a common log file. Components do not need to be certified to use this object.

This interface is exposed by a COM object that must be created using the class ID CLSID_WMDMLogger, as shown here:

IWMDMLogger* m_pLogger = NULL;
CoCreateInstance(CLSID_WMDMLogger, NULL, CLSCTX_ALL, __uuidof(IWMDMLogger), (void**)&m_pLogger);

This interface GUID is not properly defined in mssachlp.lib; therefore, to get the proper definitions when implementing this interface, you must #include both mswmdm.h and wmdmlog_i.c from wmdmlog.idl.

In addition to the methods inherited from IUnknown, the IWMDMLogger interface exposes the following methods.

Method | Description
Enable | Enables or disables logging.
GetLogFileName | Returns the full path to the current log file.
GetSizeParams | Retrieves the current size parameters of the current log file.
IsEnabled | Determines whether logging is enabled.
LogDword | Logs a DWORD value to the current log file.
LogString | Logs a string to the current log file.
Reset | Deletes the contents of the current log file.
SetLogFileName | Sets the full path to the current log file. All subsequent log entries are placed in this file.
SetSizeParams | Sets the current size parameters for the current log file.

See Also

  • Enabling Logging
  • Interfaces for Service Providers and Applications


IWMDMLogger::Enable (deprecated)

The Enable method enables or disables logging. Logging is enabled by default.

Syntax

HRESULT Enable(
  BOOL  fEnable
);

Parameters

fEnable

[in] Flag that enables logging if it is true and disables logging if it is false.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_FAIL | An unspecified error occurred.

Example Code

// Create logging object.
CoCreateInstance(CLSID_WMDMLogger, NULL, CLSCTX_ALL, __uuidof(IWMDMLogger), (void**)&m_pLogger);
BOOL enabled = FALSE;
hr = m_pLogger->IsEnabled(&enabled);
// TODO: Display a message indicating that logging is either enabled or disabled.
if(!enabled)
{
    if(m_pLogger->Enable(TRUE) != S_OK)
        m_pLogger = NULL;
}

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::GetLogFileName (deprecated)

The GetLogFileName method returns the full path to the current log file.

Syntax

HRESULT GetLogFileName(
  LPSTR  pszFilename,
  UINT nMaxChars
);

Parameters

pszFilename

[out] Pointer to a buffer to receive the log file name.

nMaxChars

[in] Specifies the size of the pszFilename buffer. This is the maximum number of characters that can be placed in the buffer, including the terminating NULL character.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | The buffer is too small.

Remarks

The default log file is <Windows directory>\System32\Wmdm.log.

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::GetSizeParams (deprecated)

The GetSizeParams method retrieves the current size parameters of the current log file.

Syntax

HRESULT GetSizeParams(
  LPDWORD  pdwMaxSize,
  LPDWORD  pdwShrinkToSize
);

Parameters

pdwMaxSize

[out] Pointer to a buffer that receives the approximate maximum size of the log file. This parameter can be NULL.

pdwShrinkToSize

[out] Pointer to a buffer that receives the approximate size to which the log file will be reduced after it reaches the maximum size. This parameter can 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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_FAIL | The method failed.

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::IsEnabled (deprecated)

The IsEnabled method determines whether logging is enabled.

Syntax

HRESULT IsEnabled(
  BOOL*  pfEnabled
);

Parameters

pfEnabled

[out] Pointer to a flag that is true on output if logging is enabled.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

The file WmdmLog.idl is the IDL source code for WmdmLog.dll. This file is processed by the MIDL tool to produce the type library (WmdmLog.tlb) and marshaling code.

Example Code

// Create logging object.
CoCreateInstance(CLSID_WMDMLogger, NULL, CLSCTX_ALL, __uuidof(IWMDMLogger), (void**)&m_pLogger);
BOOL enabled = FALSE;
hr = m_pLogger->IsEnabled(&enabled);
// TODO: Display a message that logging is either enabled or disabled.
if(!enabled)
{
    if(m_pLogger->Enable(TRUE) != S_OK)
        m_pLogger = NULL;
}

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::LogDword (deprecated)

The LogDword method logs a DWORD value to the current log file. A carriage return and line feed are added to each log entry.

Syntax

HRESULT LogDword(
  DWORD  dwFlags,
  LPSTR  pszSrcName,
  LPSTR  pszLogFormat,
  DWORD  dwLog
);

Parameters

dwFlags

[in] Flags that control the way a string is logged. This parameter is a combination of one or more of the following values.

Value | Description
WMDM_LOG_SEV_INFO | Tag the log entry as informational.
WMDM_LOG_SEV_WARN | Tag the log entry as a warning.
WMDM_LOG_SEV_ERROR | Tag the log entry as an error.
WMDM_LOG_NOTIMESTAMP | Do not include a time stamp on the log entry. Time stamps are in ISO format minus the time-zone information.

pszSrcName

[in] Optional pointer to a string containing the name of the module that is making the log entry.

pszLogFormat

[in] Pointer to a string that specifies the format of the log string. This string is of the same form as the format string for the printf function.

dwLog

[in] DWORD value to log.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid.
E_ACCESSDENIED | An error occurred while accessing the log file.
E_OUTOFMEMORY | There is not enough memory to complete this logging operation.
E_ABORT | The method timed out while trying to get exclusive access to the log file.
E_FAIL | An unspecified error occurred.

Example Code

// Send the file and metadata.
    hr = pStgCtl3->Insert3(
        flags,
        WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
        const_cast<WCHAR*>(pwszFileName), // Source file.
        NULL, // Destination file name.
        pOperation, // Null to allow the SDK to read the file; non-null to
                    // present raw data bytes to the SDK.
        pProgress, // Interface to send simple progress notifications.
        pMetadata, // IWMDMMetaData interface previously created and filled.
        NULL,
        &pNewStorage);
    if(FAILED(hr))
        m_pLogger->LogDword(WMDM_LOG_SEV_ERROR, NULL,
            "Error calling Insert3 in mySendFile: %lX", hr);

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::LogString (deprecated)

The LogString method logs a string to the current log file. A carriage return and line feed are added to each log entry.

Syntax

HRESULT LogString(
  DWORD  dwFlags,
  LPSTR  pszSrcName,
  LPSTR  pszLog
);

Parameters

dwFlags

[in] Flags that control the way a string is logged. This parameter is a combination of one or more of the following values.

Value | Description
WMDM_LOG_SEV_INFO | Tag the log entry as informational.
WMDM_LOG_SEV_WARN | Tag the log entry as a warning.
WMDM_LOG_SEV_ERROR | Tag the log entry as an error.
WMDM_LOG_NOTIMESTAMP | Do not include a time stamp on the log entry. Time stamps are in ISO format minus the time-zone information.

pszSrcName

[in] Pointer to a string containing the name of the module that is making the log entry. This parameter can be NULL.

pszLog

[in] Pointer to a string to be copied to the log. This parameter can 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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | A parameter is invalid.
E_ACCESSDENIED | An error occurred while accessing the log file.
E_OUTOFMEMORY | There is not enough memory to complete this logging operation.
E_ABORT | The method timed out while trying to get exclusive access to the log file.
E_FAIL | An unspecified error occurred.

Example Code

// Send a startup message.
hr = m_pLogger->LogString(WMDM_LOG_SEV_INFO, NULL, "Application started.");

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::Reset (deprecated)

The Reset method deletes the contents of the current log file.

Syntax

HRESULT Reset(void);

Parameters

This method takes no parameters.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_ACCESSDENIED | An error occurred while accessing the log file.
E_ABORT | The method timed out while trying to get exclusive access to the log file.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::SetLogFileName (deprecated)

The SetLogFileName method sets the full path to the current log file. All subsequent log entries will be placed in this file.

Syntax

HRESULT SetLogFileName(
  LPSTR  pszFilename
);

Parameters

pszFilename

[in] Pointer to a string that is the full path to the new log file. Note that this is not a wide-character string.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pszFilename parameter is an invalid or NULL pointer.
E_FAIL | The method failed to get exclusive access to the log file.
E_ABORT | The method timed out while trying to get exclusive access to the log file.

Remarks

The default log file is <Windows directory>\System32\Wmdm.log.

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IWMDMLogger::SetSizeParams (deprecated)

The SetSizeParams method sets the current size parameters for the current log file.

Syntax

HRESULT SetSizeParams(
  DWORD  dwMaxSize,
  DWORD  dwShrinkToSize
);

Parameters

dwMaxSize

[in] The approximate maximum size of the log file. The size of the log file is checked before each log entry is made. Therefore, the log file can grow bigger than the maximum size until the next log entry is made.

dwShrinkToSize

[in] The approximate file size to which the log file should be reduced when the maximum log file size is reached. The log file is generally shrunk to a little smaller than this value so that the file is not split in the middle of a log entry.

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 extensive list of possible error codes, see Error Codes.

Possible return values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_ABORT | The method timed out while trying to get exclusive access to the log file.
E_ACCESSDENIED | An error occurred in accessing a file.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in wmdmlog.idl.

Library: mssachlp.lib

See Also

  • Enabling Logging
  • IWMDMLogger Interface


IComponentAuthenticate Interface (deprecated)

The IComponentAuthenticate interface provides secure, encrypted communication between modules of Windows Media Device Manager. It is implemented by a service provider and created and used by an application or plug-in. To get this interface, the application calls CoCreateInstance(__uuidof(MediaDevMgr)).

The application creates and passes this interface to CSecureChannelClient::SetInterface, but never calls any methods on this interface.

The service provider implements the methods in this interface, and calls them on a private CSecureChannelServer member.

In addition to the methods inherited from IUnknown, the IComponentAuthenticate interface exposes the following methods.

Method | Description
SACAuth | Establishes a secure authenticated channel between components.
SACGetProtocols | Discovers the authentication protocols supported by another component.

See Also

  • Authenticating the Application
  • Authenticating the Service Provider
  • Interfaces for Service Providers and Applications
  • Using Secure Authenticated Channels


IComponentAuthenticate::SACAuth (deprecated)

The SACAuth method establishes a secure authenticated channel between components.

Syntax

HRESULT SACAuth(
  DWORD  dwProtocolID,
  DWORD  dwPass,
  BYTE*  pbDataIn,
  DWORD  dwDataInLen,
  BYTE**  ppbDataOut,
  DWORD*  pdwDataOutLen
);

Parameters

dwProtocolID

[in] DWORD containing the protocol identifier. For this version of Windows Media Device Manager, always set this parameter to SAC_PROTOCOL_V1.

dwPass

[in] DWORD containing the number of the current communication pass. A pass consists of two messages, one in each direction. SAC_PROTOCOL_V1 is a two-pass protocol, and the passes are numbered 0 and 1.

pbDataIn

[in] Pointer to the input data.

dwDataInLen

[in] DWORD containing the length of the data to which pbDataIn points.

ppbDataOut

[out] Pointer to a pointer to the output data.

pdwDataOutLen

[out] Pointer to a DWORD containing the length of the data to which ppbDataOut points.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pbSPSessionKey parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is called only by service providers. It is called one or more times as dictated by the protocol identifier.

The structure of the data in pbDataIn and ppbDataOut is determined by the values of dwProtocolID and dwPass.

Example Code

The following C++ code demonstrates a service provider's implementation of SACAuth. It calls CSecureChannelServer::SACAuth on a previously created private CSecureChannelServer member.

HRESULT CMyServiceProvider::SACAuth(
    DWORD   dwProtocolID,
    DWORD   dwPass,
    BYTE   *pbDataIn,
    DWORD   dwDataInLen,
    BYTE  **ppbDataOut,
    DWORD  *pdwDataOutLen)
{
    HRESULT hr = S_OK;

    // Verify that the global CSecureChannelServer member is valid.
    if(g_pAppSCServer == NULL)
        return E_FAIL;

    hr = g_pAppSCServer->SACAuth(
        dwProtocolID,
        dwPass,
        pbDataIn, dwDataInLen,
        ppbDataOut, pdwDataOutLen
    );
    return hr;
}

Requirements

Header: Defined in icomponentauthenticate.idl.

Library: mssachlp.lib

See Also

  • Authenticating the Service Provider
  • CSecureChannelServer::SACAuth
  • IComponentAuthenticate Interface


IComponentAuthenticate::SACGetProtocols (deprecated)

The SACGetProtocols method is used by a component to discover the authentication protocols supported by another component.

Syntax

HRESULT SACGetProtocols(
  DWORD**  ppdwProtocols,
  DWORD*  pdwProtocolCount
);

Parameters

ppdwProtocols

[out] Pointer to an array of supported protocols. For this version of Windows Media Device Manager, it is a single-element DWORD array containing the value SAC_PROTOCOL_V1.

pdwProtocolCount

[out] Pointer to a DWORD containing the number of protocols returned in ppdwProtocols. The number is always 1 for this version.

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 extensive list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded.
E_INVALIDARG | The pbSPSessionKey parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is implemented by a service provider, and never called by an application.

Example Code

The following method demonstrates a service provider's implementation of the SACGetProtocols method. It does this by calling CSecureChannelServer::SACGetProtocols on its private CSecureChannelServer member.

STDMETHODIMP CMyServiceProvider::SACGetProtocols(
    DWORD **ppdwProtocols,
    DWORD  *pdwProtocolCount)
{
    HRESULT hr = E_FAIL;

    // Verify that the global CSecureChannelServer member is valid.
    if(g_pAppSCServer == NULL)
       return hr;

    hr = g_pAppSCServer->SACGetProtocols(
        ppdwProtocols,
        pdwProtocolCount
    );

    return hr;
}

Requirements

Header: Defined in icomponentauthenticate.idl.

Library: mssachlp.lib

See Also

  • Authenticating the Service Provider
  • CSecureChannelServer::SACGetProtocols
  • IComponentAuthenticate Interface


Interfaces for Secure Content Providers

A secure content provider (SCP) is a plug-in component that enables Windows Media Device Manager to transfer and request rights information from DRM-protected content. Microsoft provides an SCP component that can handle DRM-protected WMA and WMV files. If your device or application will use DRM-protected content of other formats, it should create an SCP component by implementing all of these interfaces. Otherwise, you will not need to use these interfaces.

Interface | Description
ISCPSecureAuthenticate | The primary interface of the secure content provider.
ISCPSecureAuthenticate2 | Extends ISCPSecureAuthenticate by providing a way to get a session object.
ISCPSecureExchange | Used to exchange secured content and rights associated with content.
ISCPSecureExchange2 | Extends ISCPSecureExchange by providing a new version of the TransferContainerData method.
ISCPSecureExchange3 | Extends ISCPSecureExchange2 by providing improved data exchange performance, and a transfer complete callback method.
ISCPSecureQuery | Queried by Windows Media Device Manager to determine ownership of secured content.
ISCPSecureQuery2 | Extends ISCPSecureQuery through functionality that determines whether the secure content provider is responsible for the content, and if so, providing a URL for updating revoked components and determining which components have been revoked.
ISCPSecureQuery3 | Extends ISCPSecureQuery2 by providing a set of new methods for retrieving the rights and making decision on a clear channel.
ISCPSession | Provides efficient common state management for multiple operations.


ISCPSecureAuthenticate Interface (deprecated)

The ISCPSecureAuthenticate interface is the primary interface of the secure content provider, which Windows Media Device Manager queries to authenticate the secure content provider and to be authenticated by the secure content provider. This interface is used to pass information about the content to the secure content provider module, which the provider uses to report back whether it is responsible for the content. Windows Media Device Manager consults this interface whenever an application downloads content to a media device.

The secure content provider implements this interface, and Windows Media Device Manager calls its methods.

In addition to the methods inherited from IUnknown, the ISCPSecureAuthenticate interface exposes the following method.

Method | Description
GetSecureQuery | Gets a pointer to an ISCPSecureQuery interface.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureQuery Interface


ISCPSecureAuthenticate::GetSecureQuery (deprecated)

The GetSecureQuery method is used to obtain a pointer to the ISCPSecureQuery interface.

Syntax

HRESULT GetSecureQuery(
  ISCPSecureQuery**  ppSecureQuery
);

Parameters

ppSecureQuery

[out] Pointer to an ISCPSecureQuery object.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureAuthenticate Interface
  • ISCPSecureQuery Interface


ISCPSecureAuthenticate2 Interface (deprecated)

The ISCPSecureAuthenticate2 interface extends ISCPSecureAuthenticate by providing a way to get a session object.

In addition to the methods inherited from IUnknown, the ISCPSecureAuthenticate2 interface exposes the following method.

Method | Description
GetSCPSession | Gets a pointer to an ISCPSession interface that represents a session object.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureAuthenticate Interface
  • ISCPSession Interface


ISCPSecureAuthenticate2::GetSCPSession (deprecated)

The GetSCPSession method is used to obtain a pointer to the ISCPSecureQuery interface that represents a session object.

Syntax

HRESULT GetSCPSession(
  ISCPSession**  ppSCPSession
);

Parameters

ppSCPSession

[out] Pointer to an ISCPSession object.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

This method is used to obtain a secure content provider (SCP) session. An SCP session is useful during transfer of multiple files, where the session can help SCP do some of the operations only once instead of once for every file transfer. This results in better transfer performance.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureAuthenticate2 Interface


ISCPSecureExchange Interface (deprecated)

The ISCPSecureExchange interface is used to exchange secured content and rights associated with content. The secure content provider implements this interface and secure Windows Media Device Manager implementations call its methods.

In addition to the methods inherited from IUnknown, the ISCPSecureExchange interface exposes the following methods.

Method | Description
ObjectData | Transfers a block of object data to Windows Media Device Manager.
TransferComplete | Called by Windows Media Device Manager to signal the end of a secure transfer of data.
TransferContainerData | Transfers container file data to the secure content provider.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureExchange2 Interface
  • ISCPSecureExchange3 Interface


ISCPSecureExchange::ObjectData (deprecated)

The ObjectData method transfers a block of object data back to Windows Media Device Manager.

Syntax

HRESULT ObjectData(
  BYTE*  pData,
  DWORD*  pdwSize,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pData

[out] Pointer to a buffer to receive data. This parameter is included in the output message authentication code and is encrypted.

pdwSize

[in, out] Pointer to a DWORD containing the transfer size. This parameter must be included in both the input and output message authentication codes.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
S_FALSE | The method failed. Terminate interaction with the secure content provider.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

To transfer data, Windows Media Device Manager calls the TransferContainerData method to obtain the container data. ObjectData is then called to transfer blocks of object data from the secure content provider to Windows Media Device Manager. If S_OK is returned with pdwSize set to zero, Windows Media Device Manager will request no further data.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange Interface


ISCPSecureExchange::TransferComplete (deprecated)

The TransferComplete method is called by Windows Media Device Manager to signal the end of a secure transfer of data. In this method, the secure content provider can perform any additional processing required to enable the content on the target device.

Syntax

HRESULT TransferComplete();

Parameters

This method takes no parameters.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_NOT_CERTIFIED | The caller is not authorized to use this interface.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
E_FAIL | An unspecified error occurred.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange Interface


ISCPSecureExchange::TransferContainerData (deprecated)

The TransferContainerData method transfers container file data to the secure content provider. The secure content provider breaks down the container internally and reports which parts of the content are available as they are extracted from the container.

Syntax

HRESULT TransferContainerData(
  BYTE*  pData,
  DWORD  dwSize,
  UINT*  pfuReadyFlags,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pData

[in] Pointer to a buffer holding the current data being transferred from the container file. This parameter must be included in the input message authentication code and must be encrypted.

dwSize

[in] DWORD that contains the number of bytes in the buffer. This parameter must be included in the input message authentication code.

pfuReadyFlags

[out] Flag indicating which parts of the container file are ready to be read. This parameter is included in the output message authentication code. The following flags indicate what is ready.

Flag | Description
WMDM_SCP_TRANSFER_OBJECTDATA | Data of the object is available by calling the ObjectData method.
WMDM_SCP_NO_MORE_CHANGES | Set when the secure content provider has determined that it requires no further processing and/or modification of the file being transferred. Windows Media Device Manager can directly transfer the remainder of the file to the device.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_NOT_CERTIFIED | The caller is not authorized to use this interface.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
S_FALSE | The method failed. Terminate interaction with the secure content provider.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Windows Media Device Manager calls this method repeatedly, transferring data from the container file to the secure content provider. Windows Media Device Manager eventually calls this method with dwSize set to zero to indicate that it has no more data to transfer. As the secure content provider collects the data and extracts the various objects from it, it reports back to Windows Media Device Manager which objects, if any, are available after each call. If no objects are available, the secure content provider returns S_OK with the pfuReadyFlags parameter set to zero. When the secure content provider has determined that it requires no further processing and/or modification of the file being transferred, the flag WMDM_SCP_NO_MORE_CHANGES is returned. Windows Media Device Manager can then directly transfer the remainder of the file to the device.

Object data is transferred from the secure content provider by calling the ObjectData method. Windows Media Device Manager calls ObjectData repeatedly until it returns zero in the second parameter, dwBytesWrite.

The TransferComplete method is called by Windows Media Device Manager to signal the end of a secure transfer of data.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange Interface


ISCPSecureExchange2 Interface (deprecated)

The ISCPSecureExchange2 interface extends ISCPSecureExchange by providing a new version of the TransferContainerData method. TransferContainerData2 accepts a progress callback on which the secure content provider can send progress notifications for any of the steps it needs to carry out.

In addition to the methods inherited from ISCPSecureExchange, the ISCPSecureExchange2 interface exposes the following method.

Method | Description
TransferContainerData2 | Transfers container file data to the secure content provider.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureExchange Interface
  • ISCPSecureExchange3 Interface


ISCPSecureExchange2::TransferContainerData2 (deprecated)

The TransferContainerData2 method transfers container file data to the secure content provider. The secure content provider breaks down the container internally and reports which parts of the content are available as they are extracted from the container. This method extends ISCPSecureExchange::TransferContainerData by accepting a progress callback on which the secure content provider can send progress notifications for any of the steps it needs to carry out.

Syntax

HRESULT TransferContainerData2(
  BYTE*  pData,
  DWORD  dwSize,
  IWMDMProgress3*  pProgressCallback,
  UINT*  pfuReadyFlags,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pData

[in] Pointer to a buffer holding the current data being transferred from the container file. This parameter must be included in the input message authentication code and must be encrypted.

dwSize

[in] DWORD that contains the number of bytes in the buffer. This parameter must be included in the input message authentication code.

pProgressCallback

[in] Progress callback on which the secure content provider can report progress of any steps that it might need to carry out. The step will be identified by the EventId parameter of IWMDMProgress3 methods.

pfuReadyFlags

[out] Flag indicating which parts of the container file are ready to be read. This parameter is included in the output message authentication code. The following flags indicate what is ready.

Flag | Description
WMDM_SCP_TRANSFER_OBJECTDATA | Data of the object is available by calling the ObjectData method.
WMDM_SCP_NO_MORE_CHANGES | The secure content provider has determined that it requires no further processing and/or modification of the file being transferred. Windows Media Device Manager can directly transfer the remainder of the file to the device.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_NOT_CERTIFIED | The caller is not authorized to use this interface.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
S_FALSE | The method failed. Terminate interaction with the secure content provider.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Windows Media Device Manager calls this method repeatedly, transferring data from the container file to the secure content provider. Windows Media Device Manager eventually calls this method with dwSize set to zero to indicate that it has no more data to transfer. As the secure content provider collects the data and extracts the various objects from it, it reports back to Windows Media Device Manager which objects, if any, are available after each call. If no objects are available, the secure content provider returns S_OK with the pfuReadyFlags parameter set to zero. When the secure content provider has determined that it requires no further processing and/or modification of the file being transferred, the flag WMDM_SCP_NO_MORE_CHANGES is returned. Windows Media Device Manager can then directly transfer the remainder of the file to the device.

Object data is transferred from the secure content provider by calling the ObjectData method. Windows Media Device Manager calls ObjectData repeatedly until it returns zero in the second parameter, dwBytesWrite.

The TransferComplete method is called by Windows Media Device Manager to signal the end of a secure transfer of data.

Windows Media Device Manager passes the application-provided progress callback to the secure content provider in the pProgressCallback parameter. The secure content provider can use this parameter to provide progress notification for any steps that it needs to carry out. The step itself is identified by EventId, which is the first parameter of the methods of IWMDMProgress3. A specific secure content provider implementation will define EventId values for applications to use.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange Interface
  • ISCPSecureExchange::ObjectData
  • ISCPSecureExchange2 Interface
  • IWMDMProgress3 Interface


ISCPSecureExchange3 Interface (deprecated)

The ISCPSecureExchange3 interface extends ISCPSecureExchange2 by providing improved data exchange performance, and a transfer-complete callback method.

In addition to the methods inherited from ISCPSecureExchange2, the ISCPSecureExchange3 interface exposes the following methods.

Method | Description
GetObjectDataOnClearChannel | Retrieves the object data on a clear channel.
TransferCompleteForDevice | Indicates that the data transfer has completed for the device.
TransferContainerDataOnClearChannel | Transfers the container data on a clear channel.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureExchange Interface
  • ISCPSecureExchange2 Interface


ISCPSecureExchange3::GetObjectDataOnClearChannel (deprecated)

The GetObjectDataOnClearChannel method transfers a block of object data on a clear channel back to Windows Media Device Manager.

Syntax

HRESULT GetObjectDataOnClearChannel(
  IMDSPDevice*  pDevice,
  BYTE*  pData,
  DWORD*  pdwSize
);

Parameters

pDevice

[in] Pointer to the device object.

pData

[out] Pointer to a buffer to receive data.

pdwSize

[in, out] Pointer to a DWORD containing the transfer size.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
S_FALSE | The method failed. Terminate interaction with the content provider.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

To transfer data, Windows Media Device Manager calls the TransferContainerDataOnClearChannel method to obtain the container data. GetObjectDataOnClearChannel is then called to transfer blocks of object data from the content provider to Windows Media Device Manager. If S_OK is returned with pdwSize set to zero, Windows Media Device Manager will request no further data.

This method is identical to ISCPSecureExchange::ObjectData except that the data returned by this method is not encrypted. Consequently this method is more efficient.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange::ObjectData
  • ISCPSecureExchange3 Interface


ISCPSecureExchange3::TransferCompleteForDevice (deprecated)

The TransferCompleteForDevice method is called by Windows Media Device Manager to signal the end of a data transfer for a specific device.

Syntax

HRESULT TransferCompleteForDevice(
  IMDSPDevice*  pDevice
);

Parameters

pDevice

[in] Pointer to a device object.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_NOT_CERTIFIED | The caller is not authorized to use this interface.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
E_FAIL | An unspecified error occurred.

Remarks

This method is identical to ISCPSecureExchange::TransferComplete except that this method is called when transfer is completed within a transfer session.

In that case, the secure content provider needs to know which device the transfer was completed for, so this method accepts a pDevice parameter.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange::TransferComplete
  • ISCPSecureExchange3 Interface


ISCPSecureExchange3::TransferContainerDataOnClearChannel (deprecated)

The TransferContainerDataOnClearChannel method transfers container file data to the content provider through the clear channel. The content provider breaks down the container internally and reports which parts of the content are available as they are extracted from the container.

Syntax

HRESULT TransferContainerDataOnClearChannel(
  IMDSPDevice*  pDevice,
  BYTE*  pData,
  DWORD  dwSize,
  IWMDMProgress3*  pProgressCallback,
  UINT*  pfuReadyFlags
);

Parameters

pDevice

[in] Pointer to a device object.

pData

[in] Pointer to a buffer holding the current data being transferred from the container file.

dwSize

[in] DWORD that contains the number of bytes in the buffer.

pProgressCallback

[in] Progress callback on which the content provider can report progress of any steps that it might need to carry out. The step will be identified by the EventId parameter of IWMDMProgress3 methods.

pfuReadyFlags

[out] Flag indicating which parts of the container file are ready to be read. This parameter is included in the output message authentication code. The following flags indicate what is ready.

Flag | Description
WMDM_SCP_TRANSFER_OBJECTDATA | Data of the object is available by calling the GetObjectDataOnClearChannel method.
WMDM_SCP_NO_MORE_CHANGES | The content provider has determined that it requires no further processing and/or modification of the file being transferred. Windows Media Device Manager can directly transfer the remainder of the file to the device.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_NOT_CERTIFIED | The caller is not authorized to use this interface.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
S_FALSE | The method failed. Terminate interaction with the content provider.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

Windows Media Device Manager calls this method repeatedly, transferring data from the container file to the content provider. Windows Media Device Manager eventually calls this method with dwSize set to zero to indicate that it has no more data to transfer. As the content provider collects the data and extracts the various objects from it, it reports back to Windows Media Device Manager which objects, if any, are available after each call. If no objects are available, the content provider returns S_OK with the pfuReadyFlags parameter set to zero. When the content provider has determined that it requires no further processing and/or modification of the file being transferred, the flag WMDM_SCP_NO_MORE_CHANGES is returned. Windows Media Device Manager can then directly transfer the remainder of the file to the device.

Object data is transferred from the content provider by calling the GetObjectDataOnClearChannel method. Windows Media Device Manager calls GetObjectDataOnClearChannel repeatedly until it returns zero in the third parameter, pdwsize.

The ISCPSecureExchange::TransferComplete (or TransferCompleteForDevice if a session is active) method is called by Windows Media Device Manager to signal the end of a data transfer.

Windows Media Device Manager passes the application-provided progress callback to the content provider in the pProgressCallback parameter. The content provider can use this parameter to provide progress notification for any steps that it needs to carry out. The step itself is identified by EventId, which is the first parameter of the methods of IWMDMProgress3. A specific content provider implementation will define EventId values for applications to use.

This method is identical to ISCPSecureExchange::TransferContainerData except that the parameters passed to this method are not encrypted. Consequently this method is more efficient.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange::TransferContainerData
  • ISCPSecureExchange3 Interface


ISCPSecureQuery Interface (deprecated)

The ISCPSecureQuery interface is queried by Windows Media Device Manager to determine ownership of secured content. Windows Media Device Manager passes information about the content to the secure content provider, which uses that information to determine whether it is responsible for the content. Windows Media Device Manager consults this interface whenever an application downloads content to a media device.

The ISCPSecureQuery2 interface extends ISCPSecureQuery through functionality that determines whether the secure content provider is responsible for the content, and if so, providing a URL for updating revoked components and determining which components have been revoked.

The secure content provider implements this interface and secure Windows Media Device Manager implementations call its methods.

In addition to the methods inherited from IUnknown, the ISCPSecureQuery interface exposes the following methods.

Method | Description
ExamineData | Determines whether the secure content provider is responsible for the content by examining data that Windows Media Device Manager passes to this method.
GetDataDemands | Reports what data the secure content provider needs to determine rights and responsibility for a specified piece of content.
GetRights | Retrieves rights information for a piece of content. Rights are file-specific.
MakeDecision | Determines whether transferring the content to a specified device is allowed.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureQuery2 Interface
  • ISCPSecureQuery3 Interface


ISCPSecureQuery::ExamineData (deprecated)

The ExamineData method determines rights and responsibility for the content by examining data that Windows Media Device Manager passes to this method.

Syntax

HRESULT ExamineData(
  UINT  fuFlags,
  LPWSTR  pwszExtension,
  BYTE*  pData,
  DWORD  dwSize,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

fuFlags

[in] Flags describing the data offered to the secure content provider to make decisions. The following flags can be present.

Flag | Description
WMDM_SCP_EXAMINE_DATA | The pData parameter points to data to be examined.

pwszExtension

[in] Pointer to the file name extension to be examined if the secure content provider asks for an extension in the GetDataDemands call.

pData

[in] Pointer to the data at the beginning of the file to be examined. This parameter must be included in the input message authentication code and must be encrypted.

dwSize

[in] DWORD that contains the length, in bytes, of the data to be examined. This parameter must be included in the input message authentication code.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code | Description
S_OK | The method succeeded. The secure content provider is responsible for this content.
WMDM_E_CALL_OUT_OF_SEQUENCE | This method was called out of sequence. GetDataDemands must be called first.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_MOREDATA | Windows Media Device Manager must call this method again with another packet of data. The size of the packet is determined by the pdwMinExamineData parameter in the GetDataDemands method.
S_FALSE | The secure content provider is not responsible for this content. Terminate interaction with the secure content provider.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is called after the GetDataDemands method. The secure content provider uses the information passed in this method to determine whether it is responsible for the content. The fuFlags parameter is consulted to determine which data has been presented for examination. The pData parameter points to the beginning of the rights and responsibility data. The dwSize parameter contains the length, in bytes, of the rights and responsibility data.

If the WMDM_SCP_EXAMINE_DATA flag is set, then the pDataBuffer parameter contains dwDataLength of bytes for the secure content provider to examine.

If this method does not return S_OK or WMDM_E_MOREDATA, then Windows Media Device Manager does not make any further calls to this secure content provider.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureQuery Interface


ISCPSecureQuery::GetDataDemands (deprecated)

The GetDataDemands method reports which data the secure content provider needs to determine the rights and responsibility for a specified piece of content.

Syntax

HRESULT GetDataDemands(
  UINT*  pfuFlags,
  DWORD*  pdwMinRightsData,
  DWORD*  pdwMinExamineData,
  DWORD*  pdwMinDecideData,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pfuFlags

[out] Flags describing the data required by the secure content provider to make decisions. This parameter is included in the output message authentication code. At least one of the following flags must be used.

Flag | Description
WMDM_SCP_RIGHTS_DATA | The secure content provider needs data to determine rights for the content.
WMDM_SCP_EXAMINE_DATA | The secure content provider needs data to determine whether it is responsible for the content.
WMDM_SCP_DECIDE_DATA | The secure content provider needs data to determine whether to allow the content to be downloaded.
WMDM_SCP_EXAMINE_EXTENSION | The secure content provider needs to examine the file name extension to determine whether to allow the content to be downloaded.
WMDM_SCP_PROTECTED_OUTPUT | The secure content provider needs protected output.
WMDM_SCP_UNPROTECTED_OUTPUT | The secure content provider needs unprotected output.

pdwMinRightsData

[out] Pointer to a DWORD specifying the minimum amount of data needed to determine rights for this content. This parameter is included in the output message authentication code.

pdwMinExamineData

[out] Pointer to a DWORD containing the minimum number of bytes of data that the secure content provider needs to determine whether it is responsible for the content. This parameter is included in the output message authentication code.

pdwMinDecideData

[out] Pointer to a DWORD containing the minimum number of bytes of data that the secure content provider needs to determine whether to allow the content to be downloaded. This parameter is included in the output message authentication code.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
E_INVALIDARG | A parameter is an invalid or NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method must be called before any of the other methods of ISCPSecureQuery are called.

This method is called after any certificate exchanges have been successfully finished. The secure content provider fills in the parameters with the flags and data that describe its requirements for making decisions about the content.

If the secure content provider sets the WMDM_SCP_RIGHTS_DATA flag, then Windows Media Device Manager sends the amount of data specified in pdwMinRightsData by calling ISCPSecureQuery::GetRights.

If the secure content provider sets the WMDM_SCP_EXAMINE_DATA flag, then Windows Media Device Manager sends the amount of data specified in pdwMinExamineData by calling ISCPSecureQuery::ExamineData.

If the secure content provider sets the WMDM_SCP_DECIDE_DATA flag, then Windows Media Device Manager sends the amount of data specified in pdwMinDecideData by calling ISCPSecureQuery::MakeDecision.

If no examine flags are set, Windows Media Device Manager does not make any more calls. If no decide flags are set, Windows Media Device Manager still calls ISCPSecureQuery::ExamineData.

If this method does not return S_OK, then Windows Media Device Manager does not make any further calls to this secure content provider.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureQuery Interface


ISCPSecureQuery::GetRights (deprecated)

The GetRights method retrieves rights information for the current piece of content. Rights are file-specific.

Syntax

HRESULT GetRights(
  BYTE*  pData,
  DWORD  dwSize,
  BYTE*  pbSPSessionKey,
  DWORD  dwSessionKeyLen,
  IMDSPStorageGlobals*  pStgGlobals,
  PWMDMRIGHTS*  ppRights,
  UINT*  pnRightsCount,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

pData

[in] Pointer to data requested by GetDataDemands. This parameter must be included in the input message authentication code and must be encrypted.

dwSize

[in] Number of bytes of data in the pData buffer. This parameter must be included in the input message authentication code.

pbSPSessionKey

[in] Pointer to an array of bytes containing the session key for securing communication with the service provider to which pStgGlobals points. This parameter must be included in the input message authentication code and must be encrypted.

dwSessionKeyLen

[in] Length of the byte array to which pbSPSessionKey points. This parameter must be included in the input message authentication code.

pStgGlobals

[in] Pointer to an IWMDMStorageGlobals interface on the root storage of the media or device to or from which the file is being transferred.

ppRights

[out] Pointer to an array of WMDMRIGHTS structures containing the rights information for this object. The array is allocated by this method and must be freed using CoTaskMemFree. This parameter is included in the output message authentication code.

pnRightsCount

[out] Number of WMDMRIGHTS structures in the ppRights array. This parameter is included in the output message authentication code.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_CALL_OUT_OF_SEQUENCE | This method was called out of sequence. GetDataDemands and then ExamineData must be called first, in that order.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method must not be called until GetDataDemands and then ExamineData have been called, in that order.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureQuery Interface
  • IWMDMStorageGlobals Interface
  • WMDMRIGHTS


ISCPSecureQuery::MakeDecision (deprecated)

The MakeDecision method determines whether access to the content is allowed. If access is allowed, this method returns the interface that will be used to access the content.

Syntax

HRESULT MakeDecision(
  UINT  fuFlags,
  BYTE*  pData,
  DWORD  dwSize,
  DWORD  dwAppSec,
  BYTE*  pbSPSessionKey,
  DWORD  dwSessionKeyLen,
  IMDSPStorageGlobals*  pStorageGlobals,
  ISCPSecureExchange**  ppExchange,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

fuFlags

[in] Flags describing the data offered to the secure content provider for making decisions. This parameter must be included in the input message authentication code. The following flags can be present.

Flag | Description
WMDM_SCP_DECIDE_DATA | The pData parameter points to data to be examined.
WMDM_MODE_TRANSFER_PROTECTED | The output object data from the ISCPSecureExchange interface must be protected. If Windows Media Device Manager sets neither or both mode flags, DRM decides whether the output object data from the ISCPSecureExchange interface must be protected or unprotected.
WMDM_MODE_TRANSFER_UNPROTECTED | The output object data from the ISCPSecureExchange interface must be unprotected. If Windows Media Device Manager sets neither or both mode flags, DRM decides whether the output object data from the ISCPSecureExchange interface must be protected or unprotected.

pData

[in] Pointer to a data object containing the data to be examined. This parameter must be included in the input message authentication code and must be encrypted.

dwSize

[in] DWORD that contains the length, in bytes, of the data to be examined. This parameter must be included in the input message authentication code.

dwAppSec

[in] DWORD that indicates the current level of security of Windows Media Device Manager. This is the smaller of the current security levels of the application and the target service provider. This parameter must be included in the input message authentication code.

pbSPSessionKey

[in] Pointer to an array of bytes containing the session key for securing communication with the service provider to which pStgGlobals points. This parameter must be included in the input message authentication code and must be encrypted.

dwSessionKeyLen

[in] Length of the byte array to which pbSPSessionKey points. This parameter must be included in the input message authentication code.

pStorageGlobals

[in] Pointer to the IWMDMStorageGlobals interface on the root storage of the media or device to or from which the file is being transferred. This parameter must be included in the input message authentication code.

ppExchange

[out] Pointer to an exchange object that receives the exchange interface.

abMac

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_CALL_OUT_OF_SEQUENCE | This method was called out of sequence.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_MOREDATA | Windows Media Device Manager must call this method again with another packet of data. The size of the packet is determined by the pdwMinDecisionData parameter in the ISCPSecureQuery::GetDataDemands method.
S_FALSE | The caller does not have the rights required to perform the requested transfer.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is called after the ISCPSecureQuery::ExamineData method, and makes the final decision whether access to the content is allowed.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureExchange Interface
  • ISCPSecureQuery Interface
  • ISCPSecureQuery2::MakeDecision2
  • IWMDMStorageGlobals Interface


ISCPSecureQuery2 Interface (deprecated)

The ISCPSecureQuery2 interface extends ISCPSecureQuery through functionality that determines whether the secure content provider is responsible for the content, and if so, providing a URL for updating revoked components and determining which components have been revoked.

In addition to the methods inherited from ISCPSecureQuery, the ISCPSecureQuery2 interface exposes the following method.

Method | Description
MakeDecision2 | Determines whether the secure content provider is responsible for the content by examining data that Windows Media Device Manager passes to this method.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureQuery Interface
  • ISCPSecureQuery3 Interface


ISCPSecureQuery2::MakeDecision2 (deprecated)

The MakeDecision2 method determines whether the secure content provider is responsible for the content by examining data that Windows Media Device Manager passes to this method. This method provides two output parameters for error handling, a default location for updating revoked components, and a bit flag indicating which components have been revoked.

Syntax

HRESULT MakeDecision2(
  UINT  fuFlags,
  BYTE*  pData,
  DWORD  dwSize,
  DWORD  dwAppSec,
  BYTE*  pbSPSessionKey,
  DWORD  dwSessionKeyLen,
  IMDSPStorageGlobals*  pStorageGlobals,
  BYTE*  pAppCertApp,
  DWORD  dwAppCertAppLen,
  BYTE*  pAppCertSP,
  DWORD  dwAppCertSPLen,
  LPWSTR*  pszRevocationURL,
  DWORD*  pdwRevocationURLLen,
  DWORD*  pdwRevocationBitFlag,
  ULONGLONG*  pqwFileSize,
  IUnknown*  pUnknown,
  ISCPSecureExchange**  ppExchange,
  BYTE  abMac[WMDM_MAC_LENGTH]
);

Parameters

fuFlags

[in] Flags describing the data offered to the secure content provider for making decisions. This parameter must be included in the input message authentication code. One or more of the following flags can be combined using a bitwise OR.

Flag | Description
WMDM_SCP_DECIDE_DATA | The pData parameter points to the data to be examined.
WMDM_MODE_TRANSFER_PROTECTED | The output object data from the ISCPSecureExchange interface must be protected. If Windows Media Device Manager sets neither or both mode flags, Windows Media Digital Rights Manager decides whether the output object data from the ISCPSecureExchange interface must be protected or unprotected.
WMDM_MODE_TRANSFER_UNPROTECTED | The output object data from the ISCPSecureExchange interface must be unprotected. If Windows Media Device Manager sets neither or both mode flags, Windows Media Digital Rights Manager decides whether the output object data from the ISCPSecureExchange interface must be protected or unprotected.

pData

[in] Pointer to a data object containing the data to be examined. This parameter must be included in the input message authentication code and must be encrypted.

dwSize

[in] DWORD containing the size of the file data.

dwAppSec

[in] DWORD that contains the length, in bytes, of the dwAppSec member of the WMDMRIGHTS structure of the service provider and secure content provider to be examined. This parameter must be included in the input message authentication code.

pbSPSessionKey

[in] Pointer to an array of bytes containing the session key for securing communication with the service provider to which pStgGlobals points. This parameter must be included in the input message authentication code and must be encrypted.

dwSessionKeyLen

[in] DWORD containing the session key length.

pStorageGlobals

[in] Pointer to the IWMDMStorageGlobals interface on the root storage of the media or device to or from which the file is being transferred. This parameter must be included in the input message authentication code.

pAppCertApp

[in] Pointer to an application certificate of the application object.

dwAppCertAppLen

[in] DWORD containing the length, in bytes, of the application certificate.

pAppCertSP

[in] Pointer to the application certificate of the service provider object.

dwAppCertSPLen

[in] DWORD containing the length, in bytes, of the application certificate.

pszRevocationURL

[in, out] Pointer to a buffer to hold the revocation URL.

pdwRevocationURLLen

[in, out] Pointer to a DWORD containing the size of the rpszRevocationURL buffer in bytes.

pdwRevocationBitFlag

[out] Pointer to a DWORD containing the revocation bit flag. The flag value will be either zero, or one or more of the following flag names combined by using a bitwise OR.

Value | Description
WMDM_WMDM_REVOKED | Windows Media Device Manager itself has been revoked.
WMDM_APP_REVOKED | The application has been revoked and needs to be updated before any DRM-protected content can be transferred.
WMDM_SP_REVOKED | The service provider has been revoked and needs to be updated before any DRM-protected content can be transferred to it.
WMDM_SCP_REVOKED | The secure content provider has been revoked and needs to be updated before any DRM-protected content can be transferred.

pqwFileSize

[in, out] Pointer to a QWORD containing the file size. The secure content provider is responsible for updating this value or setting it to zero if the size of the destination file cannot be determined at this point.

pUnknown

[in] Pointer to an unknown interface from the application.

ppExchange

[out] Pointer to an exchange object that receives the exchange interface.

abMac[WMDM_MAC_LENGTH]

[in, out] Array of eight bytes containing the message authentication code for the parameter data of this method. (WMDM_MAC_LENGTH is defined as 8.)

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_REVOKED | The application certificate that the secure content provider uses to talk to the DRM client has been revoked.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureQuery Interface
  • ISCPSecureQuery::MakeDecision
  • ISCPSecureQuery2 Interface


ISCPSecureQuery3 Interface (deprecated)

The ISCPSecureQuery3 interface extends ISCPSecureQuery2 by providing a set of new methods for retrieving the rights and making decision on a clear channel. These methods are more efficient because they do not involve encrypting and decrypting of parameters, which happens on a secure channel.

In addition to the methods inherited from ISCPSecureQuery2, the ISCPSecureQuery3 interface exposes the following methods.

Method | Description
GetRightsOnClearChannel | Retrieves the rights on a clear channel.
MakeDecisionOnClearChannel | Makes decisions on a clear channel.

See Also

  • Interfaces for Secure Content Providers
  • ISCPSecureQuery Interface
  • ISCPSecureQuery2 Interface


ISCPSecureQuery3::GetRightsOnClearChannel (deprecated)

The GetRightsOnClearChannel method retrieves rights information for the current piece of content on a clear channel.

Syntax

HRESULT GetRightsOnClearChannel(
  BYTE*  pData,
  DWORD  dwSize,
  BYTE*  pbSPSessionKey,
  DWORD  dwSessionKeyLen,
  IMDSPStorageGlobals*  pStgGlobals,
  IWMDMProgress3*  pProgressCallback,
  PWMDMRIGHTS*  ppRights,
  UINT*  pnRightsCount
);

Parameters

pData

[in] Pointer to data object.

dwSize

[in] Number of bytes of data in the pData buffer.

pbSPSessionKey

[in] Pointer to an array of bytes containing the session key for securing communication with the service provider to which pStgGlobals points.

dwSessionKeyLen

[in] Length of the byte array to which pbSPSessionKey points.

pStgGlobals

[in] Pointer to an IWMDMStorageGlobals interface on the root storage of the media or device to or from which the file is being transferred.

pProgressCallback

[in] Pointer to an IWMDMProgress3 interface.

ppRights

[out] Pointer to an array of WMDMRIGHTS structures containing the rights information for this object. The array is allocated by this method and must be freed using CoTaskMemFree.

pnRightsCount

[out] Number of WMDMRIGHTS structures in the ppRights array.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_CALL_OUT_OF_SEQUENCE | This method was called out of sequence. ISCPSecureQuery::GetDataDemands and then ISCPSecureQuery::ExamineData must be called, in that order.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_NORIGHTS | The caller does not have the rights required to perform the requested operation.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is identical to ISCPSecureQuery::GetRights except that the parameters passed to this method are not encrypted. Consequently this method is more efficient.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureQuery::GetRights
  • ISCPSecureQuery3 Interface
  • IWMDMStorageGlobals Interface
  • WMDMRIGHTS


ISCPSecureQuery3::MakeDecisionOnClearChannel (deprecated)

The MakeDecisionOnClearChannel method determines whether access to the content is allowed on a clear channel. If access is allowed, this method returns the interface used to access the content.

Syntax

HRESULT MakeDecisionOnClearChannel(
  UINT  fuFlags,
  BYTE*  pData,
  DWORD  dwSize,
  DWORD  dwAppSec,
  BYTE*  pbSPSessionKey,
  DWORD  dwSessionKeyLen,
  IMDSPStorageGlobals*  pStorageGlobals,
  IWMDMProgress3*  pProgressCallback,
  BYTE*  pAppCertApp,
  DWORD  dwAppCertAppLen,
  BYTE*  pAppCertSP,
  DWORD  dwAppCertSPLen,
  LPWSTR*  pszRevocationURL,
  DWORD*  pdwRevocationURLLen,
  DWORD*  pdwRevocationBitFlag,
  ULONGLONG*  pqwFileSize,
  IUnknown*  pUnknown,
  ISCPSecureExchange**  ppExchange
);

Parameters

fuFlags

[in] Flags describing the data offered to the content provider for making decisions. The following flags can be present.

Flag | Description
WMDM_SCP_DECIDE_DATA | The pData parameter points to data to be examined.
WMDM_MODE_TRANSFER_PROTECTED | The output object data from the ISCPSecureExchange interface must be protected. If Windows Media Device Manager sets neither or both mode flags, digital rights management (DRM) decides whether the output object data from the ISCPSecureExchange interface must be protected or unprotected.
WMDM_MODE_TRANSFER_UNPROTECTED | The output object data from the ISCPSecureExchange interface must be unprotected. If Windows Media Device Manager sets neither or both mode flags, digital rights management (DRM) decides whether the output object data from the ISCPSecureExchange interface must be protected or unprotected.

pData

[in] Pointer to a data object containing the data to be examined.

dwSize

[in] DWORD that contains the length, in bytes, of the data to be examined.

dwAppSec

[in] DWORD that indicates the current level of security of Windows Media Device Manager. This is the smaller of the current security levels of the application and the target service provider.

pbSPSessionKey

[in] Pointer to an array of bytes containing the session key for securing communication with the service provider to which pStgGlobals points.

dwSessionKeyLen

[in] Length of the byte array to which pbSPSessionKey points.

pStorageGlobals

[in] Pointer to the IWMDMStorageGlobals interface on the root storage of the media or device to or from which the file is being transferred.

pProgressCallback

[in] Pointer to a progress callback object.

pAppCertApp

[in] Pointer to an application certificate of the application object.

dwAppCertAppLen

[in] DWORD containing the length, in bytes, of the application certificate.

pAppCertSP

[in] Pointer to the application certificate of the service provider object.

dwAppCertSPLen

[in] DWORD containing the length, in bytes, of the application certificate.

pszRevocationURL

[in, out] Pointer to a buffer to hold the revocation URL.

pdwRevocationURLLen

[in, out] Pointer to a DWORD containing the size of the rpszRevocationURL buffer in bytes.

pdwRevocationBitFlag

[out] Pointer to a DWORD containing the revocation bit flag. The flag value will be either zero or one or more of the following flag names combined by using a bitwise OR.

Value | Description
WMDM_WMDM_REVOKED | Windows Media Device Manager itself has been revoked.
WMDM_APP_REVOKED | The application has been revoked and needs to be updated before any DRM-protected content can be transferred.
WMDM_SP_REVOKED | The service provider has been revoked and needs to be updated before any DRM-protected content can be transferred to it.
WMDM_SCP_REVOKED | The content provider has been revoked and needs to be updated before any DRM-protected content can be transferred.

pqwFileSize

[in, out] Pointer to a QWORD containing the file size. The content provider is responsible for updating this value or setting it to zero if the size of the destination file cannot be determined at this point.

pUnknown

[in] Pointer to an unknown interface from the application.

ppExchange

[out] Pointer to an exchange object that receives the exchange interface.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Return code | Description
WMDM_E_CALL_OUT_OF_SEQUENCE | This method was called out of sequence.
WMDM_E_MAC_CHECK_FAILED | The message authentication code is not valid.
WMDM_E_MOREDATA | Windows Media Device Manager must call this method again with another packet of data. The size of the packet is determined by the pdwMinDecisionData parameter in the ISCPSecureQuery::GetDataDemands method.
S_FALSE | The caller does not have the rights required to perform the requested transfer.
E_INVALIDARG | A parameter is invalid or is a NULL pointer.
E_FAIL | An unspecified error occurred.

Remarks

This method is identical to ISCPSecureQuery2::MakeDecision2 except that the parameters passed to this method are not encrypted. Consequently this method is more efficient.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSecureQuery2::MakeDecision2
  • ISCPSecureQuery3 Interface


ISCPSession Interface (deprecated)

The ISCPSession interface provides efficient common state management for multiple operations.

A secure content provider (SCP) session is useful when transferring multiple files. In that case, the session can help SCP do some of the operations only once instead of once for every file transfer. This results in better transfer performance.

In addition to the methods inherited from IUnknown, the ISCPSession interface exposes the following methods.

Method | Description
BeginSession | Indicates the beginning of a session.
EndSession | Indicates the end of a session.
GetSecureQuery | Obtains a secure query object for to the session.

See Also

  • Interfaces for Secure Content Providers


ISCPSession::BeginSession (deprecated)

The BeginSession method indicates beginning of a transfer session. It can be used to optimize operations that need to occur only once per transfer session.

Syntax

HRESULT BeginSession(
  IMDSPDevice*  pIDevice,
  BYTE*  pCtx,
  DWORD  dwSizeCtx
);

Parameters

pIDevice

[in] Pointer to an IMDSPDevice object.

pCtx

[in] Pointer to the context.

dwSizeCtx

[in] DWORD containing the size of context.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSession Interface


ISCPSession::EndSession (deprecated)

The EndSession method indicates the ending of a transfer session.

Syntax

HRESULT EndSession(
  IMDSPDevice*  pIDevice,
  BYTE*  pCtx,
  DWORD  dwSizeCtx
);

Parameters

pIDevice

[in] Pointer to an IMDSPDevice object.

pCtx

[in] Pointer to the context.

dwSizeCtx

[in] DWORD containing the size of context.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSession Interface


ISCPSession::GetSecureQuery (deprecated)

The GetSecureQuery method is used to obtain a secure query object for the session.

Syntax

HRESULT GetSecureQuery(
  ISCPSecureQuery**  ppSecureQuery
);

Parameters

ppSecureQuery

[out] Pointer to a secure query object.

Return Values

If the method succeeds, it returns S_OK. If the method fails, it returns an HRESULT error code.

Remarks

This method should be used to obtain a secure query object when using secure content provider sessions for efficient transfer of multiple files.

Requirements

Header: Defined in WMSCP.idl.

Library: mssachlp.lib

See Also

  • ISCPSession Interface


Structures

Windows Media Device Manager defines the following structures.

Structure | Description
_BITMAPINFOHEADER | Defines the format of video frame.
MTP_COMMAND_DATA_IN | Contains Media Transport Protocol (MTP) custom commands that are sent to the device by using the IWMDMDevice3::DeviceIoControl method.
MTP_COMMAND_DATA_OUT | Contains Media Transport Protocol (MTP) responses that are filled by the device driver.
OPAQUECOMMAND | Contains data for commands that are passed through Windows Media Device Manager to a device but are not intended to be acted upon by Windows Media Device Manager.
_VIDEOINFOHEADER | Defines the format of a video stream.
_WAVEFORMATEX | Defines the format of waveform-audio data.
WMDM_FORMAT_CAPABILITY | Describes the capabilities of a device for a particular format. This structure contains a set of property configurations in an array of WMDM_PROP_CONFIG structures.
WMDM_PROP_CONFIG | Describes a set of compatible property values across all the properties supported by the device for a particular format. This structure contains a number of property descriptions in an array of WMDM_PROP_DESC structures.
WMDM_PROP_DESC | Describes valid values of a property in a particular property configuration.
WMDM_PROP_VALUES_ENUM | Contains an enumerated set of valid values for a particular property in a particular property configuration.
WMDM_PROP_VALUES_RANGE | Describes range of valid values for a particular property in a particular property configuration.
WMDMDATETIME | Contains a date and time.
WMDMID | Describes serial numbers and group IDs.
WMDMMetadataView | Defines the metadata view.
WMDMRIGHTS | Describes content-use rights.
WMFILECAPABILITIES | Describes a MIME type.

See Also

  • Programming Reference


_BITMAPINFOHEADER (deprecated)

The _BITMAPINFOHEADER structure defines the format of a video frame.

Syntax

typedef struct _tagBITMAPINFOHEADER{
  DWORD  biSize;
  LONG  biWidth;
  LONG  biHeight;
  WORD  biPlanes;
  WORD  biBitCount;
  DWORD  biCompression;
  DWORD  biSizeImage;
  LONG  biXPelsPerMeter;
  LONG  biYPelsPerMeter;
  DWORD  biClrUsed;
  DWORD  biClrImportant;
} _BITMAPINFOHEADER;

Members

biSize

Specifies the number of bytes required by the structure.

biWidth

Specifies the width of the bitmap, in pixels.

biHeight

Specifies the height of the bitmap, in pixels. If biHeight is positive, the bitmap is a bottom-up DIB and its origin is the lower-left corner. If biHeight is negative, the bitmap is a top-down DIB and its origin is the upper-left corner. If biHeight is negative, indicating a top-down DIB, biCompression must be either BI_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed.

biPlanes

Specifies the number of planes for the target device. This value must be set to 1.

biBitCount

Specifies the number of bits per pixel. The biBitCount member of the BITMAPINFOHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member must be one of the following values.

Value | Description
1 | The bitmap is monochrome, and the bmiColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmiColors table; if the bit is set, the pixel has the color of the second entry in the table.
2 | The bitmap has four possible color values.
4 | The bitmap has a maximum of 16 colors, and the bmiColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8 | The bitmap has a maximum of 256 colors, and the bmiColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
16 | The bitmap has a maximum of 2^16 colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each WORD in the bitmap array represents a single pixel. The relative intensities of red, green, and blue are represented with 5 bits for each color component. The value for blue is in the least significant 5 bits, followed by 5 bits each for green and red. The most significant bit is not used. The bmiColors color table is used for optimizing colors used on palette-based devices, and must contain the number of entries specified by the biClrUsed member.
24 | The bitmap has a maximum of 2^24 colors, and the bmiColors member is NULL. Each 3-byte triplet in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel. The bmiColors color table is used for optimizing colors used on palette-based devices, and must contain the number of entries specified by the biClrUsed member.
32 | The bitmap has a maximum of 2^32 colors. If the biCompression member is BI_RGB, the bmiColors member is NULL. Each DWORD in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel. The high byte in each DWORD is not used. The bmiColors color table is used for optimizing colors used on palette-based devices, and must contain the number of entries specified by the biClrUsed member. If the biCompression member is BI_BITFIELDS, the bmiColors member contains three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. Each DWORD in the bitmap array represents a single pixel.

biCompression

Specifies the type of compression for a compressed bottom-up bitmap (top-down DIBs cannot be compressed). This member can be the one of the following values.

Value | Description
BI_RGB | An uncompressed format.
BI_BITFIELDS | Specifies that the bitmap is not compressed and that the color table consists of three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16-bpp and 32-bpp bitmaps. This value is valid in Microsoft Windows CE version 2.0 and later.

biSizeImage

Specifies the size of the image, in bytes. This may be set to zero for BI_RGB bitmaps.

biXPelsPerMeter

Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. An application can use this value to select a bitmap from a resource group that best matches the characteristics of the current device.

biYPelsPerMeter

Specifies the vertical resolution, in pixels per meter, of the target device for the bitmap.

biClrUsed

Specifies the number of color indexes in the color table that are actually used by the bitmap. If this value is zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member for the compression mode specified by biCompression.

If biClrUsed is nonzero and the biBitCount member is less than 16, the biClrUsed member specifies the actual number of colors the graphics engine or device driver accesses. If biBitCount is 16 or greater, the biClrUsed member specifies the size of the color table used to optimize performance of the system color palettes. If biBitCount equals 16 or 32, the optimal color palette starts immediately following the three DWORD masks.

If the bitmap is a packed bitmap (a bitmap in which the bitmap array immediately follows the _BITMAPINFOHEADER structure and is referenced by a single pointer), the biClrUsed member must be either zero or the actual size of the color table.

biClrImportant

Specifies the number of color indexes required for displaying the bitmap. If this value is zero, all colors are required.

Remarks

This structure is contained within a _VIDEOINFOHEADER structure.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Structures
  • _VIDEOINFOHEADER


MTP_COMMAND_DATA_IN (deprecated)

The MTP_COMMAND_DATA_IN structure contains Media Transport Protocol (MTP) custom commands that are sent to the device by using the IWMDMDevice3::DeviceIoControl method.

Syntax

typedef struct _MTP_COMMAND_DATA_IN{
  WORD  OpCode;
  DWORD  NumParams;
  DWORD  Params[MTP_COMMAND_MAX_PARAMS];
  DWORD  NextPhase;
  DWORD  CommandWriteDataSize;
  BYTE   CommandWriteData[1];
} MTP_COMMAND_DATA_IN, *PMTP_COMMAND_DATA_IN;

Members

OpCode

Operation code.

NumParams

Number of parameters passed in.

Params

Parameters to the command. MTP_COMMAND_MAX_PARAMS is a defined constant with a value of 5.

NextPhase

Indicates whether the command has a read data phase, a write data phase, or no data phase. The valid values are defined in the following table.

Value | Description
MTP_NEXTPHASE_READ_DATA | Read data phase.
MTP_NEXTPHASE_WRITE_DATA | Write data phase.
MTP_NEXTPHASE_NO_DATA | No data phase.

CommandWriteDataSize

Data size of CommandWriteData[1], in bytes.

CommandWriteData[1]

Optional, first byte of data to write to the device if NextPhase is MTP_NEXTPHASE_WRITE_DATA.

Remarks

The input buffer is expected to contain an appropriately filled out MTP_COMMAND_DATA_IN structure. On exit, the device driver will fill out the MTP_COMMAND_DATA_OUT structure and save it to the output buffer. Therefore, any request must have an input buffer of at least SIZEOF_REQUIRED_COMMAND_DATA_IN bytes, which is defined as

#define SIZEOF_REQUIRED_COMMAND_DATA_IN (sizeof(MTP_COMMAND_DATA_IN)-1)

and an output buffer of at least SIZEOF_REQUIRED_COMMAND_DATA_OUT bytes, which is defined as

#define SIZEOF_REQUIRED_COMMAND_DATA_OUT (sizeof(MTP_COMMAND_DATA_OUT)-1)

It is assumed that all commands are self-contained, that is, they can be processed completely in one call. This has implications on lengthy data transfers, because chunking in the traditional sense is not supported. (For example, to issue a read for 3megabytes, the caller would have to ensure that it allocates an output buffer of 3 MB plus SIZEOF_REQUIRED_COMMAND_DATA_OUT bytes.) Lengthy data transfers should not be done with this method, but rather through normal data-transfer APIs.

Requirements

Header: Defined in MtpExt.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::DeviceIoControl
  • MTP_COMMAND_DATA_OUT
  • Structures


MTP_COMMAND_DATA_OUT (deprecated)

The MTP_COMMAND_DATA_OUT structure contains Media Transport Protocol (MTP) responses that are filled by the device driver on exiting a call to IWMDMDevice3::DeviceIoControl.

Syntax

typedef struct _MTP_COMMAND_DATA_OUT{
  WORD  ResponseCode;
  DWORD  NumParams;
  DWORD  Params[MTP_RESPONSE_MAX_PARAMS];
  DWORD  CommandReadDataSize;
  BYTE   CommandReadData[1];
} MTP_COMMAND_DATA_OUT, *PMTP_COMMAND_DATA_OUT;

Members

ResponseCode

Response code.

NumParams

Number of parameters for this response.

Params

Parameters of the response. MTP_RESPONSE_MAX_PARAMS is a defined constant with a value of 5.

CommandReadDataSize

Data size of CommandReadData[1], in bytes.

CommandReadData[1]

Optional, first byte of data to read from the device if MTP_COMMAND_DATA_IN.NextPhase is MTP_NEXTPHASE_READ_DATA.

Remarks

The input buffer is expected to contain an appropriately filled out MTP_COMMAND_DATA_IN structure. On exit, the device driver will fill out the MTP_COMMAND_DATA_OUT structure and save it to the output buffer. Therefore, any request must have an input buffer of at least SIZEOF_REQUIRED_COMMAND_DATA_IN bytes, which is defined as the following:

#define SIZEOF_REQUIRED_COMMAND_DATA_IN (sizeof(MTP_COMMAND_DATA_IN)-1)

Any request must also have an output buffer of at least SIZEOF_REQUIRED_COMMAND_DATA_OUT bytes, which is defined as the following:

#define SIZEOF_REQUIRED_COMMAND_DATA_OUT (sizeof(MTP_COMMAND_DATA_OUT)-1)

It is assumed that all commands are self-contained, that is, they can be processed completely in one call. This has implications on lengthy data transfers, because chunking in the traditional sense is not supported. (For example, to issue a read for 3megabytes, the caller would have to ensure that it allocates an output buffer of 3 MB plus SIZEOF_REQUIRED_COMMAND_DATA_OUT bytes.) Lengthy data transfers should not be done with this method, but rather through normal data transfer APIs.

Requirements

Header: Defined in MtpExt.h.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::DeviceIoControl
  • MTP_COMMAND_DATA_IN
  • Structures


OPAQUECOMMAND (deprecated)

The OPAQUECOMMAND structure contains data for commands that are passed through Windows Media Device Manager to a device but are not intended to be acted upon by Windows Media Device Manager.

Syntax

typedef struct OPAQUECOMMAND{
  GUID  guidCommand;
  DWORD  dwDataLen;
  [size_is(dwDataLen)] BYTE*  pData;
  BYTE  abMAC[20];
};

Members

guidCommand

GUID representing the requested command.

dwDataLen

Length of the data to which pData points, in bytes.

pData

Data required to execute the command, and/or data returned by the command.

abMAC[20]

This message authentication code (MAC) should include the guidCommand member, the data to which pdwDataLen points, and the data to which pData points, if any. If pData is NULL, it must not be included in the MAC. WMDM_MAC_LENGTH is defined as 20.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IMDSPDevice::SendOpaqueCommand
  • IMDSPStorage::SendOpaqueCommands
  • IWMDMDevice::SendOpaqueCommand
  • IWMDMStorage::SendOpaqueCommand
  • Structures


_VIDEOINFOHEADER (deprecated)

The _VIDEOINFOHEADER structure contains information about a video stream and includes a _BITMAPINFOHEADER structure that defines the format of an individual frame.

Syntax

typedef struct _tagVIDEOINFOHEADER{
  RECT  rcSource;
  RECT  rcTarget;
  DWORD  dwBitRate;
  DWORD  dwBitErrorRate;
  REFERENCE_TIME  AvgTimePerFrame;
  BITMAPINFOHEADER  bmiHeader;
} _VIDEOINFOHEADER;

Members

rcSource

RECT structure that specifies the source video window.

rcTarget

RECT structure that specifies the destination video window.

dwBitRate

DWORD value that specifies the video stream's approximate data rate, in bits per second.

dwBitErrorRate

DWORD value that specifies the video stream's data error rate, in bit errors per second.

AvgTimePerFrame

REFERENCE_TIME value that specifies the video frame's average display time, in 100-nanosecond units.

bmiHeader

Win32 _BITMAPINFOHEADER structure that contains color and dimension information for the video image bitmap.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • _BITMAPINFOHEADER
  • Structures


_WAVEFORMATEX (deprecated)

The _WAVEFORMATEX structure defines the format of waveform-audio data.

Syntax

typedef struct _tWAVEFORMATEX{
  WORD  wFormatTag;
  WORD  nChannels;
  DWORD  nSamplesPerSec;
  DWORD  nAvgBytesPerSec;
  WORD  nBlockAlign;
  WORD  wBitsPerSample;
  WORD  cbSize;
} _WAVEFORMATEX;

Members

wFormatTag

Must be set to a format or formats supported by the device. Note that previous versions of the Windows Media Device Manager recommended using WMDM_WAVE_FORMAT_ALL to indicate support for all formats. However, this is no longer recommended, as different media players will interpret this in different ways, and few devices can truly play any file format. It is now recommended that you use the WMDM_ENUM_PROP_VALID_VALUES_ANY value of the WMDM_ENUM_PROP_VALID_VALUES_FORM enumeration, or—better yet—specify a range of formats with the WMDM_PROP_VALUES_RANGE structure.

nChannels

Number of channels in the waveform-audio data. Monaural data uses one channel, and stereo data uses two channels.

nSamplesPerSec

Sample rate, in samples per second (Hertz), at which each channel must be played or recorded. Common values for nSamplesPerSec are 8.0 kilohertz (kHz), 11.025 kHz, 22.05 kHz, and 44.1 kHz.

nAvgBytesPerSec

Required average data-transfer rate for the format tag, in bytes per second. Playback and recording software can estimate buffer sizes by using the nAvgBytesPerSec member.

nBlockAlign

Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the wFormatTag format type. Playback and recording software must process a multiple of nBlockAlign bytes of data at a time. Data written and read from a device must always start at the beginning of a block. For example, it is not possible to correctly start playing PCM data in the middle of a sample (that is, on a boundary that is not block aligned).

wBitsPerSample

Bits per sample for the wFormatTag format type.

cbSize

This member is ignored.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IMDSPDevice::GetFormatSupport
  • IMDSPStorage::CreateStorage
  • IMDSPStorage::GetAttributes
  • IWMDMDevice::GetFormatSupport
  • IWMDMOperation::GetObjectAttributes
  • IWMDMOperation::SetObjectAttributes
  • IWMDMStorage::GetAttributes
  • Structures


WMDM_FORMAT_CAPABILITY (deprecated)

The WMDM_FORMAT_CAPABILITY structure describes the capabilities of a device for a particular format. This structure contains a set of property configurations in an array of WMDM_PROP_CONFIG structures. Each property configuration represents a set of compatible property values across all the properties supported for a given format. The application can get this structure by calling the IWMDMDevice3::GetFormatCapability method and passing in the format code. For a list of format codes, see WMDM_FORMATCODE.

Syntax

typedef struct WMDM_FORMAT_CAPABILITY{
  UINT  nPropConfig;
  [size_is(nPropConfig)] WMDM_PROP_CONFIG*  pConfigs;
};

Members

nPropConfig

Number of property configurations in the pConfigs array.

pConfigs

Pointer to an array of WMDM_PROP_CONFIG structures. The size of array is equal to the value of nPropConfig.

Remarks

The WMDM_FORMAT_CAPABILITY structure provides a flexible mechanism to express the capabilities of the device for a particular format.

If the content is meant to be rendered by the device (for example, an audio file to be played by the device), the properties of the content must match one of the property configurations returned by IWMDMDevice3::GetFormatCapability in the WMDM_FORMAT_CAPABILITY structure. For example, for an audio file, the bit rate and sample rate must satisfy one of the property configurations returned.

The caller is responsible for freeing the memory allocated for this structure. The following function demonstrates how to clear a WMDM_FORMAT_CAPABILITY structure.

void FreeFormatCapability(WMDM_FORMAT_CAPABILITY formatCap)
{
    // Loop through all configurations.
    for (UINT i=0; i < formatCap.nPropConfig; i++)
    {
        // Loop through all descriptions of a configuration and delete
        // the values particular to that description type.
        for (UINT j=0; j < formatCap.pConfigs[i].nPropDesc; j++)
        {
            switch (formatCap.pConfigs[i].pPropDesc[j].ValidValuesForm)
            {
                case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
                    for (UINT k=0; k < formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.cEnumValues; k++)
                    {
                        PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.pValues[k]));
                    }
                    CoTaskMemFree(formatCap.pConfigs[i].pPropDesc[j].ValidValues.EnumeratedValidValues.pValues);
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
                    PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeMin));
                    PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeMax));
                    PropVariantClear (&(formatCap.pConfigs[i].pPropDesc[j].ValidValues.ValidValuesRange.rangeStep));
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_ANY:
                    // No dynamically allocated memory for this value.
                default:
                    break;
            }

            // Free the memory for the description name.
            CoTaskMemFree(formatCap.pConfigs[i].pPropDesc[j].pwszPropName);
        }
        // Free the memory holding the array of description items for this configuration.
        CoTaskMemFree(formatCap.pConfigs[i].pPropDesc);
    }

    // Free the memory pointing to the array of configurations.
    CoTaskMemFree(formatCap.pConfigs);
    formatCap.nPropConfig = 0;
}

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::GetFormatCapability
  • WMDM_ENUM_PROP_VALID_VALUES_FORM
  • WMDM_PROP_CONFIG
  • WMDM_PROP_DESC
  • WMDM_PROP_VALUES_ENUM
  • WMDM_PROP_VALUES_RANGE
  • Structures


WMDM_PROP_CONFIG (deprecated)

The WMDM_PROP_CONFIG structure describes a set of compatible property values across all the properties supported by the device for a particular format. This structure contains a number of property descriptions in an array of WMDM_PROP_DESC structures.

Syntax

typedef struct _WMDM_PROP_CONFIG{
  UINT  nPreference;
  UINT  nPropDesc;
  [size_is(nPropDesc)] WMDM_PROP_DESC*  pPropDesc;
} WMDM_PROP_CONFIG;

Members

nPreference

Device's level of preference for this configuration. The lowest value indicates the most preferred configuration.

nPropDesc

Number of property descriptions contained in this configuration. There is a single property description for each property supported for the specified format.

pPropDesc

Pointer to an array of WMDM_PROP_DESC structures containing property descriptions. The size of the array is equal to the value of nPropDesc. The application must free this memory when finished with it.

Remarks

The WMDM_FORMAT_CAPABILITY structure returned by IWMDMDevice3::GetFormatCapability for a particular format consists of a number of property configurations. WMDM_PROP_CONFIG structures describe those configurations.

A property configuration describes values for all the properties supported for a given format. The values of different properties in a single configuration are compatible with each other. For example, for an audio file, a configuration will include valid values of sample rate and valid values of the bit rate such that all combinations of these sample and bit rates can be played on the device.

The caller is required to free the memory used by pPropDesc. For an example of how to do this, see WMDM_FORMAT_CAPABILITY.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::GetFormatCapability
  • WMDM_ENUM_PROP_VALID_VALUES_FORM
  • WMDM_FORMAT_CAPABILITY
  • WMDM_PROP_DESC
  • WMDM_PROP_VALUES_ENUM
  • WMDM_PROP_VALUES_RANGE
  • Structures


WMDM_PROP_DESC (deprecated)

The WMDM_PROP_DESC structure describes valid values of a property in a particular property configuration.

Syntax

typedef struct _WMDM_PROP_DESC{
  LPWSTR  pwszPropName;
  WMDM_ENUM_PROP_VALID_VALUES_FORM  ValidValuesForm;
  [switch_type(WMDM_ENUM_PROP_VALID_VALUES_FORM)] [switch_is(ValidValuesForm)]  union
  {
    [case (WMDM_ENUM_PROP_VALID_VALUES_ANY)];

    [case (WMDM_ENUM_PROP_VALID_VALUES_RANGE)]
        WMDM_PROP_VALUES_RANGE ValidValuesRange;

    [case (WMDM_ENUM_PROP_VALID_VALUES_ENUM)]
        WMDM_PROP_VALUES_ENUM EnumeratedValidValues;
  } ValidValues

} WMDM_PROP_DESC;

Members

pwszPropName

Name of the property. The application must free this memory when it is done using it.

ValidValuesForm

An WMDM_ENUM_PROP_VALID_VALUES_FORM enumeration value describing the type of values, such as a range or list. The value of this enumeration determines which member variable is used.

ValidValues

Holds the valid values of the property in a particular property configuration. This member holds one of three items: the enumeration value WMDM_ENUM_PROP_VALID_VALUES_ANY; the member ValidValuesRange; or the member EnumeratedValidValues. The value or member is indicated by ValidValuesForm.

ValidValuesRange

A WMDM_PROP_VALUES_RANGE structure containing a range of valid values. This is present only when ValidValuesForm is set to WMDM_ENUM_PROP_VALID_VALUES_RANGE. See Remarks.

EnumeratedValidValues

A WMDM_PROP_VALUES_ENUM structure containing an enumerated set of valid values. This is present only when ValidValuesForm is set to WMDM_ENUM_PROP_VALID_VALUES_ENUM. See Remarks.

Remarks

The WMDM_PROP_DESC structure contains a property description that consists of a property name and its valid values in a particular configuration.

The caller is required to free the memory used by ValidValuesRange or EnumeratedValues. For an example of how to do this, see WMDM_FORMAT_CAPABILITY.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::GetFormatCapability
  • WMDM_ENUM_PROP_VALID_VALUES_FORM
  • WMDM_FORMAT_CAPABILITY
  • WMDM_PROP_CONFIG
  • WMDM_PROP_VALUES_ENUM
  • WMDM_PROP_VALUES_RANGE
  • Structures


WMDM_PROP_VALUES_ENUM (deprecated)

The WMDM_PROP_VALUES_ENUM structure contains an enumerated set of valid values for a particular property in a particular property configuration.

Syntax

typedef struct __WMDM_PROP_VALUES_ENUM{
  UINT  cEnumValues;
  [size_is(cEnumValues)] PROPVARIANT * pValues;
} WMDM_PROP_VALUES_ENUM;

Members

cEnumValues

Count of enumerated values.

pValues

Pointer to an array of values. The size of the array is equal to the value of cEnumValues.

Remarks

This structure is used in the WMDM_PROP_DESC structure to describe an enumerated set of valid values. An enumerated set of valid values is applicable when WMDM_ENUM_PROP_VALID_VALUES_ENUM is selected from the WMDM_ENUM_PROP_VALID_VALUES_FORM enumeration.

The caller is required to free the memory used by pValues. For an example of how to do this, see WMDM_FORMAT_CAPABILITY.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::GetFormatCapability
  • WMDM_ENUM_PROP_VALID_VALUES_FORM
  • WMDM_FORMAT_CAPABILITY
  • WMDM_PROP_CONFIG
  • WMDM_PROP_DESC
  • WMDM_PROP_VALUES_RANGE
  • Structures


WMDM_PROP_VALUES_RANGE (deprecated)

The WMDM_PROP_VALUES_RANGE structure describes a range of valid values for a particular property in a particular property configuration.

Syntax

typedef struct _WMDM_PROP_VALUES_RANGE{
  PROPVARIANT rangeMin;
  PROPVARIANT rangeMax;
  PROPVARIANT rangeStep;
} WMDM_PROP_VALUES_RANGE;

Members

rangeMin

Minimum value in the range.

rangeMax

Maximum value in the range.

rangeStep

The step size in which valid values increment from the minimum value to the maximum value. This permits specifying discrete permissible values in a range.

Remarks

This structure is used in the WMDM_PROP_DESC structure to describe a range of valid values. A range of valid values is applicable when WMDM_ENUM_PROP_VALID_VALUES_ENUM is selected from the WMDM_ENUM_PROP_VALID_VALUES_FORM enumeration.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IWMDMDevice3::GetFormatCapability
  • WMDM_ENUM_PROP_VALID_VALUES_FORM
  • WMDM_FORMAT_CAPABILITY
  • WMDM_PROP_CONFIG
  • WMDM_PROP_DESC
  • WMDM_PROP_VALUES_ENUM
  • Structures


WMDMDATETIME (deprecated)

The WMDMDATETIME structure contains a date and time of day.

Syntax

typedef struct _WMDMDATETIME{
  WORD  wYear;
  WORD  wMonth;
  WORD  wDay;
  WORD  wHour;
  WORD  wMinute;
  WORD  wSecond;
} WMDMDATETIME, *PWMDMDATETIME;

Members

wYear

Word containing the four-digit year.

wMonth

Word containing the month (1-12).

wDay

Word containing the day of the month (1-31).

wHour

Word containing the hour (0-23).

wMinute

Word containing the minute (0-59).

wSecond

Word containing the second (0-59).

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IMDSPStorage::GetDate
  • IWMDMStorage::GetDate
  • WMDMRIGHTS
  • Structures


WMDMID (deprecated)

The WMDMID structure describes serial numbers and group IDs.

Syntax

typedef struct __WMDMID{
  UINT  cbSize;
  DWORD  dwVendorID;
  BYTE  pID[WMDMID_LENGTH];
  UINT  SerialNumberLength;
} WMDMID, *PWMDMID;

Members

cbSize

Size of the WMDMID structure, in bytes.

dwVendorID

DWORD containing the registered ID number of the vendor. Contains zero if not in use.

pID[WMDMID_LENGTH]

Pointer to an array of bytes containing the serial number. The serial number is a string of byte values that have no standard format. Note that this is not a wide-character value. WMDMID_LENGTH is a constant value defined in mswmdm.h.

SerialNumberLength

Actual length of the serial number returned, in bytes.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IMDSPDevice::GetSerialNumber
  • IMDSPStorageGlobals::GetSerialNumber
  • IWMDMDevice::GetSerialNumber
  • IWMDMStorageGlobals::GetSerialNumber
  • Structures


WMDMMetadataView (deprecated)

The WMDMMetadataView structure defines the metadata view. Content is organized based on this definition.

Syntax

typedef struct _WMDMMetadataView
  [string] WCHAR*  pwszViewName;
  UINT  nDepth;
  [string,size_is(nDepth)] WCHAR**  ppwszTags;
} WMDMMetadataView;

Members

pwszViewName

Pointer to a wide-character null-terminated string containing the name of the view. This is used as the name of the root node under which this view is presented.

nDepth

Integer containing the depth of the view, which indicates how many nested metadata tags are used for the view.

ppwszTags

Array of metadata tag strings for the nested tags.

Example Code

The following code creates a metadata view:

WMDMMetadataView view;
view.pwszName = L"My View";
view.nDepth = 3;  // genre, artist, album
LPCWSTR wszTagArray[3];
wszTagArray[0] = g_wszWMDMGenre;
wszTagArray[1] = g_wszWMDMAuthor;
wszTagArray[2] = g_wszWMDMAlbumTitle;
view.ppwszTags = wszTagArray;

The preceding code organizes content as follows:

My View

Genre1

Artist1

Album1

Song1

Song2

…

Album2

…

Artist2

Album1

Song1

Song2

…

Album2

…

Genre2

Artist1

Album1

Song1

Song2

…

Album2

…

Artist2

Album1

Song1

Song2

…

Album2

…

…

…

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Structures


WMDMRIGHTS (deprecated)

The WMDMRIGHTS structure describes content-use rights.

Syntax

typedef struct __WMDMRIGHTS{
  UINT  cbSize;
  DWORD  dwContentType;
  DWORD  fuFlags;
  DWORD  fuRights;
  DWORD  dwAppSec;
  DWORD  dwPlaybackCount;
  WMDMDATETIME  ExpirationDate;
} WMDMRIGHTS, *PWMDMRIGHTS;

Members

cbSize

Size of the structure, in bytes.

dwContentType

DWORD containing the type of content.

fuFlags

Bit field specifying the rights options in use for the content.

Value | Description
WMDM_RIGHTS_PLAYBACKCOUNT | Number of times that the file can be played.
WMDM_RIGHTS_EXPIRATIONDATE | Expiration date of the file.
WMDM_RIGHTS_FREESERIALIDS | Free serial identifier of the file.
WMDM_RIGHTS_GROUPID | Group identifier of the file.
WMDM_RIGHTS_NAMEDSERIALIDS | Named serial identifier of the file.

fuRights

Bit field containing the rights bits for the content.

Value | Description
WMDM_RIGHTS_PLAY_ON_PC | Content can be played on a personal computer.
WMDM_RIGHTS_COPY_TO_NON_SDMI_DEVICE | Content can be copied to a non-SDMI device.
WMDM_RIGHTS_COPY_TO_CD | Content can be copied to a CD.
WMDM_RIGHTS_COPY_TO_SDMI_DEVICE | Content can be copied to an SDMI device.

dwAppSec

Byte array that specifies the minimum level of application security.

dwPlaybackCount

DWORD containing the number of remaining times that the content can be rendered.

ExpirationDate

WMDMDATETIME structure containing the expiration date and time for the content. If the license has no expiration date, the wYear member is set to 0xFFFF, and all other members of WMDMDATETIME are ignored.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IMDSPStorage::GetRights
  • IWMDMStorage::GetRights
  • WMDMDATETIME
  • Structures


WMFILECAPABILITIES (deprecated)

The WMFILECAPABILITIES structure describes the MIME type.

Syntax

typedef struct _tagWMFILECAPABILITIES{
  LPWSTR  pwszMimeType;
  DWORD  dwReserved;
} WMFILECAPABILITIES;

Members

pwszMimeType

MIME type.

dwReserved

DWORD reserved for future use. Set to zero (0).

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • IWMDMDevice2::GetFormatSupport2
  • Structures


Enumeration Types

Windows Media Device Manager defines the following enumerations.

Enumeration type | Description
WMDM_ENUM_PROP_VALID_VALUES_FORM | Describes possible forms of valid values for a property.
WMDM_FIND_SCOPE | Defines the scope of the storage object.
WMDM_FORMATCODE | Defines a list of format codes that describe types of content transferred to and from a device.
WMDM_SESSION_TYPE | Defines the session type.
WMDM_STORAGE_ENUM_MODE | Defines how the content on the storage is to be enumerated.
WMDM_TAG_DATATYPE | Defines a data type.
WMDMMessage | Defines message types and states.

See Also

  • Programming Reference


WMDM_ENUM_PROP_VALID_VALUES_FORM (deprecated)

The WMDM_ENUM_PROP_VALID_VALUES_FORM enumeration type describes possible forms of valid values for a property.

Syntax

typedef enum _WMDM_ENUM_PROP_VALID_VALUES_FORM{
  WMDM_ENUM_PROP_VALID_VALUES_ANY  ,
  WMDM_ENUM_PROP_VALID_VALUES_RANGE  ,
  WMDM_ENUM_PROP_VALID_VALUES_ENUM
} WMDM_ENUM_PROP_VALID_VALUES_FORM;

Members

WMDM_ENUM_PROP_VALID_VALUES_ANY

All values are valid.

WMDM_ENUM_PROP_VALID_VALUES_RANGE

Valid values are expressed as a range. For detailed information, see the WMDM_PROP_VALUES_RANGE structure.

WMDM_ENUM_PROP_VALID_VALUES_ENUM

Valid values are an enumerated set. For detailed information, see the WMDM_PROP_VALUES_ENUM structure.

Remarks

This enumeration is used in the WMDM_PROP_DESC structure to specify the form of valid values for a property.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types
  • IWMDMDevice3::GetFormatCapability
  • WMDM_FORMAT_CAPABILITY
  • WMDM_PROP_CONFIG
  • WMDM_PROP_DESC
  • WMDM_PROP_VALUES_ENUM
  • WMDM_PROP_VALUES_RANGE


WMDM_FIND_SCOPE (deprecated)

The WMDM_FIND_SCOPE enumeration type defines the scope of the storage object.

Syntax

typedef enum tagWMDM_FIND_SCOPE {
  WMDM_FIND_SCOPE_GLOBAL  ,
  WMDM_FIND_SCOPE_IMMEDIATE_CHILDREN
  } WMDM_FIND_SCOPE;

Members

WMDM_FIND_SCOPE_GLOBAL

Looking for the matching object anywhere on the device.

WMDM_FIND_SCOPE_IMMEDIATE_CHILDREN

Looking for the matching object within this storage and its children.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types


WMDM_FORMATCODE (deprecated)

The WMDM_FORMATCODE enumeration type defines a list of format codes that describe types of content transferred to and from a device.

Syntax

typedef enum tagWMDM_FORMATCODE{
  WMDM_FORMATCODE_NOTUSED  =  0x0000,
  WMDM_FORMATCODE_ALLIMAGES  =  0xFFFFFFFF,
  WMDM_FORMATCODE_UNDEFINED  =  0x3000,
  WMDM_FORMATCODE_ASSOCIATION  =  0x3001,
  WMDM_FORMATCODE_SCRIPT  =  0x3002,
  WMDM_FORMATCODE_EXECUTABLE  =  0x3003,
  WMDM_FORMATCODE_TEXT  =  0x3004,
  WMDM_FORMATCODE_HTML  =  0x3005,
  WMDM_FORMATCODE_DPOF  =  0x3006,
  WMDM_FORMATCODE_AIFF  =  0x3007,
  WMDM_FORMATCODE_WAVE  =  0x3008,
  WMDM_FORMATCODE_MP3  =  0x3009,
  WMDM_FORMATCODE_AVI  =  0x300A,
  WMDM_FORMATCODE_MPEG  =  0x300B,
  WMDM_FORMATCODE_ASF  =  0x300C,
  WMDM_FORMATCODE_RESERVED_FIRST  =  0x300D,
  WMDM_FORMATCODE_RESERVED_LAST  =  0x37FF,
  WMDM_FORMATCODE_IMAGE_UNDEFINED  =  0x3800,
  WMDM_FORMATCODE_IMAGE_EXIF  =  0x3801,
  WMDM_FORMATCODE_IMAGE_TIFFEP  =  0x3802,
  WMDM_FORMATCODE_IMAGE_FLASHPIX  =  0x3803,
  WMDM_FORMATCODE_IMAGE_BMP  =  0x3804,
  WMDM_FORMATCODE_IMAGE_CIFF  =  0x3805,
  WMDM_FORMATCODE_IMAGE_GIF  =  0x3807,
  WMDM_FORMATCODE_IMAGE_JFIF  =  0x3808,
  WMDM_FORMATCODE_IMAGE_PCD  =  0x3809,
  WMDM_FORMATCODE_IMAGE_PICT  =  0x380A,
  WMDM_FORMATCODE_IMAGE_PNG  =  0x380B,
  WMDM_FORMATCODE_IMAGE_TIFF  =  0x380D,
  WMDM_FORMATCODE_IMAGE_TIFFIT  =  0x380E,
  WMDM_FORMATCODE_IMAGE_JP2  =  0x380F,
  WMDM_FORMATCODE_IMAGE_JPX  =  0x3810,
  WMDM_FORMATCODE_IMAGE_RESERVED_FIRST  =  0x3811,
  WMDM_FORMATCODE_IMAGE_RESERVED_LAST  =  0x3FFF,
  WMDM_FORMATCODE_UNDEFINEDFIRMWARE  =  0xB802,
  WMDM_FORMATCODE_WINDOWSIMAGEFORMAT  =  0xB881,
  WMDM_FORMATCODE_UNDEFINEDAUDIO  =  0xB900,
  WMDM_FORMATCODE_WMA  =  0xB901,
  WMDM_FORMATCODE_OGG = 0xB902,
  WMDM_FORMATCODE_AAC  = 0xB903,
  WMDM_FORMATCODE_AUDIBLE = 0xB904,
  WMDM_FORMATCODE_FLAC = 0xB906,
  WMDM_FORMATCODE_UNDEFINEDVIDEO  =  0xB980,
  WMDM_FORMATCODE_WMV  =  0xB981
  WMDM_FORMATCODE_MP4 = 0xB982,
  WMDM_FORMATCODE_MP2 = 0xB983
  WMDM_FORMATCODE_UNDEFINEDCOLLECTION  =  0xBA00,
  WMDM_FORMATCODE_ABSTRACTMULTIMEDIAALBUM  =  0xBA01,
  WMDM_FORMATCODE_ABSTRACTIMAGEALBUM  =  0xBA02,
  WMDM_FORMATCODE_ABSTRACTAUDIOALBUM  =  0xBA03,
  WMDM_FORMATCODE_ABSTRACTVIDEOALBUM  =  0xBA04,
  WMDM_FORMATCODE_ABSTRACTAUDIOVIDEOPLAYLIST  =  0xBA05,
  WMDM_FORMATCODE_ABSTRACTCONTACTGROUP  =  0xBA06,
  WMDM_FORMATCODE_ABSTRACTMESSAGEFOLDER  =  0xBA07,
  WMDM_FORMATCODE_ABSTRACTCHAPTEREDPRODUCTION  =  0xBA08,
  WMDM_FORMATCODE_WPLPLAYLIST  =  0xBA10,
  WMDM_FORMATCODE_M3UPLAYLIST  =  0xBA11,
  WMDM_FORMATCODE_MPLPLAYLIST  =  0xBA12,
  WMDM_FORMATCODE_ASXPLAYLIST  =  0xBA13,
  WMDM_FORMATCODE_PLSPLAYLIST  =  0xBA14,
  WMDM_FORMATCODE_UNDEFINEDDOCUMENT  =  0xBA80,
  WMDM_FORMATCODE_ABSTRACTDOCUMENT  =  0xBA81,
  WMDM_FORMATCODE_XMLDOCUMENT = 0xBA82,
  WMDM_FORMATCODE_MICROSOFTWORDDOCUMENT= 0xBA83,
  WMDM_FORMATCODE_MHTCOMPILEDHTMLDOCUMENT = 0xBA84,
  WMDM_FORMATCODE_MICROSOFTEXCELSPREADSHEET = 0xBA85,
  WMDM_FORMATCODE_MICROSOFTPOWERPOINTDOCUMENT = 0xBA86,
  WMDM_FORMATCODE_UNDEFINEDMESSAGE  =  0xBB00,
  WMDM_FORMATCODE_ABSTRACTMESSAGE  =  0xBB01,
  WMDM_FORMATCODE_UNDEFINEDCONTACT  =  0xBB80,
  WMDM_FORMATCODE_ABSTRACTCONTACT  =  0xBB81,
  WMDM_FORMATCODE_VCARD2  =  0xBB82,
  WMDM_FORMATCODE_VCARD3  =  0xBB83,
  WMDM_FORMATCODE_UNDEFINEDCALENDARITEM  =  0xBE00,
  WMDM_FORMATCODE_ABSTRACTCALENDARITEM  =  0xBE01,
  WMDM_FORMATCODE_VCALENDAR1  =  0xBE02,
  WMDM_FORMATCODE_VCALENDAR2 = 0xBE03,
  WMDM_FORMATCODE_UNDEFINEDWINDOWSEXECUTABLE  =  0xBE80
  WMDM_FORMATCODE_MEDIA_CAST = 0xBE81,
  WMDM_FORMATCODE_SECTION = 0xBE82
} WMDM_FORMATCODE;

Members

WMDM_FORMATCODE_NOTUSED

No format code is used.

WMDM_FORMATCODE_ALLIMAGES

Format code that can be used to query for all images.

WMDM_FORMATCODE_UNDEFINED

Format code used to query for all undefined objects.

WMDM_FORMATCODE_ASSOCIATION

Format code used to define a link between two objects.

WMDM_FORMATCODE_SCRIPT

Format code for a script file.

WMDM_FORMATCODE_EXECUTABLE

Format code for an executable file.

WMDM_FORMATCODE_TEXT

Format code for a text file.

WMDM_FORMATCODE_HTML

Format code for an HTML file.

WMDM_FORMATCODE_DPOF

Format code used to represent the digital print order format.

WMDM_FORMATCODE_AIFF

Format code used to represent the audio interchange file format.

WMDM_FORMATCODE_WAVE

Format code used for a WAV file.

WMDM_FORMATCODE_MP3

Format code used for an MP3 file.

WMDM_FORMATCODE_AVI

Format code used for an AVI file.

WMDM_FORMATCODE_MPEG

Format code used for an MPEG file.

WMDM_FORMATCODE_ASF

Format code used to represent an Advanced Systems Format (ASF) file.

WMDM_FORMATCODE_RESERVED_FIRST

Format code that is the first in a range reserved for Picture Transfer Protocol (PTP).

WMDM_FORMATCODE_RESERVED_LAST

Format code that is last in a range reserved for PTP.

WMDM_FORMATCODE_IMAGE_UNDEFINED

Format code used to represent and image of an undefined type.

WMDM_FORMATCODE_IMAGE_EXIF

Format code for an EXIF file. Also used for JPEG images not covered by WMDM_FORMATCODE_IMAGE_JP2 or WMDM_FORMATCODE_IMAGE_JPX.

WMDM_FORMATCODE_IMAGE_TIFFEP

Format code used for images that are of type Tagged Image File Format for Electronic Photography (TIFF/EP)

WMDM_FORMATCODE_IMAGE_FLASHPIX

Format code for a file of type FPX.

WMDM_FORMATCODE_IMAGE_BMP

Format code for a file of type BMP.

WMDM_FORMATCODE_IMAGE_CIFF

Format code for an image in the camera image file format.

WMDM_FORMATCODE_IMAGE_GIF

Format code for a GIF file.

WMDM_FORMATCODE_IMAGE_JFIF

Format code for a file of type JFIF.

WMDM_FORMATCODE_IMAGE_PCD

Format code for an image of type photo cd.

WMDM_FORMATCODE_IMAGE_PICT

Format code for an image of type PICT.

WMDM_FORMATCODE_IMAGE_PNG

Format code for an image of type PNG.

WMDM_FORMATCODE_IMAGE_TIFF

Format code for a file of type TIFF.

WMDM_FORMATCODE_IMAGE_TIFFIT

Format code for an image of type Tagged Image File Format with image technology.

WMDM_FORMATCODE_IMAGE_JP2

Format code for a jpeg200 image.

WMDM_FORMATCODE_IMAGE_JPX

Format code for an image built on JPEG200, using extended still image registration. The file name extension is usually .jpf or .jpx.

WMDM_FORMATCODE_IMAGE_RESERVED_FIRST

Format code that is the first in a range reserved for an image reference in PTP.

WMDM_FORMATCODE_IMAGE_RESERVED_LAST

Format code that is the last in a range reserved for an image reference in PTP.

WMDM_FORMATCODE_UNDEFINEDFIRMWARE

Format code when firmware is undefined.

WMDM_FORMATCODE_WINDOWSIMAGEFORMAT

Format code for Windows image format.

WMDM_FORMATCODE_UNDEFINEDAUDIO

Format code for an audio file of undefined type.

WMDM_FORMATCODE_WMA

Format code for a Windows Media Audio (WMA) file.

WMDM_FORMATCODE_OGG

Format code for a Vorbis-encoded audio file in an Ogg container.

WMDM_FORMATCODE_AAC

Format code for an Advanced Audio Coding (AAC) file.

WMDM_FORMATCODE_AUDIBLE

Format code for an Audible file.

WMDM_FORMATCODE_FLAC

Format code for a Free Lossless Audio Codec (FLAC) file.

WMDM_FORMATCODE_UNDEFINEDVIDEO

Format code for a video file with an undefined type.

WMDM_FORMATCODE_WMV

Format code for a Windows Media Video (WMV) file.

WMDM_FORMATCODE_MP4

Format code for an MP4 file.

WMDM_FORMATCODE_MP2

Format code for an MP2 file.

WMDM_FORMATCODE_UNDEFINEDCOLLECTION

Format code for a collection of an undefined type.

WMDM_FORMATCODE_ABSTRACTMULTIMEDIAALBUM

Format code for a multimedia album where the object contains the properties of a multimedia album and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTIMAGEALBUM

Format code for an image album where the object contains the properties of an image album and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTAUDIOALBUM

Format code for an audio album where the object contains the properties of an audio album and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTVIDEOALBUM

Format code for a video album where the object contains the properties of a video album and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTAUDIOVIDEOPLAYLIST

Format code for an audio/video playlist where the object contains the properties of an audio/video playlist and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTCONTACTGROUP

Format code for a contact group where the object contains the properties of a contact group and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTMESSAGEFOLDER

Format code for a message folder where the object contains the properties of a message folder and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_ABSTRACTCHAPTEREDPRODUCTION

Format code for a chaptered production where the object contains the properties of a chaptered production and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_WPLPLAYLIST

Format code for a playlist formatted with Windows Media playlist formatting.

WMDM_FORMATCODE_M3UPLAYLIST

Format code for a playlist with M3U formatting.

WMDM_FORMATCODE_MPLPLAYLIST

Format code for a playlist with MPL formatting.

WMDM_FORMATCODE_ASXPLAYLIST

Format code for a playlist with ASX formatting.

WMDM_FORMATCODE_PLSPLAYLIST

Format code for a playlist with PLS formatting.

WMDM_FORMATCODE_UNDEFINEDDOCUMENT

Format code for a document of undefined type.

WMDM_FORMATCODE_ABSTRACTDOCUMENT

Format code for a document where the object contains the properties of a document and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_XMLDOCUMENT

Format code for an XML document.

WMDM_FORMATCODE_MICROSOFTWORDDOCUMENT

Format code for a Microsoft Word document.

WMDM_FORMATCODE_MHTCOMPILEDHTMLDOCUMENT

Format code for a compiled HTML document.

WMDM_FORMATCODE_MICROSOFTEXCELSPREADSHEET

Format code for a Microsoft Excel spreadsheet.

WMDM_FORMATCODE_MICROSOFTPOWERPOINTDOCUMENT

Format code for a Microsoft PowerPoint document.

WMDM_FORMATCODE_UNDEFINEDMESSAGE

Format code for a message of undefined type.

WMDM_FORMATCODE_ABSTRACTMESSAGE

Format code for a message where the object contains the properties of a message and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_UNDEFINEDCONTACT

Format code for a contact of undefined type.

WMDM_FORMATCODE_ABSTRACTCONTACT

Format code for a contact where the object contains the properties of a contact and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_VCARD2

Format code for an electronic card with vcard version 2 formatting.

WMDM_FORMATCODE_VCARD3

Format code for an electronic card with vcard version 3 formatting.

WMDM_FORMATCODE_UNDEFINEDCALENDARITEM

Format code for an electronic calendar item of undefined type.

WMDM_FORMATCODE_ABSTRACTCALENDARITEM

Format code for a calendar item where the object contains the properties of a calendar item and, optionally, data. Any contained data is of an undefined format with respect to the MTP specification.

WMDM_FORMATCODE_VCALENDAR1

Format code for an electronic calendar item with vcalendar version 1 formatting.

WMDM_FORMATCODE_VCALENDAR2

Format code for an electronic calendar item with vcalendar version 2 formatting.

WMDM_FORMATCODE_UNDEFINEDWINDOWSEXECUTABLE

Format code for a Windows-based executable of undefined type.

WMDM_FORMATCODE_MEDIA_CAST

Format code for a media cast object.

WMDM_FORMATCODE_SECTION

Format code for a section of data that is contained in another object.

Remarks

To discover the formats supported by a device, an application can use IWMDMDevice3::GetProperty to query the g_wszWMDMFormatsSupported device property.

To discover device capabilities for a particular format, an application can call IWMDMDevice3::GetFormatCapability.

An application can set the format code while creating a storage on device by including the g_wszWMDMFormatCode property in metadata passed in the pMetaData parameter of a call to IWMDMStorageControl3::Insert3.

An application can query the format code of a storage by calling IWMDMStorage3::GetMetadata or IWMDMStorage4::GetSpecifiedMetadata and retrieving the g_wszWMDMFormatCode property.

If the device supports setting the format code after the creation of storage, an application can use IWMDMStorage3::SetMetadata to set the g_wszWMDMFormatCode property. Some devices may not allow changing the format code after the storage is created on the device. Therefore, setting this property along with the metadata passed in IWMDMStorageControl3::Insert3 is strongly recommended.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types
  • IWMDMDevice3::GetFormatCapability
  • IWMDMDevice3::GetProperty
  • IWMDMStorage3::GetMetadata
  • IWMDMStorage3::SetMetadata
  • IWMDMStorage4::GetSpecifiedMetadata
  • IWMDMStorageControl3::Insert3
  • Metadata Constants


WMDM_SESSION_TYPE (deprecated)

The WMDM_SESSION_TYPE enumeration type defines the session type.

Syntax

typedef enum tagWMDM_SESSION_TYPE{
  WMDM_SESSION_NONE  =0x0000,
  WMDM_SESSION_TRANSFER_TO_DEVICE  =0x0001,
  WMDM_SESSION_TRANSFER_FROM_DEVICE  =0x0010,
  WMDM_SESSION_DELETE  =0x0011,
  WMDM_SESSION_CUSTOM  =0x0100
} WMDM_SESSION_TYPE;

Members

WMDM_SESSION_NONE

The session is not defined.

WMDM_SESSION_TRANSFER_TO_DEVICE

The session is defined as transferring data to the device.

WMDM_SESSION_TRANSFER_FROM_DEVICE

The session is defined as transferring data from the device.

WMDM_SESSION_DELETE

The session is defined as deleting data.

WMDM_SESSION_CUSTOM

The session is defined as a custom session.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types


WMDM_STORAGE_ENUM_MODE (deprecated)

The WMDM_STORAGE_ENUM_MODE enumeration type defines how the content on the storage is to be enumerated. This enumeration is used by IWMDMStorage3::SetEnumPreference.

Syntax

typedef enum tagWMDM_STORAGE_ENUM_MODE {
  ENUM_MODE_RAW,
  ENUM_MODE_USE_DEVICE_PREF,
  ENUM_MODE_METADATA_VIEWS
} WMDM_STORAGE_ENUM_MODE;

Members

ENUM_MODE_RAW

Enumerates content on the storage just as it is organized in the file system of the storage.

ENUM_MODE_USE_DEVICE_PREF

Enumerates content on the storage based on the device preference as indicated by the UseMetadataViews device parameter.

ENUM_MODE_METADATA_VIEWS

Enumerates content on the storage by organizing the content based on a metadata view.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types


WMDM_TAG_DATATYPE (deprecated)

The WMDM_TAG_DATATYPE enumeration type defines a data type.

Syntax

typedef enum tagWMDM_TAG_DATATYPE{
  WMDM_TYPE_DWORD  =0,
  WMDM_TYPE_STRING  =1,
  WMDM_TYPE_BINARY  =2,
  WMDM_TYPE_BOOL  =3,
  WMDM_TYPE_QWORD  =4,
  WMDM_TYPE_WORD  =5,
  WMDM_TYPE_GUID  =6,
  WMDM_TYPE_DATE  =7
} WMDM_TAG_DATATYPE;

Members

WMDM_TYPE_DWORD

Specifies a 4-byte DWORD value.

WMDM_TYPE_STRING

Specifies a null-terminated Unicode string (2 bytes per character).

WMDM_TYPE_BINARY

Specifies an array of bytes.

WMDM_TYPE_BOOL

Specifies a 4-byte Boolean value.

WMDM_TYPE_QWORD

Specifies an 8-byte QWORD value.

WMDM_TYPE_WORD

Specifies a 2-byte WORD value.

WMDM_TYPE_GUID

Specifies a 128-bit (16-byte) GUID.

WMDM_TYPE_DATE

Specifies a date.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types


WMDMMessage (deprecated)

The WMDMMessage enumeration type defines message types and states.

Syntax

enum WMDMMessage{
  WMDM_MSG_DEVICE_ARRIVAL,
  WMDM_MSG_DEVICE_REMOVAL,
  WMDM_MSG_MEDIA_ARRIVAL,
  WMDM_MSG_MEDIA_REMOVAL
};

Members

WMDM_MSG_DEVICE_ARRIVAL

A Windows Media Device Manager device has been plugged in.

WMDM_MSG_DEVICE_REMOVAL

A Windows Media Device Manager device has been removed.

WMDM_MSG_MEDIA_ARRIVAL

Media has been inserted in a Windows Media Device Manager device.

WMDM_MSG_MEDIA_REMOVAL

Media has been removed from a Windows Media Device Manager device.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

  • Enumeration Types


Metadata Constants

Metadata is descriptive information about the content transferred to or from a device. In Windows Media Device Manager, metadata consists of properties, where each property is a name-value pair. The name is always a wide-character string. The value is one of several defined data types described in the WMDM_TAG_DATATYPE enumeration.

Windows Media Device Manager has predefined common properties and it is strongly recommended that you use those instead defining new ones. For each predefined property, the SDK defines a global constant that contains the name string. You can reduce the chance of typographical errors by using the global constant. For example, the constant g_wszWMDMTitle is defined as "Title", corresponding to the Title property.

The following metadata property constants have been defined for use in this SDK. These are defined in mswmdm.h.

Storage Metadata Constants

Storage property | Description | Windows Media Device Manager type | Underlying type
g_wszAudioWAVECodec | Audio codec | WMDM_TYPE_DWORD | DWORD
g_wszVideoFourCCCodec | Video codec | WMDM_TYPE_DWORD | DWORD
g_wszWMDMAlbumArt | Whether or not the device supports album art | WMDM_TYPE_BOOL | BOOL
g_wszWMDMAlbumArtist | Track's Album's Artists | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMAlbumCoverData | Album art JPEG byte blob | WMDM_TYPE_BINARY | BYTE*
g_wszWMDMAlbumCoverDuration | Album cover duration | WMDM_TYPE_DWORD | DWORD
g_wszWMDMAlbumCoverFormat | Album art format | WMDM_TYPE_DWORD | DWORD
g_wszWMDMAlbumCoverHeight | Album art height | WMDM_TYPE_DWORD | DWORD
g_wszWMDMAlbumCoverSize | Album art size | WMDM_TYPE_DWORD | DWORD
g_wszWMDMAlbumCoverWidth | Album art width | WMDM_TYPE_DWORD | DWORD
g_wszWMDMAlbumTitle | Track's Album Title | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMAudioBitDepth | Audio bit depth | WMDM_TYPE_DWORD | DWORD
g_wszWMDBackReferences | A reference to the container object. For example, an audio object would use this property to reference a playlist. | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMAuthor | Content author | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMAuthorDate | Content authored date | WMDM_TYPE_DATE | WMDMDATETIME
g_wszWMDMBitrate | Audio bit rate | WMDM_TYPE_DWORD | DWORD
g_wszWMDMBitrateType The MTP bit-rate type. (Currently not implemented.)

Valid values are:

MTP_BITRATETYPE_DISCRETE (0x001) which indicates that CBR and a discrete set of bit rates are supported.

MTP_BITRATETYPE_VARIABLE (0x0002) which indicates support for VBR.

MTP_BITRATE_TYPE_FREE (0x0003) which indicates that CBR and bit-rate values are continuous over a specified range.

 WMDM_TYPE_DWORD DWORD
g_wszWMDMBlockAlignment | Block alignment | WMDM_TYPE_DWORD | DWORD
g_wszWMDMBufferSize | Buffer size | WMDM_TYPE_DWORD | DWORD
g_wszWMDMBuyNow | Purchase this album (required for album art) | WMDM_TYPE_BOOL | BOOL
g_wszWMDMByteBookmark | A bookmark identifying the last position played or viewed in a media object. (This bookmark is a zero-based byte offset.) | WMDM_TYPE_QWORD | QWORD
g_wszWMDMCategory | A text field indicating the genre of a media item | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMCodec | Reserved for future use | WMDM_TYPE_DWORD | DWORD
g_wszWMDMComposer | Music composer | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMDataLength | The data length for the referenced object | WMDM_TYPE_QWORD | QWORD
g_wszWMDMDataOffset | A zero-based offset to the referenced object | WMDM_TYPE_QWORD | QWORD
g_wszWMDMDataUnits The units used for the data length (g_wszWMDMDataLength) and the data units (g_wszWMDMDataUnits) properties.

Units are assumed to be bytes if this property is not set.

 WMDM_TYPE_DWORD DWORD
g_wszWMDMDescription | TV series or photo description | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMDestinationURL The URL associated with an object.

This property is typically used for a media cast (or related) object.

 WMDM_TYPE_STRING LPCWSTR
g_wszWMDMRMId | Reserved for future use
g_wszWMDMDevicePlayCount | Playback count on device | WMDM_TYPE_DWORD | DWORD
g_wszWMDMDuration | Media duration, in 100 ns units | WMDM_TYPE_QWORD | QWORD
g_wszWMDMEditor The email address for the managing editor associated with a media object.

This property is typically used to identify the managing editor for an RSS channel.

 WMDM_TYPE_STRING LPCWSTR
g_wszWMDMEncodingProfile | The WMV9 encoding profiles supported by a device | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMFileAttributes | The attributes for a file object | WMDM_TYPE_QWORD | QWORD
g_wszWMDMediaClassPrimaryID | Music, video, non-music audio, other | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMFileCreationDate | File creation date | WMDM_TYPE_DATE | WMDMDATETIME
g_wszWMDMFileName | File name. Equivalent to calling IWMDMStorage::GetName. | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMFileSize | File size, in bytes. Equivalent to calling IWMDMStorage::GetSize. | WMDM_TYPE_QWORD | QWORD
g_wszWMDMFormatCode Format code for content format. It should be a WMDM_FORMATCODE

value.

 WMDM_TYPE_DWORD WMDM_FORMATCODE
g_wszWMDMFrameRate | Frame rate | WMDM_TYPE_DWORD | DWORD
g_wszWMDMGenre | Track's Genre | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMHeight | Video or image height | WMDM_TYPE_DWORD | DWORD
g_wszWMDMIsProtected | Whether content is DRM protected | WMDM_TYPE_BOOL | BOOL
g_wszWMDMIsRepeat | True if not the first time episode has aired | WMDM_TYPE_BOOL | BOOL
g_wszWMDMKeyFrameDistance | Key frame distance | WMDM_TYPE_DWORD | DWORD
g_wszWMDMLastModifiedDate | Date/time file was last modified. Equivalent to calling IWMDMStorage::GetDate. | WMDM_TYPE_DATE | WMDMDATETIME
g_wszWMDMMediaClassSecondaryID | Audio books, music videos, talk radio, and so on | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMMediaCredits | TV credits (actors, director, producers) | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMMediaGuid | Globally unique identifier for the media content | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMMediaOriginalBroadcastDateTime | Date that episode first aired | WMDM_TYPE_DATE | WMDMDATETIME
g_wszWMDMMediaOriginalChannel | Channel that episode was recorded from | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMMediaStationName | TV station call letters or name | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMMetaGenre | Content type derived from primary & secondary Class ID | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMNonConsumable | Whether content is stored as an opaque data blob on the device. If so, the device does not need to understand the format or render it. | WMDM_TYPE_BOOL | BOOL
g_wszWMDMNumChannels | Number of channels | WMDM_TYPE_DWORD | DWORD
g_wszWMDMObjectBookmark | A bookmark (in milliseconds) that specifies the last position in the media object that was played or viewed | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMOwner | The e-mail address for the owner of a media object | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMParentalRating | Advisory rating | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMPersistentUniqueID | Device-generated unique ID for storage | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMPlayCount | Total count of file playback | WMDM_TYPE_DWORD | DWORD
g_wszWMDMProviderCopyright | Copyright holder's name | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMQualitySetting | Quality setting | WMDM_TYPE_DWORD | DWORD
g_wszWMDMSampleRate | Sample rate | WMDM_TYPE_DWORD | DWORD
g_wszWMDMScanType | Scan type | WMDM_TYPE_DWORD | DWORD
g_wszWMDMSourceURL | The source URL for a media object | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMSubTitle | TV episode title | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMSubTitleDescription | TV episode description | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMSyncID | Application generated GUID for sync purposes | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMSyncTime | Device time stamp when copied | WMDM_TYPE_DATE | WMDMDATETIME
g_wszWMDMTimeBookmark | A bookmark (in milliseconds) that specifies the last position played or viewed | WMDM_TYPE_QWORD | QWORD
g_wszWMDMTimeToLive | The time (in minutes) until the content is updated | WMDM_TYPE_QWORD | QWORD
g_wszWMDMTitle | Track title | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMTotalBitrate | Total bit rate | WMDM_TYPE_DWORD | DWORD
g_wszWMDMTrack | Track Number (1–99) | WMDM_TYPE_DWORD | DWORD
g_wszWMDMTrackMood | Track's mood | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMUserEffectiveRating | Calculated from user, service ratings, and play count | WMDM_TYPE_DWORD | DWORD
g_wszWMDMUserLastPlayTime | Last listened to or viewed time stamp | WMDM_TYPE_DATE | WMDMDATETIME
g_wszWMDMUserRating | User-set rating | WMDM_TYPE_DWORD | DWORD
g_wszWMDMUserRatingOnDevice | User-set rating changed on device | WMDM_TYPE_DWORD | DWORD
g_wszWMDMVideoBitrate | Video bit rate | WMDM_TYPE_DWORD | DWORD
g_wszWMDMWebmaster | The e-mail address of the webmaster responsible for a media object | WMDM_TYPE_STRING | LPCWSTR
g_wszWMDMWidth | Video or image width | WMDM_TYPE_DWORD | DWORD
g_wszWMDMYear | Year the album was released | WMDM_TYPE_STRING | LPCWSTR

Device Metadata Constants

Device property | Description | PROPVARIANT type(vt) | Comments
g_wszWMDMSupportedDeviceProperties | Array of property names for properties supported by device | VT_BSTR | VT_ARRAY |
g_wszWMDMDeviceFriendlyName | Friendly name of the device | VT_BSTR |
g_wszWMDMFormatsSupported | Array of format codes for the formats supported by device | VT_UI4 | VT_ARRAY |
g_wszWMDMFormatsSupportedAreOrdered | Indicates whether the format returned in the supported-formats array are ordered according to device preference. If this property is set to TRUE, applications should transfer content using the format codes that appear first in the array. | VT_BOOL |
g_wszWMDMSyncRelationshipID | Sync relationship ID used by application | VT_BSTR |
g_wszWMDMDeviceModelName | Device model name | VT_BSTR |
g_wszWMDMDeviceFirmwareVersion | Firmware version | VT_UI4 |
g_wszWMDMDeviceVendorExtension | Vendor extension supported by device | VT_BSTR |
g_wszWMDMDeviceProtocol | Protocol used for communication between host and the device | VT_CLSID | Predefined values are: WMDM_DEVICE_PROTOCOL_MTP, WMDM_DEVICE_PROTOCOL_RAPI, WMDM_DEVICE_PROTOCOL_MSC
g_wszWMDMDeviceServiceProviderVendor | ID of the vendor providing a Windows Media Device Manager service provider for the device | VT_CLSID | Predefined values are: WMDM_SERVICE_PROVIDER_VENDOR_MICROSOFT
g_wszWMDMCollectionID | Reserved for future use. | VT_BSTR |
g_wszWMDMDeviceRevocationInfo | The revocation information for a device. This information would include elements like the revocation URL. | VT_BSTR |
g_wszWMDMSupportedDeviceProperties | Array of property names for properties supported by device | VT_BSTR | VT_ARRAY |
g_wszWMDMDeviceFriendlyName | Friendly name of the device | VT_BSTR |

Windows Portable Devices Metadata Constants

Windows Portable Devices property | Description | PROPVARIANT type(vt) | Comments
g_wszWPDPassthroughPropertyValues | A binary large object (or BLOB) used to set or retrieve Windows Portable Devices properties | WMDM_TYPE_BINARY | Allows Windows Media Device Manager clients to read and write Windows Portable Device properties that are not found in Windows Media Device Manager. Note that some Windows Portable Device properties may not be accessible.

See Also

  • Programming Reference


Error Codes

Windows Media Device Manager methods can return a variety of error codes. Some of these are specific to the Windows Media Device Manager, while others are defined by other SDKs or porting kits used to build a device and bubbled up to the Windows Media Device Manager methods. This section describes the various error codes that can be returned by Windows Media technologies, organized by origin.

Windows Media Device Manager Error Codes

The following error codes are defined by the Windows Media Device Manager SDK.

Return code | Description
WMDM_E_BUFFERTOOSMALL | The buffer supplied by the caller is too small. The client should increase the size of the buffer and retry the call.
WMDM_E_BUSY | The device is busy and cannot satisfy the new request.
WMDM_E_CALL_OUT_OF_SEQUENCE | Operations were called in the wrong order. (For example, calling Read without Open.)
WMDM_E_INCORRECT_APPSEC | The minimum level of application security is not correct. This can be caused if a device's key/certificate pair is not a high enough security level.
WMDM_E_CANTOPEN_PMSN_SERVICE_PIPE | PMSN service pipe can not be opened.
WMDM_E_INCORRECT_RIGHTS | The rights for a file are not correct.
WMDM_E_INTERFACEDEAD | The object has disconnected itself from the clients.
WMDM_E_INVALIDTYPE | The type is not valid.
WMDM_E_LICENSE_EXPIRED | The license has expired.
WMDM_E_LICENSE_NOTEXIST | The license does not exist.
WMDM_E_MAC_CHECK_FAILED | The message authentication code check failed.
WMDM_E_MOREDATA | There is more data.
WMDM_E_NORIGHTS | The caller does not have rights for this operation.
WMDM_E_NOTCERTIFIED | The caller is not authenticated to make this call.
WMDM_E_NOTSUPPORTED | This operation is not supported.
WMDM_E_PROCESSFAILED | The process failed.
WMDM_E_REVOKED | The license has been revoked.
WMDM_E_SDMI_NOMORECOPIES | No more copies can be made per SDMI compliance.
WMDM_E_SDMI_TRIGGER | SDMI validation failed.
WMDM_E_TOO_MANY_SESSIONS | Too many sessions exist.
WMDM_E_USER_CANCELLED | The user cancelled the operation.

A service provider should refrain from returning generic failure codes, for example, E_FAIL. It should return as specific an error code as possible, so that if the error is propagated to an application, the application can give meaningful feedback to the user.

For errors in storage and device related operations, service providers should resort to Win32 error codes. Service providers can use HRESULT_FROM_WIN32 to convert Windows error codes to HRESULT values and use them as the return values. This macro and the error codes are defined in winerror.h which is a part of the Platform SDK.

MTP Error Codes

Devices that supports Media Transport Protocol (MTP) can return the following error codes. Most of the error codes imply an error in the MTP stack, but are helpful in diagnosing the error situation.

HRESULT | MTP response code | MTP response code description | Details
0x80042003 | 0x2003 | Session Not Open | Indicates that the session handle of the operation is not a currently open session. This indicates an internal error in the MTP stack.
0x80042004 | 0x2004 | Invalid TransactionID | Indicates that the TransactionID is zero or does not refer to a valid transaction. This indicates an internal error in the MTP stack.
0x80042005 | 0x2005 | Operation Not Supported | Indicates that the operation code appears to be a valid code, but the device does not support the operation. This indicates an internal error in the MTP stack.
0x80042006 | 0x2006 | Parameter Not Supported | Indicates that a non-zero parameter was specified in conjunction with the operation, and the parameter is not used for that operation. This indicates an internal error in the MTP stack.
0x80042007 | 0x2007 | Incomplete Transfer | Indicates that the transfer did not complete, and any data transferred should be discarded. This response does not correspond to a cancelled transaction.
0x80042008 | 0x2008 | Invalid StorageID | Indicates that a storage ID sent with an operation does not refer to an actual valid store that is present on the device. This indicates an internal error in the MTP stack.
0x80042009 | 0x2009 | Invalid ObjectHandle | Indicates that an object handle does not refer to an actual object that is present on the device. The application should enumerate the storages again.
0x8004200A | 0x200A | DeviceProp Not Supported | Indicates that the device property code appears to be a valid code, but that property is not supported by the device. This indicates an internal error in the MTP stack.
0x8004200B | 0x200B | Invalid ObjectFormatCode | Indicates that the device does not support the particular object format code supplied in the given context.
0x80042012 | 0x2012 | Partial Deletion | Indicates that only a subset of the storages indicated for deletion were actually deleted, because some were write-protected or were on stores that are read-only.
0x80042013 | 0x2013 | Store Not Available | Indicates that the store (or the store that contains the indicated object) is not physically available. This can be caused by media ejection. This response shall not be used to indicate that the store is busy.
0x80042014 | 0x2014 | Specification By Format Unsupported | Indicates that the operation attempted to specify action only on objects of a particular format, and that capability is not supported. The operation should be attempted again without specifying by format. Any response of this nature infers that any future attempt to specify by format with the indicated operation will result in the same response. This indicates an internal error in the MTP stack.
0x80042015 | 0x2015 | No Valid ObjectInfo | Indicates that the host did not provide valid object info to device before transferring the object. This indicates an internal error in the MTP stack.
0x80042016 | 0x2016 | Invalid Code Format | Indicates that the data code does not have the correct format, and is therefore not valid. This indicates an internal error in the MTP stack.
0x80042017 | 0x2017 | Unknown Vendor Code | Device does not know how to handle the vendor extended code.
0x8004201A | 0x201A | Invalid ParentObject | Indicates that the object is not a valid parent object. This indicates an internal error in the MTP stack.
0x8004201B | 0x201B | Invalid DeviceProp Format | Indicates that an attempt was made to set a device property, but the data is not of the correct size or format. This indicates an internal error in the MTP stack.
0x8004201C | 0x201C | Invalid DeviceProp Value | Indicates that an attempt was made to set a device property to a value that is not allowed by the device. This indicates an internal error in the MTP stack.
0x8004201E | 0x201E | Session Already Open | Indicates that the host tried to open session while a session is already open. This indicates an internal error in the MTP stack.
0x8004201F | 0x201F | Transaction Cancelled | May be used to indicate that the operation was interrupted due to manual cancellation.
0x80042020 | 0x2020 | Specification of Destination Unsupported | Indicates that device does not support the specification of destination by the host. This indicates an internal error in the MTP stack.
0x8004A801 | 0xA801 | Invalid_ObjectPropCode | Indicates that the device does not support the sent Object Property Code in this context. This indicates an internal error in the MTP stack.
0x8004A802 | 0xA802 | Invalid_ObjectProp_Format | Indicates that an object property sent to the device is in an unsupported size or type. This indicates an internal error in the MTP stack.
0x8004A803 | 0xA803 | Invalid_ObjectProp_Value | Indicates that an object property sent to the device is the correct type, but contains a value that is not supported. This indicates an internal error in the MTP stack.
0x8004A804 | 0xA804 | Invalid_ObjectReference | Indicates that a sent Object Reference is not valid. Either the reference contains an object handle not present on the device, or the reference attempting to be set is unsupported in context. This can be due to an error in the MTP stack or due to application using a stale storage object.
0x8004A806 | 0xA806 | Invalid_Dataset | Indicates that the dataset sent in the data phase of this operation is invalid. This indicates an internal error in the MTP stack.
0x8004A807 | 0xA807 | Object_Too_Large | Indicates that the object desired to be sent cannot be stored in the file system of the device. This shall not be returned when there is insufficient space on the storage.

Windows Media DRM for Portable Devices Porting Kit errors

The following error codes are defined in the Windows Media DRM for Portable Devices Porting Kit, and may be returned by methods that call a device built on this porting kit. These error codes are related to DRM issues.

Return Code | Description | Hexadecimal value
DRM_FAILED(Status) | The operation failed. | (Status)<0
DRM_SUCCEEDED(Status) | The operation completed successfully. | (Status) >= 0
DRM_SUCCESS | The operation completed successfully. | 0x00000000L
DRM_S_FALSE | The method succeeded and returned the Boolean value FALSE. | 0x00000001L
DRM_E_FAIL | An unspecified failure has occurred. | 0x80004005L
DRM_E_INVALIDARG | A parameter is not valid or is a NULL pointer. | 0x80070057L
DRM_E_OUTOFMEMORY | The method failed to allocate the necessary memory. | 0x80000002L
DRM_E_FILENOTFOUND | The system cannot find the file specified. | 0x80030002L
DRM_E_BUFFERTOOSMALL | A buffer is too small for the data. | 0x8007007AL
DRM_E_NOTIMPL | Not implemented. | 0x80004001L
DRM_E_NOMORE | The end of the enumeration, or no more data available. | 0x80070103L
DRM_E_ARITHMETIC_OVERFLOW | An arithmetic operation resulted in overflow (loss of important bits). | 0x8007534L
DRM_E_ALGORITHMNOTSET | The encryption algorithm required for this operation is not supported. | 0x8004c017
DRM_E_APPCERT_REVOKED | The application certificate given to DRM is revoked. | 0X8004C053
DRM_E_BACKUP_EXISTS | The backup file already exists. | 0x8004c032
DRM_E_CH_ATTR_MISSING | A content header attribute is missing. | 0x80041107L
DRM_E_CH_BAD_KEY | A key is not valid. | 0x8004110EL
DRM_E_CH_CHECKSUM_MISSING | The content header checksum is missing. | 0x80041106L
DRM_E_CH_INVALID_HEADER | The content header is not valid. | 0x80041108L
DRM_E_CH_KID_MISSING | The KID attribute is missing from the content header. | 0x80041104L
DRM_E_CH_LAINFO_MISSING | The LAINFO attribute is mising from the content header. | 0x80041105L
DRM_E_CH_NOT_SIGNED | The header was not signed. | 0x80041113L
DRM_E_CH_UNABLE_TO_VERIFY | The signature of the content header cannot be verified. | 0x8004110AL
DRM_E_CH_UNKNOWN_ERROR | An unknown error occurred. | 0x80041116L
DRM_E_CH_UNSUPPORTED_HASH_ALGORITHM | The hash algorithm is not supported. | 0x8004110CL
DRM_E_CH_UNSUPPORTED_SIGN_ALGORITHM | The signature algorithm is not supported. | 0x8004110DL
DRM_E_CH_UNSUPPORTED_VERSION | The content header version is not supported. | 0x8004110BL
DRM_E_CH_VERSION_MISSING | The content header version is missing. | 0x80041103L
DRM_E_CIPHER_NOTINITIALIZED | The DRM Cipher routines were not correctly initialized before calling the encryption/decryption routines. | 0x800480D2L
DRM_E_CLIENTTIMEINVALID | The time/clock on the device is not synchronized with the license server within tolerance. | 0x8004c01c
DRM_E_CLK_INVALID_DATE | The secure clock response is not valid. | 0x8004c040
DRM_E_CLK_INVALID_RESPONSE | The secure clock response is not valid. | 0x8004c03f
DRM_E_CLK_NOT_SET | A license may exist but cannot be used because the secure clock is not set. | 0x8004C05B
DRM_E_CLK_NOT_SUPPORTED | The secure clock is not supported. | 0x8004c04a
DRM_E_CLK_RESETSTATEREADERROR | The secure clock Reset State cannot be read. | 0x8004c04d
DRM_E_CLK_RESETSTATEWRITEERROR | The secure clock Reset State cannot be written. | 0x8004c04e
DRM_E_CLK_UNSUPPORTED_VALUE | The secure clock response contains an unsupported value. | 0x8004c041
DRM_E_CONDITIONFAIL | A condition in the license failed to pass. | 0x8004c007
DRM_E_CONDITIONNOTSUPPORTED | A condition in the license is not supported by this version of DRM. | 0x8004c008
DRM_E_CRYPTO_FAILED | A cryptographic operation failed. | 0X8004C054
DRM_E_DECRYPT_NOTINITIALIZED | The DRM decryption routines were not correctly initialized before trying to decrypt data. | 0x800480D3L
DRM_E_DEVCERTEXCEEDSSIZELIMIT | The device certificate exceeds the maximum size. | 0x8004c043
DRM_E_DEVCERTINDIV_NOT_SUPPORTED | Device certificate individualization is not supported. | 0x8004c04b
DRM_E_DEVCERTREADERROR | The device certificate cannot be read. | 0x8004c045
DRM_E_DEVCERTTEMPLATEEXCEEDSSIZELIMIT | The device certificate template exceeds the maximum size. | 0x8004c044
DRM_E_DEVCERTTEMPLATEREADERROR | The device certificate template cannot be read. | 0x8004c049
DRM_E_DEVCERTWRITEERROR | The device certificate cannot be stored. | 0x8004c046
DRM_E_DEVICENOTINIT | This device has not been initialized against a DRM initialization service. | 0x8004c001
DRM_E_DRMNOTINIT | The application did not call DRM_MGR_Initialize properly. | 0x8004c002
DRM_E_DUPLICATEDHEADERATTRIBUTE | The header contains a duplicate attribute. | 0x8004c02d
DRM_E_FILEREADERROR | There was an error reading a file. | 0x8004c01a
DRM_E_FILESEEKERROR | There was an error seeking in a file. | 0x8004c037
DRM_E_FILEWRITEERROR | There was an error writing a file. | 0x8004c01b
DRM_E_HASHMISMATCH | A keyed hash check failed. | 0x8004c010
DRM_E_HDSBLOCKMISMATCH | The Checksum attribute is missing from the header. | 0x8004c031
DRM_E_HDSEXCLUSIVELOCKONLY | Only exclusive lock is accepted. | 0x8004c039
DRM_E_HDSFILECORRUPTED | The HDS file is corrupted. | 0x8004c026
DRM_E_HDSFILEEXISTS | The HDS file already exists. | 0x8004c034
DRM_E_HDSLOCKFAILED | Locking a segment of the HDS file failed. | 0x8004c036
DRM_E_HDSNAMESPACEFULL | The HDS namespace is full. | 0x8004c022
DRM_E_HDSNAMESPACEINUSE | No HDS namespace in is in use. | 0x8004c028
DRM_E_HDSNAMESPACENOTFOUND | No HDS namespace can be found. | 0x8004c023
DRM_E_HDSNOTLOCKEDEXCLUSIVE | The existing lock is not exclusive. | 0x8004c038
DRM_E_HDSRESERVEDKEYDETECTED | An HDS reserved key value was detected in UniqueKey. | 0x8004c03A
DRM_E_HDSSEEKERROR | There was an error attempting to seek in the HDS file. | 0x8004c027
DRM_E_HDSSLOTEXIST | No HDS dataslot exists. | 0x8004c025
DRM_E_HDSSLOTNOTFOUND | The HDS dataslot cannot be found. | 0x8004c024
DRM_E_HDSSTOREFULL | The HDS data file is full. | 0x8004c01d
DRM_E_HEADER_NOT_SET | A V2 content header is not set | 0x8004c03C
DRM_E_INCOMPATABLELICENSESIZE | The size of the license is incompatible. DRM does not understand this license. | 0x8004c004
DRM_E_INVALID_SECURESTORE_PASSWORD | The password used to open the secure store key was not able to validate the secure store hash. | 0x8004c029
DRM_E_INVALID_SIGNATURE | The license signature is not valid. | 0x800480CFL
DRM_E_INVALIDBINDID | The bind ID is not valid. | 0x8004c015
DRM_E_INVALIDDEVICECERTIFICATE | The device certificate is not valid. | 0x8004c035
DRM_E_INVALIDDEVICECERTIFICATETEMPLATE | The device certificate is not valid. | 0x8004c042
DRM_E_INVALIDLICENSE | The license is not valid. | 0x8004c006
DRM_E_INVALIDLICENSEFLAGS | The flags in the license are not valid. DRM does not understand them or they are conflicting. | 0x8004c005
DRM_E_INVALIDLICENSESTORE | The license store version number is incorrect, or in some other way the store is not valid. | 0x8004c019
DRM_E_INVALIDRIGHT | A right in the license in not valid. | 0x8004c003
DRM_E_INVALIDTIME | A time structure is not valid. | 0x8004c011
DRM_E_INVALIDXMLTAG | An XML tag is not valid. | 0x8004c020
DRM_E_KEY_MISMATCH | A public-private key pair is mismatched. | 0x80048013L
DRM_E_LIC_KEY_AND_CERT_MISMATCH | A key and a certificate are mismatched. | 0x80048013L
DRM_E_LIC_KEY_DECODE_FAILURE | A key cannot be decoded. | 0x80048007L
DRM_E_LIC_SIGNATURE_FAILURE | The license signature is not valid. | 0x80048008L
DRM_E_LICENSE_TOOLONG | The license size is too long. | 0x8004c032
DRM_E_LICENSEEXPIRED | The license has expired either by depleting a play count or reaching an end date. | 0x8004c009
DRM_E_LICENSEMISMATCH | The license content ID or SDK ID does not match that requested by the application. | 0x8004c00c
DRM_E_LICENSENOTBOUND | A license has not been bound to. Decryption cannot happen without a successful bind call. | 0x8004c00f
DRM_E_LICENSENOTFOUND | A license was not found in the external license store. | 0x8004c013
DRM_E_LICENSENOTYETVALID | The current time is prior to the license start time, so the license is not yet valid. | 0x8004c00a
DRM_E_LICENSESERVERNEEDSKEY | The license server needs a version of the device bind key from the initialization service. | 0x8004c018
DRM_E_LICENSESTORENOTFOUND | The external license store was not found. | 0x8004c012
DRM_E_LICENSEVERSIONNOTSUPPORTED | The DRM license version is not supported by the DRM version on the device. | 0x8004c014
DRM_E_LOGICERR | The DRM code has a logic error in it. This result should never be returned. There is an unhandled code path if it is returned | 0x8004c3e8
DRM_E_LRB_INVALIDLICENSEDATA | The license revocation response is signed with a public key different from the license server's public key. | 0x8004c073
DRM_E_LRB_INVALIDSIGNATURE | The signature in the license revocation response is not valid. | 0x8004c071
DRM_E_LRB_LGPUBKEY_MISMATCH | The license revocation response is signed with a public key different from the license server's public key. | 0x8004c072
DRM_E_LRB_NOLGPUBKEY | The license revocation response does not contain a valid license server public key. | 0x8004c070
DRM_E_MACHINEIDMISMATCH | The device has a machine ID different from that in the device certificate. | 0x8004c03e
DRM_E_METERING_INVALID_COMMAND | An invalid command was sent when processing the metering response. | 0X8004C051
DRM_E_METERING_MID_MISMATCH | The metering ID is not the same in the metering certificate and the metering response data. | 0X8004C05F
DRM_E_METERING_NOT_SUPPORTED | Metering is not supported. | 0x8004c04c
DRM_E_METERING_RESPONSE_DECRYPT_FAILED | The encrypted section of the metering response cannot be decrypted | 0X8004C060
DRM_E_METERING_STORE_CORRUPT | The metering store is corrupted. | 0X8004C052
DRM_E_METERING_WRONG_TID | The metering response contains the wrong transaction ID. | 0X8004C050
DRM_E_NEEDDEVCERTINDIV | The device certificate is a template. It needs to be individualized. | 0x8004c03d
DRM_E_NO_CLK_SUPPORTED | This device does not support any clock. So time-bound licenses cannot be played. | 0x8004C05C
DRM_E_NO_URL | The URL information cannot be found. | 0x8004C05D
DRM_E_NOACTIONINLICENSEREQUEST | The license request does not contain any actions. | 0x8004c02c
DRM_E_NOCHECKSUMINHEADER | The checksum attribute is missing from the header. | 0x8004c030
DRM_E_NOKIDINHEADER | The key ID attribute is missing from the header. | 0x8004c02e
DRM_E_NOLAINFOINHEADER | The LAINFO attribute is missing from the header. | 0x8004c02f
DRM_E_NORIGHTSREQUESTED | The application did not request any rights before trying to bind. | 0x8004c00e
DRM_E_NOXMLCDATA | No XML CDATA can be found. | 0x8004c021
DRM_E_NOXMLCLOSETAG | An XML close tag cannot be found. | 0x8004c01f
DRM_E_NOXMLOPENTAG | An XML open tag cannot be found. | 0x8004c01e
DRM_E_PKCRYPTO_FAILURE | An error occurred in an asymmetric cryptographic operation. | 0x800480D5L
DRM_E_POLICY_METERING_DISABLED | Metering code was called but metering is disabled by group or user policy. | 0x8004C059
DRM_E_POLICY_ONLINE_DISABLED | Online communication is disabled by group policy. | 0x8004C05A
DRM_E_PRIVKEYREADERROR | The private key for the device cannot be read. | 0x8004c047
DRM_E_PRIVKEYWRITEERROR | The private key for the device cannot be stored. | 0x8004c048
DRM_E_RIGHTSNOTAVAILABLE | The rights requested by the application are not available in the license. | 0x8004c00b
DRM_E_SECURESTORE_CORRUPT | The secure store is corrupted. | 0x8004c02a
DRM_E_SECURESTORE_FULL | The current secure store key is full. No more data can be added. | 0x8004c02b
DRM_E_SECURESTORE_LOCKNOTOBTAINED | Before reading or writing data to the secure store in raw mode, the lock must be obtained by using DRM_SST_OpenData. | 0x800480D4L
DRM_E_STACK_CORRUPT | The stack allocator context is corrupted. This is usually caused by a buffer overrun. | 0X8004C055
DRM_E_STACKTOOSMALL | The stack supplied to the DRM API was too small. | 0x800480D1L
DRM_E_SYNC_ENTRYNOTFOUND | The entry cannot be found in the synchronization store. | 0x800480D0L
DRM_E_UNKNOWN_BINDING_KEY | A matching binding key cannot be found for the license. | 0x8004C056
DRM_E_UNKNOWN_PROPERTY | A device property is unknown. | 0x8004C05E
DRM_E_UNSUPPORTEDALGORITHM | The encryption algorithm required for this operation is not supported. | 0x8004c016
DRM_E_V1_LICENSE_CHAIN_NOT_SUPPORTED | License chaining with V1 content is not supported. | 0x8004C057
DRM_E_V1_NOT_SUPPORTED | V1 license acquisition is not supported. | 0x8004c03B
DRM_E_WRONG_TOKEN_TYPE | The wrong type of token was used. | 0x8004C058
DRM_E_WRONGTOKENTYPE | The token parameter is of an incompatible type. | 0x8004c00d
DRM_E_XMLNOTFOUND | A required XML tag cannot be found. | 0X8004C04F
NS_E_DRM_DEBUGGING_NOT_ALLOWED | A command cannot be run with a debugger attached. | 0xC00D2767
 | The DRM security elements must be updated. The user can go to the Windows Media Individualization Page to update their computer. | 0x800480CF
 | The DRM security elements must be updated. The user can go to the Windows Media Individualization Page to update their computer. | 0x80049006

Windows Media Rights Manager SDK errors

Occasionally, you might encounter an error defined in the Windows Media Rights Manager SDK. A list of errors defined by that SDK is given in the MSDN library. However, the following Windows Media Rights Manager SDK errors were not documented.

Return code | Description | Hexadecimal value
NS_E_DRM_DEBUGGING_NOT_ALLOWED | You cannot debug when accessing DRM-protected content. | 0xC00D2767
NS_E_NOT_LICENSED | The content is not licensed. | 0xC00D00CD
NS_E_DRM_LICENSE_UNUSABLE | The license is unusable for an unspecified reason. | 0xC00D2748

See Also

  • Programming Reference


Glossary

To find a term in the glossary, click the letter of the alphabet that is the first letter in the term you want to look up.

You can also read glossary terms within the text of Help by clicking the underlined glossary term links. After you click a glossary link, the glossary term and definition appear in a pop-up window. To close the window, click anywhere on the screen.

A | B | C | D | E | F | G | H | I | J | K | L | M
N | O | P | Q | R | S | T | U | V | W | X | Y | Z

A

Active Template Library (ATL)

A collection of template classes for Microsoft Visual C++. It is used to create COM servers when writing a service provider for Windows Media Device Manager.

ATL

See definition for: Active Template Library (ATL)

authentication

The process of verifying that an entity or object is who or what it claims to be. For example, a username and password may be used to authenticate a user.

See Also:

authorization

authorization

The process of granting access to protected resources.

See Also:

authentication

Back to Top

B

bit rate

The number of bits transferred per unit of time, typically expressed in bits per second.

buffer

An area of memory reserved for temporarily holding data before that data is used by a receiving device or application. Buffering protects against the interruption of data flow.

Back to Top

C

challenge

A request for a license. A challenge contains information about the consumer's computer, a list of requested rights, and other information about the content, including the content header and key ID. This challenge can also contain a version 1 challenge in case a version 1 license is needed.

clear content

A Windows Media file that is not encrypted.

client

Any computer or program connecting to, or requesting the services of, another computer or program. Client can also refer to the software that enables the computer or program to establish the connection.

content

Audio, video, images, text, or any other information that is contained in a digital media file or stream.

See Also:

Windows Media file

Back to Top

D

decrypt

To convert encrypted content back into its original form.

See Also:

encrypt

digital rights management (DRM)

A technology that provides a persistent level of protection to digital content by encrypting it with a cryptographic key. Authorized recipients (or end users) must acquire a license in order to unlock and consume the content.

DRM

See definition for: digital rights management (DRM)

Back to Top

E

encrypt

To programmatically disguise content to hide its substance.

See Also:

decrypt

Back to Top

K

key

A piece of data that is required to unlock a packaged Windows Media file. This key is included in a separate license.

Back to Top

L

license

Data attached to protected content that describes how the content can be used.

Back to Top

M

Microsoft Secure Content Provider (SCP)

A plug-in for Windows Media Device Manager that provides digital rights management (DRM) services.

Microsoft Windows Media Player

A client/control that receives a stream from a Windows Media server or local content for playback. It either can run as a stand-alone client executable program or be embedded in a Web page, C++ program, or a Microsoft Visual Basic program that uses the client ActiveX control.

Back to Top

O

object

A collection of properties and methods that serve a particular purpose and are treated as a unit.

Back to Top

P

player

A client program or control that receives digital media content streamed from a server or played from local files. Windows Media Player is an example of a player.

plug-in

An auxiliary software component that extends or enhances the features of other software.

portable device

A mobile electronic device that can exchange files or other data with a computer or device. Examples of portable devices include Pocket PCs, portable digital music players, and Smartphones.

portable media identifier

A unique identifier for removable storage media such as CompactFlash cards. The identifier is hard coded into the storage media and is not changeable.

protect

To encrypt files with a key and add information such as the license acquisition URL.

Back to Top

S

SDMI

See definition for: Secure Digital Music Initiative (SDMI)

Secure Digital Music Initiative (SDMI)

An organization that sets standards for secure digital music. One of the main goals of SDMI is to create a framework for the secure playing, storing, and distribution of digital music.

Back to Top

W

Windows Media Encoder

A technology that compresses live or prerecorded audio and video into a Windows Media stream, which can either be distributed immediately or saved as a Windows Media file for later distribution.

Windows Media file

A file that contains audio, video, or script data. The content of the file is encoded with one of the Windows Media codecs.

Windows Media Format

The format of a digital media file or stream that was encoded with Windows Media codecs.

Windows Media Services

A service that is used to stream digital audio and video over the Internet or an intranet.

Back to Top

Previous


Legal Notice

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2006 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, Windows Server, Windows Vista, Active Directory, ActiveSync, ActiveX, Direct3D, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, Expression, FrontPage, HighMAT, Internet Explorer, JScript, Microsoft Press, MSN, Outlook, PlaysForSure logo, PowerPoint, SideShow, Visual Basic, Visual C++, Visual InterDev, Visual J++, Visual Studio, WebTV, Windows Media, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

This product contains graphics filter software; this software is based in part on the work of the Independent JPEG Group.

All other trademarks are property of their respective owners.

Some of the links in this document might let you leave Microsoft's site. The linked sites are not under the control of Microsoft and Microsoft is not responsible for the contents of any linked site or any link contained in a linked site, or any changes or updates to such sites. Microsoft is not responsible for webcasting or any other form of transmission received from any linked site. Microsoft is providing these links to you only as a convenience, and the inclusion of any link does not imply endorsement by Microsoft of the site.