Share via

IWMDMStorageControl2::Insert2

  • Article
banner art

The Insert2 method inserts content into a storage medium. The difference between IWMDMStorageControl::Insert and IWMDMStorageControl2::Insert2 is that the Insert2 method also enables you to set the name of the destination file. Using this method, an application can pass an Iunknown interface of any custom COM object to the secure content provider. This makes it possible to pass custom information from an application to a secure content provider if the application has sufficient information about the secure content provider.

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.

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_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.

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.

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.

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 End notification. Failure to do this will result in access violations.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also