IWMDMStorageControl::Insert
.gif) |
The Insert method inserts content onto a storage medium.
Syntax
HRESULT Insert(
UINT fuMode,
LPWSTR pwszFile,
IWMDMOperation* pOperation,
IWMDMProgress* pProgress,
IWMDMStorage** ppNewObject
);
Parameters
fuMode
[in] Processing mode used for the Insert 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 current object. |
| WMDM_STORAGECONTROL_INSERTAFTER | The object will be inserted after the current object. |
| WMDM_STORAGECONTROL_INSERTINTO | The object will be inserted into the current object. This is applicable only if the current object is a folder. |
| WMDM_FILE_CREATE_OVERWRITE | The object will replace the current object. |
| WMDM_CONTENT_FILE | The content being inserted is a file. |
| WMDM_CONTENT_FOLDER | The content being inserted is a 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. |
| 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. |
pwszFile
[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.
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.
ppNewObject
[out] Pointer to an IWMDMStorage interface that will contain the new content. This parameter cannot be 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.
The Insert method does not necessarily imply any particular ordering of the contents, although if the file system supports ordering, the Insert method provides that capability by means of the flags WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERTAFTER. If the file system does not support ordering (for instance, FAT32), WMDM_STORAGECONTROL_INSERTBEFORE and WMDM_STORAGECONTROL_INSERTAFTER will behave identically to each other and will insert the new storage object at the same level as the current object in the file system hierarchy. WMDM_STORAGECONTROL_INSERTINTO can be specified only if the current storage is a folder, and in that case the new storage object will become nested in the current storage.
While using WMDM_MODE_THREAD, applications must make sure that 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 End notification. Failure to do this will result in access violations.
Requirements
Header: Defined in wmdm.idl.
Library: mssachlp.lib
See Also