IBackgroundCopyJob2::SetCredentials 메서드(bits1_5.h)
프록시 또는 원격 서버 사용자 인증 요청에 사용할 자격 증명을 지정합니다.
구문
HRESULT SetCredentials(
[in] BG_AUTH_CREDENTIALS *credentials
);
매개 변수
[in] credentials
사용자 인증에 사용할 대상(프록시 또는 서버), 인증 체계 및 사용자의 자격 증명을 식별합니다. 자세한 내용은 BG_AUTH_CREDENTIALS 구조를 참조하세요.
반환 값
이 메서드는 다음 반환 값뿐만 아니라 다른 값을 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
Success |
|
인식할 수 없는 대상 열거형 값입니다. |
|
인식할 수 없는 체계 열거형 값입니다. |
|
사용자 이름이 너무 깁니다. 제한은 BG_BASIC_CREDENTIALS 구조를 참조하세요. |
|
암호가 너무 깁니다. 제한은 BG_BASIC_CREDENTIALS 구조를 참조하세요. |
|
기본 또는 다이제스트 구성표를 지정하면 BG_BASIC_CREDENTIALS 구조체의 UserName 및 Password 멤버는 NULL 일 수 없습니다. |
설명
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));
}
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista |
| 지원되는 최소 서버 | Windows Server 2003 |
| 대상 플랫폼 | Windows |
| 헤더 | bits1_5.h(Bits.h 포함) |
| 라이브러리 | Bits.lib |
| DLL | BitsPrx2.dll |
| 재배포 가능 파일 | Windows XP의 BITS 1.5 |