將檔案新增至作業

作業包含您想要傳輸的一或多個檔案。 使用下列其中一種方法將檔案新增至作業：

IBackgroundCopyJob：：AddFile

將單一檔案新增至作業。

IBackgroundCopyJob：：AddFileSet

將一或多個檔案新增至作業。 如果您要新增多個檔案，呼叫此方法比在迴圈中呼叫 AddFile 方法更有效率。

IBackgroundCopyJob3：：AddFileWithRanges

將單一檔案新增至作業。 如果您想要從檔案下載數據範圍，請使用此方法。 您只能將這個方法用於下載作業。

當您將檔案新增至作業時，您可以指定遠端名稱和檔案的本機名稱。 如需本機和遠端檔名格式的詳細資訊，請參閱 BG_FILE_INFO 結構。

上傳作業只能包含一個檔案。 如果您嘗試將多個檔案新增至上傳作業，IBackgroundCopyJob：：AddFileSet 方法會傳回BG_E_TOO_MANY_FILES。 如果您需要上傳多個檔案，請考慮使用 CAB 或 ZIP 檔案。

對於下載作業，BITS 會將使用者可以新增至作業的檔案數目限制為 200 個檔案，並將檔案的範圍數目限制為 500 個範圍。 這些限制不適用於系統管理員或服務。 若要變更這些預設限制，請參閱 組策略。

作業的擁有者或具有系統管理員許可權的使用者，可以在呼叫 IBackgroundCopyJob：：Complete 方法或 IBackgroundCopyJob：：Cancel 方法之前，隨時將檔案新增至作業。

如果您需要在將檔案新增至作業之後變更檔案的遠端名稱，您可以呼叫 IBackgroundCopyJob3：：ReplaceRemotePrefix 方法或 IBackgroundCopyFile2：：SetRemoteName 方法。 使用 ReplaceRemotePrefix 方法，在伺服器無法使用或讓漫遊用戶連線到最接近的伺服器時，變更遠端名稱的伺服器部分。 使用 SetRemoteName 方法來變更用來傳輸檔案的通訊協定，或變更檔名或路徑。

BITS 會在目的地目錄中建立暫存盤，並使用暫存盤進行文件傳輸。 若要取得暫存檔名，請呼叫 IBackgroundCopyFile3：：GetTemporaryName 方法。 當您呼叫 Complete 方法時，BITS 會將暫存檔名變更為目的地檔名。 當 BITS 建立暫存盤時，BITS 不會指定安全性描述元（檔案會從目的地目錄繼承 ACL 資訊）。 如果傳輸的數據很敏感，應用程式應該在目的地目錄上指定適當的 ACL，以防止未經授權的存取。

若要使用傳輸的檔案維護擁有者和 ACL 資訊，請呼叫 IBackgroundCopyJob3：：SetFileACLFlags 方法。

作業的擁有者（建立作業的使用者或擁有作業擁有權的系統管理員）必須擁有伺服器上檔案以及客戶端的許可權。 例如，若要下載檔案，用戶必須具有伺服器的讀取許可權，以及用戶端上本機目錄的寫入許可權。

下列範例示範如何將單一檔案新增至作業。 此範例假設 IBackgroundCopyJob 介面指標 pJob 有效。

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.
}

下列範例示範如何將多個檔案新增至作業。 此範例假設 IBackgroundCopyJob 介面指標 pJob 有效，而且本機和遠端名稱來自使用者介面中的清單。

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