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

範囲内の要素の数。

[in] Ranges

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

戻り値

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

注釈

範囲は、指定された順序で LocalName ファイルに書き込まれます。 たとえば、 範囲 がリモート ファイルのバイト 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 つ目のファイルのダウンロードの途中にある場合、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.
    }

Requirements

こちらも参照ください

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile