Метод IBackgroundCopyJob2::SetCredentials (bits1_5.h)
Указывает учетные данные, используемые для запроса проверки подлинности пользователя прокси-сервера или удаленного сервера.
Синтаксис
HRESULT SetCredentials(
[in] BG_AUTH_CREDENTIALS *credentials
);
Параметры
[in] credentials
Определяет целевой объект (прокси-сервер или сервер), схему проверки подлинности и учетные данные пользователя, используемые для проверки подлинности пользователя. Дополнительные сведения см. в разделе структура BG_AUTH_CREDENTIALS .
Возвращаемое значение
Этот метод возвращает следующие возвращаемые значения, а также другие.
| Код возврата | Описание |
|---|---|
|
Успешное завершение |
|
Нераспознанное значение перечисления целевого объекта. |
|
Значение перечисления нераспознанной схемы. |
|
Слишком длинное имя пользователя. Ограничение см. в разделе структура BG_BASIC_CREDENTIALS . |
|
Пароль слишком длинный. Ограничение см. в разделе структура BG_BASIC_CREDENTIALS . |
|
Элементы UserName и Password структуры BG_BASIC_CREDENTIALS не могут иметь значение NULL , если указана схема Basic или Digest. |
Комментарии
BITS предоставляет учетные данные прокси-серверу или серверу в ответ на запрос проверки подлинности пользователя. Задайте учетные данные перед первоначальным вызовом Resume.
Этот метод необходимо вызвать для каждой пары целевого объекта и схемы, которую вы хотите указать. Например, если вы хотите указать учетные данные прокси-сервера для обычной и дайджест-проверки подлинности, вызовите этот метод один раз, чтобы указать базовые учетные данные, и второй раз, чтобы указать учетные данные дайджеста.
Если задание в настоящее время содержит учетные данные с той же парой целевого объекта и схемы, существующие учетные данные заменяются новыми учетными данными. Учетные данные сохраняются в течение всего срока действия задания. Чтобы удалить учетные данные из задания, вызовите метод 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));
}
Требования
| Минимальная версия клиента | Windows Vista |
| Минимальная версия сервера | Windows Server 2003 |
| Целевая платформа | Windows |
| Header | bits1_5.h (включая Bits.h) |
| Библиотека | Bits.lib |
| DLL | BitsPrx2.dll |
| Распространяемые компоненты | BITS 1.5 в Windows XP |