Condividi tramite

Funzione WinHttpOpen (winhttp.h)

  • Articolo

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
WINHTTP_ACCESS_TYPE_NO_PROXY
 Risolve tutti i nomi host direttamente senza un proxy.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
Importante L'uso di questa opzione è deprecato in Windows 8.1 e versioni successive. Usare invece WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY.
 
Recupera il proxy statico o la configurazione diretta dal Registro di sistema. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY non eredita le impostazioni proxy del browser.

La configurazione del proxy WinHTTP viene impostata da uno di questi meccanismi.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 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.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 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
WINHTTP_FLAG_ASYNC
 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.
WINHTTP_FLAG_SECURE_DEFAULTS
 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
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

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 .

Nota Per Windows XP e Windows 2000, vedere Requisiti di runtime.
 

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)

Versioni di WinHTTP

WinHttpCloseHandle