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 構造体の配列。 重複または重複する範囲は指定しないでください。
戻り値
このメソッドは、次の戻り値と他の戻り値を返します。
| リターン コード | 説明 |
|---|---|
|
Success |
|
このエラーは、次のいずれかの理由で発生する可能性があります。
|
|
アップロードジョブまたはアップロード/応答ジョブでは、このメソッドを呼び出すことはできません。は、ダウンロード ジョブに対してのみこのメソッドを呼び出します。 |
|
ユーザーには、クライアント上の指定されたディレクトリに書き込む権限がありません。 |
|
範囲の 1 つが無効です。 たとえば、InitialOffset は BG_LENGTH_TO_EOF に設定されます。 |
|
重複または重複する範囲を指定することはできません。
メモ 範囲は、長さではなく値のオフセットで並べ替えられます。 オフセットが同じで逆の順序の範囲を入力すると、このエラーが返されます。 たとえば、100.5 と 100.0 をその順序で入力すると、ジョブにファイルを追加できなくなります。
|
|
MaxRangesPerFile グループ ポリシー設定によって、ファイルに指定できる範囲の数が決まります。 これらの範囲を追加すると、MaxRangesPerFile の制限を超えています。 |
|
ジョブの状態を 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 |