将文件添加到作业

作业包含一个或多个要传输的文件。 使用以下方法之一将文件添加到作业中：

IBackgroundCopyJob::AddFile

将单个文件添加到作业。

IBackgroundCopyJob::AddFileSet

将一个或多个文件添加到作业中。 如果要添加多个文件，则调用此方法比在循环中调用 AddFile 方法更有效。

IBackgroundCopyJob3::AddFileWithRanges

将单个文件添加到作业。 如果要从文件下载数据范围，请使用此方法。 只能将此方法用于下载作业。

将文件添加到作业时，可以指定远程名称和文件的本地名称。 有关本地和远程文件名的格式的详细信息，请参阅 BG_FILE_INFO 结构。

上传作业只能包含一个文件。 如果尝试将多个文件添加到上传作业，则 IBackgroundCopyJob::AddFile 和 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 在创建临时文件时不指定安全描述符（该文件从目标目录继承 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 接口指针有效，本地名称和远程名称来自用户界面中的列表。

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