IWMDMStorageControl3::Insert3

The Insert3 method is identical to the IWMDMStorageControl2::Insert2 method, except that the client can pass in an IWMDMMetaData interface pointer.

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.

fuType

[in]  Specifies the storage type and can have the following values.

pwszFileSource

[in]  Pointer to a Unicode, 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]  Name of output file.

pOperation

[in]  Pointer to an IWMDMOperation interface, an optional set of methods used to enhance the transfer of content to a media device. This parameter must be NULL if WMDM_CONTENT_FILE or WMDM_CONTENT_FOLDER is specified in fuMode.

pProgress

[in]  Pointer to an IWMDMProgress interface to be used by Windows Media Device Manager to report progress back to the application. This parameter can be NULL.

pMetaData

[in]  Pointer to a metadata object.

pUnknown

[in]  IUnknown pointer to be passed to the secure content provider.

ppNewObject

[out]  Pointer to an IWMDMStorage interface that will contain the new content. This parameter can be set to NULL.

Return Values

The method returns an HRESULT. All the interface methods in Windows Media Device Manager and service provider 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 a complete list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Remarks

When using WMDM_MODE_THREAD, call IWMDMDevice::GetStatus after each file transfer to check for WMDM_STATUS_READY. This ensures the file operation is finished.

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.

Playlist objects may specify the source file from which data will be copied to the playlist object. However, since playlist objects are not required to contain actual data, this argument is allowed to be NULL. In this case the inserted playlist object will contain only a list of reference objects. See IWMDMStorage4::SetReferences for more information on playlist reference objects. This also applies to album objects.

The client can specify attributes WMDM_FILE_ATTR_READONLY, WMDM_FILE_ATTR_HIDDEN, and WMDM_FILE_ATTR_SYSTEM as a part of fuMode. If the service provider (SP) supports setting them at creation time they will be applied. This can be used to provide better performance. It can also help in situations where the attributes have to be applied at creation time, such as in the case of overwriting a system file. This is currently supported only for MTP, mass storage, and Windows CE-based devices.

To create a playlist or album object, specify one of the following playlist or album format code values for the g_wszWMDMFormatCode property on the pMetaData parameter to this method:

WMDM_FORMATCODE_ABSTRACTAUDIOVIDEOPLAYLIST

WMDM_FORMATCODE_ABSTRACTMULTIMEDIAALBUM    

WMDM_FORMATCODE_ABSTRACTIMAGEALBUM         

WMDM_FORMATCODE_ABSTRACTAUDIOALBUM         

WMDM_FORMATCODE_ABSTRACTVIDEOALBUM         

WMDM_FORMATCODE_ABSTRACTAUDIOVIDEOPLAYLIST 

WMDM_FORMATCODE_ABSTRACTCONTACTGROUP       

WMDM_FORMATCODE_ABSTRACTMESSAGEFOLDER      

WMDM_FORMATCODE_ABSTRACTCHAPTEREDPRODUCTION

WMDM_FORMATCODE_WPLPLAYLIST                

WMDM_FORMATCODE_M3UPLAYLIST                

WMDM_FORMATCODE_MPLPLAYLIST                

WMDM_FORMATCODE_ASXPLAYLIST                

WMDM_FORMATCODE_PLSPLAYLIST                

Before using any one of these format codes, ensure that the device supports it by making a call to IWMDMDevice3::GetProperty for the property g_wszWMDMFormatsSupported.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

• IWMDMDevice::GetStatus
• IWMDMDevice3::GetProperty
• IWMDMMetaData Interface
• IWMDMOperation Interface
• IWMDMProgress Interface
• IWMDMStorage Interface
• IWMDMStorageControl2::Insert2
• IWMDMStorageControl3 Interface