IBackgroundCopyJob3：：ReplaceRemotePrefix 方法 （bits2_0.h）

將下載作業中所有遠端名稱的開頭文字替換為指定的字串。

語法

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

參數

[in] OldPrefix

空終端字串，用來識別要替換到遠端名稱中的文字。 文字必須從遠端名稱的開頭開始。

[in] NewPrefix

包含替換文字的 null 終止字串。

返回值

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

備註

通常，當伺服器無法使用時，你會用這種方法更改遠端名稱中的伺服器部分，或讓漫遊使用者連接到最近的伺服器。 此方法會更改工作中所有相符的遠端名稱。 若要更改特定檔案的遠端名稱，請使用 IBackgroundCopyFile2：：SetRemoteName 方法。

ReplaceRemotePrefix 方法會對工作中所有遠端名稱進行大小寫區分搜尋。 如果遠端名稱的開頭文字與 OldPrefix 中的字串相符，BITS 會將該文字替換為 NewPrefix 中的字串。 例如，要改變「http://Server/Path/File.ext"改為「http://NewServerName/Path/File.ext"，將 舊前綴 設為 」http://Server"以及 NewPrefix 為「http://NewServerName"」。 請注意，BITS 在搜尋時不會執行地區轉換。

如果新遠端名稱的時間戳記或檔案大小與先前的遠端名稱不同，或新伺服器不支援檢查點恢復（針對 HTTP 遠端名稱），BITS 會重新啟動下載。 否則，傳輸會從新伺服器的同一位置繼續進行。 BITS 不會重新啟動已傳輸的檔案。

你可以用這個方法來更改協議。 然而，最終的網址可能並非良好格式。 例如，從 \Server\Dir\File.ext 改為 http://Server\Dir\File.ext \Server\Dir\File.ext 可能無法解決。 考慮改用 IBackgroundCopyFile2：：SetRemoteName 方法。

請注意，如果你呼叫 IBackgroundCopyJobHttpOptions：：SetSecurityFlags 方法並設定 BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT 標誌，這個方法可能找不到可更改的 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.
     }

需求

另請參閱

IBackgroundCopyFile2：：SetRemoteName

IBackgroundCopyJob3