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

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

構文

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

パラメーター

[in] OldPrefix

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

[in] NewPrefix

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

戻り値

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

注釈

通常、この方法を使用して、サーバーが使用できないときにリモート名のサーバー部分を変更したり、ローミング ユーザーが最も近いサーバーに接続したりします。 このメソッドは、ジョブ内の一致するすべてのリモート名を変更します。 特定のファイルのリモート名を変更するには、 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.
     }

Requirements

こちらも参照ください

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3