CHttpFile (clase)
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
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
SYSTEMTIMEde 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.
| Group (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)
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de