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

Article
08/25/2023

La méthode Insert3 place le contenu dans/à côté du stockage. Cette méthode étend IWMDMStorageControl2 ::Insert2 en permettant à l’application de spécifier explicitement les métadonnées et le type de l’objet envoyé.

Syntaxe

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

Paramètres

[in] fuMode

Mode de traitement utilisé pour l’opération Insert3 . Le tableau suivant répertorie les modes de traitement qui peuvent être spécifiés dans le paramètre fuMode . Vous devez spécifier exactement l’un des deux premiers modes, exactement l’un des modes STORAGECONTROL et exactement l’un des modes CONTENT. Si WMDM_MODE_BLOCK et WMDM_MODE_THREAD sont spécifiés, le mode bloc est utilisé. La spécification des indicateurs WMDM_FILE_ATTR* dans cette fonction est plus efficace que l’appel de cette fonction en premier, puis la définition de ces attributs sur le fichier après sa création ou son envoi.

Combinaisons	Mode	Description
Exactement l’un des éléments suivants :	WMDM_MODE_BLOCK	L’opération est effectuée à l’aide du traitement en mode bloc. L’appel ne sera pas retourné tant que l’opération n’est pas terminée.
-	WMDM_MODE_THREAD	L’opération est effectuée à l’aide du traitement en mode thread. L’appel est retourné immédiatement et l’opération est effectuée dans un thread d’arrière-plan.
Facultatif	WMDM_MODE_QUERY	Un test est effectué pour déterminer si l’opération d’insertion peut réussir, mais l’insertion ne sera pas effectuée.
Exactement l’un des éléments suivants :	WMDM_STORAGECONTROL_INSERTBEFORE	L’objet est inséré avant l’objet cible.
-	WMDM_STORAGECONTROL_INSERTAFTER	L’objet est inséré après l’objet cible.
-	WMDM_STORAGECONTROL_INSERTINTO	L’objet est inséré dans l’objet actuel. Cela ne fonctionne que si l’objet actuel est un dossier.
Facultatif	WMDM_FILE_CREATE_OVERWRITE	L’objet remplacera l’objet cible.
Exactement l’un des éléments suivants :	WMDM_CONTENT_FILE	Le contenu inséré est un fichier.
-	WMDM_CONTENT_FOLDER	Le contenu inséré est un dossier. Cela ne transfère pas le contenu du dossier.
Facultatif	WMDM_CONTENT_OPERATIONINTERFACE	L’application transmet une interface IWMDMOperation pour contrôler le transfert de données.
Zéro ou plus de :	WMDM_FILE_ATTR_READONLY	Le stockage doit être défini sur lecture seule sur l’appareil.
-	WMDM_FILE_ATTR_HIDDEN	Le stockage doit être défini sur masqué sur l’appareil.
-	WMDM_FILE_ATTR_SYSTEM	Le stockage doit être défini sur système sur l’appareil.
Facultatif	WMDM_MODE_PROGRESS	L’insertion est en cours.
Facultatif de :	WMDM_MODE_TRANSFER_PROTECTED	L’insertion est en mode de transfert protégé.
-	WMDM_MODE_TRANSFER_UNPROTECTED	L’insertion est en mode de transfert non protégé.

[in] fuType

L’un des types suivants, en spécifiant le stockage actuel.

Valeur	Description
WMDM_FILE_ATTR_FILE	Le stockage actuel est un fichier.
WMDM_FILE_ATTR_FOLDER	Le stockage actuel est un dossier.

[in] pwszFileSource

Pointeur vers une chaîne à caractères larges et terminée par null indiquant où trouver le contenu de l’opération d’insertion. Ce paramètre doit être NULL si WMDM_CONTENT_OPERATIONINTERFACE est spécifié dans fuMode. Ce paramètre peut être NULL si une playlist ou un album est en cours de création.

[in] pwszFileDest

Nom facultatif du fichier sur l’appareil. Si ce n’est pas spécifié et que l’application transmet un pointeur IWMDMOperation à pOperation, Windows Media Gestionnaire de périphériques demande un nom de destination en appelant IWMDMOperation ::GetObjectName. S’il n’est pas spécifié et que l’application n’utilise pas pOperation, le nom de fichier d’origine et l’extension sont utilisés (sans le chemin d’accès).

[in] pOperation

Pointeur facultatif vers une interface IWMDMOperation pour contrôler le transfert de contenu vers un périphérique multimédia. S’il est spécifié, fuMode doit inclure l’indicateur WMDM_CONTENT_OPERATIONINTERFACE. Ce paramètre doit avoir la valeur NULL si WMDM_CONTENT_FILE ou WMDM_CONTENT_FOLDER est spécifié dans fuMode.

[in] pProgress

Pointeur facultatif vers une interface IWMDMProgress pour signaler la progression de l’action à l’application. Ce paramètre peut être NULL.

[in] pMetaData

Pointeur facultatif vers un objet de métadonnées. Créez un objet de métadonnées en appelant IWMDMStorage3 ::CreateEmptyMetadataObject. Ce paramètre permet à une application de spécifier des métadonnées (y compris le format) à définir sur l’appareil lors de la création de l’objet sur l’appareil, ce qui est plus efficace que la définition de métadonnées par la suite. Vous devez définir le format de fichier (spécifié par g_wszWMDMFormatCode). Si vous ne spécifiez pas le code de format d’un fichier lors de l’utilisation de cette méthode, un appareil MTP n’affiche pas le fichier comme étant présent dans son interface utilisateur, et les appareils non MTP se comportent de manière imprévisible.

[in] pUnknown

Pointeur IUnknown facultatif de tout objet COM personnalisé à passer au fournisseur de contenu sécurisé. Cela permet de transmettre des informations personnalisées à un fournisseur de contenu sécurisé si l’application dispose d’informations suffisantes sur le fournisseur de contenu sécurisé.

[out] ppNewObject

Pointeur vers une interface IWMDMStorage qui contiendra le nouveau contenu. L’appelant doit libérer cette interface quand il en a terminé.

Valeur retournée

Cette méthode retourne un code HRESULT. Toutes les méthodes d’interface dans Windows Media Gestionnaire de périphériques peuvent retourner l’une des classes suivantes de codes d’erreur :

Codes d’erreur COM standard
Codes d’erreur Windows convertis en valeurs HRESULT
Codes d’erreur Gestionnaire de périphériques Windows Media

Pour obtenir une liste complète des codes d’erreur possibles, consultez Codes d’erreur.

Remarques

Bien que vous puissiez définir des métadonnées sur un stockage après les avoir envoyées à l’appareil, il est plus efficace de définir ces informations dans le paramètre pMetaData de cette méthode. Cela fournit des informations supplémentaires à l’appareil pour lui permettre de transférer et de gérer le fichier de manière appropriée (par exemple, en le stockant au bon endroit) ou d’afficher des informations utiles (telles qu’une description écrite par l’utilisateur d’une image).

Pour définir les propriétés d’un appareil Windows Portable Devices (WPD), une application crée un objet IPortableDeviceValues et définit chaque propriété dans cette collection. Ensuite, l’application sérialise la collection en un objet BLOB (Binary Large Object). Une fois les données sérialisées, l’application les ajoute à L’IWMDMMetaData référencé par l’argument pMetadata à l’aide de la constante de métadonnées g_wszWPDPassthroughPropertyValues.

Si l’indicateur WMDM_MODE_THREAD est spécifié, vous devez obtenir l’achèvement status en appelant IWMDMProgress2 ::End2 ou IWMDMProgress3 ::End3. Ces méthodes garantissent que l’opération est terminée et retournent également un HRESULT avec des informations de réussite ou d’échec.

Si une application utilise WMDM_MODE_THREAD et transmet un paramètre pProgress non null, l’application doit s’assurer que l’objet auquel appartient pProgress n’est pas détruit tant que l’opération de lecture n’est pas terminée, car Windows Media Gestionnaire de périphériques envoie des notifications de progression à cet objet. Cet objet ne peut être détruit qu’après avoir reçu une notification de fin. Si vous ne le faites pas, vous obtiendrez des violations d’accès.

Lors de la création d’une playlist ou d’un autre objet de référence, l’objet « inséré » ne contient en fait aucune donnée, mais est simplement stocké sur l’appareil sous la forme d’un groupe de métadonnées faisant référence à d’autres objets (tels que des fichiers de musique). La création d’un tel objet « abstrait » sur la playlist est décrite dans Création d’une playlist sur l’appareil.

Exemples

La fonction C++ suivante envoie un fichier à un appareil. Dans le cadre du transfert, il doit ajouter des métadonnées au stockage pour spécifier le nouveau type de stockage.


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