Condividi tramite

Classe CHttpFile

  • Articolo

Fornisce la funzionalità per richiedere e leggere file in un server HTTP.

Sintassi

class CHttpFile : public CInternetFile

Membri

Costruttori protetti

Nome Descrizione
CHttpFile::CHttpFile Crea un oggetto CHttpFile.

Metodi pubblici

Nome Descrizione
CHttpFile::AddRequestHeaders Aggiunge intestazioni alla richiesta inviata a un server HTTP.
CHttpFile::EndRequest Termina una richiesta inviata a un server HTTP con la funzione membro SendRequestEx .
CHttpFile::GetFileURL Ottiene l'URL per il file specificato.
CHttpFile::GetObject Ottiene l'oggetto di destinazione del verbo in una richiesta a un server HTTP.
CHttpFile::GetVerb Ottiene il verbo utilizzato in una richiesta a un server HTTP.
CHttpFile::QueryInfo Restituisce le intestazioni di risposta o richiesta dal server HTTP.
CHttpFile::QueryInfoStatusCode Recupera il codice di stato associato a una richiesta HTTP e lo inserisce nel parametro fornito dwStatusCode .
CHttpFile::SendRequest Invia una richiesta a un server HTTP.
CHttpFile::SendRequestEx Invia una richiesta a un server HTTP usando i metodi Write o WriteString di CInternetFile.

Osservazioni:

Se la sessione Internet legge i dati da un server HTTP, è necessario creare un'istanza di CHttpFile.

Per altre informazioni sul CHttpFile funzionamento delle altre classi Internet MFC, vedere l'articolo Programmazione Internet con WinInet.

Gerarchia di ereditarietà

CObject

CFile

CStdioFile

CInternetFile

CHttpFile

Requisiti

Intestazione: afxinet.h

CHttpFile::AddRequestHeaders

Chiamare questa funzione membro per aggiungere una o più intestazioni di richiesta HTTP all'handle di richiesta HTTP.

BOOL AddRequestHeaders(
    LPCTSTR pstrHeaders,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW,
    int dwHeadersLen = -1);

BOOL AddRequestHeaders(
    CString& str,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW);

Parametri

pstrHeaders
Puntatore a una stringa contenente l'intestazione o le intestazioni da aggiungere alla richiesta. Ogni intestazione deve essere terminata da una coppia CR/LF.

dwFlags
Modifica la semantica delle nuove intestazioni. Può essere uno dei seguenti:

  • HTTP_ADDREQ_FLAG_COALESCE unisce intestazioni con lo stesso nome, usando il flag per aggiungere la prima intestazione trovata all'intestazione successiva. Ad esempio, "Accept: text/*" seguito da "Accept: audio/*" restituisce la formazione della singola intestazione "Accept: text/*, audio/*". Spetta all'applicazione chiamante garantire uno schema coesivo rispetto ai dati ricevuti dalle richieste inviate con intestazioni coalesce o separate.

  • HTTP_ADDREQ_FLAG_REPLACE Esegue una rimozione e un'aggiunta per sostituire l'intestazione corrente. Il nome dell'intestazione verrà usato per rimuovere l'intestazione corrente e il valore completo verrà usato per aggiungere la nuova intestazione. Se il valore dell'intestazione è vuoto e l'intestazione viene trovata, viene rimossa. Se non è vuoto, il valore dell'intestazione viene sostituito.

  • HTTP_ADDREQ_FLAG_ADD_IF_NEW aggiunge l'intestazione solo se non esiste già. Se ne esiste uno, viene restituito un errore.

  • HTTP_ADDREQ_FLAG_ADD Usato con REPLACE. Aggiunge l'intestazione se non esiste.

dwHeadersLen
Lunghezza, in caratteri, di pstrHeaders. Se si tratta di -1L, si presuppone che pstrHeaders sia con terminazione zero e la lunghezza venga calcolata.

str
Riferimento a un oggetto CString contenente l'intestazione o le intestazioni della richiesta da aggiungere.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

AddRequestHeaders aggiunge intestazioni in formato libero aggiuntive all'handle di richiesta HTTP. È destinato all'uso da parte di client sofisticati che necessitano di un controllo dettagliato sulla richiesta esatta inviata al server HTTP.

Nota

L'applicazione può passare più intestazioni in pstrHeaders o str per una AddRequestHeaders chiamata usando HTTP_ADDREQ_FLAG_ADD o HTTP_ADDREQ_FLAG_ADD_IF_NEW. Se l'applicazione tenta di rimuovere o sostituire un'intestazione usando HTTP_ADDREQ_FLAG_REMOVE o HTTP_ADDREQ_FLAG_REPLACE, è possibile specificare una sola intestazione in lpszHeaders.

CHttpFile::CHttpFile

Questa funzione membro viene chiamata per costruire un CHttpFile oggetto .

CHttpFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrObject,
    LPCTSTR pstrServer,
    LPCTSTR pstrVerb,
    DWORD_PTR dwContext);

CHttpFile(
    HINTERNET hFile,
    LPCTSTR pstrVerb,
    LPCTSTR pstrObject,
    CHttpConnection* pConnection);

Parametri

hFile
Handle per un file Internet.

hSession
Handle per una sessione Internet.

pstrObject
Puntatore a una stringa contenente l'oggetto CHttpFile .

pstrServer
Puntatore a una stringa contenente il nome del server.

pstrVerb
Puntatore a una stringa contenente il metodo da utilizzare durante l'invio della richiesta. Può essere POST, HEAD o GET.

dwContext
Identificatore di contesto per l'oggetto CHttpFile . Per altre informazioni su questo parametro, vedere La sezione Osservazioni.

pConnection
Puntatore a un oggetto CHttpConnection .

Osservazioni:

Non si costruisce mai direttamente un CHttpFile oggetto, anziché chiamare CInternetSession::OpenURL o CHttpConnection::OpenRequest .

Il valore predefinito per dwContext viene inviato da MFC all'oggetto CHttpFile dall'oggetto CInternetSession che ha creato l'oggetto CHttpFile . Quando si chiama CInternetSession::OpenURL o CHttpConnection si costruisce un CHttpFile oggetto, è possibile eseguire l'override dell'impostazione predefinita per impostare l'identificatore di contesto su un valore scelto. L'identificatore di contesto viene restituito a CInternetSession::OnStatusCallback per fornire lo stato sull'oggetto con cui viene identificato. Per altre informazioni sull'identificatore di contesto, vedere l'articolo Passaggi preliminari su Internet: WinInet .

CHttpFile::EndRequest

Chiamare questa funzione membro per terminare una richiesta inviata a un server HTTP con la funzione membro SendRequestEx .

BOOL EndRequest(
    DWORD dwFlags = 0,
    LPINTERNET_BUFFERS lpBuffIn = NULL,
    DWORD_PTR dwContext = 1);

Parametri

dwFlags
Flag che descrivono l'operazione. Per un elenco dei flag appropriati, vedere HttpEndRequest in Windows SDK.

lpBuffIn
Puntatore a un INTERNET_BUFFERS inizializzato che descrive il buffer di input usato per l'operazione.

dwContext
Identificatore di contesto per l'operazione CHttpFile. Per altre informazioni su questo parametro, vedere La sezione Osservazioni.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata ha esito negativo, determinare la causa dell'errore esaminando l'oggetto CInternetException generato.

Osservazioni:

Il valore predefinito per dwContext viene inviato da MFC all'oggetto dall'oggetto CHttpFile CInternetSession che ha creato l'oggetto CHttpFile . Quando si chiama CInternetSession::OpenURL o CHttpConnection per costruire un CHttpFile oggetto, è possibile eseguire l'override dell'impostazione predefinita per impostare l'identificatore di contesto su un valore scelto. L'identificatore di contesto viene restituito a CInternetSession::OnStatusCallback per fornire lo stato sull'oggetto con cui viene identificato. Per altre informazioni sull'identificatore di contesto, vedere l'articolo Passaggi preliminari su Internet: WinInet .

CHttpFile::GetFileURL

Chiamare questa funzione membro per ottenere il nome del file HTTP come URL.

virtual CString GetFileURL() const;

Valore restituito

Oggetto CString contenente un URL che fa riferimento alla risorsa associata a questo file.

Osservazioni:

Utilizzare questa funzione membro solo dopo una chiamata riuscita a SendRequest o su un CHttpFile oggetto creato correttamente da OpenURL.

CHttpFile::GetObject

Chiamare questa funzione membro per ottenere il nome dell'oggetto associato a questo CHttpFileoggetto .

CString GetObject() const;

Valore restituito

Oggetto CString contenente il nome dell'oggetto.

Osservazioni:

Utilizzare questa funzione membro solo dopo una chiamata riuscita a SendRequest o su un CHttpFile oggetto creato correttamente da OpenURL.

CHttpFile::GetVerb

Chiamare questa funzione membro per ottenere il verbo HTTP (o il metodo) associato a questo CHttpFileoggetto .

CString GetVerb() const;

Valore restituito

Oggetto CString contenente il nome del verbo HTTP (o metodo).

Osservazioni:

Utilizzare questa funzione membro solo dopo una chiamata riuscita a SendRequest o su un CHttpFile oggetto creato correttamente da OpenURL.

CHttpFile::QueryInfo

Chiamare questa funzione membro per restituire le intestazioni di risposta o richiesta da una richiesta HTTP.

BOOL QueryInfo(
    DWORD dwInfoLevel,
    LPVOID lpvBuffer,
    LPDWORD lpdwBufferLength,
    LPDWORD lpdwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    CString& str,
    LPDWORD dwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    SYSTEMTIME* pSysTime,
    LPDWORD dwIndex = NULL) const;

Parametri

dwInfoLevel
Combinazione dell'attributo per la query e i flag seguenti che specificano il tipo di informazioni richieste:

  • HTTP_QUERY_CUSTOM trova il nome dell'intestazione e restituisce questo valore in lpvBuffer nell'output. HTTP_QUERY_CUSTOM genera un'asserzione se l'intestazione non viene trovata.

  • HTTP_QUERY_FLAG_REQUEST_HEADERS In genere, l'applicazione esegue una query sulle intestazioni di risposta, ma un'applicazione può anche eseguire query sulle intestazioni delle richieste usando questo flag.

  • HTTP_QUERY_FLAG_SYSTEMTIME Per tali intestazioni il cui valore è una stringa di data/ora, ad esempio "Last-Modified-Time", questo flag restituisce il valore di intestazione come struttura WIN32 SYSTEMTIME standard che non richiede all'applicazione di analizzare i dati. Se si usa questo flag, è possibile usare l'override SYSTEMTIME della funzione.

  • HTTP_QUERY_FLAG_NUMBER Per le intestazioni il cui valore è un numero, ad esempio il codice di stato, questo flag restituisce i dati come numero a 32 bit.

Per un elenco dei valori possibili, vedere la sezione Osservazioni .

lpvBuffer
Puntatore al buffer che riceve le informazioni.

lpdwBufferLength
In caso di immissione, punta a un valore contenente la lunghezza del buffer di dati, in numero di caratteri o byte. Per informazioni più dettagliate su questo parametro, vedere la sezione Osservazioni .

lpdwIndex
Puntatore a un indice di intestazione in base zero. Può essere NULL. Usare questo flag per enumerare più intestazioni con lo stesso nome. In input lpdwIndex indica l'indice dell'intestazione specificata da restituire. In output lpdwIndex indica l'indice dell'intestazione successiva. Se non è possibile trovare l'indice successivo, viene restituito ERROR_HTTP_HEADER_NOT_FOUND.

str
Riferimento all'oggetto CString che riceve le informazioni restituite.

dwIndex
Valore di indice. Vedere lpdwIndex.

pSysTime
Puntatore a una struttura SYSTEMTIME Win32.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

Utilizzare questa funzione membro solo dopo una chiamata riuscita a SendRequest o su un CHttpFile oggetto creato correttamente da OpenURL.

È possibile recuperare i tipi di dati seguenti da QueryInfo:

  • stringhe (impostazione predefinita)

  • SYSTEMTIME (per "Data:" "Expires:" e così via)

  • DWORD (per STATUS_CODE, CONTENT_LENGTH e così via)

Quando una stringa viene scritta nel buffer e la funzione membro ha esito positivo, lpdwBufferLength contiene la lunghezza della stringa in caratteri meno 1 per il carattere NULL di terminazione.

I possibili valori dwInfoLevel includono:

  • HTTP_QUERY_MIME_VERSION

  • HTTP_QUERY_CONTENT_TYPE

  • HTTP_QUERY_CONTENT_TRANSFER_ENCODING

  • HTTP_QUERY_CONTENT_ID

  • HTTP_QUERY_CONTENT_DESCRIPTION

  • HTTP_QUERY_CONTENT_LENGTH

  • HTTP_QUERY_ALLOWED_METHODS

  • HTTP_QUERY_PUBLIC_METHODS

  • HTTP_QUERY_DATE

  • HTTP_QUERY_EXPIRES

  • HTTP_QUERY_LAST_MODIFIED

  • HTTP_QUERY_MESSAGE_ID

  • HTTP_QUERY_URI

  • HTTP_QUERY_DERIVED_FROM

  • HTTP_QUERY_LANGUAGE

  • HTTP_QUERY_COST

  • HTTP_QUERY_WWW_LINK

  • HTTP_QUERY_PRAGMA

  • HTTP_QUERY_VERSION

  • HTTP_QUERY_STATUS_CODE

  • HTTP_QUERY_STATUS_TEXT

  • HTTP_QUERY_RAW_HEADERS

  • HTTP_QUERY_RAW_HEADERS_CRLF

CHttpFile::QueryInfoStatusCode

Chiamare questa funzione membro per ottenere il codice di stato associato a una richiesta HTTP e inserirlo nel parametro dwStatusCode fornito.

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Parametri

dwStatusCode
Riferimento a un codice di stato. I codici di stato indicano l'esito positivo o negativo dell'evento richiesto. Per una selezione di descrizioni del codice di stato, vedere La sezione Osservazioni.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata non riesce, è possibile chiamare la funzione Win32 GetLastError per determinare la causa dell'errore.

Osservazioni:

Utilizzare questa funzione membro solo dopo una chiamata riuscita a SendRequest o su un CHttpFile oggetto creato correttamente da OpenURL.

I codici di stato HTTP rientrano in gruppi che indicano l'esito positivo o negativo della richiesta. Le tabelle seguenti descrivono i gruppi di codici di stato e i codici di stato HTTP più comuni.

Raggruppa significato
200-299 Success
300-399 Informazioni
400-499 Errore di richiesta
500-599 Errore server

Codici di stato HTTP comuni:

Codice di stato significato
200 URL localizzato, trasmissione segue
400 Richiesta non comprensibile
404 URL richiesto non trovato
405 Il server non supporta il metodo richiesto
500 Errore del server sconosciuto
503 Capacità del server raggiunta

CHttpFile::SendRequest

Chiamare questa funzione membro per inviare una richiesta a un server HTTP.

BOOL SendRequest(
    LPCTSTR pstrHeaders = NULL,
    DWORD dwHeadersLen = 0,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

BOOL SendRequest(
    CString& strHeaders,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

Parametri

pstrHeaders
Puntatore a una stringa contenente il nome delle intestazioni da inviare.

dwHeadersLen
Lunghezza delle intestazioni identificate da pstrHeaders.

lpOptional
Eventuali dati facoltativi da inviare immediatamente dopo le intestazioni della richiesta. Questa operazione viene in genere usata per le operazioni POST e PUT. Può essere NULL se non sono presenti dati facoltativi da inviare.

dwOptionalLen
Lunghezza di lpOptional.

strHeaders
Stringa contenente il nome delle intestazioni per la richiesta inviata.

Valore restituito

Diverso da zero se ha esito positivo; in caso contrario 0. Se la chiamata ha esito negativo, determinare la causa dell'errore esaminando l'oggetto CInternetException generato.

CHttpFile::SendRequestEx

Chiamare questa funzione membro per inviare una richiesta a un server HTTP.

BOOL SendRequestEx(
    DWORD dwTotalLen,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

BOOL SendRequestEx(
    LPINTERNET_BUFFERS lpBuffIn,
    LPINTERNET_BUFFERS lpBuffOut,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

Parametri

dwTotalLen
Numero di byte da inviare nella richiesta.

dwFlags
Flag che descrivono l'operazione. Per un elenco dei flag appropriati, vedere HttpSendRequestEx in Windows SDK.

dwContext
Identificatore di contesto per l'operazione CHttpFile. Per altre informazioni su questo parametro, vedere La sezione Osservazioni.

lpBuffIn
Puntatore a un INTERNET_BUFFERS inizializzato che descrive il buffer di input usato per l'operazione.

lpBuffOut
Puntatore a un INTERNET_BUFFERS inizializzato che descrive il buffer di output usato per l'operazione.

Valore restituito

Diverso da zero se ha esito positivo. Se la chiamata ha esito negativo, determinare la causa dell'errore esaminando l'oggetto CInternetException generato.

Osservazioni:

Questa funzione consente all'applicazione di inviare dati usando i metodi Write e WriteString di CInternetFile. È necessario conoscere la lunghezza dei dati da inviare prima di chiamare l'override di questa funzione. La prima sostituzione consente di specificare la lunghezza dei dati da inviare. Il secondo override accetta puntatori alle strutture INTERNET_BUFFERS, che possono essere usate per descrivere il buffer in modo dettagliato.

Dopo la scrittura del contenuto nel file, chiamare EndRequest per terminare l'operazione.

Il valore predefinito per dwContext viene inviato da MFC all'oggetto dall'oggetto CHttpFile CInternetSession che ha creato l'oggetto CHttpFile . Quando si chiama CInternetSession::OpenURL o CHttpConnection per costruire un CHttpFile oggetto, è possibile eseguire l'override dell'impostazione predefinita per impostare l'identificatore di contesto su un valore scelto. L'identificatore di contesto viene restituito a CInternetSession::OnStatusCallback per fornire lo stato sull'oggetto con cui viene identificato. Per altre informazioni sull'identificatore di contesto, vedere l'articolo Passaggi preliminari su Internet: WinInet .

Esempio

Questo frammento di codice invia il contenuto di una stringa a una DLL denominata MFCISAPI.DLL nel server LOCALHOST. Anche se in questo esempio viene usata una sola chiamata a WriteString, l'uso di più chiamate per l'invio di dati in blocchi è accettabile.

CString strData = _T("Some very long data to be POSTed here!");
pServer = session.GetHttpConnection(_T("localhost"));
pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_POST,
                             _T("/MFCISAPI/MFCISAPI.dll?"));
pFile->SendRequestEx(strData.GetLength());

pFile->WriteString(strData);
pFile->EndRequest();

Vedi anche

Classe CInternetFile
Grafico della gerarchia
Classe CInternetFile
Classe CGopherFile
Classe CHttpConnection