IBackgroundCopyJob：：AddFileSet 方法 (bits.h)

项目
08/22/2023

将多个文件添加到作业。

语法

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

参数

[in] cFileCount

paFileSet 中的元素数。

[in] pFileSet

BG_FILE_INFO结构的数组，用于标识要传输的文件的本地和远程文件名。

上传作业仅限于单个文件。如果数组包含多个元素，或者作业已包含文件，则方法返回BG_E_TOO_MANY_FILES。

返回值

此方法返回以下 HRESULT 值以及其他值。

返回代码	说明
S_OK	文件已成功添加到作业。
BG_E_TOO_MANY_FILES	上传作业只能包含一个文件;不能向作业添加多个文件。数组中的文件均未添加到作业。
BG_E_TOO_MANY_FILES_IN_JOB	MaxFilesPerJob 组策略设置确定作业可以包含的文件数。将文件添加到作业超出了 MaxFilesPerJob 限制。
E_INVALIDARG	由于以下原因之一，可能会收到此错误：本地或远程文件名无效。远程文件名使用不受支持的协议。本地文件名是使用相对路径指定的。
E_ACCESSDENIED	用户无权写入客户端上的指定目录。

注解

将多个文件添加到作业时调用 AddFileSet 方法比在循环中调用 IBackgroundCopyJob：：AddFile 方法更高效。若要将单个文件添加到作业，请调用 AddFile 方法。有关详细信息，请参阅将文件添加到作业。

若要将文件添加到 BITS 从中下载文件数据范围的作业，请调用 IBackgroundCopyJob3：：AddFileWithRanges 方法。

上传作业只能包含一个文件。如果添加多个文件，该方法将返回BG_E_TOO_MANY_FILES。

对于下载，BITS 保证文件版本 (基于文件大小和日期，而不是传输的内容) 一致;但是，它不保证一组文件是一致的。例如，如果在服务器上更新文件时 BITS 正在下载两个文件中的第二个文件，则 BITS 将重新启动第二个文件的下载;但是，不会再次下载第一个文件。

请注意，如果您拥有从服务器下载的文件，则应为每个新版本的文件创建一个新 URL。如果对新版本的文件使用相同的 URL，某些代理服务器可能会从其缓存中提供过时数据，因为它们不会向原始服务器验证文件是否过时。

对于上传，如果在传输文件时本地文件发生更改，BITS 将生成错误。错误代码BG_E_FILE_CHANGED，上下文BG_ERROR_CONTEXT_LOCAL_FILE。

BITS 按顺序传输作业中的文件。如果在传输文件时出错，作业将进入错误状态，在解决错误之前不会处理作业中的更多文件。

默认情况下，用户最多可向作业添加 200 个文件。此限制不适用于管理员或服务帐户。若要更改默认值，请设置 MaxFilesPerJob 组策略。

在 Windows Vista 之前： 用户可以添加到作业的文件数没有限制。

有关可伸缩性问题，请参阅使用 BITS 时的最佳做法。

示例

以下示例演示如何将多个文件添加到下载作业。该示例假定 IBackgroundCopyJob 接口指针有效。

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

要求

要求	值
最低受支持的客户端	Windows XP
最低受支持的服务器	Windows Server 2003
目标平台	Windows
标头	bits.h
Library	Bits.lib
DLL	QmgrPrxy.dll