Funzione WinHttpSetCredentials (winhttp.h)

Articolo
03/15/2023

La funzione WinHttpSetCredentials passa le credenziali di autorizzazione necessarie al server.

Sintassi

WINHTTPAPI BOOL WinHttpSetCredentials(
  [in] HINTERNET hRequest,
  [in] DWORD     AuthTargets,
  [in] DWORD     AuthScheme,
  [in] LPCWSTR   pwszUserName,
  [in] LPCWSTR   pwszPassword,
  [in] LPVOID    pAuthParams
);

Parametri

[in] hRequest

Handle HINTERNET valido restituito da WinHttpOpenRequest.

[in] AuthTargets

Intero senza segno che specifica un flag contenente la destinazione di autenticazione. Può essere uno dei valori della tabella seguente.

Valore	Significato
WINHTTP_AUTH_TARGET_SERVER	Le credenziali vengono passate a un server.
WINHTTP_AUTH_TARGET_PROXY	Le credenziali vengono passate a un proxy.

[in] AuthScheme

Intero senza segno che specifica un flag contenente lo schema di autenticazione. Deve essere uno degli schemi di autenticazione supportati restituiti da WinHttpQueryAuthSchemes. La tabella seguente identifica i valori possibili.

Valore	Significato
WINHTTP_AUTH_SCHEME_BASIC	Usare l'autenticazione di base.
WINHTTP_AUTH_SCHEME_NTLM	Usare l'autenticazione NTLM.
WINHTTP_AUTH_SCHEME_PASSPORT	Usare l'autenticazione passport.
WINHTTP_AUTH_SCHEME_DIGEST	Usare l'autenticazione del digest.
WINHTTP_AUTH_SCHEME_NEGOTIATE	Seleziona tra l'autenticazione NTLM e Kerberos.

[in] pwszUserName

Puntatore a una stringa contenente un nome utente valido.

[in] pwszPassword

Puntatore a una stringa contenente una password valida. La password può essere vuota.

[in] pAuthParams

Questo parametro è riservato e deve essere NULL.

Valore restituito

Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per informazioni sull'errore estese, chiamare GetLastError. La tabella seguente identifica i codici di errore restituiti.

Codice di errore	Descrizione
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Impossibile eseguire l'operazione richiesta perché l'handle fornito non è nello stato corretto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Il tipo di handle fornito non è corretto per questa operazione.
ERROR_WINHTTP_INTERNAL_ERROR	Si è verificato un errore interno.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta (codice errore di Windows).

Commenti

Anche quando WinHTTP viene usato in modalità asincrona, ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione opera in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Le credenziali impostate da WinHttpSetCredentials vengono usate solo per una singola richiesta; WinHTTP non memorizza nella cache queste credenziali per l'uso nelle richieste successive. Di conseguenza, le applicazioni devono essere scritte in modo che possano rispondere a più sfide. Se viene rieseguata una connessione autenticata, le richieste successive non possono essere richieste, ma il codice deve essere in grado di rispondere a una richiesta in qualsiasi momento.

Per codice di esempio che illustra l'uso di WinHttpSetCredentials, vedere Autenticazione in WinHTTP.

Nota Quando si usa l'autenticazione Passport e si risponde a un codice di stato 407, un'applicazione WinHTTP deve usare WinHttpSetOption per fornire credenziali proxy anziché WinHttpSetCredentials. Questo vale solo quando si usa l'autenticazione Passport; in tutte le altre circostanze, usare WinHttpSetCredentials, perché WinHttpSetOption è meno sicuro.

Nota Per Windows XP e Windows 2000, vedere la sezione Requisiti di runtime della pagina iniziale WinHttp.

Requisiti


Client minimo supportato	Windows XP, Windows 2000 Professional con SP3 [solo app desktop]
Server minimo supportato	Windows Server 2003, Windows 2000 Server con SP3 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winhttp.h
Libreria	Winhttp.lib
DLL	Winhttp.dll
Componente ridistribuibile	WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000.