IWMDMStorageControl3::Insert3-Methode (mswmdm.h)

Artikel
08/25/2023

Die Insert3-Methode fügt Inhalte in/neben den Speicher ein. Diese Methode erweitert IWMDMStorageControl2::Insert2 , indem die Anwendung die Metadaten und den Typ des gesendeten Objekts explizit angeben kann.

Syntax

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

Parameter

[in] fuMode

Verarbeitungsmodus, der für den Insert3-Vorgang verwendet wird. In der folgenden Tabelle sind die Verarbeitungsmodi aufgeführt, die im fuMode-Parameter angegeben werden können. Sie müssen genau einen der ersten beiden Modi angeben, genau einen der STORAGECONTROL-Modi und genau einen der INHALTSmodi. Wenn sowohl WMDM_MODE_BLOCK als auch WMDM_MODE_THREAD angegeben werden, wird der Blockmodus verwendet. Das Angeben der WMDM_FILE_ATTR*-Flags in dieser Funktion ist effizienter, als zuerst diese Funktion aufzurufen und dann diese Attribute für die Datei festzulegen, nachdem sie erstellt oder gesendet wurde.

Kombinationen	Mode	BESCHREIBUNG
Genau eine der folgenden:	WMDM_MODE_BLOCK	Der Vorgang wird mithilfe der Blockmodusverarbeitung ausgeführt. Der Aufruf wird erst zurückgegeben, wenn der Vorgang abgeschlossen ist.
-	WMDM_MODE_THREAD	Der Vorgang wird mithilfe der Threadmodusverarbeitung ausgeführt. Der Aufruf wird sofort zurückgegeben, und der Vorgang wird in einem Hintergrundthread ausgeführt.
Optional	WMDM_MODE_QUERY	Es wird ein Test durchgeführt, um festzustellen, ob der Einfügevorgang erfolgreich war, aber der Einfügevorgang nicht ausgeführt wird.
Genau eine der folgenden:	WMDM_STORAGECONTROL_INSERTBEFORE	Das Objekt wird vor dem Zielobjekt eingefügt.
-	WMDM_STORAGECONTROL_INSERTAFTER	Das Objekt wird nach dem Zielobjekt eingefügt.
-	WMDM_STORAGECONTROL_INSERTINTO	Das Objekt wird in das aktuelle Objekt eingefügt. Dies funktioniert nur, wenn das aktuelle Objekt ein Ordner ist.
Optional	WMDM_FILE_CREATE_OVERWRITE	Das -Objekt ersetzt das Zielobjekt.
Genau eine der folgenden:	WMDM_CONTENT_FILE	Der eingefügte Inhalt ist eine Datei.
-	WMDM_CONTENT_FOLDER	Der eingefügte Inhalt ist ein Ordner. Dadurch wird der Inhalt des Ordners nicht übertragen.
Optional	WMDM_CONTENT_OPERATIONINTERFACE	Die Anwendung übergibt eine IWMDMOperation-Schnittstelle , um die Datenübertragung zu steuern.
Null oder mehr von:	WMDM_FILE_ATTR_READONLY	Der Speicher sollte auf dem Gerät auf schreibgeschützt festgelegt werden.
-	WMDM_FILE_ATTR_HIDDEN	Der Speicher sollte auf dem Gerät auf ausgeblendet festgelegt werden.
-	WMDM_FILE_ATTR_SYSTEM	Der Speicher sollte auf dem Gerät auf System festgelegt werden.
Optional	WMDM_MODE_PROGRESS	Die Einfügung wird ausgeführt.
Optional:	WMDM_MODE_TRANSFER_PROTECTED	Die Einfügung befindet sich im geschützten Übertragungsmodus.
-	WMDM_MODE_TRANSFER_UNPROTECTED	Das Einfügen befindet sich im ungeschützten Übertragungsmodus.

[in] fuType

Einer der folgenden Typen, der den aktuellen Speicher angibt.

Wert	BESCHREIBUNG
WMDM_FILE_ATTR_FILE	Der aktuelle Speicher ist eine Datei.
WMDM_FILE_ATTR_FOLDER	Der aktuelle Speicher ist ein Ordner.

[in] pwszFileSource

Zeiger auf eine Breitzeichenzeichenfolge mit NULL-Beendigung, die angibt, wo der Inhalt für den Einfügevorgang zu finden ist. Dieser Parameter muss NULL sein, wenn WMDM_CONTENT_OPERATIONINTERFACE in fuMode angegeben ist. Dieser Parameter kann NULL sein, wenn eine Wiedergabeliste oder ein Album erstellt wird.

[in] pwszFileDest

Optionaler Dateiname auf dem Gerät. Wenn nicht angegeben und die Anwendung einen IWMDMOperation-Zeiger an pOperation übergibt, fordert Windows Media Geräte-Manager einen Zielnamen an, indem IWMDMOperation::GetObjectName aufgerufen wird. Wenn nicht angegeben und die Anwendung pOperation nicht verwendet, werden der ursprüngliche Dateiname und die ursprüngliche Erweiterung (ohne Pfad) verwendet.

[in] pOperation

Optionaler Zeiger auf eine IWMDMOperation-Schnittstelle , um die Übertragung von Inhalten auf ein Mediengerät zu steuern. Wenn angegeben, muss fuMode das flag WMDM_CONTENT_OPERATIONINTERFACE enthalten. Dieser Parameter muss NULL sein, wenn WMDM_CONTENT_FILE oder WMDM_CONTENT_FOLDER in fuMode angegeben ist.

[in] pProgress

Optionaler Zeiger auf eine IWMDMProgress-Schnittstelle , um den Aktionsfortschritt zurück an die Anwendung zu melden. Dieser Parameter kann NULL sein.

[in] pMetaData

Optionaler Zeiger auf ein Metadatenobjekt. Erstellen Sie ein neues Metadatenobjekt, indem Sie IWMDMStorage3::CreateEmptyMetadataObject aufrufen. Mit diesem Parameter kann eine Anwendung Metadaten (einschließlich Format) angeben, die während der Objekterstellung auf dem Gerät festgelegt werden sollen, was effizienter ist als das Festlegen von Metadaten nachher. Sie müssen das Dateiformat festlegen (durch g_wszWMDMFormatCode angegeben). Wenn Sie den Formatcode einer Datei bei Verwendung dieser Methode nicht angeben, zeigt ein MTP-Gerät die Datei nicht als in seiner Benutzeroberfläche an, und Nicht-MTP-Geräte verhalten sich unvorhersehbar.

[in] pUnknown

Optionaler IUnknown-Zeiger eines benutzerdefinierten COM-Objekts, das an den Anbieter für sichere Inhalte übergeben werden soll. Dies ermöglicht es, benutzerdefinierte Informationen an einen sicheren Inhaltsanbieter zu übergeben, wenn die Anwendung über ausreichende Informationen zum Anbieter sicherer Inhalte verfügt.

[out] ppNewObject

Zeiger auf eine IWMDMStorage-Schnittstelle , die den neuen Inhalt enthält. Der Aufrufer muss diese Schnittstelle freigeben, wenn er damit fertig ist.

Rückgabewert

Die Methode gibt ein HRESULT zurück. Alle Schnittstellenmethoden in Windows Media Geräte-Manager können eine der folgenden Klassen von Fehlercodes zurückgeben:

Com-Standardfehlercodes
In HRESULT-Werte konvertierte Windows-Fehlercodes
Windows Media Geräte-Manager Fehlercodes

Eine ausführliche Liste möglicher Fehlercodes finden Sie unter Fehlercodes.

Hinweise

Obwohl Sie Metadaten für einen Speicher festlegen können, nachdem sie an das Gerät gesendet wurden, ist es effizienter, diese Informationen im pMetaData-Parameter dieser Methode festzulegen. Dadurch werden dem Gerät zusätzliche Informationen bereitgestellt, damit es die Datei entsprechend übertragen und behandeln kann (z. B. durch speichern sie an der richtigen Stelle) oder nützliche Informationen (z. B. eine vom Benutzer geschriebene Beschreibung eines Bilds) anzeigen kann.

Um Eigenschaften für ein WPD-Gerät (Windows Portable Devices) festzulegen, erstellt eine Anwendung ein IPortableDeviceValues-Objekt und legt jede Eigenschaft in dieser Auflistung fest. Anschließend würde die Anwendung die Auflistung in ein binary large object (BLOB) serialisieren. Sobald die Daten serialisiert sind, fügt die Anwendung sie dem IWMDMMetaData hinzu, auf den das pMetadata-Argument mit der g_wszWPDPassthroughPropertyValues Metadatenkonstante verweist.

Wenn das WMDM_MODE_THREAD-Flag angegeben ist, sollten Sie die Status der Vervollständigung erhalten, indem Sie entweder IWMDMProgress2::End2 oder IWMDMProgress3::End3 aufrufen. Diese Methoden stellen sicher, dass der Vorgang abgeschlossen ist, und geben auch ein HRESULT mit Erfolgs- oder Fehlerinformationen zurück.

Wenn eine Anwendung WMDM_MODE_THREAD verwendet und einen pProgress-Parameter ungleich NULL übergibt, muss die Anwendung sicherstellen, dass das Objekt, zu dem pProgress gehört, erst zerstört wird, wenn der Lesevorgang abgeschlossen ist, da Windows Media Geräte-Manager Statusbenachrichtigungen an dieses Objekt sendet. Dieses Objekt kann erst zerstört werden, nachdem es eine Endbenachrichtigung erhalten hat. Wenn dies nicht geschieht, werden Zugriffsverletzungen verursacht.

Beim Erstellen einer Wiedergabeliste oder eines anderen Verweisobjekts enthält das "eingefügte" Objekt eigentlich keine Daten, sondern wird einfach auf dem Gerät als Gruppe von Metadatenverweise auf andere Objekte (z. B. Musikdateien) gespeichert. Das Erstellen eines solchen "abstrakten" Objekts in der Wiedergabeliste wird unter Erstellen einer Wiedergabeliste auf dem Gerät beschrieben.

Beispiele

Die folgende C++-Funktion sendet eine Datei an ein Gerät. Im Rahmen der Übertragung müssen dem Speicher Metadaten hinzugefügt werden, um den neuen Speichertyp anzugeben.


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