Метод IBackgroundCopyJob2::SetCredentials (bits1_5.h)

Указывает учетные данные, используемые для запроса проверки подлинности пользователя прокси-сервера или удаленного сервера.

Синтаксис

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

Параметры

[in] credentials

Определяет целевой объект (прокси-сервер), схему проверки подлинности и учетные данные пользователя для проверки подлинности пользователей. Дополнительные сведения см . в BG_AUTH_CREDENTIALS структуре.

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

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

Замечания

BITS предоставляет учетные данные прокси-серверу или серверу в ответ на запрос проверки подлинности пользователя. Задайте учетные данные перед начальным вызовом резюме.

Этот метод необходимо вызвать для каждой пары целевых и схем, которые требуется предоставить. Например, если вы хотите указать учетные данные прокси-сервера для обычной и дайджест-проверки подлинности, вызовите этот метод один раз, чтобы указать базовые учетные данные и второй раз, чтобы указать учетные данные дайджеста.

Если задание в настоящее время содержит учетные данные с той же целевой парой и схемой, существующие учетные данные заменяются новыми учетными данными. Учетные данные сохраняются для жизни задания. Чтобы удалить учетные данные из задания, вызовите метод IBackgroundCopyJob2::RemoveCredentials .

Если вы знаете схемы, которые будет запрашивать прокси-сервер, вы можете указать только эти учетные данные. В противном случае укажите учетные данные для всех схем.

Задание вводит состояние BG_JOB_STATE_ERROR , если вы не предоставляете учетные данные, запрошенные прокси-сервером или сервером, или прокси-сервер не может пройти проверку подлинности учетных данных. Проверьте код ошибки, чтобы определить, произошел ли сбой проверки подлинности на сервере (BG_E_HTTP_ERROR_401) или прокси-сервере (BG_E_HTTP_ERROR_407). Чтобы получить код ошибки, вызовите метод IBackgroundCopyJob::GetError для получения указателя интерфейса IBackgroundCopyError . Затем вызовите метод IBackgroundCopyError::GetError , чтобы получить код ошибки. После определения места сбоя проверки подлинности (прокси-сервера или сервера) укажите новые учетные данные, используемые для прокси-сервера или сервера, и вызовите метод IBackgroundCopyJob::Resume для возобновления задания. Так как вы не можете определить, какая схема завершилась ошибкой, укажите учетные данные для всех схем перед вызовом метода Resume .

Нет метода получения учетных данных, заданных вами.

Этот метод необходимо вызвать в контексте владельца задания.

Вызов метода IBackgroundCopyJob::TakeOwnership удаляет учетные данные из задания.

Чтобы указать неявные учетные данные (учетные данные пользователя, вошедшего в систему), задайте для схемы значение NTLM, а имя пользователя и пароль — NULL. Если указать неявные учетные данные для прокси-сервера, BITS также будет использовать неявные учетные данные для проверки подлинности сервера, если вы не указали явные учетные данные сервера.

Примеры

В следующем примере показано, как вызвать метод SetCredentials , чтобы указать базовые учетные данные для запроса проверки подлинности пользователя сервера. В примере используется функция CredUIPromptForCredentials для записи имени пользователя и пароля. В примере предполагается допустимый указатель интерфейса IBackgroundCopyJob, pJob . В этом примере функция SecureZeroMemory используется для очистки расположений памяти, связанных с конфиденциальной информацией. Функция SecureZeroMemory определена в WinBase.h.

#define MAX_STR_LENGTH 300+1    // BITS limit for user name and password

CREDUI_INFO cuiinfo;
WCHAR szUserName[MAX_STR_LENGTH];  
WCHAR szPassword[MAX_STR_LENGTH];
DWORD rc;
IBackgroundCopyJob* pJob;
IBackgroundCopyJob2* pJob2 = NULL;
BG_AUTH_CREDENTIALS ac;

cuiinfo.cbSize = sizeof(CREDUI_INFO);
cuiinfo.hbmBanner = NULL;
cuiinfo.hwndParent = NULL; //Desktop is parent
cuiinfo.pszCaptionText = L"Server Authentication";
cuiinfo.pszMessageText = L"Enter user credentials for Basic authentication.";

//Initialize the UserName and Password fields. This example sets  
//UserName to blank, but you could also set UserName to the owner 
//of the job or the current user. For an example that retrieves the owner's
//name, see the example code for the IBackgroundCopyJob::GetOwner method. 
szUserName[0] = L'\0';
szPassword[0] = L'\0';
rc = CredUIPromptForCredentials(&cuiinfo, NULL, NULL, 0,
    szUserName, MAX_STR_LENGTH,
    szPassword, MAX_STR_LENGTH, 
    NULL, CREDUI_FLAGS_DO_NOT_PERSIST | CREDUI_FLAGS_GENERIC_CREDENTIALS);

if (NO_ERROR == rc)
{
    pJob->QueryInterface(__uuidof(IBackgroundCopyJob2), (void**)&pJob2);
    ac.Target = BG_AUTH_TARGET_SERVER;
    ac.Scheme = BG_AUTH_SCHEME_BASIC;
    ac.Credentials.Basic.UserName = szUserName;
    ac.Credentials.Basic.Password = szPassword;
    hr = pJob2->SetCredentials(&ac);
    if (FAILED(hr))
    {
      //Handle error
    }
    SecureZeroMemory(szUserName, sizeof(szUserName));
    SecureZeroMemory(szPassword, sizeof(szPassword));
}

Требования

См. также

Аутентификация

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials