IWMDMStorageControl3::Insert3-Methode (mswmdm.h)

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.

[in] fuType

Einer der folgenden Typen, der den aktuellen Speicher angibt.

[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

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

Anforderungen

Weitere Informationen

Erstellen einer Wiedergabeliste auf dem Gerät

IWMDMDevice::GetStatus

IWMDMMetaData-Schnittstelle

IWMDMOperation-Schnittstelle

IWMDMProgress-Schnittstelle

IWMDMStorage-Schnittstelle

IWMDMStorageControl2::Insert2

IWMDMStorageControl3-Schnittstelle

Schreiben von Dateien auf das Gerät