IBackgroundCopyJob2::SetCredentials-Methode (bits1_5.h)
Gibt die Anmeldeinformationen an, die für eine Proxy- oder Remoteserver-Benutzerauthentifizierungsanforderung verwendet werden sollen.
Syntax
HRESULT SetCredentials(
[in] BG_AUTH_CREDENTIALS *credentials
);
Parameter
[in] credentials
Identifiziert das Ziel (Proxy oder Server), das Authentifizierungsschema und die Anmeldeinformationen des Benutzers, die für die Benutzerauthentifizierung verwendet werden sollen. Ausführliche Informationen finden Sie in der BG_AUTH_CREDENTIALS-Struktur .
Rückgabewert
Diese Methode gibt neben anderen auch die folgenden Rückgabewerte zurück.
| Rückgabecode | Beschreibung |
|---|---|
|
Erfolg |
|
Nicht erkannter Zielaufzählungswert. |
|
Nicht erkannter Schemaaufzählungswert. |
|
Der Benutzername ist zu lang. Das Limit finden Sie in der BG_BASIC_CREDENTIALS-Struktur . |
|
Das Kennwort ist zu lang. Das Limit finden Sie in der BG_BASIC_CREDENTIALS-Struktur . |
|
Die Member UserName und Password der BG_BASIC_CREDENTIALS-Struktur können nicht NULL sein, wenn Sie das Basic- oder Digest-Schema angeben. |
Hinweise
BITS stellt die Anmeldeinformationen für einen Proxy oder Server als Reaktion auf eine Anforderung für die Benutzerauthentifizierung bereit. Legen Sie die Anmeldeinformationen vor dem ersten Aufruf auf Fortsetzen fest.
Sie müssen diese Methode für jedes Ziel- und Schemapaar aufrufen, das Sie bereitstellen möchten. Wenn Sie beispielsweise Proxyanmeldeinformationen für die Basic- und Digest-Authentifizierung angeben möchten, rufen Sie diese Methode einmal auf, um die Basic-Anmeldeinformationen anzugeben, und ein zweites Mal, um die Digestanmeldeinformationen anzugeben.
Wenn der Auftrag derzeit Anmeldeinformationen mit demselben Ziel- und Schemapaar enthält, werden die vorhandenen Anmeldeinformationen durch die neuen Anmeldeinformationen ersetzt. Die Anmeldeinformationen bleiben für die Lebensdauer des Auftrags erhalten. Um die Anmeldeinformationen aus dem Auftrag zu entfernen, rufen Sie die IBackgroundCopyJob2::RemoveCredentials-Methode auf.
Wenn Sie wissen, welche Schemas der Proxy oder Server anfordern wird, können Sie nur diese Anmeldeinformationen angeben. Geben Sie andernfalls Anmeldeinformationen für alle Schemas an.
Der Auftrag wechselt in den BG_JOB_STATE_ERROR Zustand, wenn Sie die vom Proxy oder Server angeforderten Anmeldeinformationen nicht angeben oder der Proxy oder Server die Anmeldeinformationen nicht authentifizieren kann. Überprüfen Sie den Fehlercode, um festzustellen, ob bei der Authentifizierung auf dem Server (BG_E_HTTP_ERROR_401) oder Proxy (BG_E_HTTP_ERROR_407) ein Fehler aufgetreten ist. Um den Fehlercode abzurufen, rufen Sie die IBackgroundCopyJob::GetError-Methode auf, um einen IBackgroundCopyError-Schnittstellenzeiger abzurufen. Rufen Sie dann die IBackgroundCopyError::GetError-Methode auf, um den Fehlercode abzurufen. Nachdem Sie ermittelt haben, wo die Authentifizierung fehlgeschlagen ist (Proxy oder Server), geben Sie neue Anmeldeinformationen an, die für den Proxy oder Server verwendet werden sollen, und rufen Sie die IBackgroundCopyJob::Resume-Methode auf, um den Auftrag fortzusetzen. Da Sie nicht ermitteln können, welches Schema fehlgeschlagen ist, geben Sie vor dem Aufrufen der Resume-Methode Anmeldeinformationen für alle Schemas an.
Es gibt keine Methode zum Abrufen von Anmeldeinformationen, die Sie festgelegt haben.
Sie müssen diese Methode im Kontext des Besitzers des Auftrags aufrufen.
Durch Aufrufen der IBackgroundCopyJob::TakeOwnership-Methode werden die Anmeldeinformationen aus dem Auftrag entfernt.
Um implizite Anmeldeinformationen (die Anmeldeinformationen des angemeldeten Benutzers) anzugeben, legen Sie das Schema auf NTLM und den Benutzernamen und das Kennwort auf NULL fest. Wenn Sie implizite Anmeldeinformationen für einen Proxy angeben, verwendet BITS auch die impliziten Anmeldeinformationen für die Serverauthentifizierung, es sei denn, Sie geben explizite Serveranmeldeinformationen an.
Beispiele
Das folgende Beispiel zeigt, wie Sie die SetCredentials-Methode aufrufen, um Basic-Anmeldeinformationen für eine Serverbenutzerauthentifizierungsanforderung anzugeben. Im Beispiel wird die CredUIPromptForCredentials-Funktion verwendet, um den Benutzernamen und das Kennwort zu erfassen. Im Beispiel wird von einem gültigen IBackgroundCopyJob-Schnittstellenzeiger pJob ausgegangen. Im Beispiel wird die SecureZeroMemory-Funktion verwendet, um die Speicherspeicherorte zu löschen, die den vertraulichen Informationen zugeordnet sind. Die SecureZeroMemory-Funktion ist in WinBase.h definiert.
#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));
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista |
| Unterstützte Mindestversion (Server) | Windows Server 2003 |
| Zielplattform | Windows |
| Kopfzeile | bits1_5.h (bits.h einschließen) |
| Bibliothek | Bits.lib |
| DLL | BitsPrx2.dll |
| Verteilbare Komponente | BITS 1.5 unter Windows XP |