IBackgroundCopyJob3：：ReplaceRemotePrefix 方法 (bits2_0.h)

  • 项目

将下载作业中所有远程名称的起始文本替换为指定的字符串。

语法

HRESULT ReplaceRemotePrefix(
  [in] LPCWSTR OldPrefix,
  [in] LPCWSTR NewPrefix
);

参数

[in] OldPrefix

以 Null 结尾的字符串，用于标识远程名称中要替换的文本。 文本必须从远程名称的开头开始。

[in] NewPrefix

包含替换文本的以 Null 结尾的字符串。

返回值

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

返回代码 说明
S_OK
 成功
S_FALSE
 找不到匹配项。
E_INVALIDARG
 应用 NewPrefix 会创建无效 URL 或新 URL 太长， (URL) 不能超过 2,200 个字符。

如果 OldPrefix 或 NewPrefix 为空字符串，则还可以接收此返回代码。
E_NOTIMPL
 不能为上传或上传-回复作业调用此方法;仅为下载作业调用此方法。
BG_E_INVALID_STATE
 作业的状态不能 BG_JOB_STATE_CANCELLED 或 BG_JOB_STATE_ACKNOWLEDGED。

注解

通常，在服务器不可用时，使用此方法更改远程名称的服务器部分，或者允许漫游用户连接到最近的服务器。 此方法更改作业中所有匹配的远程名称。 若要更改特定文件的远程名称，请使用 IBackgroundCopyFile2：：SetRemoteName 方法。

ReplaceRemotePrefix 方法对作业中的所有远程名称执行区分大小写的搜索。 如果远程名称的起始文本与 OldPrefix 中的字符串匹配，则 BITS 会将文本替换为 在 NewPrefix 中找到的字符串。 例如，若要更改“http://Server/Path/File.ext"设置为“http://NewServerName/Path/File.ext"，将 OldPrefix 设置为”http://Server"和 NewPrefix 为 “http://NewServerName"。 请注意，BITS 不会在搜索中执行区域设置转换。

如果新远程名称的时间戳或文件大小与以前的远程名称不同，或者新服务器不支持 http 远程名称) 检查点恢复 (，则 BITS 将重启下载。 否则，传输将从新服务器上的同一位置恢复。 BITS 不会重启已传输的文件。

可以使用此方法更改协议。 但是，生成的 URL 格式可能不正确。 例如，从 \Server\Dir\File.ext 更改为 http://Server\Dir\File.ext 可能无法解析。 请考虑改用 IBackgroundCopyFile2：：SetRemoteName 方法。

请注意，如果调用 IBackgroundCopyJobHttpOptions：：SetSecurityFlags 方法并设置 BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT 标志，此方法可能无法找到要更改的 URL。 如果 URL 已重定向，则此策略会将原始 URL 更改为最终的重定向 URL。

示例

以下示例演示如何调用 ReplaceRemotePrefix 方法来更改 URL 的服务器名称。 该示例假定 IBackgroundCopyJob 变量 pJob 有效，并且作业包含一个或多个文件。

     IBackgroundCopyJob *pJob;
     IBackgroundCopyJob3 *pJob3 = NULL;

     //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
     //interface pointer. The IBackgroundCopyJob3 interface contains the ReplaceRemotePrefix method.
     hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
     if (S_OK == hr)
     {
          pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

          //Identify the old and new remote name text. For example, "http://oldservername" and 
          //"http://newservername". For SMB, specify "\\\\oldservername" and "\\\\newservername".
          hr = pJob3->ReplaceRemotePrefix(L"<OLDSERVERNAMEGOESHERE>", L"<NEWSERVERNAMEGOESHERE>");
          if (S_FALSE == hr)
          {
               wprintf(L"The job does not contain files with a remote name that matches the prefix.\n");
          }
          else if (FAILED(hr))
          {
               //Handle error.
               //Returns E_NOTIMPL if not a download job.
               //Returns E_INVALIDARG if new prefix is empty or the resulting URL is invalid.
          }

          pJob3->Release();
     }
     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 XP（在 Windows Server 2003 和 Windows XP 上使用 SP2、KB842773）
最低受支持的服务器 Windows Server 2008、Windows Server 2003 SP1
目标平台 Windows
标头 bits2_0.h (包括 Bits.h)
Library Bits.lib
DLL BitsPrx3.dll

另请参阅

IBackgroundCopyFile2：：SetRemoteName

IBackgroundCopyJob3