Sessioni HTTP

WinINet consente di accedere alle risorse nel Web Wide World Wide (WWW). Queste risorse possono essere accessibili direttamente tramite InternetOpenUrl (per altre informazioni, vedere Accesso diretto agli URL).

Le risorse su WWW sono accessibili tramite http. Le funzioni HTTP gestiscono i protocolli sottostanti, consentendo all'applicazione di accedere alle informazioni su WWW. Man mano che il protocollo HTTP si evolve, i protocolli sottostanti vengono aggiornati per mantenere il comportamento della funzione.

Il diagramma seguente illustra le relazioni delle funzioni usate con il protocollo HTTP. Le caselle ombreggiate rappresentano le funzioni che restituiscono handle HINTERNET , mentre le caselle semplici rappresentano le funzioni che usano l'handle HINTERNET creato dalla funzione in base alla quale dipendono.

Per altre informazioni, vedere Handle DI HINTERNET.

Uso delle funzioni WinINet per accedere a WWW

• Avvio di una connessione a WWW
• Apertura di una richiesta
• Aggiunta di intestazioni di richiesta
• Invio di una richiesta
• Registrazione dei dati nel server
• Ottenere informazioni su una richiesta
• Download di risorse da WWW

Le funzioni seguenti vengono usate durante le sessioni HTTP per accedere a WWW.

Avvio di una connessione a WWW

Per avviare una connessione a WWW, l'applicazione deve chiamare la funzione InternetConnect nella radice DIEDNET restituita da InternetOpen. InternetConnect deve stabilire una sessione HTTP dichiarando il tipo di servizio INTERNET_SERVICE_HTTP. Per altre informazioni sull'uso di InternetConnect, vedere Uso di InternetConnect.

Apertura di una richiesta

La funzione HttpOpenRequest apre una richiesta HTTP e restituisce un handle JSONNET che può essere usato dalle altre funzioni HTTP. A differenza delle altre funzioni aperte (ad esempio FtpOpenFile e InternetOpenUrl), HttpOpenRequest non invia la richiesta a Internet quando viene chiamata. La funzione HttpSendRequest invia la richiesta e stabilisce una connessione sulla rete.

HttpOpenRequest accetta un handle di sessione HTTP creato da InternetConnect e un verbo HTTP, nome dell'oggetto, stringa di versione, referrer, accetta tipi, flag e valore di contesto.

Il verbo HTTP è una stringa da usare nella richiesta. I verbi HTTP comuni usati nelle richieste includono GET, PUT e POST. Se questo valore è impostato su NULL, HttpOpenRequest usa il valore predefinito GET.

Il nome dell'oggetto è una stringa che contiene il nome dell'oggetto di destinazione del verbo HTTP specificato. Si tratta in genere di un nome file, di un modulo eseguibile o di un identificatore di ricerca. Se il nome dell'oggetto specificato è una stringa vuota, HttpOpenRequest cerca la pagina predefinita.

La stringa di versione deve contenere la versione HTTP. Se questo parametro è NULL, la funzione usa ""HTTP/1.1"".

Il referrer specifica l'indirizzo del documento da cui è stato ottenuto il nome dell'oggetto. Se questo parametro è NULL, non viene specificato alcun referrer.

La stringa con terminazione null contenente i tipi di accettazione indica i tipi di contenuto accettati dall'applicazione. L'impostazione di questo parametro su NULL indica che nessun tipo di contenuto viene accettato dall'applicazione. Se viene fornita una stringa vuota, l'applicazione indica che accetta solo documenti di tipo ""text/*"". Il valore ""text/*"" indica documenti di sola testo, non immagini o altri file binari.

I valori del flag controllano la memorizzazione nella cache, i cookie e i problemi di sicurezza. Per Microsoft Network (MSN), NTLM e altri tipi di autenticazione, impostare il flag di INTERNET_FLAG_KEEP_CONNECTION .

Se il flag di INTERNET_FLAG_ASYNC è stato impostato nella chiamata a InternetOpen, è necessario impostare un valore di contesto diverso da zero per un'operazione asincrona appropriata.

L'esempio seguente è una chiamata di esempio a HttpOpenRequest.

hHttpRequest = HttpOpenRequest( hHttpSession, "GET", "", NULL, "", NULL, 0, 0);

Aggiunta di intestazioni di richiesta

La funzione HttpAddRequestHeaders consente alle applicazioni di aggiungere una o più intestazioni di richiesta alla richiesta iniziale. Questa funzione consente a un'applicazione di aggiungere intestazioni di formato libero aggiuntive all'handle di richiesta HTTP; è destinato all'uso da parte di applicazioni sofisticate che richiedono un controllo preciso sulla richiesta inviata al server HTTP.

HttpAddRequestHeaders richiede un handle di richiesta HTTP creato da HttpOpenRequest, una stringa che contiene le intestazioni, la lunghezza delle intestazioni e i modificatori.

Invio di una richiesta

HttpSendRequest stabilisce una connessione a Internet e invia la richiesta al sito specificato. Questa funzione richiede un handle HINTERNET creato da HttpOpenRequest. HttpSendRequest può anche inviare intestazioni aggiuntive o informazioni facoltative. Le informazioni facoltative vengono generalmente usate per le operazioni che scrivono informazioni nel server, ad esempio PUT e POST.

Dopo che HttpSendRequest invia la richiesta, l'applicazione può usare le funzioni InternetReadFile, InternetQueryDataAvailable e InternetSetFilePointer nell'handle HINTERNET creato da HttpOpenRequest per scaricare le risorse del server.

Registrazione dei dati nel server

Per pubblicare i dati in un server, il verbo HTTP nella chiamata a HttpOpenRequest deve essere POST o PUT. L'indirizzo del buffer che contiene i dati POST deve quindi essere passato al parametro lpOptional in HttpSendRequest. Il parametro dwOptionalLength deve essere impostato sulle dimensioni dei dati.

È anche possibile usare la funzione InternetWriteFile per pubblicare i dati in un handle HINTERNET inviato usando HttpSendRequestEx.

Ottenere informazioni su una richiesta

HttpQueryInfo consente a un'applicazione di recuperare informazioni su una richiesta HTTP. La funzione richiede un handle HINTERNET creato da HttpOpenRequest o InternetOpenUrl, un valore a livello di informazioni e una lunghezza del buffer. HttpQueryInfo accetta anche un buffer che archivia le informazioni e un indice di intestazione in base zero che enumera più intestazioni con lo stesso nome.

Download di risorse da WWW

Dopo aver aperto una richiesta con HttpOpenRequest e inviarla al server con HttpSendRequest, l'applicazione può usare le funzioni InternetReadFile, InternetQueryDataAvailable e InternetSetFilePointer per scaricare la risorsa dal server HTTP.

Nell'esempio seguente viene scaricata una risorsa. La funzione accetta l'handle nella finestra corrente, il numero di identificazione di una casella di modifica e un handle HINTERNET creato da HttpOpenRequest e inviato da HttpSendRequest. Usa InternetQueryDataAvailable per determinare le dimensioni della risorsa e quindi scaricarla usando InternetReadFile. Il contenuto viene quindi visualizzato nella casella di modifica.

int WINAPI Dumper(HWND hX, int intCtrlID, HINTERNET hResource)
{
    LPTSTR lpszData;    // buffer for the data
    DWORD  dwSize;       // size of the data available
    DWORD  dwDownloaded; // size of the downloaded data
    DWORD  dwSizeSum=0;  // size of the data in the textbox
    LPTSTR lpszHolding;  // buffer to merge the textbox data and buffer

    // Set the cursor to an hourglass.
    SetCursor(LoadCursor(NULL,IDC_WAIT));

    // This loop handles reading the data.
    do
    {
        // The call to InternetQueryDataAvailable determines the
        // amount of data available to download.
        if (!InternetQueryDataAvailable(hResource,&dwSize,0,0))
        {
            printf("InternetQueryDataAvailable failed (%d)\n", GetLastError());
            SetCursor(LoadCursor(NULL,IDC_ARROW));
            return FALSE;
        }
        else
        {
            // Allocate a buffer of the size returned by
            // InternetQueryDataAvailable.
            lpszData = new TCHAR[dwSize+1];

            // Read the data from the HINTERNET handle.
            if(!InternetReadFile(hResource,
                                 (LPVOID)lpszData,
                                 dwSize,
                                 &dwDownloaded))
            {
                printf("InternetReadFile failed (%d)\n", GetLastError());
                delete[] lpszData;
                break;
            }
            else
            {
                // Add a null terminator to the end of the data buffer
                lpszData[dwDownloaded]='\0';

                // Allocate the holding buffer.
                lpszHolding = new TCHAR[dwSizeSum + dwDownloaded + 1];

                // Check if there has been any data written
                // to the textbox.
                if (dwSizeSum != 0)
                {
                    // Retrieve the data stored in the textbox if any
                    GetDlgItemText(hX,intCtrlID,
                                   (LPTSTR)lpszHolding,
                                   dwSizeSum);

                    // Add a null terminator at the end of the
                    // textbox data.
                    lpszHolding[dwSizeSum]='\0';
                }
                else
                {
                    // Make the holding buffer an empty string.
                    lpszHolding[0]='\0';
                }

                size_t cchDest = dwSizeSum + dwDownloaded + dwDownloaded + 1;
                LPTSTR* ppszDestEnd = 0;
                size_t* pcchRemaining = 0;

                // Add the new data to the holding buffer
                HRESULT hr = StringCchCatEx(lpszHolding,
                                            cchDest,
                                            lpszData,
                                            ppszDestEnd,
                                            pcchRemaining,
                                            STRSAFE_NO_TRUNCATION);

                if(SUCCEEDED(hr))
                {
                    // Write the holding buffer to the textbox.
                    SetDlgItemText(hX,intCtrlID,(LPTSTR)lpszHolding);

                    // Delete the two buffers.
                    delete[] lpszHolding;
                    delete[] lpszData;

                    // Add the size of the downloaded data to the
                    // textbox data size.
                    dwSizeSum = dwSizeSum + dwDownloaded + 1;

                    // Check the size of the remaining data.
                    // If it is zero, break.
                    if (dwDownloaded == 0)
                        break;
                    else
                    {
                    //  TODO: Insert error handling code here.
                    }
                }
            }
        }
    }
    while(TRUE);

    // Close the HINTERNET handle.
    InternetCloseHandle(hResource);

    // Set the cursor back to an arrow.
    SetCursor(LoadCursor(NULL,IDC_ARROW));

    return TRUE;
}