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
指定要下載範圍的一或多個 BG_FILE_RANGE 結構的陣列。 請勿指定重複或重疊的範圍。
傳回值
這個方法會傳回下列傳回值，以及其他傳回值。
| 傳回碼 | Description |
|---|---|
|
Success |
|
基於下列其中一個原因，您可以收到此錯誤：
|
|
您無法呼叫這個方法來上傳或上傳回復工作;只針對下載作業呼叫這個方法。 |
|
用戶沒有寫入用戶端上指定目錄的許可權。 |
|
其中一個範圍無效。 例如，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 | 其中一個範圍超出遠端檔案的界限。 |
| BG_E_INSUFFICIENT_RANGE_SUPPORT | 伺服器不支援範圍。 |
BITS 保證檔案版本會根據檔案大小和日期 (，而不是它傳輸的內容) 一致;不過，它不保證一組檔案會一致。 例如，如果 BITS 在作業中下載作業中兩個檔案的第二個檔案在伺服器上更新時，BITS 會重新啟動第二個檔案的下載;不過，不會再次下載第一個檔案。
根據預設，用戶可以為檔案新增最多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 與 Windows Server 2003 上的 SP2、KB842773 和 Windows XP |
| 最低支援的伺服器 | Windows Server 2008、Windows Server 2003 SP1 |
| 目標平台 | Windows |
| 標頭 | bits2_0.h (包含 Bits.h) |
| 程式庫 | Bits.lib |
| Dll | BitsPrx3.dll |