Metodo IBackgroundCopyJob2::SetCredentials (bits1_5.h)
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 |
|---|---|
|
Operazione riuscita |
|
Valore di enumerazione di destinazione non riconosciuto. |
|
Valore di enumerazione dello schema non riconosciuto. |
|
Il nome utente è troppo lungo. Per il limite, vedere la struttura BG_BASIC_CREDENTIALS . |
|
La password è troppo lunga. Per il limite, vedere la struttura BG_BASIC_CREDENTIALS . |
|
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.
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 |