Método IWMDMStorageControl::Insert (mswmdm.h)

Artigo
08/25/2023

O método Insert coloca o conteúdo no armazenamento no dispositivo.

Sintaxe

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

Parâmetros

[in] fuMode

Um OR bit a bit dos valores a seguir. 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.

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.
Exatamente um de:	WMDM_STORAGECONTROL_INSERTBEFORE	O objeto é inserido antes do objeto atual.
	WMDM_STORAGECONTROL_INSERTAFTER	O objeto é inserido após o objeto atual.
	WMDM_STORAGECONTROL_INSERTINTO	O objeto é inserido no objeto atual. Isso só funcionará se o objeto atual for uma pasta.
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.
	WMDM_CONTENT_OPERATIONINTERFACE	O conteúdo que está sendo inserido é uma interface de operação. Os dados do conteúdo devem ser gravados na interface IWMDMOperation implementada pelo aplicativo.
Zero ou mais de:	WMDM_FILE_CREATE_OVERWRITE	O objeto substituirá o objeto atual.
	WMDM_MODE_QUERY	Um teste é executado para determinar se a operação de inserção pode ser bem-sucedida, mas a inserção não será executada.
	WMDM_MODE_PROGRESS	O método deve retornar notificações de progresso por meio de pProgress.
Zero ou um dos seguintes:	WMDM_MODE_TRANSFER_PROTECTED	A inserção está no modo de transferência protegida.
	WMDM_MODE_TRANSFER_UNPROTECTED	A inserção está no modo de transferência desprotegida.

[in] pwszFile

Ponteiro para uma cadeia de caracteres largos terminada em nulo indicando 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.

[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 deve 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 a ser usada pelo Windows Media Gerenciador de Dispositivos para relatar o progresso de volta para o aplicativo. Se isso for usado, fuMode deverá incluir WMDM_MODE_PROGRESS.

[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 do Windows Media Gerenciador de Dispositivos

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

Comentários

Se o dispositivo der suporte a IWMDMStorageControl3::Insert3, esse é o método preferencial a ser usado.

O nome e a extensão do objeto salvo no dispositivo serão iguais ao nome e à extensão do arquivo de origem (se pOperation for NULL).

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.

O método Insert não garante que o dispositivo dê suporte à inserção de arquivo ordenada, mas fornece os sinalizadores WMDM_STORAGECONTROL_INSERTBEFORE e WMDM_STORAGECONTROL_INSERTAFTER caso o faça. Se o sistema de arquivos não der suporte à ordenação (por exemplo, FAT32), WMDM_STORAGECONTROL_INSERTBEFORE e WMDM_STORAGECONTROL_INSERTAFTER simplesmente inserirá o novo objeto de armazenamento no mesmo nível que o objeto atual na hierarquia do sistema de arquivos.

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 inserção 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 end. A falha ao fazer isso resultará em violações de acesso.