Menambahkan File ke Pekerjaan

Pekerjaan berisi satu atau beberapa file yang ingin Anda transfer. Gunakan salah satu metode berikut untuk menambahkan file ke pekerjaan:

IBackgroundCopyJob::AddFile

Menambahkan satu file ke pekerjaan.

IBackgroundCopyJob::AddFileSet

Menambahkan satu atau beberapa file ke pekerjaan. Jika Anda menambahkan beberapa file, lebih efisien untuk memanggil metode ini daripada memanggil metode AddFile dalam perulangan.

IBackgroundCopyJob3::AddFileWithRanges

Menambahkan satu file ke pekerjaan. Gunakan metode ini jika Anda ingin mengunduh rentang data dari file. Anda hanya dapat menggunakan metode ini untuk mengunduh pekerjaan.

Saat menambahkan file ke pekerjaan, Anda menentukan nama jarak jauh dan nama lokal file. Untuk detail tentang format nama file lokal dan jarak jauh, lihat struktur BG_FILE_INFO.

Pekerjaan unggahan hanya dapat berisi satu file. Metode IBackgroundCopyJob::AddFile dan IBackgroundCopyJob::AddFileSet mengembalikan BG_E_TOO_MANY_FILES jika Anda mencoba menambahkan lebih dari satu file ke pekerjaan pengunggahan. Jika Anda perlu mengunggah lebih dari satu file, pertimbangkan untuk menggunakan file CAB atau ZIP.

Untuk pekerjaan pengunduhan, BITS membatasi jumlah file yang dapat ditambahkan pengguna ke pekerjaan ke 200 file dan jumlah rentang untuk file hingga rentang 500. Batas ini tidak berlaku untuk administrator atau layanan. Untuk mengubah batas default ini, lihat Kebijakan Grup.

Pemilik pekerjaan atau pengguna dengan hak istimewa administrator dapat menambahkan file ke pekerjaan kapan saja sebelum memanggil metode IBackgroundCopyJob::Complete atau metode IBackgroundCopyJob::Cancel.

Jika Anda perlu mengubah nama file jarak jauh setelah menambahkan file ke pekerjaan, Anda dapat memanggil metode IBackgroundCopyJob3::ReplaceRemotePrefix atau metode IBackgroundCopyFile2::SetRemoteName. Gunakan metode ReplaceRemotePrefix untuk mengubah bagian server dari nama jarak jauh ketika server tidak tersedia atau untuk membiarkan pengguna roaming terhubung ke server terdekat. Gunakan metode SetRemoteName untuk mengubah protokol yang digunakan untuk mentransfer file atau untuk mengubah nama atau jalur file.

BITS membuat file sementara di direktori tujuan dan menggunakan file sementara untuk transfer file. Untuk mendapatkan nama file sementara, panggil metode IBackgroundCopyFile3::GetTemporaryName. BITS mengubah nama file sementara ke nama file tujuan saat Anda memanggil metode Lengkap. BITS tidak menentukan deskriptor keamanan saat membuat file sementara (file mewarisi informasi ACL dari direktori tujuan). Jika data yang ditransfer sensitif, aplikasi harus menentukan ACL yang sesuai pada direktori tujuan untuk mencegah akses yang tidak sah.

Untuk mempertahankan informasi pemilik dan ACL dengan file yang ditransfer, panggil metode IBackgroundCopyJob3::SetFileACLFlags.

Pemilik pekerjaan (pengguna yang membuat pekerjaan atau administrator yang mengambil kepemilikan pekerjaan) harus memiliki izin ke file di server serta klien. Misalnya, untuk mengunduh file, pengguna harus memiliki izin baca di server dan menulis izin ke direktori lokal pada klien.

Contoh berikut menunjukkan cara menambahkan satu file ke pekerjaan. Contoh mengasumsikan penunjuk antarmuka IBackgroundCopyJob , pJob, valid.

HRESULT hr;
IBackgroundCopyJob* pJob;

//Replace parameters with variables that contain valid paths.
hr = pJob->AddFile(L"https://ServerName/Path/File.Ext", L"d:\\Path\\File.Ext");
if (SUCCEEDED(hr))
{
  //Do something.
}

Contoh berikut menunjukkan cara menambahkan beberapa file ke pekerjaan. Contoh mengasumsikan penunjuk antarmuka IBackgroundCopyJob , pJob, valid dan nama lokal dan jarak jauh berasal dari daftar di antarmuka pengguna.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
ULONG idx = 0;
ULONG nCount = 0;            //Set to the number of files to add to the job.
LPWSTR pszLocalName = NULL;  //Comes from the list in the user interface.
LPWSTR pszRemoteName = NULL; //Comes from the list in the user interface.

//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);
}