IWMDMStorageControl3::Insert3
.gif) |
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.
| 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. |
| WMDM_MODE_QUERY | A test will be performed to determine whether the insert operation could succeed, but the insert will not be performed. |
| WMDM_STORAGECONTROL_INSERTBEFORE | The object will be inserted before the target object. |
| WMDM_STORAGECONTROL_INSERTAFTER | The object will be inserted after the target object. |
| WMDM_FILE_CREATE_OVERWRITE | The object will replace the target object. |
| WMDM_CONTENT_FILE | The content being inserted is a file. |
| WMDM_CONTENT_FOLDER | The content being inserted is a folder. |
| 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. |
| 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. |
| WMDM_MODE_PROGRESS | The insertion is in progress. |
| WMDM_MODE_TRANSFER_PROTECTED | The insertion is in protected transfer mode. |
| WMDM_MODE_TRANSFER_UNPROTECTED | The insertion is in unprotected transfer mode. |
fuType
[in] Specifies the storage type and can have the following values.
| Value | Description |
| WMDM_FILE_ATTR_FILE | This is a file on the storage medium. |
| WMDM_FILE_ATTR_FOLDER | This is a folder on the storage medium. |
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.
| 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
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