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 结构的数组，这些结构指定要下载的范围。 不要指定重复或重叠的范围。

返回值

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

返回代码 说明
S_OK
 成功
E_INVALIDARG
 由于以下原因之一，可能会收到此错误：
  • RangeCount 参数为零;必须指定一个或多个区域。
  • 本地或远程文件名无效。
  • 远程文件名使用不受支持的协议。
  • 本地文件名是使用相对路径指定的。
E_NOTIMPL
 不能对上传或上传-答复作业调用此方法;仅对下载作业调用此方法。
E_ACCESSDENIED
 用户没有权限写入客户端上的指定目录。
BG_E_INVALID_RANGE
 其中一个范围无效。 例如，InitialOffset 设置为 BG_LENGTH_TO_EOF。
BG_E_OVERLAPPING_RANGES
 不能指定重复或重叠的范围。
注意 范围按值的偏移量而不是长度进行排序。 如果输入的偏移量相同，但顺序相反，则返回此错误。 例如，如果按该顺序输入 100.5 和 100.0，则无法将文件添加到作业。
 
BG_E_TOO_MANY_RANGES_IN_FILE
 MaxRangesPerFile 组策略设置确定可以为文件指定多少个范围。 添加这些范围超出了 MaxRangesPerFile 限制。
BG_E_INVALID_STATE
 作业的状态不能 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

另请参阅

BG_FILE_RANGE

IBackgroundCopyFile2：：GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob：：AddFile