IBackgroundCopyJob2::SetCredentials-Methode (bits1_5.h)

Artikel
08/22/2023

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
S_OK	Erfolg
BG_E_INVALID_AUTH_TARGET	Nicht erkannter Zielaufzählungswert.
BG_E_INVALID_AUTH_SCHEME	Nicht erkannter Schemaaufzählungswert.
BG_E_USERNAME_TOO_LARGE	Der Benutzername ist zu lang. Das Limit finden Sie in der BG_BASIC_CREDENTIALS-Struktur .
BG_E_PASSWORD_TOO_LARGE	Das Kennwort ist zu lang. Das Limit finden Sie in der BG_BASIC_CREDENTIALS-Struktur .
E_INVALIDARG	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.

Hinweis BITS ignoriert Anmeldeinformationen für Remotenamen , die einen SMB-Pfad angeben.

Hinweis BITS authentifiziert den Server nicht oder verschlüsselt den Kanal nicht. Verwenden Sie HTTPS, wenn dies ein Problem für Ihre Anwendung ist.

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

Weitere Informationen

Authentifizierung

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials

Freigeben über