Metodo IBackgroundCopyJob2::SetCredentials (bits1_5.h)

Articolo
08/22/2023

Specifica le credenziali da usare per una richiesta di autenticazione utente proxy o server remoto.

Sintassi

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

Parametri

[in] credentials

Identifica la destinazione (proxy o server), lo schema di autenticazione e le credenziali dell'utente da usare per l'autenticazione utente. Per informazioni dettagliate, vedere la struttura BG_AUTH_CREDENTIALS .

Valore restituito

Questo metodo restituisce i valori restituiti seguenti, nonché altri.

Codice restituito	Descrizione
S_OK	Operazione riuscita
BG_E_INVALID_AUTH_TARGET	Valore di enumerazione di destinazione non riconosciuto.
BG_E_INVALID_AUTH_SCHEME	Valore di enumerazione dello schema non riconosciuto.
BG_E_USERNAME_TOO_LARGE	Il nome utente è troppo lungo. Per il limite, vedere la struttura BG_BASIC_CREDENTIALS .
BG_E_PASSWORD_TOO_LARGE	La password è troppo lunga. Per il limite, vedere la struttura BG_BASIC_CREDENTIALS .
E_INVALIDARG	I membri UserName e Password della struttura BG_BASIC_CREDENTIALS non possono essere NULL se si specifica lo schema Basic o Digest.

Commenti

BITS fornisce le credenziali a un proxy o a un server in risposta a una richiesta di autenticazione utente. Impostare le credenziali prima della chiamata iniziale a Resume.

È necessario chiamare questo metodo per ogni coppia di destinazione e schema da fornire. Ad esempio, se si desidera specificare le credenziali proxy per l'autenticazione Basic e Digest, chiamare questo metodo una volta per specificare le credenziali di base e una seconda volta per specificare le credenziali digest.

Se il processo contiene attualmente le credenziali con la stessa destinazione e la stessa coppia di schemi, le credenziali esistenti vengono sostituite con le nuove credenziali. Le credenziali vengono mantenute per la vita del processo. Per rimuovere le credenziali dal processo, chiamare il metodo IBackgroundCopyJob2::RemoveCredentials .

Se si conosce lo schema richiesto dal proxy o dal server, è possibile fornire solo queste credenziali. In caso contrario, specificare le credenziali per tutti gli schemi.

Il processo entra nello stato BG_JOB_STATE_ERROR se non si specificano le credenziali richieste dal proxy o dal server oppure il proxy o il server non può autenticare le credenziali. Controllare il codice di errore per determinare se l'autenticazione non è riuscita nel server (BG_E_HTTP_ERROR_401) o proxy (BG_E_HTTP_ERROR_407). Per recuperare il codice di errore, chiamare il metodo IBackgroundCopyJob::GetError per recuperare un puntatore dell'interfaccia IBackgroundCopyError . Chiamare quindi il metodo IBackgroundCopyError::GetError per recuperare il codice di errore. Dopo aver determinato dove l'autenticazione non è riuscita (proxy o server), specificare nuove credenziali da usare per il proxy o il server e chiamare il metodo IBackgroundCopyJob::Resume per riprendere il processo. Poiché non è possibile determinare quale schema non è riuscito, specificare le credenziali per tutti gli schemi prima di chiamare il metodo Resume .

Non esiste alcun metodo per recuperare le credenziali impostate.

È necessario chiamare questo metodo nel contesto del proprietario del processo.

La chiamata al metodo IBackgroundCopyJob::TakeOwnership rimuove le credenziali dal processo.

Per specificare le credenziali implicite (le credenziali dell'utente registrate), impostare lo schema su NTLM e il nome utente e la password su NULL. Se si specificano credenziali implicite per un proxy, BITS userà anche le credenziali implicite per l'autenticazione server, a meno che non si specifichino le credenziali del server esplicite.

Nota BITS ignora le credenziali per i nomi remoti che specificano un percorso SMB.

Nota BITS non autentica il server o crittografa il canale. Usare HTTPS se si tratta di un problema per l'applicazione.

Esempio

Nell'esempio seguente viene illustrato come chiamare il metodo SetCredentials per specificare le credenziali di base per una richiesta di autenticazione utente server. Nell'esempio viene usata la funzione CredUIPromptForCredentials per acquisire il nome utente e la password. L'esempio presuppone un puntatore dell'interfaccia IBackgroundCopyJob valido, pJob . Nell'esempio viene usata la funzione SecureZeroMemory per cancellare le posizioni di memoria associate alle informazioni riservate. La funzione SecureZeroMemory è definita in 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));
}

Requisiti


Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2003
Piattaforma di destinazione	Windows
Intestazione	bits1_5.h (includere Bits.h)
Libreria	Bits.lib
DLL	BitsPrx2.dll
Componente ridistribuibile	BITS 1.5 in Windows XP

Vedi anche

autenticazione

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials

Share via