IBackgroundCopyJob：：AddFile 方法 (bits.h)

将单个文件添加到作业。

语法

HRESULT AddFile(
  [in] LPCWSTR RemoteUrl,
  [in] LPCWSTR LocalName
);

[in] RemoteUrl

以 Null 结尾的字符串，其中包含服务器上文件的名称。有关指定远程名称的信息，请参阅BG_FILE_INFO结构的 RemoteName 成员和备注部分。

[in] LocalName

以 Null 结尾的字符串，其中包含客户端上文件的名称。有关指定本地名称的信息，请参阅 BG_FILE_INFO 结构的 LocalName 成员和备注部分。

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

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

若要一次向作业添加多个文件，请调用 IBackgroundCopyJob：：AddFileSet 方法。将多个文件添加到作业时调用 AddFileSet 方法比在循环中调用 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 时的最佳做法。

有关将单个文件添加到作业的示例，请参阅将文件添加到作业。