Metodo IWMDMStorageControl3::Insert3 (mswmdm.h)

Articolo
08/25/2023

Il metodo Insert3 inserisce il contenuto in/accanto alla risorsa di archiviazione. Questo metodo estende IWMDMStorageControl2::Insert2 consentendo all'applicazione di specificare in modo esplicito i metadati e il tipo dell'oggetto inviato.

Sintassi

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

Parametri

[in] fuMode

Modalità di elaborazione utilizzata per l'operazione Insert3 . Nella tabella seguente sono elencate le modalità di elaborazione che è possibile specificare nel parametro fuMode . È necessario specificare esattamente una delle prime due modalità, esattamente una delle modalità STORAGECONTROL e esattamente una delle modalità CONTENT. Se vengono specificati sia WMDM_MODE_BLOCK che WMDM_MODE_THREAD, viene utilizzata la modalità di blocco. La specifica dei flag WMDM_FILE_ATTR* in questa funzione è più efficiente rispetto alla chiamata di questa funzione prima, quindi all'impostazione di questi attributi nel file dopo la creazione o l'invio.

Combinazioni	Mode	Descrizione
Esattamente uno di:	WMDM_MODE_BLOCK	L'operazione viene eseguita usando l'elaborazione in modalità blocco. La chiamata non verrà restituita fino al termine dell'operazione.
-	WMDM_MODE_THREAD	L'operazione viene eseguita usando l'elaborazione in modalità thread. La chiamata restituisce immediatamente e l'operazione viene eseguita in un thread in background.
Facoltativo	WMDM_MODE_QUERY	Viene eseguito un test per determinare se l'operazione di inserimento può avere esito positivo, ma l'inserimento non verrà eseguito.
Esattamente uno di:	WMDM_STORAGECONTROL_INSERTBEFORE	L'oggetto viene inserito prima dell'oggetto di destinazione.
-	WMDM_STORAGECONTROL_INSERTAFTER	L'oggetto viene inserito dopo l'oggetto di destinazione.
-	WMDM_STORAGECONTROL_INSERTINTO	L'oggetto viene inserito nell'oggetto corrente. Questa operazione funzionerà solo se l'oggetto corrente è una cartella.
Facoltativo	WMDM_FILE_CREATE_OVERWRITE	L'oggetto sostituirà l'oggetto di destinazione.
Esattamente uno di:	WMDM_CONTENT_FILE	Il contenuto inserito è un file.
-	WMDM_CONTENT_FOLDER	Il contenuto da inserire è una cartella. Questo non trasferisce il contenuto della cartella.
Facoltativo	WMDM_CONTENT_OPERATIONINTERFACE	L'applicazione passa un'interfaccia IWMDMOperation per controllare il trasferimento dei dati.
Zero o più di:	WMDM_FILE_ATTR_READONLY	Lo spazio di archiviazione deve essere impostato su sola lettura nel dispositivo.
-	WMDM_FILE_ATTR_HIDDEN	Lo spazio di archiviazione deve essere impostato su nascosto nel dispositivo.
-	WMDM_FILE_ATTR_SYSTEM	Lo spazio di archiviazione deve essere impostato sul sistema nel dispositivo.
Facoltativo	WMDM_MODE_PROGRESS	L'inserimento è in corso.
Facoltativo:	WMDM_MODE_TRANSFER_PROTECTED	L'inserimento è in modalità di trasferimento protetto.
-	WMDM_MODE_TRANSFER_UNPROTECTED	L'inserimento è in modalità di trasferimento non protetto.

[in] fuType

Uno dei tipi seguenti, specificando la risorsa di archiviazione corrente.

Valore	Descrizione
WMDM_FILE_ATTR_FILE	L'archiviazione corrente è un file.
WMDM_FILE_ATTR_FOLDER	Lo spazio di archiviazione corrente è una cartella.

[in] pwszFileSource

Puntatore a una stringa con terminazione Null a caratteri wide che indica dove trovare il contenuto per l'operazione di inserimento. Questo parametro deve essere NULL se WMDM_CONTENT_OPERATIONINTERFACE è specificato in fuMode. Questo parametro può essere NULL se viene creata una playlist o un album.

[in] pwszFileDest

Nome facoltativo del file nel dispositivo. Se non specificato e l'applicazione passa un puntatore IWMDMOperation a pOperation, Windows Media Gestione dispositivi richiederà un nome di destinazione chiamando IWMDMOperation::GetObjectName. Se non specificato e l'applicazione non usa pOperation, vengono usati il nome e l'estensione del file originale (senza il percorso).

[in] pOperation

Puntatore facoltativo a un'interfaccia IWMDMOperation , per controllare il trasferimento del contenuto in un dispositivo multimediale. Se specificato, fuMode deve includere il flag WMDM_CONTENT_OPERATIONINTERFACE. Questo parametro deve essere NULL se WMDM_CONTENT_FILE o WMDM_CONTENT_FOLDER è specificato in fuMode.

[in] pProgress

Puntatore facoltativo a un'interfaccia IWMDMProgress per segnalare lo stato di avanzamento dell'azione all'applicazione. Questo parametro può essere NULL.

[in] pMetaData

Puntatore facoltativo a un oggetto metadati. Creare un nuovo oggetto metadati chiamando IWMDMStorage3::CreateEmptyMetadataObject. Questo parametro consente a un'applicazione di specificare metadati (incluso il formato) di impostare nel dispositivo durante la creazione dell'oggetto, che è più efficiente rispetto all'impostazione dei metadati in un secondo momento. È necessario impostare il formato di file (specificato da g_wszWMDMFormatCode). Se non si specifica il codice di formato di un file quando si usa questo metodo, un dispositivo MTP non visualizzerà il file come presente nell'interfaccia utente e i dispositivi non MTP si comportano in modo imprevedibile.

[in] pUnknown

Puntatore IUnknown facoltativo di qualsiasi oggetto COM personalizzato da passare al provider di contenuti protetti. In questo modo è possibile passare informazioni personalizzate a un provider di contenuti sicuro se l'applicazione dispone di informazioni sufficienti sul provider di contenuti protetti.

[out] ppNewObject

Puntatore a un'interfaccia IWMDMStorage che conterrà il nuovo contenuto. Il chiamante deve rilasciare questa interfaccia al termine dell'operazione.

Valore restituito

Il metodo restituisce un valore HRESULT. Tutti i metodi di interfaccia in Windows Media Gestione dispositivi possono restituire una delle classi di codici di errore seguenti:

Codici di errore COM standard
Codici di errore di Windows convertiti in valori HRESULT
Codici di errore di Windows Media Gestione dispositivi

Per un elenco completo dei codici di errore possibili, vedere Codici di errore.

Commenti

Sebbene sia possibile impostare i metadati in una risorsa di archiviazione dopo l'invio al dispositivo, è più efficiente impostare queste informazioni nel parametro pMetaData di questo metodo. In questo modo vengono fornite informazioni aggiuntive al dispositivo per consentire il trasferimento e la gestione del file in modo appropriato (ad esempio, archiviandolo nella posizione corretta) o visualizzare informazioni utili (ad esempio una descrizione scritta dall'utente di un'immagine).

Per impostare le proprietà per un dispositivo WINDOWS Portable Devices (WPD), un'applicazione crea un oggetto IPortableDeviceValues e imposta ogni proprietà in questa raccolta. Quindi, l'applicazione serializzerebbe la raccolta in un oggetto di grandi dimensioni binario (BLOB). Dopo aver serializzato i dati, l'applicazione lo aggiungerà alla costante metadati IWMDMMetaData a cui fa riferimento l'argomento pMetadata usando la costante dei metadati g_wszWPDPassthroughPropertyValues.

Se viene specificato il flag WMDM_MODE_THREAD, è necessario ottenere lo stato di completamento chiamando IWMDMProgress2::End2 o IWMDMProgress3::End3. Questi metodi assicureranno che l'operazione sia completata e restituirà anche un HRESULT con informazioni sull'esito positivo o negativo.

Se un'applicazione usa WMDM_MODE_THREAD e passa un parametro pProgress diverso da null, l'applicazione deve assicurarsi che l'oggetto a cui appartiene pProgress non venga eliminato fino al completamento dell'operazione di lettura, perché Windows Media Gestione dispositivi invierà notifiche di stato a questo oggetto. Questo oggetto può essere eliminato solo dopo la ricezione di una notifica finale. Questa operazione comporta violazioni di accesso.

Quando si crea una playlist o un altro oggetto di riferimento, l'oggetto che viene "inserito" in realtà non contiene dati ma viene semplicemente archiviato nel dispositivo come gruppo di riferimenti ai metadati ad altri oggetti (ad esempio file musicali). La creazione di un oggetto "astratta" nella playlist è descritta in Creazione di una playlist nel dispositivo.

Esempio

La funzione C++ seguente invia un file a un dispositivo. Nell'ambito del trasferimento, deve aggiungere metadati all'archiviazione per specificare il nuovo tipo di archiviazione.


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