IBackgroundCopyJob3：：AddFileWithRanges 方法 (bits2_0.h)

發行項
02/23/2024

將檔案新增至下載作業，並指定您要下載的檔案範圍。

語法

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
S_OK	Success
E_INVALIDARG	基於下列其中一個原因，您可以收到此錯誤： RangeCount 參數為零;您必須指定一或多個範圍。本機或遠端檔名無效。遠端檔名會使用不支援的通訊協定。本機檔名是使用相對路徑來指定。
E_NOTIMPL	您無法呼叫這個方法來上傳或上傳回復工作;只針對下載作業呼叫這個方法。
E_ACCESSDENIED	用戶沒有寫入用戶端上指定目錄的許可權。
BG_E_INVALID_RANGE	其中一個範圍無效。例如，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	其中一個範圍超出遠端檔案的界限。
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