Metode IBackgroundCopyFile2::SetRemoteName (bits2_0.h)

Mengubah nama jarak jauh menjadi URL baru dalam pekerjaan pengunduhan.

Sintaks

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Parameter

[in] Val

String yang dihentikan null yang berisi nama file di server. Untuk informasi tentang menentukan nama jarak jauh, lihat bagian Anggota RemoteName dan Keterangan dari struktur BG_FILE_INFO .

Menampilkan nilai

Metode ini mengembalikan nilai pengembalian berikut, serta nilai lainnya.

Menampilkan kode	Deskripsi
S_OK	Berhasil
E_INVALIDARG	Nama jarak jauh baru adalah URL yang tidak valid atau URL baru terlalu panjang (URL tidak boleh melebihi 2.200 karakter).
E_NOTIMPL	Anda tidak dapat memanggil metode ini untuk mengunggah atau mengunggah pekerjaan balasan; hanya panggil metode ini untuk mengunduh pekerjaan.
BG_E_INVALID_STATE	Status pekerjaan tidak dapat BG_JOB_STATE_CANCELLED atau BG_JOB_STATE_ACKNOWLEDGED.

Keterangan

Biasanya, Anda memanggil metode ini jika Anda ingin mengubah protokol yang digunakan untuk mentransfer file (misalnya, dari SMB ke HTTP) atau jika Anda ingin mengubah nama atau jalur file.

Metode ini tidak diserialisasikan ketika kembali. Untuk menserialisasikan perubahan, tangguhkan pekerjaan, panggil metode ini (jika mengubah beberapa file dalam pekerjaan, gunakan perulangan), dan lanjutkan pekerjaan. Memanggil metode IBackgroundCopyJob::Resume menserialisasikan perubahan.

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.

Jika nama jarak jauh mengidentifikasi jalur blok pesan server (SMB), tabel berikut mengidentifikasi kemungkinan kode kesalahan yang dapat terjadi setelah Anda melanjutkan pekerjaan. Kesalahan ini menempatkan pekerjaan dalam status BG_JOB_STATE_ERROR .

Kode kesalahan	Deskripsi
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND)	Direktori tidak ditemukan.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	File tidak ditemukan.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	Pengguna tidak memiliki akses ke file yang ditentukan dalam Val.

 

Contoh

Contoh berikut menunjukkan cara memanggil metode SetRemoteName untuk mengubah nama jarak jauh file. Contoh mengasumsikan variabel IBackgroundCopyJob , pJob, valid dan pekerjaan berisi satu atau beberapa file.

     IBackgroundCopyJob *pJob;
     IEnumBackgroundCopyFiles* pFiles = NULL;
     IBackgroundCopyFile* pFile = NULL;
     IBackgroundCopyFile2* pFile2 = NULL;
     WCHAR* pRemoteFileName = NULL;
     ULONG cFileCount = 0;

     hr = pJob->Suspend();
     hr = pJob->EnumFiles(&pFiles);
     if (SUCCEEDED(hr))
     {
          //Get the count of files in the job. 
          hr = pFiles->GetCount(&cFileCount);

          //Enumerate the files in the job.
          for (ULONG idx=0; idx<cFileCount; idx++)
          {
               hr = pFiles->Next(1, &pFile, NULL);
               if (S_OK == hr)
               {
                    //Get the local name of the file.
                    hr = pFile->GetRemoteName(&pRemoteFileName);
                    if (SUCCEEDED(hr))
                    {
                         //Determine if you want to replace the remote name of this file.
                         if (<CONDITIONGOESHERE>)
                         {
                              //Need to query the IBackgroundCopyFile interface for an IBackgroundCopyFile2
                              //interface pointer. The IBackgroundCopyFile2 interface contains the SetRemoteName method.
                              hr = pFile->QueryInterface(__uuidof(IBackgroundCopyFile2), (void**)&pFile2);
                              if (S_OK == hr)
                              {
                                   hr = pFile2->SetRemoteName(L"<NEWURLGOESHERE>");
                                   if (FAILED(hr))
                                   {
                                        //Handle error. 
                                        //Returns E_NOTIMPL if not a download job.
                                        //Returns E_INVALIDARG if invalid URL.
                                   }
                              }
                              else
                              {
                                   //handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
                                   //running on the computer is less than BITS 2.0.
                              }
                         }
                         CoTaskMemFree(pRemoteFileName); 
                    }    
                    pFile->Release(); 
                    pFile = NULL;
               }
               else
               {
                    //Handle error
                    break;
               }
          }

          pFiles->Release();
          pFiles = NULL;
     }

     hr = pJob->Resume(); //Force the job to serialize.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista, Windows XP dengan SP2, KB842773 pada 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

IBackgroundCopyJob3::ReplaceRemotePrefix