共用方式為

IBackgroundCopyJob3：：ReplaceRemotePrefix 方法 (bits2_0.h)

  • 發行項

以指定的字串取代下載作業中所有遠端名稱的開頭文字。

語法

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

參數

[in] OldPrefix

Null 終止字串，可識別遠端名稱中要取代的文字。 文字必須從遠端名稱的開頭開始。

[in] NewPrefix

包含取代文字的 Null 終止字串。

傳回值

這個方法會傳回下列傳回值，以及其他傳回值。

傳回碼 Description
S_OK
 Success
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 上的 SP2、KB842773 和 Windows XP
最低支援的伺服器 Windows Server 2008、Windows Server 2003 SP1
目標平台 Windows
標頭 bits2_0.h (包含 Bits.h)
程式庫 Bits.lib
Dll BitsPrx3.dll

另請參閱

IBackgroundCopyFile2：：SetRemoteName

IBackgroundCopyJob3