Partilhar via

Classe CHttpFile

  • Artigo

Fornece a funcionalidade de solicitar e ler arquivos em um servidor HTTP.

Sintaxe

class CHttpFile : public CInternetFile

Membros

Construtores Protegidos

Nome Descrição
CHttpFile::CHttpFile Cria um objeto CHttpFile.

Métodos públicos

Nome Descrição
CHttpFile::AddRequestHeaders Adiciona cabeçalhos à solicitação enviada a um servidor HTTP.
CHttpFile::EndRequest Encerra uma solicitação enviada a um servidor HTTP com a função de membro SendRequestEx.
CHttpFile::GetFileURL Recebe a URL do arquivo especificado.
CHttpFile::GetObject Recebe o objeto de destino do verbo em uma solicitação para um servidor HTTP.
CHttpFile::GetVerb Recebe o verbo usado em uma solicitação para um servidor HTTP.
CHttpFile::QueryInfo Retorna os cabeçalhos de resposta ou de solicitação do servidor HTTP.
CHttpFile::QueryInfoStatusCode Recupera o código de status associado a uma solicitação HTTP e o coloca no parâmetro dwStatusCode fornecido.
CHttpFile::SendRequest Envia uma solicitação para um servidor HTTP.
CHttpFile::SendRequestEx Envia uma solicitação para um servidor HTTP usando os métodos Write ou WriteString de CInternetFile.

Comentários

Se a sessão da Internet ler os dados de um servidor HTTP, você deve criar uma instância de CHttpFile.

Para saber mais sobre como CHttpFile funciona com as outras classes de Internet do MFC, confira o artigo Programação na Internet com o WinInet.

Hierarquia de herança

CObject

CFile

CStdioFile

CInternetFile

CHttpFile

Requisitos

Cabeçalho: afxinet.h

CHttpFile::AddRequestHeaders

Chame essa função de membro para adicionar um ou mais cabeçalhos de solicitação HTTP ao identificador de solicitação 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 cadeia de caracteres que contém o cabeçalho ou os cabeçalhos a serem acrescentados à solicitação. Cada cabeçalho deve ser terminado por um par CR/LF.

dwFlags
Modifica a semântica dos novos cabeçalhos. Um dos seguintes pode ser feito:

  • HTTP_ADDREQ_FLAG_COALESCE Mescla os cabeçalhos do mesmo nome, usando o sinalizador para adicionar o primeiro cabeçalho encontrado ao cabeçalho subsequente. Por exemplo, "Accept: text/*" seguido de "Accept: audio/*" resulta na formação do cabeçalho individual "Accept: text/*, audio/*". Cabe ao aplicativo de chamada garantir um esquema coeso em relação aos dados recebidos por solicitações enviadas com cabeçalhos unidos ou separados.

  • HTTP_ADDREQ_FLAG_REPLACE Executa 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 completo será usado para adicionar o novo cabeçalho. Se o header-value estiver vazio e o cabeçalho for encontrado, ele será removido. Se não estiver vazio, o header-value será substituído.

  • HTTP_ADDREQ_FLAG_ADD_IF_NEW Só adiciona o cabeçalho se ele ainda não existir. Se existir, um erro será retornado.

  • HTTP_ADDREQ_FLAG_ADD Usado com REPLACE. Adiciona o cabeçalho se ele não existir.

dwHeadersLen
O tamanho, em caracteres, de pstrHeaders. Se for -1L, pstrHeaders é considerado como terminado em zero e o tamanho é calculado.

str
Uma referência a um objeto CString que contém o cabeçalho ou os cabeçalhos de solicitação a serem adicionados.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

AddRequestHeaders acrescenta cabeçalhos adicionais de formato livre ao identificador de solicitação HTTP. Destina-se a ser usado por clientes avançados que precisam de controle detalhado sobre a solicitação exata enviada ao servidor HTTP.

Observação

O aplicativo pode passar vários cabeçalhos em pstrHeaders ou str para uma chamada AddRequestHeaders usando HTTP_ADDREQ_FLAG_ADD ou HTTP_ADDREQ_FLAG_ADD_IF_NEW. Se o aplicativo tentar remover ou substituir um cabeçalho usando HTTP_ADDREQ_FLAG_REMOVE ou HTTP_ADDREQ_FLAG_REPLACE, somente um cabeçalho poderá ser fornecido em lpszHeaders.

CHttpFile::CHttpFile

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

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 identificador para um arquivo da Internet.

hSession
Um identificador para uma sessão da Internet.

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

pstrServer
Um ponteiro para uma cadeia de caracteres contendo o nome do servidor.

pstrVerb
Um ponteiro para uma cadeia de caracteres que contém o método a ser usado ao enviar a solicitação. Pode ser POST, HEAD ou GET.

dwContext
O identificador de contexto do objeto CHttpFile. Confira Comentários, para obter mais informações sobre esse parâmetro.

pConnection
Um ponteiro para um objeto CHttpConnection.

Comentários

Você nunca constrói um objeto CHttpFile diretamente. Em vez disso, chame CInternetSession::OpenURL ou CHttpConnection::OpenRequest.

O valor padrão para dwContext é enviado pela biblioteca MFC para o objeto CHttpFile do objeto CInternetSession que criou o objeto CHttpFile. Ao chamar CInternetSession::OpenURL ou CHttpConnection para construir um objeto CHttpFile, você pode substituir o padrão para definir o identificador de contexto como um valor de sua escolha. O identificador de contexto retorna para CInternetSession::OnStatusCallback para fornecer status sobre o objeto com o qual é identificado. Confira o artigo Primeiras etapas da Internet: WinInet para mais informações sobre o identificador de contexto.

CHttpFile::EndRequest

Chame essa função de membro para encerrar uma solicitação enviada a um servidor HTTP com a função de membro SendRequestEx.

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

Parâmetros

dwFlags
Sinalizadores que descrevem a operação. Para obter uma lista dos sinalizadores apropriados, confira HttpEndRequest no SDK do Windows.

lpBuffIn
Ponteiro para um INTERNET_BUFFERS inicializado que descreve o buffer de entrada usado para a operação.

dwContext
O identificador de contexto da operação CHttpFile. Confira Comentários, para obter mais informações sobre esse parâmetro.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, determine a causa da falha examinando o objeto CInternetException gerado.

Comentários

O valor padrão para dwContext é enviado pelo MFC para o objeto CHttpFile do objeto CInternetSession que criou o objeto CHttpFile. Quando você chama CInternetSession::OpenURL ou CHttpConnection para construir um objeto CHttpFile, você pode substituir o padrão para definir o identificador de contexto como um valor de sua escolha. O identificador de contexto retorna para CInternetSession::OnStatusCallback para fornecer status sobre o objeto com o qual é identificado. Confira o artigo Primeiros passos da Internet: WinInet para obter mais informações sobre o identificador de contexto.

CHttpFile::GetFileURL

Chame essa função de membro para obter o nome do arquivo HTTP como URL.

virtual CString GetFileURL() const;

Valor de retorno

Um objeto CString que contém uma URL que referencia o recurso associado a esse arquivo.

Comentários

Use essa função de membro somente após uma chamada bem-sucedida para SendRequest ou em um objeto CHttpFile criado com êxito pelo OpenURL.

CHttpFile::GetObject

Chame essa função de membro para obter o nome do objeto associado a esse CHttpFile.

CString GetObject() const;

Valor de retorno

Um objeto CString que contém o nome do objeto.

Comentários

Use essa função de membro somente após uma chamada bem-sucedida para SendRequest ou em um objeto CHttpFile criado com êxito pelo OpenURL.

CHttpFile::GetVerb

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

CString GetVerb() const;

Valor de retorno

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

Comentários

Use essa função de membro somente após uma chamada bem-sucedida para SendRequest ou em um objeto CHttpFile criado com êxito pelo OpenURL.

CHttpFile::QueryInfo

Chame essa função de membro para retornar cabeçalhos de resposta ou de solicitação a partir de uma solicitação 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 para a consulta e os seguintes sinalizadores que especificam o tipo de informação solicitada:

  • HTTP_QUERY_CUSTOM Localiza o nome do cabeçalho e retorna esse valor no lpvBuffer na saída. HTTP_QUERY_CUSTOM gera uma declaração se o cabeçalho não foi encontrado.

  • HTTP_QUERY_FLAG_REQUEST_HEADERS Normalmente, o aplicativo consulta os cabeçalhos de resposta, mas um aplicativo também pode consultar cabeçalhos de solicitação usando esse sinalizador.

  • HTTP_QUERY_FLAG_SYSTEMTIME Para esses cabeçalhos cujo valor é uma cadeia de caracteres de data/hora, como "Last-Modified-Time", esse sinalizador retorna o valor do cabeçalho como estrutura padrão do WIN32 SYSTEMTIME, que não exige que o aplicativo analise os dados. Se você usar esse sinalizador, convém usar a substituição SYSTEMTIME da função.

  • HTTP_QUERY_FLAG_NUMBER Para esses cabeçalhos cujo valor é um número, como o código de status, esse sinalizador retorna os dados como um número de 32 bits.

Confira a seção Comentários, para obter uma lista de valores possíveis.

lpvBuffer
Um ponteiro para o buffer que recebe as informações.

lpdwBufferLength
Na entrada, isso aponta para um valor que contém o tamanho do buffer de dados, em número de caracteres ou bytes. Confira a seção Comentários, para obter informações mais detalhadas sobre esse parâmetro.

lpdwIndex
Um ponteiro para um índice de cabeçalho baseado em zero. Pode ser NULL. Use esse sinalizador para enumerar vários cabeçalhos com o mesmo nome. Na entrada, lpdwIndex indica o índice do cabeçalho especificado a ser retornado. Na saída, lpdwIndex indica o índice do próximo cabeçalho. Se o próximo índice não puder ser encontrado, ERROR_HTTP_HEADER_NOT_FOUND será retornado.

str
Uma referência ao objeto CString que recebe as informações retornadas.

dwIndex
Um valor do índice. Confira lpdwIndex.

pSysTime
Um ponteiro para uma estrutura SYSTEMTIME do Win32.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

Use essa função de membro somente após uma chamada bem-sucedida para SendRequest ou em um objeto CHttpFile criado com êxito pelo OpenURL.

Você pode recuperar os seguintes tipos de dados do QueryInfo:

  • cadeias de caracteres (padrão)

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

  • DWORD (para STATUS_CODE, CONTENT_LENGTH etc.)

Quando uma cadeia de caracteres é gravada no buffer e a função de membro é bem-sucedida, lpdwBufferLength contém o tamanho da cadeia de caracteres em caracteres menos 1, para o caractere NULL de término.

Os possíveis valores 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 essa função de membro para obter o código de status associado a uma solicitação 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 status. Os códigos de status indicam o êxito ou a falha do evento solicitado. Confira Comentários, para obter uma seleção de descrições de código de status.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

Use essa função de membro somente após uma chamada bem-sucedida para SendRequest ou em um objeto CHttpFile criado com êxito pelo OpenURL.

Os códigos de status HTTP se enquadram em grupos, que indicam o êxito ou a falha da solicitação. As tabelas a seguir descrevem os grupos de códigos de status e os códigos de status HTTP mais comuns.

Grupo Significado
200 a 299 Êxito
300 a 399 Informações
400-499 Erro de solicitação
500-599 Erro do servidor

Códigos de status HTTP comuns:

Código de status Significado
200 URL localizada, transmissão a seguir
400 Solicitação ininteligível
404 URL solicitada não encontrada
405 O servidor não dá suporte ao método solicitado
500 Erro de servidor desconhecido
503 Capacidade do servidor atingida

CHttpFile::SendRequest

Chame essa função de membro para enviar uma solicitação para 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 ponteiro para uma cadeia de caracteres que contém o nome dos cabeçalhos a serem enviados.

dwHeadersLen
O tamanho dos cabeçalhos identificados por pstrHeaders.

lpOptional
Todos os dados opcionais a serem enviados imediatamente após os cabeçalhos de solicitação. Geralmente, isso é usado para operações POST e PUT. Isso pode ser NULL, se não houver dados opcionais a serem enviados.

dwOptionalLen
O tamanho de lpOptional.

strHeaders
Uma cadeia de caracteres que contém o nome dos cabeçalhos para a solicitação que está sendo enviada.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, determine a causa da falha examinando o objeto CInternetException gerado.

CHttpFile::SendRequestEx

Chame essa função de membro para enviar uma solicitação para 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 serem enviados na solicitação.

dwFlags
Sinalizadores que descrevem a operação. Para obter uma lista dos sinalizadores apropriados, confira HttpSendRequestEx no SDK do Windows.

dwContext
O identificador de contexto da operação CHttpFile. Confira Comentários, para obter mais informações sobre esse parâmetro.

lpBuffIn
Ponteiro para um INTERNET_BUFFERS inicializado que descreve o buffer de entrada usado para a operação.

lpBuffOut
Ponteiro para um INTERNET_BUFFERS inicializado que descreve o buffer de saída usado para a operação.

Valor de retorno

Um valor diferente de zero, se tiver êxito. Se a chamada falhar, determine a causa da falha examinando o objeto CInternetException gerado.

Comentários

Essa função permite que o aplicativo envie dados usando os métodos Write e WriteString de CInternetFile. Você deve saber o tamanho dos dados a serem enviados, antes de chamar qualquer substituição dessa função. A primeira substituição permite que você especifique o tamanho dos dados que deseja enviar. A segunda substituição aceita ponteiros para estruturas INTERNET_BUFFERS, que podem ser usadas para descrever o buffer detalhadamente.

Depois que o conteúdo for gravado no arquivo, chame EndRequest para encerrar a operação.

O valor padrão para dwContext é enviado pelo MFC para o objeto CHttpFile do objeto CInternetSession que criou o objeto CHttpFile. Quando você chama CInternetSession::OpenURL ou CHttpConnection para construir um objeto CHttpFile, você pode substituir o padrão para definir o identificador de contexto como um valor de sua escolha. O identificador de contexto retorna para CInternetSession::OnStatusCallback para fornecer status sobre o objeto com o qual é identificado. Confira o artigo Primeiras etapas da Internet: WinInet para mais informações sobre o identificador de contexto.

Exemplo

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

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

Confira também

Classe CInternetFile
Gráfico da hierarquia
Classe CInternetFile
Classe CGopherFile
Classe CHttpConnection