Compartir a través de

Clase CInternetFile

  • Artículo

Permite el acceso a archivos de sistemas remotos que utilizan protocolos de Internet.

Sintaxis

class CInternetFile : public CStdioFile

Miembros

Constructores protegidos

Nombre Descripción
CInternetFile::CInternetFile Construye un objeto CInternetFile.

Métodos públicos

Nombre Descripción
CInternetFile::Abort Cierra el archivo y omite todas las advertencias y los errores.
CInternetFile::Close Cierra un objeto CInternetFile y libera sus recursos.
CInternetFile::Flush Vacía el contenido del búfer de escritura y se asegura de que los datos en memoria se escriban en la máquina de destino.
CInternetFile::GetLength Devuelve el tamaño del archivo.
CInternetFile::Read Lee el número de bytes especificados.
CInternetFile::ReadString Lee una secuencia de caracteres.
CInternetFile::Seek Cambia la posición del puntero en un archivo abierto.
CInternetFile::SetReadBufferSize Establece el tamaño del búfer donde se leerán los datos.
CInternetFile::SetWriteBufferSize Establece el tamaño del búfer donde se escribirán los datos.
CInternetFile::Write Escribe el número de bytes especificados.
CInternetFile::WriteString Escribe una cadena terminada en null en un archivo.

Operadores públicos

Nombre Descripción
CInternetFile::operator HINTERNET Operador de conversión para un manipulador de Internet.

Miembros de datos protegidos

Nombre Descripción
CInternetFile::m_hFile Manipulador de un archivo.

Comentarios

Proporciona una clase base para las clases de archivo CHttpFile y CGopherFile. Nunca se crea un CInternetFile objeto directamente. En su lugar, cree un objeto de una de sus clases derivadas llamando a CGopherConnection::OpenFile o CHttpConnection::OpenRequest. También puede crear un objeto CInternetFile mediante una llamada a CFtpConnection::OpenFile.

Las funciones miembro de CInternetFile Open, LockRange, UnlockRange y Duplicate no se han implementado para CInternetFile. Si llama a estas funciones en un objeto CInternetFile, obtendrá una excepción CNotSupportedException.

Para obtener más información sobre cómo funciona CInternetFile 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

Requisitos

Encabezado: afxinet.h

CInternetFile::Abort

Cierra el archivo asociado a este objeto y hace que no esté disponible para su lectura o escritura.

virtual void Abort();

Comentarios

Si no ha cerrado el archivo antes de destruir el objeto, el destructor lo cierra automáticamente.

Al controlar excepciones, Abort difiere de Close de dos maneras importantes. En primer lugar, la función Abort no produce una excepción en los errores porque omite los errores. En segundo lugar, Abort no DECLARA si el archivo no se ha abierto o se ha cerrado anteriormente.

CInternetFile::CInternetFile

Se llama a esta función miembro cuando se crea un objeto CInternetFile.

CInternetFile(
    HINTERNET hFile,
    LPCTSTR pstrFileName,
    CInternetConnection* pConnection,
    BOOL bReadMode);

CInternetFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrFileName,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext,
    BOOL bReadMode);

Parámetros

hFile
Identificador de un archivo de Internet.

pstrFileName
Puntero a una cadena que contiene el nombre de archivo.

pConnection
Puntero a un objeto CInternetConnection.

bReadMode
Indica si el archivo es de solo lectura.

hSession
Identificador de una sesión de Internet.

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

dwContext
Identificador de contexto del objeto CInternetFile. Consulte Fundamentos de WinInet para obtener más información sobre el identificador de contexto.

Comentarios

Nunca se crea un CInternetFile objeto directamente. En su lugar, cree un objeto de una de sus clases derivadas llamando a CGopherConnection::OpenFile o CHttpConnection::OpenRequest. También puede crear un objeto CInternetFile mediante una llamada a CFtpConnection::OpenFile.

CInternetFile::Close

Cierra un objeto CInternetFile y libera sus recursos.

virtual void Close();

Comentarios

Si el archivo se abrió para escritura, hay una llamada implícita a Flush para asegurarse de que todos los datos almacenados en búfer se escriban en el host. Debe llamar a Close cuando haya terminado de usar un archivo.

CInternetFile::Flush

Llame a esta función miembro para vaciar el contenido del búfer de escritura.

virtual void Flush();

Comentarios

Use Flush para asegurarse de que todos los datos en memoria se hayan escrito realmente en la máquina de destino y para asegurarse de que se haya completado la transacción con la máquina host. Flush solo es efectivo en los objetos CInternetFile abiertos para escritura.

CInternetFile::GetLength

Devuelve el tamaño del archivo.

virtual ULONGLONG GetLength() const;

CInternetFile::m_hFile

Manipulador del archivo asociado a este objeto.

HINTERNET m_hFile;

CInternetFile::operator HINTERNET

Use este operador para obtener el manipulador de Windows de la sesión actual de Internet.

operator HINTERNET() const;

CInternetFile::Read

Llame a esta función miembro para leer en la memoria proporcionada, comenzando en lpvBuf, el número especificado de bytes, nCount.

virtual UINT Read(
    void* lpBuf,
    UINT nCount);

Parámetros

lpBuf
Puntero a una dirección de memoria para la que se leen datos de archivo.

nCount
Número de bytes que se escribirán.

Valor devuelto

Número de bytes que se transfieren al búfer. El valor devuelto puede ser menor que nCount si se alcanzó el final del archivo.

Comentarios

La función devuelve el número de bytes que se leyeron realmente (un número que puede ser menor que nCount si se termina el archivo). Si se produce un error al leer el archivo, la función genera un objeto CInternetException que describe el error. Tenga en cuenta que leer más allá del final del archivo no se considera un error y no se generará ninguna excepción.

Para asegurarse de que se hayan recuperado todos los datos, una aplicación debe seguir llamando al método CInternetFile::Read hasta que el método devuelva cero.

CInternetFile::ReadString

Llame a esta función miembro para leer una secuencia de caracteres hasta que encuentre un carácter de nueva línea.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Parámetros

pstr
Puntero a una cadena que recibirá la línea que se va a leer.

nMax
Número máximo de caracteres que se van a leer.

rString
Referencia al objeto CString que recibe la línea leída.

Valor devuelto

Puntero al búfer que contiene los datos sin formato recuperados del objeto CInternetFile. Independientemente del tipo de datos del búfer pasado a este método, no realiza ninguna manipulación en los datos (por ejemplo, conversión a Unicode), por lo que debe asignar los datos devueltos a la estructura esperada, como si se devolva el void * tipo.

NULL si se alcanzó el final del archivo sin leer ningún dato; o, si es un valor booleano, si se alcanzó el final del archivo sin leer ningún dato.

Comentarios

La función coloca la línea resultante en la memoria a la que hace referencia el parámetro pstr. Deja de leer caracteres cuando alcanza el número máximo de caracteres, especificado por nMax. El búfer siempre recibe un carácter nulo de terminación.

Si llama a ReadString sin llamar primero a SetReadBufferSize, tendrá un búfer de 4096 bytes.

CInternetFile::Seek

Llame a esta función miembro para cambiar la posición del puntero en un archivo abierto previamente.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Parámetros

lOffset
Desplazamiento en bytes que se va a mover el puntero de lectura y escritura en el archivo.

nFrom
Referencia relativa del desplazamiento. Debe ser uno de los siguientes valores:

  • CFile::begin Mover el puntero del archivo lOff bytes hacia delante desde el principio del archivo.

  • CFile::current Mover el puntero del archivo lOff bytes desde la posición actual en el archivo.

  • CFile::end Mover el puntero del archivo lOff bytes desde el final del archivo. lOff debe ser negativo para buscar en el archivo existente; los valores positivos buscarán más allá del final del archivo.

Valor devuelto

Nuevo desplazamiento en bytes desde el principio del archivo si la posición solicitada es legal; de lo contrario, el valor es indefinido y se genera un objeto CInternetException.

Comentarios

La función Seek permite el acceso aleatorio al contenido de un archivo moviendo el puntero una cantidad especificada, absoluta o relativamente. En realidad, no se lee ningún dato durante la búsqueda.

En este momento, solo se admite una llamada a esta función miembro para los datos asociados a objetos CHttpFile. No se admite para solicitudes FTP ni gopher. Si llama a Seek para uno de estos servicios no admitidos, se devolverá el código de error ERROR_INTERNET_INVALID_OPERATION de Win32.

Cuando se abre un archivo, el puntero del archivo se encuentra en el desplazamiento 0, el principio del archivo.

Nota:

El uso de Seek puede provocar una llamada implícita a Flush.

Ejemplo

Consulte el ejemplo de la implementación de la clase base (CFile::Seek).

CInternetFile::SetReadBufferSize

Llame a esta función miembro para establecer el tamaño del búfer de lectura temporal utilizado por un objeto derivado de CInternetFile.

BOOL SetReadBufferSize(UINT nReadSize);

Parámetros

nReadSize
Tamaño deseado del búfer en bytes.

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

Las API de WinInet subyacentes no realizan el almacenamiento en búfer, por lo tanto, elija un tamaño de búfer que permita a la aplicación leer datos de forma eficaz, independientemente de la cantidad de datos que se van a leer. Si cada llamada a Read normalmente implica una gran cantidad de datos (por ejemplo, cuatro o más kilobytes), no debe necesitar un búfer. Sin embargo, si llama a Read para obtener pequeños fragmentos de datos, o si usa ReadString para leer líneas individuales a la vez, un búfer de lectura mejora el rendimiento de la aplicación.

De manera predeterminada, un objeto CInternetFile no proporciona almacenamiento en búfer para la lectura. Si llama a esta función miembro, debe asegurarse de que el archivo se haya abierto para acceso de lectura.

Puede aumentar el tamaño del búfer en cualquier momento, pero reducir el búfer no tendrá ningún efecto. Si llama a ReadString sin llamar primero a SetReadBufferSize, tendrá un búfer de 4096 bytes.

CInternetFile::SetWriteBufferSize

Llame a esta función miembro para establecer el tamaño del búfer de escritura temporal utilizado por un objeto derivado de CInternetFile.

BOOL SetWriteBufferSize(UINT nWriteSize);

Parámetros

nWriteSize
El tamaño del búfer , en bytes.

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

Las API de WinInet subyacentes no realizan el almacenamiento en búfer, por lo tanto, elija un tamaño de búfer que permita a la aplicación escribir datos de forma eficaz, independientemente de la cantidad de datos que se van a escribir. Si cada llamada a Write normalmente implica una gran cantidad de datos (por ejemplo, cuatro o más kilobytes a la vez), no debe necesitar un búfer. Sin embargo, si llama a Write para escribir pequeños fragmentos de datos, un búfer de escritura mejora el rendimiento de la aplicación.

De manera predeterminada, un objeto CInternetFile no proporciona almacenamiento en búfer para la escritura. Si llama a esta función miembro, debe asegurarse de que el archivo se haya abierto para acceso de escritura. Puede cambiar el tamaño del búfer de escritura en cualquier momento, pero si lo hace, se produce una llamada implícita a Flush.

CInternetFile::Write

Llame a esta función miembro para escribir en la memoria proporcionada, lpvBuf, el número especificado de bytes, nCount.

virtual void Write(
    const void* lpBuf,
    UINT nCount);

Parámetros

lpBuf
Puntero al primer byte que se va a escribir.

nCount
Especifica el número de bytes que se van a escribir.

Comentarios

Si se produce un error al escribir los datos, la función genera un objeto CInternetException que describe el error.

CInternetFile::WriteString

Esta función escribe una cadena terminada en null en el archivo asociado.

virtual void WriteString(LPCTSTR pstr);

Parámetros

pstr
Puntero a una cadena que contiene el contenido que se va a escribir.

Comentarios

Si se produce un error al escribir los datos, la función genera un objeto CInternetException que describe el error.

Consulte también

CStdioFile (clase)
Gráfico de jerarquías
CInternetConnection (clase)