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

[アーティクル]
08/22/2023

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

構文

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 構造体の配列。重複または重複する範囲は指定しないでください。

戻り値

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

リターンコード	説明
S_OK	Success
E_INVALIDARG	このエラーは、次のいずれかの理由で発生する可能性があります。 RangeCount パラメーターは 0 です。1 つ以上の範囲を指定する必要があります。ローカルまたはリモートのファイル名が無効です。リモートファイル名では、サポートされていないプロトコルが使用されます。ローカルファイル名は、相対パスを使用して指定されました。
E_NOTIMPL	アップロードジョブまたはアップロード/応答ジョブでは、このメソッドを呼び出すことはできません。は、ダウンロードジョブに対してのみこのメソッドを呼び出します。
E_ACCESSDENIED	ユーザーには、クライアント上の指定されたディレクトリに書き込む権限がありません。
BG_E_INVALID_RANGE	範囲の 1 つが無効です。たとえば、InitialOffset は BG_LENGTH_TO_EOF に設定されます。
BG_E_OVERLAPPING_RANGES	重複または重複する範囲を指定することはできません。メモ範囲は、長さではなく値のオフセットで並べ替えられます。オフセットが同じで逆の順序の範囲を入力すると、このエラーが返されます。たとえば、100.5 と 100.0 をその順序で入力すると、ジョブにファイルを追加できなくなります。
BG_E_TOO_MANY_RANGES_IN_FILE	MaxRangesPerFile グループポリシー設定によって、ファイルに指定できる範囲の数が決まります。これらの範囲を追加すると、MaxRangesPerFile の制限を超えています。
BG_E_INVALID_STATE	ジョブの状態を BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGEDすることはできません。

注釈

範囲は、指定された順序で 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状態になります。

エラーコード	説明
BG_E_INVALID_SERVER_RESPONSE	BITS では、重複または重複する範囲を統合するサーバーはサポートされていません。
BG_E_INVALID_RANGE	範囲の 1 つがリモートファイルの境界外にあります。
BG_E_INSUFFICIENT_RANGE_SUPPORT	サーバーは範囲をサポートしていません。

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.
    }

要件

要件	値
サポートされている最小のクライアント	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

こちらもご覧ください

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile

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

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース