Метод IBackgroundCopyFile2::SetRemoteName (bits2_0.h)

Статья
08/22/2023

Изменяет удаленное имя на новый URL-адрес в задании загрузки.

Синтаксис

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Параметры

[in] Val

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

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

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

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

Как правило, этот метод вызывается, если требуется изменить протокол, используемый для передачи файла (например, из SMB в HTTP), или если требуется изменить имя или путь к файлу.

Этот метод не сериализуется при возврате. Чтобы сериализовать изменение, приостановите задание, вызовите этот метод (при изменении нескольких файлов в задании и используйте цикл) и возобновите задание. Вызов метода IBackgroundCopyJob::Resume сериализует изменение.

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

Если удаленное имя определяет путь к блоку сообщений сервера (SMB), в следующей таблице указаны возможные коды ошибок, которые могут возникнуть после возобновления задания. Эти ошибки помещает задание в состояние BG_JOB_STATE_ERROR .

Код ошибки	Описание
`HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND)`	Каталог не найден.
`HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)`	Файл не найден.
`HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)`	Пользователь не имеет доступа к файлу, указанному в Val.

Примеры

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

     IBackgroundCopyJob *pJob;
     IEnumBackgroundCopyFiles* pFiles = NULL;
     IBackgroundCopyFile* pFile = NULL;
     IBackgroundCopyFile2* pFile2 = NULL;
     WCHAR* pRemoteFileName = NULL;
     ULONG cFileCount = 0;

     hr = pJob->Suspend();
     hr = pJob->EnumFiles(&pFiles);
     if (SUCCEEDED(hr))
     {
          //Get the count of files in the job. 
          hr = pFiles->GetCount(&cFileCount);

          //Enumerate the files in the job.
          for (ULONG idx=0; idx<cFileCount; idx++)
          {
               hr = pFiles->Next(1, &pFile, NULL);
               if (S_OK == hr)
               {
                    //Get the local name of the file.
                    hr = pFile->GetRemoteName(&pRemoteFileName);
                    if (SUCCEEDED(hr))
                    {
                         //Determine if you want to replace the remote name of this file.
                         if (<CONDITIONGOESHERE>)
                         {
                              //Need to query the IBackgroundCopyFile interface for an IBackgroundCopyFile2
                              //interface pointer. The IBackgroundCopyFile2 interface contains the SetRemoteName method.
                              hr = pFile->QueryInterface(__uuidof(IBackgroundCopyFile2), (void**)&pFile2);
                              if (S_OK == hr)
                              {
                                   hr = pFile2->SetRemoteName(L"<NEWURLGOESHERE>");
                                   if (FAILED(hr))
                                   {
                                        //Handle error. 
                                        //Returns E_NOTIMPL if not a download job.
                                        //Returns E_INVALIDARG if invalid URL.
                                   }
                              }
                              else
                              {
                                   //handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
                                   //running on the computer is less than BITS 2.0.
                              }
                         }
                         CoTaskMemFree(pRemoteFileName); 
                    }    
                    pFile->Release(); 
                    pFile = NULL;
               }
               else
               {
                    //Handle error
                    break;
               }
          }

          pFiles->Release();
          pFiles = NULL;
     }

     hr = pJob->Resume(); //Force the job to serialize.

Требования

Требование	Значение
Минимальная версия клиента	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

IBackgroundCopyJob3::ReplaceRemotePrefix