Funzione WinHttpConnect (winhttp.h)

Articolo
08/07/2024

La funzione WinHttpConnect specifica il server di destinazione iniziale di una richiesta HTTP e restituisce un handle di connessione a una sessione HTTP per tale destinazione iniziale.

Sintassi

WINHTTPAPI HINTERNET WinHttpConnect(
  [in] HINTERNET     hSession,
  [in] LPCWSTR       pswzServerName,
  [in] INTERNET_PORT nServerPort,
  [in] DWORD         dwReserved
);

Parametri

[in] hSession

Valido handle di sessione WINHTTP restituito da una chiamata precedente a WinHttpOpen.

[in] pswzServerName

Puntatore a un nullstringa con terminazione contenente il nome host di un server HTTP. In alternativa, la stringa può contenere l'indirizzo IP del sito come stringa, ad esempio 10.0.1.45. Si noti che WinHttp non accetta nomi host internazionali senza convertirli prima in Punycode. Per altre informazioni, vedere Gestione dei nomi di dominio internazionali (IDN).

[in] nServerPort

Intero senza segno che specifica la porta TCP/IP nel server a cui viene stabilita una connessione. Questo parametro può essere qualsiasi numero di porta TCP/IP valido o uno dei valori seguenti.

Valore	Significato
INTERNET_DEFAULT_HTTP_PORT	Usa la porta predefinita per i server HTTP (porta 80).
INTERNET_DEFAULT_HTTPS_PORT	Usa la porta predefinita per i server HTTPS (porta 443). La selezione di questa porta non stabilisce automaticamente una connessione sicura. È comunque necessario specificare l'uso della semantica delle transazioni sicure usando il flag WINHTTP_FLAG_SECURE con WinHttpOpenRequest.
INTERNET_DEFAULT_PORT	Usa la porta 80 per HTTP e la porta 443 per Secure Hypertext Transfer Protocol (HTTPS).

[in] dwReserved

Questo parametro è riservato e deve essere 0.

Valore restituito

Restituisce un handle di connessione valido alla sessione HTTP se la connessione ha esito positivo oppure null in caso contrario. Per recuperare informazioni sull'errore estese, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Codici di errore	Descrizione
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_WINHTTP_INVALID_URL	L'URL non è valido.
ERROR_WINHTTP_OPERATION_CANCELLED	L'operazione è stata annullata, in genere perché l'handle in cui la richiesta era operativa è stata chiusa prima del completamento dell'operazione.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Non è stato possibile riconoscere lo schema URL o non è supportato.
ERROR_WINHTTP_SHUTDOWN	Il supporto della funzione WinHTTP viene arrestato o scaricato.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows)

Osservazioni

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

Al termine dell'utilizzo dell'applicazione chiamante, l'handle di RESTITUITO da winHttpConnect, deve essere chiuso usando la funzione WinHttpCloseHandle .

WinHttpConnect specifica il server HTTP di destinazione, tuttavia una risposta può provenire da un altro server se la richiesta è stata reindirizzata. È possibile determinare l'URL del server che invia la risposta chiamando WinHttpQueryOption con il flag WINHTTP_OPTION_URL.

Nota Per Windows XP e Windows 2000, vedi la sezione Requisiti Run-Time della pagina iniziale di WinHttp.

Esempi

L'esempio seguente illustra come usare la semantica delle transazioni sicura per scaricare una risorsa da un server HTTPS. Il codice di esempio inizializza l'API (Application Programming Interface) di Microsoft Windows HTTP Services (WinHTTP), seleziona un server HTTPS di destinazione, quindi apre e invia una richiesta per questa risorsa protetta.
WinHttpQueryDataAvailable viene usato con l'handle di richiesta per determinare la quantità di dati disponibili per il download, quindi viene usato WinHttpReadData per leggere tali dati. Questo processo viene ripetuto fino a quando non viene recuperato e visualizzato l'intero documento.


    DWORD dwSize = 0;
    DWORD dwDownloaded = 0;
    LPSTR pszOutBuffer;
    BOOL  bResults = FALSE;
    HINTERNET  hSession = NULL, 
               hConnect = NULL,
               hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen( L"WinHTTP Example/1.0",  
                            WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                            WINHTTP_NO_PROXY_NAME, 
                            WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
                                   INTERNET_DEFAULT_HTTPS_PORT, 0);

    // Create an HTTP request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       WINHTTP_FLAG_SECURE);

    // Send a request.
    if (hRequest)
        bResults = WinHttpSendRequest( hRequest,
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       0, 0);

 
    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // Keep checking for data until there is nothing left.
    if (bResults)
        do 
        {
            // Check for available data.
            dwSize = 0;
            if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
                printf("Error %u in WinHttpQueryDataAvailable.\n", GetLastError());

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                dwSize=0;
            }
            else
            {
                // Read the Data.
                ZeroMemory(pszOutBuffer, dwSize+1);

                if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                                      dwSize, &dwDownloaded))
                    printf( "Error %u in WinHttpReadData.\n", GetLastError());
                else
                    printf( "%s\n", pszOutBuffer);
            
                // Free the memory allocated to the buffer.
                delete [] pszOutBuffer;
            }

        } while (dwSize > 0);


    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n", GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Fabbisogno

Requisito	Valore
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	Finestre
intestazione	winhttp.h
libreria	Winhttp.lib
dll	Winhttp.dll
Ridistribuibile	WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000.