Funzione WinHttpQueryHeaders (winhttp.h)

Articolo
03/04/2024

La funzione WinHttpQueryHeaders recupera le informazioni sull'intestazione associate a una richiesta HTTP.

Vedere anche WinHttpQueryHeadersEx, che offre un modo per recuperare i nomi di intestazione e le stringhe di valore analizzate.

Sintassi

WINHTTPAPI BOOL WinHttpQueryHeaders(
  [in]           HINTERNET hRequest,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPCWSTR   pwszName,
  [out]          LPVOID    lpBuffer,
  [in, out]      LPDWORD   lpdwBufferLength,
  [in, out]      LPDWORD   lpdwIndex
);

Parametri

[in] hRequest

Handle di richiesta HINTERNET restituito da WinHttpOpenRequest. WinHttpReceiveResponse deve essere stato chiamato per questo handle e aver completato prima che Venga chiamato WinHttpQueryHeaders .

[in] dwInfoLevel

Valore di tipo DWORD che specifica una combinazione di flag di attributo e modificatori elencati nella pagina Flag informazioni query . Questi flag di attributo e modificatore indicano che le informazioni vengono richieste e come formattare.

[in, optional] pwszName

Puntatore a una stringa contenente il nome dell'intestazione. Se il flag in dwInfoLevel non è WINHTTP_QUERY_CUSTOM, impostare questo parametro su WINHTTP_HEADER_NAME_BY_INDEX.

[out] lpBuffer

Puntatore al buffer che riceve le informazioni. L'impostazione di questo parametro su WINHTTP_NO_OUTPUT_BUFFER causa la restituzione di FALSE. La chiamata a GetLastError restituisce quindi ERROR_INSUFFICIENT_BUFFER e lpdwBufferLength contiene il numero di byte necessari per contenere le informazioni richieste.

[in, out] lpdwBufferLength

Puntatore a un valore di tipo DWORD che specifica la lunghezza del buffer di dati, in byte. Quando la funzione restituisce, questo parametro contiene il puntatore a un valore che specifica la lunghezza delle informazioni scritte nel buffer. Quando la funzione restituisce stringhe, si applicano le regole seguenti.

Se la funzione ha esito positivo, lpdwBufferLength specifica la lunghezza della stringa, in byte, meno 2 per il valore null di terminazione.
Se la funzione ha esito negativo e ERROR_INSUFFICIENT_BUFFER viene restituita, lpdwBufferLength specifica il numero di byte che l'applicazione deve allocare per ricevere la stringa.

[in, out] lpdwIndex

Puntatore a un indice di intestazione in base zero usato per enumerare più intestazioni con lo stesso nome. Quando si chiama la funzione, questo parametro è l'indice dell'intestazione specificata da restituire. Quando la funzione restituisce, questo parametro è l'indice dell'intestazione successiva. Se non è possibile trovare l'indice successivo, viene restituito ERROR_WINHTTP_HEADER_NOT_FOUND . Impostare questo parametro su WINHTTP_NO_HEADER_INDEX per specificare che deve essere restituita solo la prima occorrenza di un'intestazione.

Valore restituito

Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per informazioni dettagliate sull'errore, chiamare GetLastError. Tra i codici di errore restituiti sono i seguenti.

Codice di errore	Descrizione
ERROR_WINHTTP_HEADER_NOT_FOUND	Impossibile individuare l'intestazione richiesta.
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.

Per impostazione predefinita , WinHttpQueryHeaders restituisce una stringa. È tuttavia possibile richiedere dati sotto forma di struttura SYSTEMTIME o DWORD includendo il flag di modificatore appropriato in dwInfoLevel. Nella tabella seguente vengono illustrati i possibili tipi di dati che WinHttpQueryHeaders possono restituire insieme al flag di modifica usato per selezionare tale tipo di dati.

Tipo di dati	Flag del modificatore
LPCWSTR	Valore predefinito. Nessun flag di modifica richiesto.
SYSTEMTIME	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

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

Esempio

Nell'esempio seguente viene illustrato come ottenere un handle HINTERNET , aprire una sessione HTTP, creare e inviare un'intestazione di richiesta ed esaminare l'intestazione di risposta restituita.

    DWORD dwSize = 0;
    LPVOID lpOutBuffer = NULL;
    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/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_HTTP_PORT, 0);

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

    // 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);

    // First, use WinHttpQueryHeaders to obtain the size of the buffer.
    if (bResults)
    {
        WinHttpQueryHeaders( hRequest, WINHTTP_QUERY_RAW_HEADERS_CRLF,
                             WINHTTP_HEADER_NAME_BY_INDEX, NULL,
                             &dwSize, WINHTTP_NO_HEADER_INDEX);

        // Allocate memory for the buffer.
        if( GetLastError( ) == ERROR_INSUFFICIENT_BUFFER )
        {
            lpOutBuffer = new WCHAR[dwSize/sizeof(WCHAR)];

            // Now, use WinHttpQueryHeaders to retrieve the header.
            bResults = WinHttpQueryHeaders( hRequest,
                                       WINHTTP_QUERY_RAW_HEADERS_CRLF,
                                       WINHTTP_HEADER_NAME_BY_INDEX,
                                       lpOutBuffer, &dwSize,
                                       WINHTTP_NO_HEADER_INDEX);
        }
    }

    // Print the header contents.
    if (bResults)
        printf("Header contents: \n%S",lpOutBuffer);

    // Free the allocated memory.
    delete [] lpOutBuffer;

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