IWMDMStorageControl：：Insert 方法 (mswmdm.h)

项目
08/25/2023

Insert 方法将内容放入设备上的存储中。

语法

HRESULT Insert(
  [in]  UINT           fuMode,
  [in]  LPWSTR         pwszFile,
  [in]  IWMDMOperation *pOperation,
  [in]  IWMDMProgress  *pProgress,
  [out] IWMDMStorage   **ppNewObject
);

参数

[in] fuMode

以下值的按位 OR 。下表列出了可在 fuMode 参数中指定的处理模式。必须指定前两种模式之一、STORAGECONTROL 模式之一和 CONTENT 模式之一。如果同时指定WMDM_MODE_BLOCK和WMDM_MODE_THREAD，则使用块模式。

组合	“模式”	说明
恰好是以下项之一：	WMDM_MODE_BLOCK	该操作是使用块模式处理执行的。在操作完成之前，调用不会返回。
	WMDM_MODE_THREAD	该操作是使用线程模式处理执行的。调用将立即返回，并且操作在后台线程中执行。
恰好是以下项之一：	WMDM_STORAGECONTROL_INSERTBEFORE	对象插入到当前对象之前。
	WMDM_STORAGECONTROL_INSERTAFTER	对象插入到当前对象之后。
	WMDM_STORAGECONTROL_INSERTINTO	对象插入到当前对象中。仅当当前对象是文件夹时，此操作才起作用。
恰好是以下项之一：	WMDM_CONTENT_FILE	要插入的内容是文件。
	WMDM_CONTENT_FOLDER	要插入的内容是一个文件夹。这不会传输文件夹的内容。
	WMDM_CONTENT_OPERATIONINTERFACE	要插入的内容是一个操作接口。内容的数据应写入应用程序实现的 IWMDMOperation 接口。
零个或多个：	WMDM_FILE_CREATE_OVERWRITE	对象将替换当前对象。
	WMDM_MODE_QUERY	执行测试以确定插入操作是否可以成功，但不会执行插入。
	WMDM_MODE_PROGRESS	方法应通过 pProgress 返回进度通知。
零或以下项之一：	WMDM_MODE_TRANSFER_PROTECTED	插入处于受保护的传输模式。
	WMDM_MODE_TRANSFER_UNPROTECTED	插入处于不受保护的传输模式。

[in] pwszFile

指向以 null 结尾的宽字符字符串的指针，该字符串指示在何处查找插入操作的内容。如果在 fuMode 中指定了WMDM_CONTENT_OPERATIONINTERFACE，此参数必须为 NULL。

[in] pOperation

指向 IWMDMOperation 接口的可选指针，用于控制内容到媒体设备的传输。如果指定， 则 fuMode 必须包含 WMDM_CONTENT_OPERATIONINTERFACE 标志。如果在 fuMode 中指定了WMDM_CONTENT_FILE或WMDM_CONTENT_FOLDER，此参数必须为 NULL。

[in] pProgress

指向 IWMDMProgress 接口的可选指针，Windows Media 设备管理器将进度报告回应用程序。如果使用此功能， 则 fuMode 应包含WMDM_MODE_PROGRESS。

[out] ppNewObject

指向将包含新内容的 IWMDMStorage 接口的指针。调用方在完成此接口后必须释放它。

返回值

该方法返回 HRESULT。 Windows Media 设备管理器中的所有接口方法都可以返回以下任一类错误代码：

标准 COM 错误代码
转换为 HRESULT 值的 Windows 错误代码
Windows Media 设备管理器错误代码

有关可能错误代码的广泛列表，请参阅错误代码。

注解

如果设备支持 IWMDMStorageControl3：：Insert3，则这是要使用的首选方法。

如果 pOperation 为 NULL) ，则保存在设备上的对象的名称和扩展名将与源文件的名称和扩展名相同 (。

如果指定了WMDM_MODE_THREAD标志，则应通过调用 IWMDMProgress2：：End2 或 IWMDMProgress3：：End3 来获取完成状态。这些方法将确保操作完成，并且还会返回包含成功或失败信息的 HRESULT。

Insert 方法不保证设备支持有序文件插入，但它提供标志WMDM_STORAGECONTROL_INSERTBEFORE和WMDM_STORAGECONTROL_INSERTAFTER以防它支持。例如，如果文件系统不支持排序 (，则 FAT32) 、WMDM_STORAGECONTROL_INSERTBEFORE 和 WMDM_STORAGECONTROL_INSERTAFTER 将仅将新的存储对象插入到文件系统层次结构中的当前对象所在的同一级别。

如果应用程序使用 WMDM_MODE_THREAD并传递非 nullpProgress 参数，则应用程序必须确保 pProgress 所属的对象在插入操作完成之前不会被销毁，因为 Windows Media 设备管理器将向此对象发送进度通知。此对象只有在收到结束通知后才能销毁。如果不这样做，将导致访问冲突。