Metode IBackgroundCopyJob3::AddFileWithRanges (bits2_0.h)

  • Artikel

Menambahkan file ke pekerjaan pengunduhan dan menentukan rentang file yang ingin Anda unduh.

Sintaks

HRESULT AddFileWithRanges(
  [in] LPCWSTR          RemoteUrl,
  [in] LPCWSTR          LocalName,
  [in] DWORD            RangeCount,
  [in] BG_FILE_RANGE [] Ranges
);

Parameter

[in] RemoteUrl

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

Dimulai dengan BITS 3.0, protokol SMB tidak didukung untuk rentang.

BITS 2.5 dan 2.0: BITS mendukung protokol SMB untuk rentang.

[in] LocalName

String yang dihentikan null yang berisi nama file pada klien. Untuk informasi tentang menentukan nama lokal, lihat bagian Anggota LocalName dan Keterangan dari struktur BG_FILE_INFO .

[in] RangeCount

Jumlah elemen dalam Rentang.

[in] Ranges

Array dari satu atau beberapa struktur BG_FILE_RANGE yang menentukan rentang yang akan diunduh. Jangan tentukan rentang duplikat atau tumpang tindih.

Menampilkan nilai

Metode ini mengembalikan nilai pengembalian berikut, serta yang lain.

Menampilkan kode Deskripsi
S_OK
 Berhasil
E_INVALIDARG
 Anda dapat menerima kesalahan ini karena salah satu alasan berikut:
  • Parameter RangeCount adalah nol; Anda harus menentukan satu atau beberapa rentang.
  • Nama file lokal atau jarak jauh tidak valid.
  • Nama file jarak jauh menggunakan protokol yang tidak didukung.
  • Nama file lokal ditentukan menggunakan jalur relatif.
E_NOTIMPL
 Anda tidak dapat memanggil metode ini untuk mengunggah atau mengunggah pekerjaan balasan; hanya panggil metode ini untuk mengunduh pekerjaan.
E_ACCESSDENIED
 Pengguna tidak memiliki izin untuk menulis ke direktori yang ditentukan pada klien.
BG_E_INVALID_RANGE
 Salah satu rentang tidak valid. Misalnya, InitialOffset diatur ke BG_LENGTH_TO_EOF.
BG_E_OVERLAPPING_RANGES
 Anda tidak dapat menentukan rentang duplikat atau tumpang tindih.
Catatan Rentang diurutkan berdasarkan offset nilai, bukan panjangnya. Jika rentang dimasukkan yang memiliki offset yang sama, tetapi berada dalam urutan terbalik, maka kesalahan ini akan dikembalikan. Misalnya, jika 100.5 dan 100.0 dimasukkan dalam urutan tersebut, maka Anda tidak akan dapat menambahkan file ke pekerjaan.
 
BG_E_TOO_MANY_RANGES_IN_FILE
 Pengaturan Kebijakan Grup MaxRangesPerFile menentukan berapa banyak rentang yang dapat Anda tentukan untuk file. Menambahkan rentang ini melebihi batas MaxRangesPerFile.
BG_E_INVALID_STATE
 Status pekerjaan tidak dapat BG_JOB_STATE_CANCELLED atau BG_JOB_STATE_ACKNOWLEDGED.

Keterangan

Rentang ditulis ke file LocalName dalam urutan yang diberikan. Misalnya, jika Rentang mengidentifikasi byte 100-199, 900-999, dan 400-499 dari file jarak jauh, file lokal akan memiliki panjang 300 byte. Byte 0-99 dari file lokal akan berisi byte 100-199 dari file jarak jauh, byte 100-199 dari file lokal akan berisi byte 900-999 dari file jarak jauh, dan byte 200-299 dari file lokal akan berisi byte 400-499 dari file jarak jauh.

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
BG_E_INVALID_SERVER_RESPONSE BITS tidak mendukung server yang mengonsolidasikan rentang duplikat atau tumpang tindih.
BG_E_INVALID_RANGE Salah satu rentang berada di luar batas file jarak jauh.
BG_E_INSUFFICIENT_RANGE_SUPPORT Server tidak mendukung rentang.
 

BITS menjamin bahwa versi file (berdasarkan ukuran dan tanggal file, bukan konten) yang ditransfernya akan konsisten; namun, itu tidak menjamin bahwa sekumpulan file akan konsisten. Misalnya, jika BITS berada di tengah-tengah mengunduh file kedua dari dua file dalam pekerjaan pada saat file diperbarui di server, BITS memulai ulang pengunduhan file kedua; namun, file pertama tidak diunduh lagi.

Secara default, pengguna dapat menambahkan hingga 500 rentang untuk file. Batas ini tidak berlaku untuk administrator atau akun layanan. Untuk mengubah default, atur kebijakan grup MaxRangesPerFile .

Sebelum Windows Vista: Tidak ada batasan jumlah file yang dapat ditambahkan pengguna ke pekerjaan.

Untuk performa yang lebih baik pada transfer file yang mendukung Windows BranchCache, disarankan agar Anda mengatur panjang rentang menjadi setidaknya 400 byte.

Contoh

Contoh berikut menunjukkan cara memanggil metode AddFileWithRanges untuk menentukan rentang file yang akan diunduh. Contoh mengasumsikan variabel IBackgroundCopyJob , pJob, valid.

    IBackgroundCopyJob *pJob;
    IBackgroundCopyJob3 *pJob3 = NULL;
    DWORD dwRangeCount = 3;                  //Number of elements in Ranges.
    BG_FILE_RANGE Ranges[] = {24, 17,        //Array of ranges to download (offset and length).
                              111, BG_LENGTH_TO_EOF,
                              83, 7
                             };

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

         //Add a file to the job and specify the ranges from the file to download.
         hr = pJob3->AddFileWithRanges(L"<REMOTENAMEGOESHERE>", L"<LOCALNAMEGOESHERE>",
                                       dwRangeCount, Ranges);
         if (FAILED(hr))
         {
              //Handle error.
              //Returns E_NOTIMPL if not a download job.
              //Returns E_INVALIDARG if dwRangeCount is zero or the remote or local name is invalid.
              //Returns BG_E_INVALID_RANGE if one of the ranges is invalid.
              //Returns BG_E_OVERLAPPING_RANGES if you specify overlapping or duplicate ranges.
         }

          pJob3->Release(); //Release the interface if you are done with it.
     }
    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

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile