Funzione WinHttpOpen (winhttp.h)
La funzione WinHttpOpen inizializza, per un'applicazione, l'uso di funzioni WinHTTP e restituisce un handle di sessione WinHTTP.
Sintassi
WINHTTPAPI HINTERNET WinHttpOpen(
[in, optional] LPCWSTR pszAgentW,
[in] DWORD dwAccessType,
[in] LPCWSTR pszProxyW,
[in] LPCWSTR pszProxyBypassW,
[in] DWORD dwFlags
);
Parametri
[in, optional] pszAgentW
Puntatore a una variabile stringa contenente il nome dell'applicazione o dell'entità che chiama le funzioni WinHTTP. Questo nome viene usato come agente utente nel protocollo HTTP.
[in] dwAccessType
Tipo di accesso richiesto. Può trattarsi di uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Risolve tutti i nomi host direttamente senza un proxy. |
|
Importante L'uso di questa opzione è deprecato in Windows 8.1 e versioni successive. Usare invece WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY.
La configurazione del proxy WinHTTP viene impostata da uno di questi meccanismi.
|
|
Passa le richieste al proxy a meno che non venga specificato un elenco di bypass del proxy e il nome da risolvere ignora il proxy. In questo caso, questa funzione usa i valori passati per pwszProxyName e pwszProxyBypass. |
|
Usa le impostazioni proxy di sistema e per utente (inclusa la configurazione del proxy di Internet Explorer) per determinare quali proxy/proxy usare. Tenta automaticamente di gestire il failover tra più proxy, configurazioni proxy diverse per ogni interfaccia e autenticazione. Supportato in Windows 8.1 e versioni successive. |
[in] pszProxyW
Puntatore a una variabile stringa che contiene il nome del server proxy da usare quando l'accesso proxy viene specificato impostando dwAccessType su WINHTTP_ACCESS_TYPE_NAMED_PROXY. Le funzioni WinHTTP riconoscono solo proxy di tipo CERN per HTTP. Se dwAccessType non è impostato su WINHTTP_ACCESS_TYPE_NAMED_PROXY, questo parametro deve essere impostato su WINHTTP_NO_PROXY_NAME.
[in] pszProxyBypassW
Puntatore a una variabile stringa che contiene un elenco facoltativo delimitato da punto e virgola di nomi host o indirizzi IP o entrambi, che non devono essere indirizzati tramite il proxy quando dwAccessType è impostato su WINHTTP_ACCESS_TYPE_NAMED_PROXY. L'elenco può contenere caratteri jolly. Non usare una stringa vuota, perché la funzione WinHttpOpen la usa come elenco di bypass del proxy. Se questo parametro specifica la macro "<local>" nell'elenco come unica voce, questa funzione ignora qualsiasi nome host che non contiene un punto. Se dwAccessType non è impostato su WINHTTP_ACCESS_TYPE_NAMED_PROXY, questo parametro deve essere impostato su WINHTTP_NO_PROXY_BYPASS.
[in] dwFlags
Valore intero long senza segno che contiene i flag che indicano varie opzioni che influiscono sul comportamento di questa funzione. Questo parametro può avere il valore seguente.
| Valore | Significato |
|---|---|
|
Usare le funzioni WinHTTP in modo asincrono. Per impostazione predefinita, tutte le funzioni WinHTTP che usano l'handle SKUNET restituito vengono eseguite in modo sincrono. Quando questo flag è impostato, il chiamante deve specificare una funzione di callback tramite WinHttpSetStatusCallback. |
|
Quando questo flag è impostato, WinHttp richiederà l'uso di TLS 1.2 o versione successiva. Se il chiamante tenta di abilitare le versioni precedenti di TLS impostando WINHTTP_OPTION_SECURE_PROTOCOLS, l'operazione avrà esito negativo con ERROR_ACCESS_DENIED. Inoltre, il fallback TLS verrà disabilitato. Si noti che l'impostazione di questo flag imposta anche il flag WINHTTP_FLAG_ASYNC. |
Valore restituito
Restituisce un handle di sessione valido in caso di esito positivo o NULL in caso contrario. Per recuperare informazioni sull'errore estese, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.
| Codice di errore | Descrizione |
|---|---|
|
Si è verificato un errore interno. |
|
Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows) |
Commenti
Ti consigliamo vivamente di usare WinHTTP in modalità asincrona, ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, in modo che l'utilizzo dell'OGGETTO RESTITUITo diventi asincrono. Il valore restituito indica l'esito positivo o negativo. Per recuperare informazioni sull'errore estese, chiamare GetLastError.
La funzione WinHttpOpen è la prima delle funzioni WinHTTP chiamate da un'applicazione. Inizializza le strutture di dati WinHTTP interne e prepara le chiamate future dall'applicazione. Al termine dell'uso delle funzioni WinHTTP, l'applicazione deve chiamare WinHttpCloseHandle per liberare l'handle di sessione ed eventuali risorse associate.
L'applicazione può effettuare un numero qualsiasi di chiamate a WinHttpOpen, anche se una singola chiamata è normalmente sufficiente. Ogni chiamata a WinHttpOpen apre un nuovo contesto di sessione. Poiché i dati utente non vengono condivisi tra più contesti di sessione, un'applicazione che effettua richieste per conto di più utenti deve creare una sessione separata per ogni utente, in modo da non condividere cookie e stato di autenticazione specifici dell'utente. L'applicazione deve definire comportamenti separati per ogni istanza di WinHttpOpen , ad esempio server proxy diversi configurati per ogni istanza.
Dopo che l'applicazione chiamante ha terminato di usare l'handle DELL'interfaccia UTENTE RESTITUITA da WinHttpOpen, deve essere chiusa usando la funzione WinHttpCloseHandle .
Esempio
Il codice di esempio seguente mostra come recuperare il valore di timeout di connessione predefinito.
DWORD data;
DWORD dwSize = sizeof(DWORD);
// Use WinHttpOpen to obtain an HINTERNET handle.
HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
if (hSession)
{
// Use WinHttpQueryOption to retrieve internet options.
if (WinHttpQueryOption( hSession,
WINHTTP_OPTION_CONNECT_TIMEOUT,
&data, &dwSize))
{
printf("Connection timeout: %u ms\n\n",data);
}
else
{
printf( "Error %u in WinHttpQueryOption.\n",
GetLastError());
}
// When finished, release the HINTERNET handle.
WinHttpCloseHandle(hSession);
}
else
{
printf("Error %u in WinHttpOpen.\n", GetLastError());
}
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. |
Vedi anche
Informazioni sui servizi HTTP di Microsoft Windows (WinHTTP)