Metode IWMDMStorageControl3::Insert3 (mswmdm.h)

Artikel
03/15/2023

Metode Insert3 menempatkan konten ke dalam/di samping penyimpanan. Metode ini memperluas IWMDMStorageControl2::Insert2 dengan memungkinkan aplikasi untuk secara eksplisit menentukan metadata dan jenis objek yang dikirim.

Sintaks

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

Mode pemrosesan yang digunakan untuk operasi Insert3 . Tabel berikut mencantumkan mode pemrosesan yang dapat ditentukan dalam parameter fuMode . Anda harus menentukan salah satu dari dua mode pertama, tepat salah satu mode STORAGECONTROL, dan tepat salah satu mode CONTENT. Jika WMDM_MODE_BLOCK dan WMDM_MODE_THREAD ditentukan, mode blokir akan digunakan. Menentukan bendera WMDM_FILE_ATTR* dalam fungsi ini lebih efisien daripada memanggil fungsi ini terlebih dahulu, lalu mengatur atribut ini pada file setelah dibuat atau dikirim.

Kombinasi	Mode	Deskripsi
Tepat salah satu dari:	WMDM_MODE_BLOCK	Operasi dilakukan menggunakan pemrosesan mode blok. Panggilan tidak akan kembali sampai operasi selesai.
-	WMDM_MODE_THREAD	Operasi dilakukan menggunakan pemrosesan mode utas. Panggilan akan segera kembali, dan operasi dilakukan di utas latar belakang.
Opsional	WMDM_MODE_QUERY	Pengujian dilakukan untuk menentukan apakah operasi penyisipan dapat berhasil, tetapi sisipan tidak akan dilakukan.
Tepat salah satu dari:	WMDM_STORAGECONTROL_INSERTBEFORE	Objek disisipkan sebelum objek target.
-	WMDM_STORAGECONTROL_INSERTAFTER	Objek disisipkan setelah objek target.
-	WMDM_STORAGECONTROL_INSERTINTO	Objek disisipkan ke dalam objek saat ini. Ini hanya akan berfungsi jika objek saat ini adalah folder.
Opsional	WMDM_FILE_CREATE_OVERWRITE	Objek akan menggantikan objek target.
Tepat salah satu dari:	WMDM_CONTENT_FILE	Isi yang sedang disisipkan adalah file.
-	WMDM_CONTENT_FOLDER	Isi yang sedang disisipkan adalah folder. Ini tidak akan mentransfer isi folder.
Opsional	WMDM_CONTENT_OPERATIONINTERFACE	Aplikasi ini melewati antarmuka IWMDMOperation untuk mengontrol transfer data.
Nol atau lebih dari:	WMDM_FILE_ATTR_READONLY	Penyimpanan harus diatur ke baca-saja di perangkat.
-	WMDM_FILE_ATTR_HIDDEN	Penyimpanan harus diatur ke disembunyikan pada perangkat.
-	WMDM_FILE_ATTR_SYSTEM	Penyimpanan harus diatur ke sistem pada perangkat.
Opsional	WMDM_MODE_PROGRESS	Penyisipan sedang berlangsung.
Opsional salah satu dari:	WMDM_MODE_TRANSFER_PROTECTED	Penyisipan dalam mode transfer terproteksi.
-	WMDM_MODE_TRANSFER_UNPROTECTED	Penyisipan dalam mode transfer yang tidak terlindungi.

[in] fuType

Salah satu jenis berikut, menentukan penyimpanan saat ini.

Nilai	Deskripsi
WMDM_FILE_ATTR_FILE	Penyimpanan saat ini adalah file.
WMDM_FILE_ATTR_FOLDER	Penyimpanan saat ini adalah folder.

[in] pwszFileSource

Penunjuk ke string karakter lebar dan dihentikan null yang menunjukkan tempat menemukan konten untuk operasi penyisipan. Parameter ini harus NULL jika WMDM_CONTENT_OPERATIONINTERFACE ditentukan dalam fuMode. Parameter ini bisa null jika daftar putar atau album sedang dibuat.

[in] pwszFileDest

Nama opsional file pada perangkat. Jika tidak ditentukan dan aplikasi meneruskan penunjuk IWMDMOperation ke pOperation, Windows Media Device Manager akan meminta nama tujuan dengan memanggil IWMDMOperation::GetObjectName. Jika tidak ditentukan dan aplikasi tidak menggunakan pOperation, nama file dan ekstensi asli digunakan (tanpa jalur).

[in] pOperation

Penunjuk opsional ke antarmuka IWMDMOperation , untuk mengontrol transfer konten ke perangkat media. Jika ditentukan, fuMode harus menyertakan bendera WMDM_CONTENT_OPERATIONINTERFACE. Parameter ini harus NULL jika WMDM_CONTENT_FILE atau WMDM_CONTENT_FOLDER ditentukan dalam fuMode.

[in] pProgress

Penunjuk opsional ke antarmuka IWMDMProgress untuk melaporkan kemajuan tindakan kembali ke aplikasi. Parameter ini bisa NULL.

[in] pMetaData

Penunjuk opsional ke objek metadata. Buat objek metadata baru dengan memanggil IWMDMStorage3::CreateEmptyMetadataObject. Parameter ini memungkinkan aplikasi untuk menentukan metadata (termasuk format) untuk diatur pada perangkat selama pembuatan objek pada perangkat, yang lebih efisien daripada mengatur metadata setelahnya. Anda harus mengatur format file (ditentukan oleh g_wszWMDMFormatCode). Jika Anda tidak menentukan kode format file saat menggunakan metode ini, perangkat MTP tidak akan menampilkan file seperti yang ada di antarmuka penggunanya, dan perangkat non-MTP akan berpotensi tidak terduga.

[in] pUnknown

Penunjuk IUnknown opsional dari objek COM kustom apa pun yang akan diteruskan ke penyedia konten aman. Hal ini memungkinkan untuk meneruskan informasi kustom ke penyedia konten yang aman jika aplikasi memiliki informasi yang memadai tentang penyedia konten yang aman.

[out] ppNewObject

Penunjuk ke antarmuka IWMDMStorage yang akan berisi konten baru. Pemanggil harus merilis antarmuka ini setelah selesai.

Nilai kembali

Metode mengembalikan HRESULT. Semua metode antarmuka di Windows Media Device Manager dapat mengembalikan salah satu kelas kode kesalahan berikut:

Kode kesalahan COM standar
Kode kesalahan Windows dikonversi ke nilai HRESULT
Kode kesalahan Pengelola Perangkat Windows Media

Untuk daftar ekstensif kemungkinan kode kesalahan, lihat Kode Kesalahan.

Keterangan

Meskipun Anda dapat mengatur metadata pada penyimpanan setelah mengirimkannya ke perangkat, lebih efisien untuk mengatur informasi ini dalam parameter pMetaData dari metode ini. Melakukannya memberikan informasi tambahan kepada perangkat untuk memungkinkannya mentransfer dan menangani file dengan tepat (misalnya, dengan menyimpannya di tempat yang benar) atau menampilkan informasi yang berguna (seperti deskripsi gambar yang ditulis pengguna).

Untuk mengatur properti untuk perangkat Windows Portable Devices (WPD), aplikasi akan membuat objek IPortableDeviceValues dan mengatur setiap properti ke dalam koleksi ini. Kemudian, aplikasi akan membuat serialisasi koleksi ke objek besar biner (BLOB). Setelah data diserialisasikan, aplikasi akan menambahkannya ke IWMDMMetaData yang dirujuk oleh argumen pMetadata menggunakan konstanta metadata g_wszWPDPassthroughPropertyValues.

Jika bendera WMDM_MODE_THREAD ditentukan, Anda harus mendapatkan status penyelesaian dengan memanggil IWMDMProgress2::End2 atau IWMDMProgress3::End3. Metode ini akan memastikan bahwa operasi selesai dan juga akan mengembalikan HRESULT dengan informasi keberhasilan atau kegagalan.

Jika aplikasi menggunakan WMDM_MODE_THREAD dan melewati parameter pProgressnon-null, aplikasi harus memastikan bahwa objek tempat pProgress berada tidak dihancurkan sampai operasi baca selesai, karena Windows Media Device Manager akan mengirim pemberitahuan kemajuan ke objek ini. Objek ini dapat dihancurkan hanya setelah menerima pemberitahuan akhir. Kegagalan untuk melakukan ini akan mengakibatkan pelanggaran akses.

Saat membuat daftar putar atau objek referensi lainnya, objek yang "dimasukkan" sebenarnya tidak berisi data tetapi hanya disimpan di perangkat sebagai sekelompok referensi metadata ke objek lain (seperti file musik). Membuat objek "abstrak" seperti itu pada daftar putar dijelaskan dalam Membuat Daftar Putar pada Perangkat.

Contoh

Fungsi C++ berikut mengirimkan file ke perangkat. Sebagai bagian dari transfer, ia harus menambahkan metadata ke penyimpanan untuk menentukan jenis penyimpanan baru.


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