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 |
---|---|
|
Berhasil |
|
Nama jarak jauh baru adalah URL yang tidak valid atau URL baru terlalu panjang (URL tidak boleh melebihi 2.200 karakter). |
|
Anda tidak dapat memanggil metode ini untuk mengunggah atau mengunggah pekerjaan balasan; hanya panggil metode ini untuk mengunduh pekerjaan. |
|
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 |