Classe CHttpFile
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
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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
SYSTEMTIMEda 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 Devolução
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 Devolução
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 | Sucesso |
| 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 Devolução
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 Devolução
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
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários