Метод 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, содержащая имя файла на сервере. Сведения об указании удаленного имени см. в разделе Элемент RemoteName и примечания структуры BG_FILE_INFO .

Начиная с BITS 3.0 протокол SMB не поддерживается для диапазонов.

BITS 2.5 и 2.0: BITS поддерживает протокол SMB для диапазонов.

[in] LocalName

Строка, завершающаяся нулевым значением, которая содержит имя файла на клиенте. Сведения об указании локального имени см. в разделе Элемент LocalName и примечания структуры BG_FILE_INFO .

[in] RangeCount

Количество элементов в диапазоне.

[in] Ranges

Массив из одной или нескольких BG_FILE_RANGE структур, указывающих диапазоны для скачивания. Не указывайте повторяющиеся или перекрывающиеся диапазоны.

Возвращаемое значение

Этот метод возвращает следующие возвращаемые значения, а также другие.

Код возврата	Описание
S_OK	Успешное завершение
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 в указанном порядке. Например, если диапазоны определяют байты удаленного файла 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 , чтобы указать диапазоны скачиваемого файла. В примере предполагается, что переменная IBackgroundCopyJobpJob является допустимой.

    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 с пакетом обновления 2 (SP2), KB842773 в Windows Server 2003 и Windows XP
Минимальная версия сервера	Windows Server 2008, Windows Server 2003 с пакетом обновления 1 (SP1)
Целевая платформа	Windows
Header	bits2_0.h (включая Bits.h)
Библиотека	Bits.lib
DLL	BitsPrx3.dll