Compartir a través de

CHttpFile (clase)

  • Artículo

Proporciona la funcionalidad para solicitar y leer archivos en un servidor HTTP.

Sintaxis

class CHttpFile : public CInternetFile

Miembros

Constructores protegidos

Nombre Descripción
CHttpFile::CHttpFile Crea un objeto CHttpFile.

Métodos públicos

Nombre Descripción
CHttpFile::AddRequestHeaders Agrega encabezados a la solicitud enviada a un servidor HTTP.
CHttpFile::EndRequest Finaliza una solicitud enviada a un servidor HTTP con la función miembro SendRequestEx .
CHttpFile::GetFileURL Obtiene la dirección URL del archivo especificado.
CHttpFile::GetObject Obtiene el objeto de destino del verbo en una solicitud a un servidor HTTP.
CHttpFile::GetVerb Obtiene el verbo que se usó en una solicitud a un servidor HTTP.
CHttpFile::QueryInfo Devuelve los encabezados de respuesta o solicitud del servidor HTTP.
CHttpFile::QueryInfoStatusCode Recupera el código de estado asociado a una solicitud HTTP y lo coloca en el parámetro proporcionado dwStatusCode.
CHttpFile::SendRequest Envía una solicitud a un servidor HTTP.
CHttpFile::SendRequestEx Envía una solicitud a un servidor HTTP mediante los métodos Write o WriteString de CInternetFile.

Comentarios

Si la sesión de Internet lee datos de un servidor HTTP, debe crear una instancia de CHttpFile.

Para obtener más información sobre cómo funciona CHttpFile con las otras clases de Internet de MFC, vea el artículo Programación de Internet con WinInet.

Jerarquía de herencia

CObject

CFile

CStdioFile

CInternetFile

CHttpFile

Requisitos

Encabezado: afxinet.h

CHttpFile::AddRequestHeaders

Llame a esta función miembro para agregar uno o varios encabezados de solicitud HTTP al identificador de solicitud 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
Puntero a una cadena que contiene el encabezado o los encabezados que se van a anexar a la solicitud. Cada encabezado debe terminar por un par CR/LF.

dwFlags
Modifica la semántica de los nuevos encabezados. Puede ser uno de los siguientes:

  • HTTP_ADDREQ_FLAG_COALESCE Combina encabezados con el mismo nombre, utilizando la marca para agregar el primer encabezado encontrado al encabezado posterior. Por ejemplo, "Accept: text/*" seguido de "Accept: audio/*" da como resultado la formación del encabezado único "Accept: text/*, audio/*". Es la aplicación que realiza la llamada la que garantiza un esquema cohesivo con respecto a los datos recibidos por las solicitudes enviadas con encabezados unidos o independientes.

  • HTTP_ADDREQ_FLAG_REPLACE Realiza una eliminación y una adición para reemplazar el encabezado actual. El nombre del encabezado se usará para quitar el encabezado actual y se usará el valor completo para agregar el nuevo encabezado. Si el valor de encabezado está vacío y se encuentra el encabezado, se quita. Si no está vacío, se reemplaza el valor de encabezado.

  • HTTP_ADDREQ_FLAG_ADD_IF_NEW Solo agrega el encabezado si aún no existe. De lo contrario, se devolverá un error.

  • HTTP_ADDREQ_FLAG_ADD Se usa con REPLACE. Agrega el encabezado si no existe.

dwHeadersLen
Longitud, en caracteres, de pstrHeaders. Si es -1L, se supone que pstrHeaders termina en cero y se calcula la longitud.

str
Referencia a un objeto CString que contiene el encabezado o los encabezados de solicitud que se van a agregar.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero. Si se produce un error en la llamada, se puede llamar a la función GetLastError de Win32 para determinar la causa del error.

Comentarios

AddRequestHeaders anexa encabezados de formato libre adicionales al identificador de solicitud HTTP. Está diseñado para ser utilizado por clientes sofisticados que necesitan un control detallado sobre la solicitud exacta enviada al servidor HTTP.

Nota:

La aplicación puede pasar varios encabezados en pstrHeaders o str para una llamada AddRequestHeaders mediante HTTP_ADDREQ_FLAG_ADD o HTTP_ADDREQ_FLAG_ADD_IF_NEW. Si la aplicación intenta quitar o reemplazar un encabezado mediante HTTP_ADDREQ_FLAG_REMOVE o HTTP_ADDREQ_FLAG_REPLACE, solo se puede proporcionar un encabezado en lpszHeaders.

CHttpFile::CHttpFile

Se llama a esta función miembro para construir un 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
Identificador de un archivo de Internet.

hSession
Identificador de una sesión de Internet.

pstrObject
Puntero a una cadena que contiene el objeto CHttpFile.

pstrServer
Puntero a una cadena que contiene el nombre del servidor.

pstrVerb
Puntero a una cadena que contiene el método que se va a usar al enviar la solicitud. Puede ser POST, HEAD o GET.

dwContext
Identificador de contexto del objeto CHttpFile. Para obtener más información acerca de este parámetro, vea Comentarios.

pConnection
Puntero a un objeto CHttpConnection .

Comentarios

Nunca se crea un objeto CHttpFile directamente; en su lugar, llama a CInternetSession::OpenURL o CHttpConnection::OpenRequest.

MFC envía el valor predeterminado de dwContext al objeto CHttpFile desde el objeto CInternetSession que creó el objeto CHttpFile. Al llamar a CInternetSession::OpenURL o CHttpConnection para construir un objeto CHttpFile, se puede invalidar el valor predeterminado para establecer el identificador de contexto en un valor de su elección. El identificador de contexto se devuelve a CInternetSession::OnStatusCallback para proporcionar el estado del objeto con el que se identifica. Vea el artículo Internet First Steps: WinInet para obtener más información sobre el identificador de contexto.

CHttpFile::EndRequest

Llame a esta función miembro para finalizar una solicitud enviada a un servidor HTTP con la función miembro SendRequestEx.

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

Parámetros

dwFlags
Marcas que describen la operación. Para obtener una lista de las marcas adecuadas, consulte HttpEndRequest en Windows SDK.

lpBuffIn
Puntero a INTERNET_BUFFERS inicializado que describe el búfer de entrada usado para la operación.

dwContext
Identificador de contexto para la operación CHttpFile. Para obtener más información acerca de este parámetro, vea Comentarios.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero. Si se produce un error en la llamada, determine la causa del error examinando el objeto CInternetException generado.

Comentarios

MFC envía el valor predeterminado de dwContext al objeto CHttpFile desde el objeto CInternetSession que creó el objeto CHttpFile. Al llamar a CInternetSession::OpenURL o CHttpConnection para construir un objeto CHttpFile, puede invalidar el valor predeterminado para establecer el identificador de contexto en un valor de su elección. El identificador de contexto se devuelve a CInternetSession::OnStatusCallback para proporcionar el estado del objeto con el que se identifica. Consulte el artículo Internet First Steps: WinInet para más información sobre el identificador de contexto.

CHttpFile::GetFileURL

Llame a esta función miembro para obtener el nombre del archivo HTTP como URL.

virtual CString GetFileURL() const;

Valor devuelto

Objeto CString que contiene una dirección URL que hace referencia al recurso asociado a este archivo.

Comentarios

Use esta función miembro solo después de una llamada correcta a SendRequest o en un objeto CHttpFile creado correctamente por OpenURL.

CHttpFile::GetObject

Llame a esta función miembro para obtener el nombre del objeto asociado a este CHttpFile.

CString GetObject() const;

Valor devuelto

Objeto CString que contiene el nombre del objeto.

Comentarios

Use esta función miembro solo después de una llamada correcta a SendRequest o en un objeto CHttpFile creado correctamente por OpenURL.

CHttpFile::GetVerb

Llame a esta función miembro para obtener el verbo HTTP (o método) asociado a este CHttpFile.

CString GetVerb() const;

Valor devuelto

Objeto CString que contiene el nombre del verbo HTTP (o método).

Comentarios

Use esta función miembro solo después de una llamada correcta a SendRequest o en un objeto CHttpFile creado correctamente por OpenURL.

CHttpFile::QueryInfo

Llame a esta función miembro para devolver encabezados de respuesta o solicitud de una solicitud 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
Combinación del atributo que se va a consultar y las marcas siguientes que especifican el tipo de información solicitada:

  • HTTP_QUERY_CUSTOM Busca el nombre del encabezado y devuelve este valor en lpvBuffer en la salida. HTTP_QUERY_CUSTOM produce una aserción si no se encuentra el encabezado.

  • HTTP_QUERY_FLAG_REQUEST_HEADERS Normalmente, la aplicación consulta los encabezados de respuesta, pero una aplicación también puede consultar encabezados de solicitud mediante esta marca.

  • HTTP_QUERY_FLAG_SYSTEMTIME Para esos encabezados cuyo valor es una cadena de fecha y hora, como "Hora de última modificación", esta marca devuelve el valor de encabezado como una estructura SYSTEMTIME Win32 estándar que no requiere que la aplicación analice los datos. Si usa esta marca, puede que desee usar la invalidación SYSTEMTIME de la función.

  • HTTP_QUERY_FLAG_NUMBER Para esos encabezados cuyo valor es un número, como el código de estado, esta marca devuelve los datos como un número de 32 bits.

Consulte la sección Comentarios para obtener una lista de valores posibles.

lpvBuffer
Puntero al búfer que recibe la información.

lpdwBufferLength
En la entrada, esto apunta a un valor que contiene la longitud del búfer de datos, en número de caracteres o bytes. Consulte la sección Comentarios para obtener información más detallada sobre este parámetro.

lpdwIndex
Puntero a un índice de encabezado de base cero. Puede ser NULL. Use esta marca para enumerar varios encabezados con el mismo nombre. En la entrada, lpdwIndex indica el índice del encabezado especificado que se va a devolver. En la salida, lpdwIndex indica el índice del encabezado siguiente. Si no se encuentra el siguiente índice, se devuelve ERROR_HTTP_HEADER_NOT_FOUND.

str
Referencia al objeto CString que recibe la información devuelta.

dwIndex
Valor de índice Vea lpdwIndex.

pSysTime
Puntero a una estructura SYSTEMTIME de Win32.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero. Si se produce un error en la llamada, se puede llamar a la función GetLastError de Win32 para determinar la causa del error.

Comentarios

Use esta función miembro solo después de una llamada correcta a SendRequest o en un objeto CHttpFile creado correctamente por OpenURL.

Puede recuperar los siguientes tipos de datos desde QueryInfo:

  • cadenas (valor predeterminado)

  • SYSTEMTIME (para encabezados "Data:" "Expires:" etc.)

  • DWORD (para STATUS_CODE, CONTENT_LENGTH, etc.)

Cuando se escribe una cadena en el búfer y la función miembro se realiza correctamente, lpdwBufferLength contiene la longitud de la cadena en caracteres menos 1 para el carácter NULL de terminación.

Los posibles valores de dwInfoLevel son los siguientes:

  • 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

Llame a esta función miembro para obtener el código de estado asociado a una solicitud HTTP y colóquelo en el parámetro dwStatusCode proporcionado.

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Parámetros

dwStatusCode
Referencia a un código de estado. Los códigos de estado indican el éxito o el error del evento solicitado. Vea Comentarios para obtener una selección de descripciones de código de estado.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero. Si se produce un error en la llamada, se puede llamar a la función GetLastError de Win32 para determinar la causa del error.

Comentarios

Use esta función miembro solo después de una llamada correcta a SendRequest o en un objeto CHttpFile creado correctamente por OpenURL.

Los códigos de estado HTTP se dividen en grupos que indican el éxito o error de la solicitud. En las tablas siguientes se describen los grupos de código de estado y los códigos de estado HTTP más comunes.

Grupo Significado
200 a 299 Correcto
300 a 399 Información
400-499 Error de solicitud
500-599 Error de servidor

Códigos de estado HTTP comunes:

status code Significado
200 URL ubicada, la transmisión continúa
400 Solicitud ininteligible
404 No se encontró la dirección URL solicitada
405 El servidor no admite el método solicitado
500 Error de servidor desconocido
503 Se ha alcanzado la capacidad del servidor

CHttpFile::SendRequest

Llame a esta función miembro para enviar una solicitud a un 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
Puntero a una cadena que contiene el nombre de los encabezados que se envían.

dwHeadersLen
Longitud de los encabezados identificados por pstrHeaders.

lpOptional
Cualquier dato opcional que se envíe inmediatamente después de los encabezados de solicitud. Esto se usa generalmente para las operaciones POST y PUT. Puede ser NULL si no hay datos opcionales que enviar.

dwOptionalLen
Longitud de lpOptional.

strHeaders
Cadena que contiene el nombre de los encabezados de la solicitud que se envían.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero. Si se produce un error en la llamada, determine la causa del error examinando el objeto CInternetException generado.

CHttpFile::SendRequestEx

Llame a esta función miembro para enviar una solicitud a un 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 que se enviarán en la solicitud.

dwFlags
Marcas que describen la operación. Para obtener una lista de las marcas adecuadas, consulte HttpEndRequest en Windows SDK.

dwContext
Identificador de contexto para la operación CHttpFile. Para obtener más información acerca de este parámetro, vea Comentarios.

lpBuffIn
Puntero a INTERNET_BUFFERS inicializado que describe el búfer de entrada usado para la operación.

lpBuffOut
Puntero a INTERNET_BUFFERS inicializado que describe el búfer de salida usado para la operación.

Valor devuelto

Diferente de cero si es correcto. Si se produce un error en la llamada, determine la causa del error examinando el objeto CInternetException generado.

Comentarios

Esta función permite que la aplicación envíe datos mediante los métodos Write y WriteString de CInternetFile. Debe conocer la longitud de los datos que se van a enviar antes de llamar a cualquiera de las invalidaciones de esta función. La primera invalidación le permite especificar la longitud de los datos que desea enviar. La segunda invalidación acepta punteros a estructuras de INTERNET_BUFFERS que se pueden usar para describir el búfer con gran detalle.

Una vez escrito el contenido en el archivo, llame a EndRequest para finalizar la operación.

MFC envía el valor predeterminado de dwContext al objeto CHttpFile desde el objeto CInternetSession que creó el objeto CHttpFile. Al llamar a CInternetSession::OpenURL o CHttpConnection para construir un objeto CHttpFile, puede invalidar el valor predeterminado para establecer el identificador de contexto en un valor de su elección. El identificador de contexto se devuelve a CInternetSession::OnStatusCallback para proporcionar el estado del objeto con el que se identifica. Vea el artículo Internet First Steps: WinInet para obtener más información sobre el identificador de contexto.

Ejemplo

Este fragmento de código envía el contenido de una cadena a un archivo DLL denominado MFCISAPI.DLL en el servidor LOCALHOST. Aunque en este ejemplo solo se usa una llamada a WriteString, es aceptable usar varias llamadas para enviar datos en bloques.

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 también

CInternetFile (clase)
Gráfico de jerarquías
CInternetFile (clase)
CGopherFile (clase)
CHttpConnection (clase)