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

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

Синтаксис

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

Параметры

[in] OldPrefix

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

[in] NewPrefix

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

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

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

Комментарии

Как правило, этот метод используется для изменения части удаленного имени сервера, когда сервер недоступен, или для разрешения перемещаемых пользователей подключаться к ближайшему серверу. Этот метод изменяет все соответствующие удаленные имена в задании. Чтобы изменить удаленное имя определенного файла, используйте метод 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.
     }

Требования

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

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3