IBackgroundCopyJob3::ReplaceRemotePrefix メソッド (bits2_0.h)

ダウンロード ジョブ内のすべてのリモート名の開始テキストを、指定した文字列に置き換えます。

構文

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

パラメーター

[in] OldPrefix

リモート名で置き換えるテキストを識別する null で終わる文字列。 テキストは、リモート名の先頭から始まる必要があります。

[in] NewPrefix

置換テキストを含む null で終わる文字列。

戻り値

このメソッドは、次の戻り値と他の戻り値を返します。

リターン コード 説明
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 が有効であり、ジョブに 1 つ以上のファイルが含まれていることを前提としています。

     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 Server 2003 の Windows Vista、SP2 の Windows XP、KB842773、および Windows XP
サポートされている最小のサーバー Windows Server 2008、Windows Server 2003 SP1
対象プラットフォーム Windows
ヘッダー bits2_0.h (Bits.h を含む)
Library Bits.lib
[DLL] BitsPrx3.dll

こちらもご覧ください

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3