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

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

構文

HRESULT AddFileWithRanges(
  [in] LPCWSTR          RemoteUrl,
  [in] LPCWSTR          LocalName,
  [in] DWORD            RangeCount,
  [in] BG_FILE_RANGE [] Ranges
);

パラメーター

[in] RemoteUrl

サーバー上のファイルの名前を含む Null で終わる文字列。 リモート名の指定については、BG_FILE_INFO構造体の RemoteName メンバーと備考セクションを参照してください。

BITS 3.0 以降では、SMB プロトコルは範囲ではサポートされていません。

BITS 2.5 および 2.0: BITS では、範囲の SMB プロトコルがサポートされています。

[in] LocalName

クライアント上のファイルの名前を含む Null で終わる文字列。 ローカル名の指定については、BG_FILE_INFO構造体の LocalName メンバーと解説に関するセクションを参照してください。

[in] RangeCount

Ranges 内の要素の数。

[in] Ranges

ダウンロードする範囲を指定する 1 つ以上の BG_FILE_RANGE 構造体の配列。 重複または重複する範囲は指定しないでください。

戻り値

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

注釈

範囲は、指定された順序で 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 は、転送するファイルのバージョン (コンテンツではなく、ファイル のサイズと日付に基づく) が一貫していることを保証します。ただし、一連のファイルに一貫性があることを保証するものではありません。 たとえば、BITS がサーバーでファイルが更新されるときにジョブ内の 2 つ目のファイルの 2 つ目をダウンロードする途中にある場合、BITS は 2 番目のファイルのダウンロードを再開します。ただし、最初のファイルは再びダウンロードされません。

既定では、ユーザーはファイルに最大 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.
    }

要件

こちらもご覧ください

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile