Classe CHttpFile

Fornece a funcionalidade para solicitar e ler ficheiros num servidor HTTP.

Sintaxe

class CHttpFile : public CInternetFile

Membros

Construtores Protegidos

Métodos Públicos

Observações

Se a sua sessão de Internet lê dados de um servidor HTTP, deve criar uma instância de CHttpFile.

Para saber mais sobre como CHttpFile funciona com as outras aulas de Internet do MFC, consulte o artigo Programação da Internet com WinInet.

Hierarquia de herança

CObject

CFile

CStdioFile

Ficheiro CInternet

CHttpFile

Requerimentos

Cabeçalho: afxinet.h

CHttpFicheiro::AddRequestHeaders

Chame esta função membro para adicionar um ou mais cabeçalhos de pedido HTTP ao handle de pedido 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);

Parâmetros

PstrHeaders
Um ponteiro para uma string contendo o cabeçalho ou cabeçalhos para anexar ao pedido. Cada cabeçalho deve ser terminado por um par CR/LF.

dwBandeiras
Modifica a semântica dos novos cabeçalhos. Pode ser um dos seguintes:

• HTTP_ADDREQ_FLAG_COALESCE Funde cabeçalhos com o mesmo nome, usando a flag para adicionar o primeiro cabeçalho encontrado ao cabeçalho seguinte. Por exemplo, "Aceitar: texto/*" seguido de "Aceitar: áudio/*" resulta na formação do único cabeçalho "Aceitar: texto/*, áudio/*". Cabe à aplicação que chama garantir um esquema coeso relativamente aos dados recebidos por pedidos enviados com cabeçalhos coalescidos ou separados.

• HTTP_ADDREQ_FLAG_REPLACE Realiza uma remoção e adição para substituir o cabeçalho atual. O nome do cabeçalho será usado para remover o cabeçalho atual, e o valor total será usado para adicionar o novo cabeçalho. Se o valor do cabeçalho estiver vazio e o cabeçalho for encontrado, é removido. Se não estiver vazio, o valor do cabeçalho é substituído.

• HTTP_ADDREQ_FLAG_ADD_IF_NEW Só adiciona o cabeçalho se este ainda não existir. Se existir uma, é devolvido um erro.

• HTTP_ADDREQ_FLAG_ADD Usado com SUBSTITUIR. Adiciona o cabeçalho se este não existir.

dwHeadersLen
O comprimento, em caracteres, dos pstrHeaders. Se isto for -1L, então assume-se que os pstrHeaders têm terminação zero e o comprimento é calculado.

STR
Uma referência a um objeto CString contendo o cabeçalho ou cabeçalhos do pedido a adicionar.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

AddRequestHeaders adiciona cabeçalhos adicionais de formato livre ao handler do pedido HTTP. Destina-se a ser utilizado por clientes sofisticados que necessitam de controlo detalhado sobre o pedido exato enviado ao servidor HTTP.

CHttpFicheiro::CHttpFile

Esta função membro é chamada para construir um CHttpFile objeto.

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

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

Parâmetros

hFile
Um endereço para um ficheiro da Internet.

hSession
Um nome para uma sessão na Internet.

pstrObject
Um ponteiro para uma cadeia que contém o CHttpFile objeto.

pstrServer
Um apontador para uma string contendo o nome do servidor.

pstrVerb
Um ponteiro para uma string contendo o método a ser usado ao enviar o pedido. Pode ser POST, HEAD ou GET.

dwContext
O identificador de contexto para o CHttpFile objeto. Consulte Observações para mais informações sobre este parâmetro.

pConnection
Um ponteiro para um objeto CHttpConnection .

Observações

Nunca constróis um CHttpFile objeto diretamente; em vez disso, chama CInternetSession::OpenURL ou CHttpConnection::OpenRequest .

O valor predefinido para dwContext é enviado pelo MFC para o CHttpFile objeto a partir do objeto CInternetSession que criou o CHttpFile objeto. Quando chama CInternetSession::OpenURL ou CHttpConnection constrói um CHttpFile objeto, pode sobrepor o padrão para definir o identificador de contexto com um valor à sua escolha. O identificador de contexto é devolvido a CInternetSession::OnStatusCallback para fornecer o estado do objeto com o qual está identificado. Consulte o artigo Internet First Steps: WinInet para mais informações sobre o identificador de contexto.

CHttpFicheiro::FimPedido

Chame esta função membro para terminar um pedido enviado a um servidor HTTP com a função membro SendRequestEx .

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

Parâmetros

dwBandeiras
Bandeiras a descrever a operação. Para uma lista dos flags apropriados, veja HttpEndRequest no SDK do Windows.

lpBuffIn
Apontador para uma INTERNET_BUFFERS inicializada que descreve o buffer de entrada usado para a operação.

dwContext
O identificador de contexto da CHttpFile operação. Consulte Observações para mais informações sobre este parâmetro.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, determine a causa da falha examinando o objeto CInternetException lançado.

Observações

O valor padrão do dwContext é enviado pelo MFC para o CHttpFile objeto a partir do objeto CInternetSession que criou o CHttpFile objeto. Quando chama CInternetSession::OpenURL ou CHttpConnection para construir um CHttpFile objeto, pode sobrepor o padrão para definir o identificador de contexto para um valor à sua escolha. O identificador de contexto é devolvido a CInternetSession::OnStatusCallback para fornecer o estado do objeto com o qual está identificado. Consulte o artigo Internet First Steps: WinInet para mais informações sobre o identificador de contexto.

CHttpFile::GetFileURL

Chame esta função membro para obter o nome do ficheiro HTTP como URL.

virtual CString GetFileURL() const;

Valor de retorno

Um objeto CString contendo uma URL que faz referência ao recurso associado a este ficheiro.

Observações

Use esta função membro apenas após uma chamada bem-sucedida para SendRequest ou num CHttpFile objeto criado com sucesso pelo OpenURL.

CHttpFile::GetObject

Chame esta função membro para obter o nome do objeto associado a este CHttpFile.

CString GetObject() const;

Valor de retorno

Um objeto CString contendo o nome do objeto.

Observações

Use esta função membro apenas após uma chamada bem-sucedida para SendRequest ou num CHttpFile objeto criado com sucesso pelo OpenURL.

CHttpFicheiro::GetVerb

Chame esta função membro para obter o verbo HTTP (ou método) associado a este CHttpFile.

CString GetVerb() const;

Valor de retorno

Um objeto CString contendo o nome do verbo HTTP (ou método).

Observações

Use esta função membro apenas após uma chamada bem-sucedida para SendRequest ou num CHttpFile objeto criado com sucesso pelo OpenURL.

CHttpFicheiro::QueryInfo

Chame esta função membro para devolver cabeçalhos de resposta ou pedido de um pedido 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;

Parâmetros

dwInfoLevel
Uma combinação do atributo a consultar e das seguintes bandeiras que especificam o tipo de informação solicitada:

• HTTP_QUERY_CUSTOM Encontra o nome do cabeçalho e devolve esse valor em lpvBuffer na saída. HTTP_QUERY_CUSTOM lança uma afirmação se o cabeçalho não for encontrado.

• HTTP_QUERY_FLAG_REQUEST_HEADERS Normalmente, a aplicação consulta os cabeçalhos de resposta, mas uma aplicação também pode consultar cabeçalhos de pedidos usando este flag.

• HTTP_QUERY_FLAG_SYSTEMTIME Para os cabeçalhos cujo valor é uma cadeia de data/hora, como "Last-Modified-Time", esta flag devolve o valor do cabeçalho como uma estrutura padrão Win32 SYSTEMTIME que não exige que a aplicação analise os dados. Se usares este flag, podes querer usar a SYSTEMTIME sobreposição da função.

• HTTP_QUERY_FLAG_NUMBER Para os cabeçalhos cujo valor é um número, como o código de estado, esta bandeira devolve os dados como um número de 32 bits.

Consulte a secção de Observações para uma lista dos valores possíveis.

lpvBuffer
Um apontador para o buffer que recebe a informação.

lpdwBufferLength
Ao inserir, isto aponta para um valor contendo o comprimento do buffer de dados, em número de caracteres ou bytes. Consulte a secção Observações para informações mais detalhadas sobre este parâmetro.

lpdwIndex
Um apontador para um índice de cabeçalho baseado em zero. Pode ser NULL. Use esta bandeira para enumerar múltiplos cabeçalhos com o mesmo nome. Na entrada, lpdwIndex indica o índice do cabeçalho especificado a retornar. Na saída, lpdwIndex indica o índice do próximo cabeçalho. Se o próximo índice não for encontrado, ERROR_HTTP_HEADER_NOT_FOUND é devolvido.

STR
Uma referência ao objeto CString que recebe a informação devolvida.

dwIndex
Um valor de índice. Ver lpdwIndex.

pSysTime
Um apontador para uma estrutura SYSTEMTIME do Win32.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

Use esta função membro apenas após uma chamada bem-sucedida para SendRequest ou num CHttpFile objeto criado com sucesso pelo OpenURL.

Pode obter os seguintes tipos de dados a partir de QueryInfo:

• Strings (padrão)

• SYSTEMTIME (para "Data:" "Expires:" etc., cabeçalhos)

• DWORD (para STATUS_CODE, CONTENT_LENGTH, etc.)

Quando uma cadeia é escrita no buffer, e a função membro tem sucesso, lpdwBufferLength contém o comprimento da cadeia em caracteres menos 1 para o carácter NULL que termina.

Os valores possíveis de dwInfoLevel incluem:

• 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

Chame esta função membro para obter o código de estado associado a um pedido HTTP e coloque-o no parâmetro dwStatusCode fornecido.

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Parâmetros

dwStatusCode
Uma referência a um código de estado. Os códigos de estado indicam o sucesso ou fracasso do evento solicitado. Consulte Observações para uma seleção de descrições de códigos de estado.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

Use esta função membro apenas após uma chamada bem-sucedida para SendRequest ou num CHttpFile objeto criado com sucesso pelo OpenURL.

Os códigos de estado HTTP dividem-se em grupos que indicam o sucesso ou fracasso do pedido. As tabelas seguintes descrevem os grupos de códigos de estado e os códigos de estado HTTP mais comuns.

Códigos de Estado HTTP Comuns:

CHttpFicheiro::EnviarPedido

Chame esta função membro para enviar um pedido a um servidor 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);

Parâmetros

PstrHeaders
Um apontador para uma string contendo o nome dos cabeçalhos a enviar.

dwHeadersLen
O comprimento dos cabeçalhos identificados por pstrHeaders.

lpOptional
Quaisquer dados opcionais para enviar imediatamente após os cabeçalhos dos pedidos. Isto é geralmente utilizado para operações POST e PUT. Isto pode ser NULL se não houver dados opcionais para enviar.

dwOptionalLen
A duração do lpOptional.

Cabeçalhos strHeaders
Uma string contendo o nome dos cabeçalhos do pedido enviado.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, determine a causa da falha examinando o objeto CInternetException lançado.

CHttpFicheiro::SendRequestEx

Chame esta função membro para enviar um pedido a um servidor 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);

Parâmetros

dwTotalLen
Número de bytes a enviar no pedido.

dwBandeiras
Bandeiras a descrever a operação. Para uma lista de flags apropriados, veja HttpSendRequestEx no SDK do Windows.

dwContext
O identificador de contexto da CHttpFile operação. Consulte Observações para mais informações sobre este parâmetro.

lpBuffIn
Apontador para uma INTERNET_BUFFERS inicializada que descreve o buffer de entrada usado para a operação.

lpBuffOut
Apontador para uma INTERNET_BUFFERS inicializada que descreve o buffer de saída usado para a operação.

Valor de retorno

Não nulo se for bem-sucedido. Se a chamada falhar, determine a causa da falha examinando o objeto CInternetException lançado.

Observações

Esta função permite que a sua aplicação envie dados usando os métodos Write e WriteString de CInternetFile. Deve saber o comprimento dos dados a enviar antes de chamar qualquer um dos overrides desta função. A primeira sobreposição permite-te especificar o comprimento dos dados que gostarias de enviar. A segunda sobreposição aceita ponteiros para INTERNET_BUFFERS estruturas, que podem ser usados para descrever o buffer em grande detalhe.

Depois de o conteúdo ser escrito no ficheiro, chame o EndRequest para terminar a operação.

O valor padrão do dwContext é enviado pelo MFC para o CHttpFile objeto a partir do objeto CInternetSession que criou o CHttpFile objeto. Quando chama CInternetSession::OpenURL ou CHttpConnection para construir um CHttpFile objeto, pode sobrepor o padrão para definir o identificador de contexto para um valor à sua escolha. O identificador de contexto é devolvido a CInternetSession::OnStatusCallback para fornecer o estado do objeto com o qual está identificado. Consulte o artigo Internet First Steps: WinInet para mais informações sobre o identificador de contexto.

Example

Este fragmento de código envia o conteúdo de uma cadeia para uma DLL chamada MFCISAPI.DLL no servidor LOCALHOST. Embora este exemplo use apenas uma chamada para WriteString, é aceitável usar múltiplas chamadas para enviar dados em blocos.

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();

Consulte também

Classe CInternetFile
Gráfico de Hierarquia
Classe CInternetFile
Classe CGopherFile
Classe CHttpConnection