Método IWMDMStorageControl3::Insert3 (mswmdm.h)

Artigo
03/15/2023

O método Insert3 coloca o conteúdo no/ao lado do armazenamento. Esse método estende IWMDMStorageControl2::Insert2 , permitindo que o aplicativo especifique explicitamente os metadados e o tipo do objeto que está sendo enviado.

Sintaxe

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
);

Parâmetros

[in] fuMode

Modo de processamento usado para a operação Insert3 . A tabela a seguir lista os modos de processamento que podem ser especificados no parâmetro fuMode . Você deve especificar exatamente um dos dois primeiros modos, exatamente um dos modos STORAGECONTROL e exatamente um dos modos CONTENT. Se WMDM_MODE_BLOCK e WMDM_MODE_THREAD forem especificados, o modo de bloco será usado. Especificar os sinalizadores WMDM_FILE_ATTR* nessa função é mais eficiente do que chamar essa função primeiro e, em seguida, definir esses atributos no arquivo depois que ele tiver sido criado ou enviado.

Combinações	Mode	Descrição
Exatamente um de:	WMDM_MODE_BLOCK	A operação é executada usando o processamento do modo de bloco. A chamada não retornará até que a operação seja concluída.
-	WMDM_MODE_THREAD	A operação é executada usando o processamento do modo thread. A chamada retornará imediatamente e a operação será executada em um thread em segundo plano.
Opcional	WMDM_MODE_QUERY	Um teste é executado para determinar se a operação de inserção pode ter êxito, mas a inserção não será executada.
Exatamente um de:	WMDM_STORAGECONTROL_INSERTBEFORE	O objeto é inserido antes do objeto de destino.
-	WMDM_STORAGECONTROL_INSERTAFTER	O objeto é inserido após o objeto de destino.
-	WMDM_STORAGECONTROL_INSERTINTO	O objeto é inserido no objeto atual. Isso só funcionará se o objeto atual for uma pasta.
Opcional	WMDM_FILE_CREATE_OVERWRITE	O objeto substituirá o objeto de destino.
Exatamente um de:	WMDM_CONTENT_FILE	O conteúdo que está sendo inserido é um arquivo.
-	WMDM_CONTENT_FOLDER	O conteúdo que está sendo inserido é uma pasta. Isso não transferirá o conteúdo da pasta.
Opcional	WMDM_CONTENT_OPERATIONINTERFACE	O aplicativo está passando uma interface IWMDMOperation para controlar a transferência de dados.
Zero ou mais de:	WMDM_FILE_ATTR_READONLY	O armazenamento deve ser definido como somente leitura no dispositivo.
-	WMDM_FILE_ATTR_HIDDEN	O armazenamento deve ser definido como oculto no dispositivo.
-	WMDM_FILE_ATTR_SYSTEM	O armazenamento deve ser definido como sistema no dispositivo.
Opcional	WMDM_MODE_PROGRESS	A inserção está em andamento.
Opcional de:	WMDM_MODE_TRANSFER_PROTECTED	A inserção está no modo de transferência protegido.
-	WMDM_MODE_TRANSFER_UNPROTECTED	A inserção está no modo de transferência desprotegido.

[in] fuType

Um dos tipos a seguir, especificando o armazenamento atual.

Valor	Descrição
WMDM_FILE_ATTR_FILE	O armazenamento atual é um arquivo.
WMDM_FILE_ATTR_FOLDER	O armazenamento atual é uma pasta.

[in] pwszFileSource

Ponteiro para uma cadeia de caracteres largo e terminada em nulo que indica onde localizar o conteúdo da operação de inserção. Esse parâmetro deverá ser NULL se WMDM_CONTENT_OPERATIONINTERFACE for especificado em fuMode. Esse parâmetro poderá ser NULL se uma playlist ou um álbum estiver sendo criado.

[in] pwszFileDest

Nome opcional do arquivo no dispositivo. Se não for especificado e o aplicativo passar um ponteiro IWMDMOperation para pOperation, o Windows Media Gerenciador de Dispositivos solicitará um nome de destino chamando IWMDMOperation::GetObjectName. Se não for especificado e o aplicativo não usar pOperation, o nome do arquivo original e a extensão serão usados (sem o caminho).

[in] pOperation

Ponteiro opcional para uma interface IWMDMOperation para controlar a transferência de conteúdo para um dispositivo de mídia. Se especificado, fuMode deverá incluir o sinalizador WMDM_CONTENT_OPERATIONINTERFACE. Esse parâmetro deverá ser NULL se WMDM_CONTENT_FILE ou WMDM_CONTENT_FOLDER for especificado em fuMode.

[in] pProgress

Ponteiro opcional para uma interface IWMDMProgress para relatar o progresso da ação de volta ao aplicativo. Este parâmetro pode ser NULL.

[in] pMetaData

Ponteiro opcional para um objeto de metadados. Crie um novo objeto de metadados chamando IWMDMStorage3::CreateEmptyMetadataObject. Esse parâmetro permite que um aplicativo especifique metadados (incluindo formato) a serem definidos no dispositivo durante a criação do objeto no dispositivo, o que é mais eficiente do que definir metadados posteriormente. Você deve definir o formato de arquivo (especificado por g_wszWMDMFormatCode). Se você não especificar o código de formato de um arquivo ao usar esse método, um dispositivo MTP não mostrará o arquivo como presente em sua interface do usuário e dispositivos não MTP se comportarão de forma imprevisível.

[in] pUnknown

Ponteiro IUnknown opcional de qualquer objeto COM personalizado a ser passado para o provedor de conteúdo seguro. Isso possibilita passar informações personalizadas para um provedor de conteúdo seguro se o aplicativo tiver informações suficientes sobre o provedor de conteúdo seguro.

[out] ppNewObject

Ponteiro para uma interface IWMDMStorage que conterá o novo conteúdo. O chamador deve liberar essa interface quando terminar com ela.

Retornar valor

O método retorna um HRESULT. Todos os métodos de interface no Windows Media Gerenciador de Dispositivos podem retornar qualquer uma das seguintes classes de códigos de erro:

Códigos de erro COM padrão
Códigos de erro do Windows convertidos em valores HRESULT
Códigos de erro de Gerenciador de Dispositivos do Windows Media

Para obter uma ampla lista de possíveis códigos de erro, consulte Códigos de erro.

Comentários

Embora você possa definir metadados em um armazenamento depois de enviá-los para o dispositivo, é mais eficiente definir essas informações no parâmetro pMetaData desse método. Isso fornece informações adicionais para o dispositivo para permitir que ele transfira e manipule o arquivo adequadamente (por exemplo, armazenando-o no local correto) ou exiba informações úteis (como uma descrição escrita pelo usuário de uma imagem).

Para definir propriedades para um dispositivo WPD (Dispositivos Portáteis do Windows), um aplicativo criaria um objeto IPortableDeviceValues e definiria cada propriedade nesta coleção. Em seguida, o aplicativo serializaria a coleção para um BLOB (objeto binário grande). Depois que os dados forem serializados, o aplicativo os adicionará à IWMDMMetaData referenciada pelo argumento pMetadata usando a constante de metadados g_wszWPDPassthroughPropertyValues.

Se o sinalizador WMDM_MODE_THREAD for especificado, você deverá obter status de conclusão chamando IWMDMProgress2::End2 ou IWMDMProgress3::End3. Esses métodos garantirão que a operação seja concluída e também retornarão um HRESULT com informações de êxito ou falha.

Se um aplicativo usa WMDM_MODE_THREAD e passa um parâmetro pProgress não nulo, o aplicativo deve garantir que o objeto ao qual o pProgress pertence não seja destruído até que a operação de leitura seja concluída, pois o Windows Media Gerenciador de Dispositivos enviará notificações de progresso para esse objeto. Esse objeto só pode ser destruído depois de receber uma notificação final. A falha ao fazer isso resultará em violações de acesso.

Ao criar uma playlist ou outro objeto de referência, o objeto que está sendo "inserido" na verdade não contém dados, mas é simplesmente armazenado no dispositivo como um grupo de referências de metadados a outros objetos (como arquivos de música). A criação desse objeto "abstrato" na playlist é descrita em Criando uma playlist no dispositivo.

Exemplos

A função C++ a seguir envia um arquivo para um dispositivo. Como parte da transferência, ele deve adicionar metadados ao armazenamento para especificar o novo tipo de armazenamento.


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;
}