Funzione WinHttpSendRequest (winhttp.h)
La funzione WinHttpSendRequest invia la richiesta specificata al server HTTP.
Sintassi
WINHTTPAPI BOOL WinHttpSendRequest(
[in] HINTERNET hRequest,
[in, optional] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in, optional] LPVOID lpOptional,
[in] DWORD dwOptionalLength,
[in] DWORD dwTotalLength,
[in] DWORD_PTR dwContext
);
Parametri
[in] hRequest
Handle HINTERNET restituito da WinHttpOpenRequest.
[in, optional] lpszHeaders
Puntatore a una stringa contenente le intestazioni aggiuntive da aggiungere alla richiesta. Questo parametro può essere WINHTTP_NO_ADDITIONAL_HEADERS se non sono presenti intestazioni aggiuntive da aggiungere.
[in] dwHeadersLength
Valore intero lungo senza segno che contiene la lunghezza, in caratteri, delle intestazioni aggiuntive. Se questo parametro è -1L e pwszHeaders non è NULL, questa funzione presuppone che pwszHeaders sia con terminazione null e la lunghezza viene calcolata.
[in, optional] lpOptional
Puntatore a un buffer che contiene tutti i dati facoltativi da inviare immediatamente dopo le intestazioni della richiesta. Questo parametro viene in genere usato per le operazioni POST e PUT. I dati facoltativi possono essere la risorsa o i dati pubblicati nel server. Questo parametro può essere WINHTTP_NO_REQUEST_DATA se non sono presenti dati facoltativi da inviare.
Se il parametro dwOptionalLength è 0, questo parametro viene ignorato e impostato su NULL.
Questo buffer deve rimanere disponibile finché l'handle di richiesta non viene chiuso o la chiamata a WinHttpReceiveResponse è stata completata.
[in] dwOptionalLength
Valore intero lungo senza segno che contiene la lunghezza, in byte, dei dati facoltativi. Questo parametro può essere zero se non sono presenti dati facoltativi da inviare.
Questo parametro deve contenere una lunghezza valida quando il parametro lpOptional non è NULL. In caso contrario, lpOptional viene ignorato e impostato su NULL.
[in] dwTotalLength
Valore intero lungo senza segno che contiene la lunghezza, in byte, dei dati totali inviati. Questo parametro specifica l'intestazione Content-Length della richiesta. Se il valore di questo parametro è maggiore della lunghezza specificata da dwOptionalLength, è possibile usare WinHttpWriteData per inviare dati aggiuntivi.
dwTotalLength non deve cambiare tra le chiamate a WinHttpSendRequest per la stessa richiesta. Se dwTotalLength deve essere modificato, il chiamante deve creare una nuova richiesta.
[in] dwContext
Puntatore a una variabile di dimensioni puntatore contenente un valore definito dall'applicazione passato, con l'handle della richiesta, a qualsiasi funzione di callback.
Valore restituito
Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per informazioni sull'errore estese, chiamare GetLastError. I codici di errore sono elencati nella tabella seguente.
| Codice di errore | Descrizione |
|---|---|
|
Restituito se la connessione al server non è riuscita. |
|
Il server HTTP sicuro richiede un certificato client. L'applicazione recupera l'elenco di emittenti di certificati chiamando WinHttpQueryOption con l'opzione WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST .
Se il server richiede il certificato client, ma non lo richiede, l'applicazione può chiamare in alternativa WinHttpSetOption con l'opzione WINHTTP_OPTION_CLIENT_CERT_CONTEXT . In questo caso, l'applicazione specifica la macro WINHTTP_NO_CLIENT_CERT_CONTEXT nel parametro lpBuffer di WinHttpSetOption. Per altre informazioni, vedere l'opzione WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Windows Server 2003 con SP1, Windows XP con SP2 e Windows 2000: Questo errore non è supportato. |
|
La connessione al server è stata reimpostata o terminata o è stato rilevato un protocollo SSL non compatibile. Ad esempio, WinHTTP versione 5.1 non supporta SSL2 a meno che il client non lo abilita in modo specifico. |
|
Impossibile eseguire l'operazione richiesta perché l'handle fornito non è nello stato corretto. |
|
Il tipo di handle fornito non è corretto per questa operazione. |
|
Si è verificato un errore interno. |
|
L'URL non è valido. |
|
Tentativo di accesso non riuscito. Quando si verifica questo errore, l'handle di richiesta deve essere chiuso con WinHttpCloseHandle. È necessario creare un nuovo handle di richiesta prima di riprovare la funzione che originariamente ha generato questo errore. |
|
Impossibile risolvere il nome del server. |
|
L'operazione è stata annullata, in genere perché l'handle in cui è stata eseguita la richiesta è stata chiusa prima del completamento dell'operazione. |
|
Restituito quando una risposta in ingresso supera un limite di dimensioni WinHTTP interno. |
|
Il certificato Secure Sockets Layer (SSL) inviato dal server sono stati rilevati uno o più errori. Per determinare il tipo di errore rilevato, verificare tramite una notifica di WINHTTP_CALLBACK_STATUS_SECURE_FAILURE in una funzione di callback dello stato. Per altre informazioni, vedere WINHTTP_STATUS_CALLBACK. |
|
Il supporto della funzione WinHTTP viene arrestato o scaricato. |
|
Timeout della richiesta. |
|
L'URL ha specificato uno schema diverso da "http:" o "https:". |
|
Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows) Windows Server 2003, Windows XP e Windows 2000: L'intervallo di prenotazioni TCP impostato con l'opzione WINHTTP_OPTION_PORT_RESERVATION non è sufficiente per inviare questa richiesta. |
|
La lunghezza del contenuto specificata nel parametro dwTotalLength non corrisponde alla lunghezza specificata nell'intestazione Content-Length.
Il parametro lpOptional deve essere NULL e il parametro dwOptionalLength deve essere zero quando è presente l'intestazione Transfer-Encoding. L'intestazione Content-Length non può essere presente quando è presente l'intestazione Transfer-Encoding. |
|
L'applicazione deve chiamare di nuovo WinHttpSendRequest a causa di un problema di reindirizzamento o autenticazione.
Windows Server 2003 con SP1, Windows XP con SP2 e Windows 2000: Questo errore non è supportato. |
Commenti
Anche quando WinHTTP viene usato in modalità asincrona, ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione può operare in modo sincrono o asincrono. In entrambi i casi, se la richiesta viene inviata correttamente, l'applicazione viene richiamata con lo stato di completamento impostato su WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE. Il completamento WINHTTP_CALLBACK_STATUS_REQUEST_ERROR indica che l'operazione è stata completata in modo asincrono, ma non riuscita. Dopo aver ricevuto il callback dello stato WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE , l'applicazione può iniziare a ricevere una risposta dal server con WinHttpReceiveResponse. Prima di allora, non è possibile chiamare altre funzioni asincrone, in caso contrario, ERROR_WINHTTP_INCORRECT_HANDLE_STATE viene restituito.
Un'applicazione non deve eliminare o modificare il buffer puntato da lpOptional fino a quando l'handle di richiesta non viene chiuso o la chiamata a WinHttpReceiveResponse è stata completata, perché è possibile riscontrare una richiesta di autenticazione o un reindirizzamento che richiedeva i dati facoltativi durante la ricezione della risposta. Se l'operazione deve essere interrotta con WinHttpCloseHandle, l'applicazione deve mantenere il buffer valido finché non riceve il callback WINHTTP_CALLBACK_STATUS_REQUEST_ERROR con un codice di errore ERROR_WINHTTP_OPERATION_CANCELLED .
Se WinHTTP viene usato in modo sincrono, ovvero quando WINHTP_FLAG_ASYNC non è stato impostato in WinHttpOpen, un'applicazione non viene chiamata con stato di completamento anche se viene registrata una funzione di callback. Anche in questa modalità, l'applicazione può chiamare WinHttpReceiveResponse quando WinHttpSendRequest restituisce.
La funzione WinHttpSendRequest invia la richiesta specificata al server HTTP e consente al client di specificare intestazioni aggiuntive da inviare insieme alla richiesta.
Questa funzione consente anche al client di specificare dati facoltativi da inviare al server HTTP immediatamente dopo le intestazioni della richiesta. Questa funzionalità viene in genere usata per le operazioni di scrittura, ad esempio PUT e POST.
Un'applicazione può usare lo stesso handle di richiesta HTTP in più chiamate a WinHttpSendRequest per inviare nuovamente la stessa richiesta, ma l'applicazione deve leggere tutti i dati restituiti dalla chiamata precedente prima di chiamare nuovamente questa funzione.
Il nome e il valore delle intestazioni di richiesta aggiunte con questa funzione vengono convalidati. Le intestazioni devono essere ben formatte. Per altre informazioni sulle intestazioni HTTP valide, vedere RFC 2616. Se viene usata un'intestazione non valida, questa funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER. L'intestazione non valida non viene aggiunta.
Windows 2000: Quando si inviano richieste da più thread, potrebbe verificarsi una riduzione significativa delle prestazioni della rete e della CPU.
Windows XP e Windows 2000: Vedere Requisiti di runtime.
WinHttpSetStatusCallback
Se è stata installata una funzione di callback di stato con WinHttpSetStatusCallback, quelle delle notifiche seguenti impostate nel parametro dwNotificationFlags di WinHttpSetStatusCallback indicano lo stato di avanzamento nell'invio della richiesta:- WINHTTP_CALLBACK_STATUS_DETECTING_PROXY (non implementata)
- WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE (solo in modalità asincrona)
- WINHTTP_CALLBACK_STATUS_REDIRECT
- WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
- WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESOLVING_NAME
- WINHTTP_CALLBACK_STATUS_NAME_RESOLVED
- WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER
- WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER
- WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
- WINHTTP_CALLBACK_STATUS_REQUEST_SENT
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
Supporto per un caricamento maggiore di 4 GB
A partire da Windows Vista e Windows Server 2008, WinHttp supporta il caricamento di file fino alle dimensioni di un LARGE_INTEGER (2^64 byte) usando l'intestazione Content-Length. Le lunghezze del payload specificate nella chiamata a WinHttpSendRequest sono limitate alle dimensioni di un DWORD (2^32 byte). Per caricare i dati in un URL maggiore di una DWORD, l'applicazione deve fornire la lunghezza nell'intestazione Content-Length della richiesta. In questo caso, l'applicazione client WinHttp chiama WinHttpSendRequest con il parametro dwTotalLength impostato su WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH.Se l'intestazione Content-Length specifica una lunghezza inferiore a 2^32, l'applicazione deve specificare anche la lunghezza del contenuto nella chiamata a WinHttpSendRequest. Se il parametro dwTotalLength non corrisponde alla lunghezza specificata nell'intestazione Content-Length, la chiamata non riesce e restituisce ERROR_INVALID_PARAMETER.
L'intestazione Content-Length può essere aggiunta nella chiamata a WinHttpAddRequestHeaders oppure può essere specificata nel parametro lpszHeader di WinHttpSendRequest , come illustrato nell'esempio di codice seguente.
BOOL fRet = WinHttpSendRequest(
hReq,
L"Content-Length: 68719476735\r\n",
-1L,
WINHTTP_NO_REQUEST_DATA,
0,
WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
pMyContent);
Intestazione di codifica di trasferimento
A partire da Windows Vista e Windows Server 2008, WinHttp consente alle applicazioni di eseguire la codifica di trasferimento in blocchi sui dati inviati al server. Quando l'intestazione Transfer-Encoding è presente nella richiesta WinHttp, il parametro dwTotalLength nella chiamata a WinHttpSendRequest è impostato su WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH e l'applicazione invia il corpo dell'entità in una o più chiamate a WinHttpWriteData. Il parametro lpOptional di WinHttpSendRequest deve essere NULL e il parametro dwOptionLength deve essere zero, in caso contrario viene restituito un errore di ERROR_WINHTTP_INVALID_PARAMETER . Per terminare il trasferimento dei dati in blocchi, l'applicazione genera un blocco di lunghezza zero e lo invia nell'ultima chiamata a WinHttpWriteData.Esempio
Nell'esempio di codice seguente 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 errors.
if (!bResults)
printf("Error %d has occurred.\n",GetLastError());
// Close 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. |
Vedi anche
Informazioni su Microsoft Windows HTTP Services (WinHTTP)
WINHTTP_STATUS_CALLBACK