Метод IBackgroundCopyJob3::ReplaceRemotePrefix (bits2_0.h)

Статья
03/14/2023

Заменяет начальный текст всех удаленных имен в задании загрузки указанной строкой.

Синтаксис

HRESULT ReplaceRemotePrefix(
  [in] LPCWSTR OldPrefix,
  [in] LPCWSTR NewPrefix
);

Параметры

[in] OldPrefix

Строка, завершающаяся null, идентифицирующая текст, который необходимо заменить в удаленном имени. Текст должен начинаться с начала удаленного имени.

[in] NewPrefix

Строка, завершающаяся значением NULL, содержащая замещающий текст.

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

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

Код возврата	Описание
S_OK	Успешное завершение
S_FALSE	Совпадений не найдено.
E_INVALIDARG	При применении NewPrefix создается недопустимый URL-адрес или новый URL-адрес слишком длинный (длина URL-адреса не может превышать 2200 символов). Этот код возврата также можно получить, если OldPrefix или NewPrefix являются пустой строкой.
E_NOTIMPL	Этот метод нельзя вызывать для заданий отправки или отправки и ответа; вызывать этот метод только для заданий скачивания.
BG_E_INVALID_STATE	Состояние задания не может быть BG_JOB_STATE_CANCELLED или BG_JOB_STATE_ACKNOWLEDGED.

Как правило, этот метод используется для изменения части удаленного имени сервера, когда сервер недоступен, или для разрешения перемещаемых пользователей подключаться к ближайшему серверу. Этот метод изменяет все соответствующие удаленные имена в задании. Чтобы изменить удаленное имя определенного файла, используйте метод IBackgroundCopyFile2::SetRemoteName .

Метод ReplaceRemotePrefix выполняет поиск всех удаленных имен в задании с учетом регистра. Если начальный текст удаленного имени совпадает со строкой в OldPrefix, BITS заменяет текст строкой, найденной в NewPrefix. Например, чтобы изменить "http://Server/Path/File.ext" значение "http://NewServerName/Path/File.ext", задайте для OldPrefix значение "http://Server" и NewPrefix на "http://NewServerName". Обратите внимание, что BITS не выполняет преобразования языкового стандарта в поиске.

Если метка времени или размер файла нового удаленного имени отличается от предыдущего удаленного имени или новый сервер не поддерживает возобновление контрольных точек (для удаленных имен HTTP), BITS перезапускает скачивание. В противном случае передача возобновляется из той же позиции на новом сервере. BITS не перезапускает уже переданные файлы.

Этот метод можно использовать для изменения протоколов. Однако результирующий URL-адрес может быть неправильно сформирован. Например, изменение с \Server\Dir\File.ext на http://Server\Dir\File.ext может не разрешиться. Вместо этого рекомендуется использовать метод IBackgroundCopyFile2::SetRemoteName .

Обратите внимание, что этот метод может не найти URL-адреса для изменения, если вы вызвали метод IBackgroundCopyJobHttpOptions::SetSecurityFlags и установили флаг BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT . Эта политика изменяет исходный URL-адрес на окончательный, перенаправленный URL-адрес, если URL-адрес перенаправлен.

Примеры

В следующем примере показано, как вызвать метод ReplaceRemotePrefix для изменения имени сервера URL-адреса. В примере предполагается, что переменная IBackgroundCopyJobpJob является допустимой и задание содержит один или несколько файлов.

     IBackgroundCopyJob *pJob;
     IBackgroundCopyJob3 *pJob3 = NULL;

     //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
     //interface pointer. The IBackgroundCopyJob3 interface contains the ReplaceRemotePrefix method.
     hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
     if (S_OK == hr)
     {
          pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

          //Identify the old and new remote name text. For example, "http://oldservername" and 
          //"http://newservername". For SMB, specify "\\\\oldservername" and "\\\\newservername".
          hr = pJob3->ReplaceRemotePrefix(L"<OLDSERVERNAMEGOESHERE>", L"<NEWSERVERNAMEGOESHERE>");
          if (S_FALSE == hr)
          {
               wprintf(L"The job does not contain files with a remote name that matches the prefix.\n");
          }
          else if (FAILED(hr))
          {
               //Handle error.
               //Returns E_NOTIMPL if not a download job.
               //Returns E_INVALIDARG if new prefix is empty or the resulting URL is invalid.
          }

          pJob3->Release();
     }
     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

См. также раздел

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3

Поделиться через