Funzione WinHttpOpenRequest (winhttp.h)

Articolo
03/04/2024

La funzione WinHttpOpenRequest crea un handle di richiesta HTTP.

Sintassi

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Parametri

[in] hConnect

Handle di connessione HINTERNET a una sessione HTTP restituita da WinHttpConnect.

[in] pwszVerb

Puntatore a una stringa contenente il verbo HTTP da usare nella richiesta. Se questo parametro è NULL, la funzione usa GET come verbo HTTP. Nota Questa stringa deve essere tutta maiuscola. Molti server considerano i verbi HTTP come distinzione tra maiuscole e minuscole e le richieste di Internet Engineering Task Force (IETF) per i commenti (RFC) includono questi verbi usando solo caratteri maiuscoli.

[in] pwszObjectName

Puntatore a una stringa contenente il nome della risorsa di destinazione del verbo HTTP specificato. Si tratta in genere di un nome file, di un modulo eseguibile o di un identificatore di ricerca.

[in] pwszVersion

Puntatore a una stringa contenente la versione HTTP. Se questo parametro è NULL, la funzione usa HTTP/1.1.

[in] pwszReferrer

Puntatore a una stringa che specifica l'URL del documento da cui è stato ottenuto l'URL nella richiesta pwszObjectName . Se questo parametro è impostato su WINHTTP_NO_REFERER, non viene specificato alcun documento di riferimento.

[in] ppwszAcceptTypes

Puntatore a una matrice con terminazione null dei puntatori di stringa che specifica i tipi di supporto accettati dal client. Se questo parametro è impostato su WINHTTP_DEFAULT_ACCEPT_TYPES, nessun tipo viene accettato dal client. In genere, i server gestiscono una mancanza di tipi accettati come indicazione che il client accetta solo documenti di tipo "text/*"; ovvero solo documenti di testo, senza immagini o altri file binari. Per un elenco di tipi di supporti validi, vedere Tipi di supporti definiti da IANA in http://www.iana.org/assignments/media-types/.

[in] dwFlags

Valore intero lungo senza segno contenente i valori del flag Internet. Questo può essere uno o più dei valori seguenti:

Valore	Significato
WINHTTP_FLAG_BYPASS_PROXY_CACHE	Questo flag fornisce lo stesso comportamento di WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE	I caratteri non sicuri nell'URL passato per pwszObjectName non vengono convertiti in sequenze di escape.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY	I caratteri non sicuri nel componente di query dell'URL passato per pwszObjectName non vengono convertiti in sequenze di escape.
WINHTTP_FLAG_ESCAPE_PERCENT	La stringa passata per pwszObjectName viene convertita da un LPCWSTR a un LPSTR. Tutti i caratteri non sicuri vengono convertiti in una sequenza di escape, incluso il simbolo percentuale. Per impostazione predefinita, tutti i caratteri non sicuri tranne il simbolo percentuale vengono convertiti in una sequenza di escape.
WINHTTP_FLAG_NULL_CODEPAGE	La stringa passata per pwszObjectName si presuppone che sia costituita da caratteri ANSI validi rappresentati da WCHAR. Nessun controllo viene eseguito per i caratteri non sicuri. Windows 7: Questa opzione è obsoleta.
WINHTTP_FLAG_REFRESH	Indica che la richiesta deve essere inoltrata al server di origine anziché inviare una versione memorizzata nella cache di una risorsa da un server proxy. Quando viene usato questo flag, viene aggiunta un'intestazione "Pragma: no-cache" all'handle della richiesta. Quando si crea un'intestazione di richiesta HTTP/1.1, viene aggiunto anche "Cache-Control: no-cache".
WINHTTP_FLAG_SECURE	Utilizza semantica sicura delle transazioni. Ciò si traduce nell'uso di Secure Sockets Layer (SSL)/Transport Layer Security (TLS).

Valore restituito

Restituisce un handle di richiesta HTTP valido se ha esito positivo o NULL in caso contrario. Per informazioni sull'errore estese, chiamare GetLastError. Tra i codici di errore restituiti sono i seguenti.

Codice 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 è stata eseguita la richiesta è stata chiusa prima del completamento dell'operazione.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	L'URL ha specificato uno schema diverso da "http:" o "https:".
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows)

Commenti

Il valore restituito indica l'esito positivo o negativo. Per informazioni dettagliate sull'errore, chiamare GetLastError.

La funzione WinHttpOpenRequest crea un nuovo handle di richiesta HTTP e archivia i parametri specificati in tale handle. Un handle di richiesta HTTP contiene una richiesta di invio a un server HTTP e contiene tutte le intestazioni RFC822/MIME/HTTP da inviare come parte della richiesta.

Se pwszVerb è impostato su "HEAD", l'intestazione Content-Length viene ignorata.

Se una funzione di callback di stato è stata installata con WinHttpSetStatusCallback, una notifica di WINHTTP_CALLBACK_STATUS_HANDLE_CREATED indica che WinHttpOpenRequest ha creato un handle di richiesta.

Al termine dell'applicazione chiamante, l'handle HINTERNET restituito da WinHttpOpenRequest deve essere chiuso usando la funzione WinHttpCloseHandle .

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

Esempio

In questo esempio viene illustrato come ottenere un handle HINTERNET , aprire una sessione HTTP, creare un'intestazione di richiesta e inviare tale intestazione al server.


    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.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       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);

    // PLACE ADDITIONAL CODE HERE.

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