Metode IBackgroundCopyJob::AddFileSet (bits.h)

Artikel
03/14/2023

Menambahkan beberapa file ke pekerjaan.

Sintaks

HRESULT AddFileSet(
  [in] ULONG        cFileCount,
  [in] BG_FILE_INFO *pFileSet
);

Parameter

[in] cFileCount

Jumlah elemen dalam paFileSet.

[in] pFileSet

Array struktur BG_FILE_INFO yang mengidentifikasi nama file lokal dan jarak jauh dari file yang akan ditransfer.

Unggah pekerjaan dibatasi untuk satu file. Jika array berisi lebih dari satu elemen, atau pekerjaan sudah berisi file, metode mengembalikan BG_E_TOO_MANY_FILES.

Nilai kembali

Metode ini mengembalikan nilai HRESULT berikut, serta yang lain.

Menampilkan kode	Deskripsi
S_OK	File berhasil ditambahkan ke pekerjaan.
BG_E_TOO_MANY_FILES	Unggah pekerjaan hanya dapat berisi satu file; Anda tidak dapat menambahkan lebih dari satu file ke pekerjaan. Tidak ada file dalam array yang ditambahkan ke pekerjaan.
BG_E_TOO_MANY_FILES_IN_JOB	Pengaturan Kebijakan Grup MaxFilesPerJob menentukan berapa banyak file yang dapat dimuat pekerjaan. Menambahkan file ke pekerjaan melebihi batas MaxFilesPerJob.
E_INVALIDARG	Anda dapat menerima kesalahan ini karena salah satu alasan berikut: 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_ACCESSDENIED	Pengguna tidak memiliki izin untuk menulis ke direktori yang ditentukan pada klien.

Keterangan

Lebih efisien untuk memanggil metode AddFileSet saat menambahkan beberapa file ke pekerjaan daripada memanggil metode IBackgroundCopyJob::AddFile dalam perulangan. Untuk menambahkan satu file ke pekerjaan, panggil metode AddFile . Untuk informasi selengkapnya, lihat Menambahkan File ke Pekerjaan.

Untuk menambahkan file ke pekerjaan tempat BITS mengunduh rentang data dari file, panggil metode IBackgroundCopyJob3::AddFileWithRanges .

Unggah pekerjaan hanya dapat berisi satu file. Jika Anda menambahkan lebih dari satu file, metode akan mengembalikan BG_E_TOO_MANY_FILES.

Untuk unduhan, 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 pada saat file diperbarui di server, BITS memulai ulang pengunduhan file kedua; namun, file pertama tidak diunduh lagi.

Perhatikan bahwa jika Anda memiliki file yang diunduh dari server, Anda harus membuat URL baru untuk setiap versi baru file. Jika Anda menggunakan URL yang sama untuk versi baru file, beberapa server proksi dapat melayani data kedaluarsa dari cache mereka karena tidak memverifikasi dengan server asli jika file kedaluarsa.

Untuk unggahan, BITS menghasilkan kesalahan jika file lokal berubah saat file sedang ditransfer. Kode kesalahan BG_E_FILE_CHANGED dan konteksnya BG_ERROR_CONTEXT_LOCAL_FILE.

BITS mentransfer file dalam pekerjaan secara berurutan. Jika terjadi kesalahan saat mentransfer file, pekerjaan berpindah ke status kesalahan dan tidak ada lagi file dalam pekerjaan yang diproses sampai kesalahan diselesaikan.

Secara default, pengguna dapat menambahkan hingga 200 file ke pekerjaan. Batas ini tidak berlaku untuk administrator atau akun layanan. Untuk mengubah default, atur kebijakan grup MaxFilesPerJob .

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

Untuk masalah skalabilitas, lihat Praktik Terbaik Saat Menggunakan BITS.

Contoh

Contoh berikut menunjukkan cara menambahkan beberapa file ke pekerjaan pengunduhan. Contoh mengasumsikan penunjuk antarmuka IBackgroundCopyJob valid.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
int idx = 0;
int nCount = 0;  //Number of files to add to the job.
LPWSTR pszLocalName = NULL;
LPWSTR pszRemoteName = NULL;

//Set nCount to the number of files to transfer.

//Allocate a block of memory to contain the array of BG_FILE_INFO structures.
//The BG_FILE_INFO structure contains the local and remote names of the 
//file being transferred.
paFiles = (BG_FILE_INFO*) malloc(sizeof(BG_FILE_INFO) * nCount);
if (NULL == paFiles)
{
  //Handle error
}
else
{
  //Add local and remote file name pairs to the memory block. 
  for (idx=0; idx<nCount; idx++)
  {
    //Set pszLocalName to point to an LPWSTR that contains the local name or
    //allocate memory for pszLocalName and copy the local name to pszLocalName.
    (paFiles+idx)->LocalName = pszLocalName;

    //Set pszRemoteName to point to an LPWSTR that contains the remote name or
    //allocate memory for pszRemoteName and copy the remote name to pszRemoteName.
    (paFiles+idx)->RemoteName = pszRemoteName;
  }

  //Add the files to the job.
  hr = pJob->AddFileSet(nCount, paFiles);
  if (SUCCEEDED(hr))
  {
     //Do Something.
  }

  //Free the memory block for the array of BG_FILE_INFO structures. If you allocated
  //memory for the local and remote file names, loop through the array and free the
  //memory for the file names before you free paFiles.
  free(paFiles);
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP
Server minimum yang didukung	Windows Server 2003
Target Platform	Windows
Header	bits.h
Pustaka	Bits.lib
DLL	QmgrPrxy.dll