Метод IWMDMStorageControl3::Insert3 (mswmdm.h)

Статья
03/15/2023

Метод Insert3 помещает содержимое в хранилище или рядом с ним. Этот метод расширяет возможности IWMDMStorageControl2::Insert2 , позволяя приложению явно указывать метаданные и тип отправляемого объекта.

Синтаксис

HRESULT Insert3(
  [in]  UINT           fuMode,
  [in]  UINT           fuType,
  [in]  LPWSTR         pwszFileSource,
  [in]  LPWSTR         pwszFileDest,
  [in]  IWMDMOperation *pOperation,
  [in]  IWMDMProgress  *pProgress,
  [in]  IWMDMMetaData  *pMetaData,
  [in]  IUnknown       *pUnknown,
  [out] IWMDMStorage   **ppNewObject
);

Параметры

[in] fuMode

Режим обработки, используемый для операции Insert3 . В следующей таблице перечислены режимы обработки, которые можно указать в параметре fuMode . Необходимо указать только один из первых двух режимов, ровно один из режимов STORAGECONTROL и ровно один из режимов CONTENT. Если указаны как WMDM_MODE_BLOCK, так и WMDM_MODE_THREAD, используется блочный режим. Указание флагов WMDM_FILE_ATTR* в этой функции эффективнее, чем первый вызов этой функции, а затем установка этих атрибутов в файле после его создания или отправки.

Комбинации	Режим	Описание
Точно один из следующих вариантов:	WMDM_MODE_BLOCK	Операция выполняется с помощью обработки в блочном режиме. Вызов не будет возвращать, пока операция не будет завершена.
-	WMDM_MODE_THREAD	Операция выполняется с помощью обработки в режиме потока. Вызов возвращается немедленно, и операция выполняется в фоновом потоке.
Необязательно	WMDM_MODE_QUERY	Выполняется проверка, чтобы определить, может ли операция вставки быть успешной, но вставка не будет выполнена.
Точно один из следующих вариантов:	WMDM_STORAGECONTROL_INSERTBEFORE	Объект вставляется перед целевым объектом.
-	WMDM_STORAGECONTROL_INSERTAFTER	Объект вставляется после целевого объекта.
-	WMDM_STORAGECONTROL_INSERTINTO	Объект вставляется в текущий объект . Это будет работать, только если текущий объект является папкой.
Необязательно	WMDM_FILE_CREATE_OVERWRITE	Объект заменит целевой объект.
Точно один из следующих вариантов:	WMDM_CONTENT_FILE	Вставляемое содержимое является файлом.
-	WMDM_CONTENT_FOLDER	Вставляемое содержимое является папкой. Это не приведет к переносу содержимого папки.
Необязательно	WMDM_CONTENT_OPERATIONINTERFACE	Приложение передает интерфейс IWMDMOperation для управления передачей данных.
Ноль или более из:	WMDM_FILE_ATTR_READONLY	На устройстве хранилище должно быть доступно только для чтения.
-	WMDM_FILE_ATTR_HIDDEN	Хранилище должно быть скрыто на устройстве.
-	WMDM_FILE_ATTR_SYSTEM	Для хранилища должно быть задано значение System на устройстве.
Необязательно	WMDM_MODE_PROGRESS	Выполняется вставка.
Необязательный один из следующих вариантов:	WMDM_MODE_TRANSFER_PROTECTED	Вставка находится в защищенном режиме передачи.
-	WMDM_MODE_TRANSFER_UNPROTECTED	Вставка находится в незащищенном режиме передачи.

[in] fuType

Один из следующих типов, указывающий текущее хранилище.

Значение	Описание
WMDM_FILE_ATTR_FILE	Текущим хранилищем является файл.
WMDM_FILE_ATTR_FOLDER	Текущим хранилищем является папка.

[in] pwszFileSource

Указатель на строку с расширенными символами, заканчивающуюся null, указывающую, где найти содержимое для операции вставки. Этот параметр должен иметь значение NULL, если WMDM_CONTENT_OPERATIONINTERFACE указан в fuMode. Этот параметр может иметь значение NULL , если создается список воспроизведения или альбом.

[in] pwszFileDest

Необязательное имя файла на устройстве. Если не указано и приложение передает указатель IWMDMOperation на pOperation, диспетчер устройств Windows Media запросит имя назначения, вызвав IWMDMOperation::GetObjectName. Если не указано и приложение не использует pOperation, используются исходное имя файла и расширение (без пути).

[in] pOperation

Необязательный указатель на интерфейс IWMDMOperation для управления передачей содержимого на устройство мультимедиа. Если этот параметр задан, параметр fuMode должен содержать флаг WMDM_CONTENT_OPERATIONINTERFACE. Этот параметр должен иметь значение NULL, если в fuMode указано WMDM_CONTENT_FILE или WMDM_CONTENT_FOLDER.

[in] pProgress

Необязательный указатель на интерфейс IWMDMProgress для передачи отчета о ходе выполнения действия в приложение. Этот параметр может принимать значение NULL.

[in] pMetaData

Необязательный указатель на объект метаданных. Создайте новый объект метаданных, вызвав IWMDMStorage3::CreateEmptyMetadataObject. Этот параметр позволяет приложению указывать метаданные (включая формат), заданные на устройстве во время создания объекта на устройстве, что является более эффективным, чем настройка метаданных после этого. Необходимо задать формат файла (заданный g_wszWMDMFormatCode). Если не указать код формата файла при использовании этого метода, устройство MTP не будет отображать файл в пользовательском интерфейсе, а устройства, отличные от MTP, будут вести себя непредсказуемо.

[in] pUnknown

Необязательный указатель IUnknown любого пользовательского COM-объекта, передаваемого поставщику защищенного содержимого. Это позволяет передавать пользовательские сведения поставщику защищенного содержимого, если приложение располагает достаточными сведениями о поставщике защищенного содержимого.

[out] ppNewObject

Указатель на интерфейс IWMDMStorage , который будет содержать новое содержимое. Вызывающий объект должен освободить этот интерфейс после завершения работы с ним.

Возвращаемое значение

Метод возвращает HRESULT. Все методы интерфейса в Windows Media диспетчер устройств могут возвращать любой из следующих классов кодов ошибок:

Стандартные коды ошибок COM
Коды ошибок Windows, преобразованные в значения HRESULT
Коды ошибок диспетчер устройств Windows Media

Подробный список возможных кодов ошибок см. в разделе Коды ошибок.

Хотя метаданные в хранилище можно задать после их отправки на устройство, эффективнее задать эти сведения в параметре pMetaData этого метода. Это позволяет устройству передавать и обрабатывать файл соответствующим образом (например, сохраняя его в нужном месте) или отображать полезную информацию (например, написанное пользователем описание рисунка).

Чтобы задать свойства для устройства Windows Portable Devices (WPD), приложение создаст объект IPortableDeviceValues и зададит каждое свойство в этой коллекции. Затем приложение сериализует коллекцию в большой двоичный объект (BLOB). После сериализации данных приложение добавит их в IWMDMMetaData , на который ссылается аргумент pMetadata , с помощью константы метаданных g_wszWPDPassthroughPropertyValues.

Если указан флаг WMDM_MODE_THREAD, необходимо получить состояние завершения, вызвав IWMDMProgress2::End2 или IWMDMProgress3::End3. Эти методы гарантируют, что операция завершена, а также возвращают HRESULT с информацией об успешном или неудачном выполнении.

Если приложение использует WMDM_MODE_THREAD и передает параметр pProgress, отличный от NULL, приложение должно убедиться, что объект, которому принадлежит pProgress, не будет уничтожен до завершения операции чтения, так как windows Media диспетчер устройств будет отправлять уведомления о ходе выполнения в этот объект. Этот объект можно уничтожить только после получения уведомления об окончании. В противном случае это приведет к нарушениям доступа.

При создании списка воспроизведения или другого ссылочного объекта объект, который "вставляется", фактически не содержит данных, но просто хранится на устройстве в виде группы метаданных, ссылающихся на другие объекты (например, музыкальные файлы). Создание такого "абстрактного" объекта в списке воспроизведения описано в разделе Создание списка воспроизведения на устройстве.

Примеры

Следующая функция C++ отправляет файл на устройство. В рамках передачи необходимо добавить метаданные в хранилище, чтобы указать новый тип хранилища.


HRESULT mySendFile(LPCWSTR pwszFileName, IWMDMStorage* pStorage, IWMDMOperation* pOperation)
{
   HRESULT hr = S_OK;

   // A dummy loop to handle unrecoverable errors. When we hit an error we
   // can't handle or don't like, we just use a 'break' statement.
   // The custom BREAK_HR macro checks for failed HRESULT values and does this.
   do
   {
      if (pwszFileName == NULL || pStorage == NULL)
      {
         BREAK_HR(E_POINTER,"","Bad pointer passed in.");
         return E_POINTER;
      }

      // Make sure the destination is a folder.
      DWORD attributes = 0;
      _WAVEFORMATEX format;
      hr = pStorage->GetAttributes(&attributes, &format);
      if (!(attributes | WMDM_FILE_ATTR_FOLDER))
      {
         BREAK_HR(E_FAIL, "", "Storage submitted to mySendFile is not a folder.");
         return E_FAIL;
      }

      // Transcode the file
      hr = myTranscodeMethod(pwszFileName);
      BREAK_HR(hr, "Couldn't transcode the file in mySendFile.", "Transcoded the file in mySendFile.");
      //
      // Let's set some metadata in the storage.
      //
      CComPtr<IWMDMStorage3> pStorage3;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorage3), (void**)(&pStorage3));
      BREAK_HR(hr, "Got an IWMDMStorage3 interface in mySendFile.","Couldn't get an IWMDMStorage3 in mySendFile.");

      // First create the IWMDMMetaData interface.
      IWMDMMetaData* pMetadata;
      hr = pStorage3->CreateEmptyMetadataObject(&pMetadata);
      BREAK_HR(hr,"Created an IWMDMMetaData interface in mySendFile.","Couldn't create an IWMDMMetaData interface in mySendFile.");

      //
      // Set the file format.
      //
      WMDM_FORMATCODE fileFormat = myGetWMDM_FORMATCODE(pwszFileName);
      hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMFormatCode, (BYTE*)&fileFormat, sizeof(WMDM_TYPE_DWORD));


      //
      // Get the proper interface and transfer the file.
      //
      CComPtr<IWMDMStorageControl3> pStgCtl3;
      CComPtr<IWMDMStorage> pNewStorage;
      hr = pStorage->QueryInterface(__uuidof(IWMDMStorageControl3),(void**)(&pStgCtl3));

      // Get the simple file name to use for the destination file.
      wstring destFile = pwszFileName;
      destFile = destFile.substr(destFile.find_last_of(L"\\") + 1);

      // Get a progress indicator.
      CComQIPtr<IWMDMProgress> pProgress(this);

      // Set the flags for the operation.
      UINT flags = WMDM_MODE_BLOCK | // Synchronous call. 
         WMDM_STORAGECONTROL_INSERTINTO | // Insert it into the destination folder.
         WMDM_CONTENT_FILE | // We're inserting a file.
         WMDM_FILE_CREATE_OVERWRITE; // Overwrite existing files.
      if (pOperation != NULL)
         flags |= WMDM_CONTENT_OPERATIONINTERFACE;

      // Send the file and metadata.
      hr = pStgCtl3->Insert3(
         flags,
         WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
         const_cast<WCHAR*>(pwszFileName), // Source file.
         NULL, // Destination file name.
         pOperation, // Null to allow Windows Media Device Manager to read 
                     // the file; non-null to present raw data bytes to 
                     // Windows Media Device Manager.
         pProgress, // Interface to send simple progress notifications.
         pMetadata, // IWMDMMetaData interface previously created and filled.
         NULL, 
         &pNewStorage);
      if (FAILED(hr))
         m_pLogger->LogDword(WMDM_LOG_SEV_ERROR, NULL, "Error calling Insert3 in mySendFile: %lX", hr);
      BREAK_HR(hr, "Wrote a file to the device in mySendFile", "Couldn't write to the device in mySendFile.");

   } while (FALSE); // End of dummy loop

   return hr;
}