Funzione WinHttpConnect (winhttp.h)

Articolo
03/04/2024

La funzione WinHttpConnect specifica il server di destinazione iniziale di una richiesta HTTP e restituisce un handle di connessione CONNECTIONNET 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

Handle di sessione WINHTTP WINHTTP VALIDO restituito da una chiamata precedente a WinHttpOpen.

[in] pswzServerName

Puntatore a una stringa con terminazione Null contenente il nome host di un server HTTP. In alternativa, la stringa può contenere l'indirizzo IP del sito in ASCII, ad esempio 10.0.1.45. Si noti che WinHttp non accetta nomi host internazionali senza convertirli per primi in Punycode. Per altre informazioni, vedere Gestione dei nomi di dominio internazionalizzati (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 di transazione sicura 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 o NULL in caso contrario. Per recuperare informazioni sull'errore estese, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Codici 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 su cui era operativa la richiesta è stato chiuso prima del completamento dell'operazione.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Non è stato possibile riconoscere lo schema URL oppure 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)

Commenti

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 informazioni dettagliate sull'errore, chiamare GetLastError.

Dopo che l'applicazione chiamante ha terminato di usare l'handle DELL'interfaccia UTENTE RESTITUITA da WinHttpConnect, deve essere chiusa 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, vedere la sezione Requisiti di runtime della pagina iniziale di WinHttp.

Esempio

L'esempio seguente illustra come usare la semantica della transazione 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 WinHttpReadData viene usato per leggere i dati. Questo processo si ripete 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);

Requisiti

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	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.