IBackgroundCopyJob3

IBackgroundCopyJob3 インターフェイスは、ファイルの範囲(レンジ)をダウンロードしたり、リモートファイル名のプレフィックスを変更したりするために使用します。

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

このメソッドは、以下の戻り値のほか、その他の値を返します。

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

ダウンロードジョブにファイルを追加し、そのファイルのうちダウンロードする範囲(レンジ)を指定します。

このメソッドは、以下の戻り値のほか、その他の値を返します。

各範囲は、指定された順序で LocalName のファイルに書き込まれます。たとえば、Ranges がリモートファイルのバイト 100-199、900-999、400-499 を指定している場合、ローカルファイルの長さは 300 バイトになります。ローカルファイルのバイト 0-99 にはリモートファイルのバイト 100-199 が、ローカルファイルのバイト 100-199 にはリモートファイルのバイト 900-999 が、ローカルファイルのバイト 200-299 にはリモートファイルのバイト 400-499 が格納されます。

次の表は、ジョブを再開した後に発生する可能性のあるエラーコードを示しています。これらのエラーが発生すると、ジョブは BG_JOB_STATE_ERROR 状態になります。

BITS は、転送するファイルのバージョン(内容ではなく、ファイルサイズと日付に基づく)の一貫性を保証しますが、ファイルの集合としての一貫性は保証しません。たとえば、ジョブ内の 2 つのファイルのうち 2 番目のファイルをダウンロードしている最中にサーバー上でファイルが更新された場合、BITS は 2 番目のファイルのダウンロードを最初からやり直しますが、1 番目のファイルは再度ダウンロードされません。

既定では、ユーザーは 1 つのファイルに対して最大 500 個の範囲を追加できます。この制限は、管理者やサービスアカウントには適用されません。既定値を変更するには、MaxRangesPerFile グループポリシーを設定します。

Windows Vista より前: ユーザーがジョブに追加できるファイル数に制限はありません。

Windows BranchCache を有効にしたファイル転送でより良いパフォーマンスを得るには、範囲の長さを 400 バイト以上に設定することを推奨します。

例

次の例は、AddFileWithRanges メソッドを呼び出して、ダウンロードするファイルの範囲を指定する方法を示しています。この例では、IBackgroundCopyJob 型の変数 pJob が有効であることを前提としています。

    IBackgroundCopyJob *pJob;
    IBackgroundCopyJob3 *pJob3 = NULL;
    DWORD dwRangeCount = 3;                  //Number of elements in Ranges.
    BG_FILE_RANGE Ranges[] = {24, 17,        //Array of ranges to download (offset and length).
                              111, BG_LENGTH_TO_EOF,
                              83, 7
                             };

    //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
    //interface pointer. The IBackgroundCopyJob3 interface contains the AddFileWithRanges method.
    hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
    if (S_OK == hr)
    {
         pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

         //Add a file to the job and specify the ranges from the file to download.
         hr = pJob3->AddFileWithRanges(L"<REMOTENAMEGOESHERE>", L"<LOCALNAMEGOESHERE>",
                                       dwRangeCount, Ranges);
         if (FAILED(hr))
         {
              //Handle error.
              //Returns E_NOTIMPL if not a download job.
              //Returns E_INVALIDARG if dwRangeCount is zero or the remote or local name is invalid.
              //Returns BG_E_INVALID_RANGE if one of the ranges is invalid.
              //Returns BG_E_OVERLAPPING_RANGES if you specify overlapping or duplicate ranges.
         }

          pJob3->Release(); //Release the interface if you are done with it.
     }
    else
    {
         //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
         //running on the computer is less than BITS 2.0.
    }

SMB を使用してファイルをダウンロードまたはアップロードする際に維持する、所有者情報と ACL 情報を指定します。

このメソッドは、以下の HRESULT 値のほか、その他の値を返します。

これらのフラグは、SMB プロトコルを指定するリモートファイル名に適用されます。HTTP 転送の場合、BITS はこれらのフラグを無視します。

BITS は、SMB ファイルについてはファイルのタイムスタンプと属性(拡張属性は除く)を引き継ぎます。

BITS は、一時転送ファイルを作成する時点ではなく、ファイル転送が完了した時点で所有者情報と ACL 情報をファイルに適用します。BITS は一時転送ファイルを作成する際にセキュリティ記述子を指定しません(ファイルはコピー先ディレクトリから ACL 情報を継承します)。転送するデータが機密である場合、アプリケーションは不正アクセスを防ぐために、コピー先ディレクトリに適切な ACL を指定する必要があります。

ジョブ内のすべてのファイルに適切な所有者情報と ACL 情報が設定されるようにするには、ジョブを作成した後、IBackgroundCopyJob::Resume メソッドを呼び出す前に、このメソッドを呼び出してください。そうしないと、フラグを設定する前に転送されたファイルには、適切な所有者情報と ACL 情報が設定されません。

このメソッドは、DOS の XCopy コマンドをモデルにしています。

FAT ファイルシステムにダウンロードする場合、所有者情報と ACL 情報は維持されません。

所有者情報または ACL 情報をコピーするための特権をユーザーがローカルコンピューターおよびリモートコンピューターで持っていない場合、BITS はジョブを一時的なエラー状態にし、エラーコードを E_ACCESSDENIED に設定します。

例

次の例は、SetFileACLFlags メソッドを呼び出して、BITS がダウンロードするファイルに対して維持する所有者情報と ACL 情報を指定する方法を示しています。この例では、IBackgroundCopyJob 型の変数 pJob が有効であり、新しいジョブを指していて、かつ中断状態であることを前提としています。

     IBackgroundCopyJob *pJob;
     IBackgroundCopyJob3 *pJob3 = NULL;

     //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
     //interface pointer. The IBackgroundCopyJob3 interface contains the SetACLFlags method.
     hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
     if (S_OK == hr)
     {
          pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

          //Copy the group and DACL information for each file.
          hr = pJob3->SetACLFlags(BG_COPY_FILE_GROUP | BG_COPY_FILE_DACL);
          if (FAILED(hr))
          {
               //Handle error.
          }

          ... //Add one or more files and resume the job.
          pJob3->Resume();

          //When done, release the interface pointer.
          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.
     }

SMB を使用してファイルを転送する際に維持する所有者情報と ACL 情報を示すフラグを取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値を返します。