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 Vista、Windows XP SP2、Windows Server 2003 の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