Metode IBackgroundCopyJob3::ReplaceRemotePrefix (bits2_0.h)

Mengganti teks awal semua nama jarak jauh dalam pekerjaan pengunduhan dengan string yang ditentukan.

Sintaks

HRESULT ReplaceRemotePrefix(
  [in] LPCWSTR OldPrefix,
  [in] LPCWSTR NewPrefix
);

Parameter

[in] OldPrefix

String yang dihentikan null yang mengidentifikasi teks untuk diganti dalam nama jarak jauh. Teks harus dimulai di awal nama jarak jauh.

[in] NewPrefix

String yang dihentikan null yang berisi teks pengganti.

Menampilkan nilai

Metode ini mengembalikan nilai pengembalian berikut, serta yang lain.

Menampilkan kode	Deskripsi
S_OK	Berhasil
S_FALSE	Tidak ditemukan kecocokan.
E_INVALIDARG	Menerapkan NewPrefix membuat URL yang tidak valid atau URL baru terlalu panjang (URL tidak boleh melebihi 2.200 karakter). Anda juga dapat menerima kode pengembalian ini jika OldPrefix atau NewPrefix adalah string kosong.
E_NOTIMPL	Anda tidak dapat memanggil metode ini untuk mengunggah atau mengunggah pekerjaan balasan; panggil metode ini hanya untuk mengunduh pekerjaan.
BG_E_INVALID_STATE	Status pekerjaan tidak dapat BG_JOB_STATE_CANCELLED atau BG_JOB_STATE_ACKNOWLEDGED.

Keterangan

Biasanya, Anda menggunakan metode ini untuk mengubah bagian server dari nama jarak jauh ketika server tidak tersedia atau membiarkan pengguna roaming terhubung ke server terdekat. Metode ini mengubah semua nama jarak jauh yang cocok dalam pekerjaan. Untuk mengubah nama jarak jauh file tertentu, gunakan metode IBackgroundCopyFile2::SetRemoteName .

Metode ReplaceRemotePrefix melakukan pencarian peka huruf besar/kecil dari semua nama jarak jauh dalam pekerjaan. Jika teks awal nama jarak jauh cocok dengan string di OldPrefix, BITS mengganti teks dengan string yang ditemukan di NewPrefix. Misalnya, untuk mengubah "http://Server/Path/File.ext" ke "http://NewServerName/Path/File.ext", atur OldPrefix ke "http://Server" dan NewPrefix ke "http://NewServerName". Perhatikan bahwa BITS tidak melakukan konversi lokal dalam pencarian.

Jika stempel waktu atau ukuran file dari nama jarak jauh baru berbeda dari nama jarak jauh sebelumnya atau server baru tidak mendukung resume titik pemeriksaan (untuk nama jarak jauh HTTP), BITS memulai ulang unduhan. Jika tidak, transfer dilanjutkan dari posisi yang sama di server baru. BITS tidak memulai ulang file yang sudah ditransfer.

Anda dapat menggunakan metode ini untuk mengubah protokol. Namun, URL yang dihasilkan mungkin tidak terbentuk dengan baik. Misalnya, mengubah dari \Server\Dir\File.ext ke http://Server\Dir\File.ext mungkin tidak teratasi. Pertimbangkan untuk menggunakan metode IBackgroundCopyFile2::SetRemoteName sebagai gantinya.

Perhatikan bahwa metode ini mungkin tidak menemukan URL untuk diubah jika Anda memanggil metode IBackgroundCopyJobHttpOptions::SetSecurityFlags dan mengatur bendera BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT . Kebijakan ini mengubah URL asli ke URL akhir yang dialihkan jika URL dialihkan.

Contoh

Contoh berikut menunjukkan cara memanggil metode ReplaceRemotePrefix untuk mengubah nama server URL. Contoh mengasumsikan variabel IBackgroundCopyJob , pJob, valid dan pekerjaan berisi satu atau beberapa file.

     IBackgroundCopyJob *pJob;
     IBackgroundCopyJob3 *pJob3 = NULL;

     //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
     //interface pointer. The IBackgroundCopyJob3 interface contains the ReplaceRemotePrefix method.
     hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
     if (S_OK == hr)
     {
          pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

          //Identify the old and new remote name text. For example, "http://oldservername" and 
          //"http://newservername". For SMB, specify "\\\\oldservername" and "\\\\newservername".
          hr = pJob3->ReplaceRemotePrefix(L"<OLDSERVERNAMEGOESHERE>", L"<NEWSERVERNAMEGOESHERE>");
          if (S_FALSE == hr)
          {
               wprintf(L"The job does not contain files with a remote name that matches the prefix.\n");
          }
          else if (FAILED(hr))
          {
               //Handle error.
               //Returns E_NOTIMPL if not a download job.
               //Returns E_INVALIDARG if new prefix is empty or the resulting URL is invalid.
          }

          pJob3->Release();
     }
     else
     {
          //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
          //running on the computer is less than BITS 2.0.
     }

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista, Windows XP dengan SP2,KB842773 di Windows Server 2003, dan Windows XP
Server minimum yang didukung	Windows Server 2008, Windows Server 2003 dengan SP1
Target Platform	Windows
Header	bits2_0.h (termasuk Bits.h)
Pustaka	Bits.lib
DLL	BitsPrx3.dll

Lihat juga

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3