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

Artículo
03/15/2023

El método Insert3 coloca contenido en/junto al almacenamiento. Este método extiende IWMDMStorageControl2::Insert2 al permitir que la aplicación especifique explícitamente los metadatos y el tipo del objeto que se envía.

Sintaxis

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 procesamiento usado para la operación Insert3 . En la tabla siguiente se enumeran los modos de procesamiento que se pueden especificar en el parámetro fuMode . Debe especificar exactamente uno de los dos primeros modos, exactamente uno de los modos STORAGECONTROL y exactamente uno de los modos CONTENT. Si se especifican WMDM_MODE_BLOCK y WMDM_MODE_THREAD, se usa el modo de bloque. Especificar las marcas WMDM_FILE_ATTR* en esta función es más eficaz que llamar primero a esta función y, a continuación, establecer estos atributos en el archivo una vez creado o enviado.

Combinaciones	Mode	Descripción
Exactamente uno de:	WMDM_MODE_BLOCK	La operación se realiza mediante el procesamiento del modo de bloque. La llamada no se devolverá hasta que finalice la operación.
-	WMDM_MODE_THREAD	La operación se realiza mediante el procesamiento del modo de subproceso. La llamada se devolverá inmediatamente y la operación se realiza en un subproceso en segundo plano.
Opcionales	WMDM_MODE_QUERY	Se realiza una prueba para determinar si la operación de inserción se pudo realizar correctamente, pero no se realizará la inserción.
Exactamente uno de:	WMDM_STORAGECONTROL_INSERTBEFORE	El objeto se inserta antes del objeto de destino.
-	WMDM_STORAGECONTROL_INSERTAFTER	El objeto se inserta después del objeto de destino.
-	WMDM_STORAGECONTROL_INSERTINTO	El objeto se inserta en el objeto actual. Esto solo funcionará si el objeto actual es una carpeta.
Opcionales	WMDM_FILE_CREATE_OVERWRITE	El objeto reemplazará el objeto de destino.
Exactamente uno de:	WMDM_CONTENT_FILE	El contenido que se va a insertar es un archivo.
-	WMDM_CONTENT_FOLDER	El contenido que se va a insertar es una carpeta. Esto no transferirá el contenido de la carpeta.
Opcionales	WMDM_CONTENT_OPERATIONINTERFACE	La aplicación pasa una interfaz IWMDMOperation para controlar la transferencia de datos.
Cero o más de:	WMDM_FILE_ATTR_READONLY	El almacenamiento debe establecerse en de solo lectura en el dispositivo.
-	WMDM_FILE_ATTR_HIDDEN	El almacenamiento debe establecerse en oculto en el dispositivo.
-	WMDM_FILE_ATTR_SYSTEM	El almacenamiento debe establecerse en el sistema en el dispositivo.
Opcionales	WMDM_MODE_PROGRESS	La inserción está en curso.
Opcional:	WMDM_MODE_TRANSFER_PROTECTED	La inserción está en modo de transferencia protegida.
-	WMDM_MODE_TRANSFER_UNPROTECTED	La inserción está en modo de transferencia desprotegida.

[in] fuType

Uno de los siguientes tipos, especificando el almacenamiento actual.

Valor	Descripción
WMDM_FILE_ATTR_FILE	El almacenamiento actual es un archivo.
WMDM_FILE_ATTR_FOLDER	El almacenamiento actual es una carpeta.

[in] pwszFileSource

Puntero a una cadena terminada en null de caracteres anchos que indica dónde encontrar el contenido de la operación de inserción. Este parámetro debe ser NULL si se especifica WMDM_CONTENT_OPERATIONINTERFACE en fuMode. Este parámetro puede ser NULL si se crea una lista de reproducción o un álbum.

[in] pwszFileDest

Nombre opcional del archivo en el dispositivo. Si no se especifica y la aplicación pasa un puntero IWMDMOperation a pOperation, Windows Media Administrador de dispositivos solicitará un nombre de destino llamando a IWMDMOperation::GetObjectName. Si no se especifica y la aplicación no usa pOperation, se usan el nombre de archivo y la extensión originales (sin la ruta de acceso).

[in] pOperation

Puntero opcional a una interfaz IWMDMOperation para controlar la transferencia de contenido a un dispositivo multimedia. Si se especifica, fuMode debe incluir la marca WMDM_CONTENT_OPERATIONINTERFACE. Este parámetro debe ser NULL si se especifica WMDM_CONTENT_FILE o WMDM_CONTENT_FOLDER en fuMode.

[in] pProgress

Puntero opcional a una interfaz IWMDMProgress para notificar el progreso de la acción a la aplicación. Este parámetro puede ser NULL.

[in] pMetaData

Puntero opcional a un objeto de metadatos. Cree un nuevo objeto de metadatos llamando a IWMDMStorage3::CreateEmptyMetadataObject. Este parámetro permite a una aplicación especificar metadatos (incluido el formato) para establecerlos en el dispositivo durante la creación de objetos en el dispositivo, lo que es más eficaz que establecer los metadatos después. Debe establecer el formato de archivo (especificado por g_wszWMDMFormatCode). Si no especifica el código de formato de un archivo al usar este método, un dispositivo MTP no mostrará el archivo como está presente en su interfaz de usuario y los dispositivos que no sean MTP se comportarán de forma impredecible.

[in] pUnknown

Puntero IUnknown opcional de cualquier objeto COM personalizado que se va a pasar al proveedor de contenido seguro. Esto permite pasar información personalizada a un proveedor de contenido seguro si la aplicación tiene suficiente información sobre el proveedor de contenido seguro.

[out] ppNewObject

Puntero a una interfaz IWMDMStorage que contendrá el nuevo contenido. El autor de la llamada debe liberar esta interfaz cuando termine con ella.

Valor devuelto

El método devuelve un valor HRESULT. Todos los métodos de interfaz de Windows Media Administrador de dispositivos pueden devolver cualquiera de las siguientes clases de códigos de error:

Códigos de error COM estándar
Códigos de error de Windows convertidos en valores HRESULT
Códigos de error de windows Media Administrador de dispositivos

Para obtener una lista extensa de posibles códigos de error, consulte Códigos de error.

Comentarios

Aunque puede establecer metadatos en un almacenamiento después de enviarlo al dispositivo, es más eficaz establecer esta información en el parámetro pMetaData de este método. Esto proporciona información adicional al dispositivo para permitir que transfiera y controle el archivo de forma adecuada (por ejemplo, almacenándolo en el lugar correcto) o muestre información útil (como una descripción escrita por el usuario de una imagen).

Para establecer las propiedades de un dispositivo Windows Portable Devices (WPD), una aplicación crearía un objeto IPortableDeviceValues y establecería cada propiedad en esta colección. A continuación, la aplicación serializaría la colección en un objeto binario grande (BLOB). Una vez serializados los datos, la aplicación la agregaría al IWMDMMetaData al que hace referencia el argumento pMetadata mediante la constante de metadatos g_wszWPDPassthroughPropertyValues.

Si se especifica la marca WMDM_MODE_THREAD, debe obtener el estado de finalización llamando a IWMDMProgress2::End2 o IWMDMProgress3::End3. Estos métodos garantizarán que la operación esté completa y también devolverán un HRESULT con información de éxito o error.

Si una aplicación usa WMDM_MODE_THREAD y pasa un parámetro pProgress distinto de null, la aplicación debe asegurarse de que el objeto al que pertenece pProgress no se destruye hasta que se complete la operación de lectura, ya que Windows Media Administrador de dispositivos enviará notificaciones de progreso a este objeto. Este objeto solo se puede destruir después de recibir una notificación de finalización. Si no lo hace, se producirán infracciones de acceso.

Al crear una lista de reproducción u otro objeto de referencia, el objeto que se está "insertando" no contiene datos, sino que simplemente se almacena en el dispositivo como un grupo de referencias de metadatos a otros objetos (como archivos de música). La creación de este objeto "abstracto" en la lista de reproducción se describe en Creación de una lista de reproducción en el dispositivo.

Ejemplos

La siguiente función de C++ envía un archivo a un dispositivo. Como parte de la transferencia, debe agregar metadatos al almacenamiento para especificar el nuevo tipo de almacenamiento.


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