将文件添加到作业

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

IBackgroundCopyJob::AddFile

将单个文件添加到作业。

IBackgroundCopyJob::AddFileSet

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

IBackgroundCopyJob3::AddFileWithRanges

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

将文件添加到作业时,请指定文件的远程名称和本地名称。 有关本地和远程文件名格式的详细信息,请参阅 BG _ FILE _ INFO 结构。

上传作业只能包含一个文件。 如果尝试将多个文件添加到上传作业 ,IBackgroundCopyJob::AddFileFileIBackgroundCopyJob::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 接口指针 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);
}