IBackgroundCopyJob3：：AddFileWithRanges 方法 (bits2_0.h)
将文件添加到下载作业，并指定要下载的文件的范围。
语法
HRESULT AddFileWithRanges(
[in] LPCWSTR RemoteUrl,
[in] LPCWSTR LocalName,
[in] DWORD RangeCount,
[in] BG_FILE_RANGE [] Ranges
);
参数
[in] RemoteUrl
以 Null 结尾的字符串，其中包含服务器上文件的名称。 有关指定远程名称的信息，请参阅BG_FILE_INFO结构的 RemoteName 成员和备注部分。
从 BITS 3.0 开始，范围不支持 SMB 协议。
BITS 2.5 和 2.0： BITS 支持范围的 SMB 协议。
[in] LocalName
以 Null 结尾的字符串，其中包含客户端上文件的名称。 有关指定本地名称的信息，请参阅 BG_FILE_INFO 结构的 LocalName 成员和备注部分。
[in] RangeCount
Ranges 中的元素数。
[in] Ranges
一个或多个 BG_FILE_RANGE 结构的数组，这些结构指定要下载的范围。 不要指定重复或重叠的范围。
返回值
此方法返回以下返回值以及其他返回值。
| 返回代码 | 说明 |
|---|---|
|
成功 |
|
由于以下原因之一，可能会收到此错误：
|
|
不能对上传或上传-答复作业调用此方法;仅对下载作业调用此方法。 |
|
用户没有权限写入客户端上的指定目录。 |
|
其中一个范围无效。 例如，InitialOffset 设置为 BG_LENGTH_TO_EOF。 |
|
不能指定重复或重叠的范围。
注意 范围按值的偏移量而不是长度进行排序。 如果输入的偏移量相同，但顺序相反，则返回此错误。 例如，如果按该顺序输入 100.5 和 100.0，则无法将文件添加到作业。
|
|
MaxRangesPerFile 组策略设置确定可以为文件指定多少个范围。 添加这些范围超出了 MaxRangesPerFile 限制。 |
|
作业的状态不能 BG_JOB_STATE_CANCELLED 或 BG_JOB_STATE_ACKNOWLEDGED。 |
注解
范围按给定的顺序写入 LocalName 文件。 例如，如果 Ranges 标识远程文件的字节 100-199、900-999 和 400-499，则本地文件的长度将为 300 字节。 本地文件的字节 0-99 将包含远程文件的字节 100-199，本地文件的字节 100-199 将包含远程文件的字节 900-999，本地文件的字节 200-299 将包含远程文件的字节 400-499。
下表标识了恢复作业后可能出现的错误代码。 这些错误会将作业置于BG_JOB_STATE_ERROR状态。
| 错误代码 | 说明 |
|---|---|
| BG_E_INVALID_SERVER_RESPONSE | BITS 不支持合并重复或重叠范围的服务器。 |
| BG_E_INVALID_RANGE | 其中一个范围超出了远程文件的边界。 |
| BG_E_INSUFFICIENT_RANGE_SUPPORT | 服务器不支持范围。 |
BITS 保证文件版本根据文件大小和日期 (，而不是根据文件传输的内容) 保持一致;但是，它不保证一组文件是一致的。 例如，如果在服务器上更新文件时，BITS 正在下载作业中两个文件中的第二个文件，则 BITS 将重新启动第二个文件的下载;但是，不会再次下载第一个文件。
默认情况下，用户最多可为文件添加 500 个范围。 此限制不适用于管理员或服务帐户。 若要更改默认值，请设置 MaxRangesPerFile 组策略。
在 Windows Vista 之前： 用户可以添加到作业的文件数没有限制。
为了提高已启用 Windows BranchCache 的文件传输的性能，建议将范围长度设置为至少 400 字节。
示例
以下示例演示如何调用 AddFileWithRanges 方法来指定要下载的文件的范围。 该示例假定 IBackgroundCopyJob 变量 pJob 有效。
IBackgroundCopyJob *pJob;
IBackgroundCopyJob3 *pJob3 = NULL;
DWORD dwRangeCount = 3; //Number of elements in Ranges.
BG_FILE_RANGE Ranges[] = {24, 17, //Array of ranges to download (offset and length).
111, BG_LENGTH_TO_EOF,
83, 7
};
//Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
//interface pointer. The IBackgroundCopyJob3 interface contains the AddFileWithRanges method.
hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
if (S_OK == hr)
{
pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.
//Add a file to the job and specify the ranges from the file to download.
hr = pJob3->AddFileWithRanges(L"<REMOTENAMEGOESHERE>", L"<LOCALNAMEGOESHERE>",
dwRangeCount, Ranges);
if (FAILED(hr))
{
//Handle error.
//Returns E_NOTIMPL if not a download job.
//Returns E_INVALIDARG if dwRangeCount is zero or the remote or local name is invalid.
//Returns BG_E_INVALID_RANGE if one of the ranges is invalid.
//Returns BG_E_OVERLAPPING_RANGES if you specify overlapping or duplicate ranges.
}
pJob3->Release(); //Release the interface if you are done with it.
}
else
{
//Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
//running on the computer is less than BITS 2.0.
}
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista、Windows SERVER 2003 上带有 SP2、KB842773 的 Windows XP 和 Windows XP |
| 最低受支持的服务器 | Windows Server 2008、Windows Server 2003 SP1 |
| 目标平台 | Windows |
| 标头 | bits2_0.h (包括 Bits.h) |
| Library | Bits.lib |
| DLL | BitsPrx3.dll |