Panoramica dell'API server HTTP

L'elenco seguente identifica una tipica sequenza di operazioni che usano l'API server HTTP:

• Inizializzare l'API server HTTP usando la funzione HttpInitialize.
• Creare una coda di richieste usando la funzioneHttpCreateHttpHandle.
• Registrare uno o più URL usando la funzione HttpAddUrl.
• Ricevere le richieste in ingresso indirizzate agli URL registrati usando la funzione HttpReceiveHttpRequest e inviare risposte HTTP per queste richieste usando la funzioneHttpSendHttpResponse.
• (Facoltativo) Quando si invia una risposta, inviare un corpo di entità aggiuntivo usando la funzione httpSendResponseEntityBody.
• Eseguire operazioni di pulizia usando le funzioni di HttpRemoveUrl, CloseHandle e HttpTerminate.

Nelle operazioni che usano gli URL, si noti che è l'URL elaborato contenuto nel membro cookedUrl della struttura HTTP_REQUEST_V1 che deve essere usata. Non usare l'URL non elaborato nel membro pRawUrl, che è esclusivamente per scopi di tracciamento e statistici.

Ogni applicazione crea una propria coda di richieste. Un'applicazione ottiene l'handle della coda di richieste da HttpCreateHttpHandle. Passa questo handle alla funzione HttpAddUrl per aggiungere un URL alla coda delle richieste. L'applicazione riceve la notifica di una richiesta in ingresso e la recupera dalla coda delle richieste chiamando la funzione HttpReceiveHttpRequest con l'handle della coda delle richieste. È possibile utilizzare questa funzione per ricevere le intestazioni della richiesta HTTP oppure sia le intestazioni che il corpo del messaggio. HttpReceiveHttpRequest restituisce anche un identificatore di richiesta (RequestId) per la richiesta ricevuta univoca per l'handle della richiesta.

Nota

È responsabilità dell'applicazione esaminare tutte le intestazioni di richiesta pertinenti, includendo quelle di negoziazione del contenuto se vengono usate, e rifiutare le richieste quando appropriato in base al contenuto delle intestazioni. L'API server HTTP garantisce solo che ogni riga di intestazione venga terminata correttamente e non contenga caratteri non validi.

 

Usare la funzione HttpReceiveRequestEntityBody con l'handle della coda delle richieste per recuperare parti successive del corpo dell'entità di una richiesta, se presenti.

Nota

L'API server HTTP decodifica i messaggi in blocchi sul lato ricezione, ma non esegue la codifica in blocchi sul lato invio. Se la suddivisione in blocchi è necessaria sul lato di invio, l'applicazione deve implementarla. Per altre informazioni sulla codifica in blocchi, vedere RFC 2616.

 

Usare la funzione HttpReceiveClientCertificate con le applicazioni che gestiscono GLI URL usando uno schema sicuro ("https") per recuperare facoltativamente le informazioni sul certificato del client.

Le risposte vengono inviate con la funzionehttpSendHttpResponse. Questa funzione usa RequestId dalla richiesta corrispondente per inviare la risposta. Una risposta può essere inviata in diverse chiamate API nel tempo chiamando la funzione HttpSendResponseEntityBody con il RequestId dalla richiesta ricevuta originariamente.

Nota

Per impostazione predefinita, HttpSendHttpResponse usa "Microsoft-HTTPAPI/1.0" come intestazione "Server:". Se un'applicazione specifica un'intestazione del server in una risposta, tale valore viene inserito come prima parte dell'intestazione del server, seguito da uno spazio e quindi da "Microsoft-HTTPAPI/1.0".

 

In generale, l'API server HTTP nasconde i dettagli della gestione delle connessioni e la relativa creazione e rimozione dalle applicazioni. Tuttavia, un'applicazione può rilevare facoltativamente la chiusura di una connessione chiamando HttpWaitForDisconnect.

Le applicazioni devono eseguire la pulizia attenendosi alla procedura seguente:

• Quando l'applicazione non è in ascolto o non risponde a un URL, l'URL viene rimosso usando la funzione HttpRemoveURL.
• Quando l'applicazione ha finito di utilizzare la coda delle richieste, chiudere l'handle della coda delle richieste usando la funzione CloseHandle.
• Quando l'applicazione ha terminato l'utilizzo della Server API HTTP, chiamare la funzione HttpTerminate.