Edit

Share via

CInternetFile Class

  • Article

Allows access to files on remote systems that use Internet protocols.

Syntax

class CInternetFile : public CStdioFile

Members

Protected Constructors

Name Description
CInternetFile::CInternetFile Constructs a CInternetFile object.

Public Methods

Name Description
CInternetFile::Abort Closes the file, ignoring all warnings and errors.
CInternetFile::Close Closes a CInternetFile and frees its resources.
CInternetFile::Flush Flushes the contents of the write buffer and makes sure the data in memory is written to the target machine.
CInternetFile::GetLength Returns the size of the file.
CInternetFile::Read Reads the number of specified bytes.
CInternetFile::ReadString Reads a stream of characters.
CInternetFile::Seek Repositions the pointer in an open file.
CInternetFile::SetReadBufferSize Sets the size of the buffer where data will be read.
CInternetFile::SetWriteBufferSize Sets the size of the buffer where data will be written.
CInternetFile::Write Writes the number of specified bytes.
CInternetFile::WriteString Writes a null-terminated string to a file.

Public Operators

Name Description
CInternetFile::operator HINTERNET A casting operator for an Internet handle.

Protected Data Members

Name Description
CInternetFile::m_hFile A handle to a file.

Remarks

Provides a base class for the CHttpFile and CGopherFile file classes. You never create a CInternetFile object directly. Instead, create an object of one of its derived classes by calling CGopherConnection::OpenFile or CHttpConnection::OpenRequest. You also can create a CInternetFile object by calling CFtpConnection::OpenFile.

The CInternetFile member functions Open, LockRange, UnlockRange, and Duplicate are not implemented for CInternetFile. If you call these functions on a CInternetFile object, you will get a CNotSupportedException.

To learn more about how CInternetFile works with the other MFC Internet classes, see the article Internet Programming with WinInet.

Inheritance Hierarchy

CObject

CFile

CStdioFile

CInternetFile

Requirements

Header: afxinet.h

CInternetFile::Abort

Closes the file associated with this object and makes the file unavailable for reading or writing.

virtual void Abort();

Remarks

If you have not closed the file before destroying the object, the destructor closes it for you.

When handling exceptions, Abort differs from Close in two important ways. First, the Abort function does not throw an exception on failures because it ignores failures. Second, Abort does not ASSERT if the file has not been opened or was closed previously.

CInternetFile::CInternetFile

This member function is called when a CInternetFile object is created.

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

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

Parameters

hFile
A handle to an Internet file.

pstrFileName
A pointer to a string containing the file name.

pConnection
A pointer to a CInternetConnection object.

bReadMode
Indicates whether the file is read-only.

hSession
A handle to an Internet session.

pstrServer
A pointer to a string containing the name of the server.

dwContext
The context identifier for the CInternetFile object. See WinInet Basics for more information about the context identifier.

Remarks

You never create a CInternetFile object directly. Instead, create an object of one of its derived classes by calling CGopherConnection::OpenFile or CHttpConnection::OpenRequest. You also can create a CInternetFile object by calling CFtpConnection::OpenFile.

CInternetFile::Close

Closes a CInternetFile and frees any of its resources.

virtual void Close();

Remarks

If the file was opened for writing, there is an implicit call to Flush to assure that all buffered data is written to the host. You should call Close when you are finished using a file.

CInternetFile::Flush

Call this member function to flush the contents of the write buffer.

virtual void Flush();

Remarks

Use Flush to assure that all data in memory has actually been written to the target machine and to assure your transaction with the host machine has been completed. Flush is only effective on CInternetFile objects opened for writing.

CInternetFile::GetLength

Returns the size of the file.

virtual ULONGLONG GetLength() const;

CInternetFile::m_hFile

A handle to the file associated with this object.

HINTERNET m_hFile;

CInternetFile::operator HINTERNET

Use this operator to get the Windows handle for the current Internet session.

operator HINTERNET() const;

CInternetFile::Read

Call this member function to read into the given memory, starting at lpvBuf, the specified number of bytes, nCount.

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

Parameters

lpBuf
A pointer to a memory address to which file data is read.

nCount
The number of bytes to be written.

Return Value

The number of bytes transferred to the buffer. The return value may be less than nCount if the end of file was reached.

Remarks

The function returns the number of bytes actually read — a number that may be less than nCount if the file ends. If an error occurs while reading the file, the function throws a CInternetException object that describes the error. Note that reading past the end of the file is not considered an error and no exception will be thrown.

To ensure all data is retrieved, an application must continue to call the CInternetFile::Read method until the method returns zero.

CInternetFile::ReadString

Call this member function to read a stream of characters until it finds a newline character.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Parameters

pstr
A pointer to a string which will receive the line being read.

nMax
The maximum number of characters to be read.

rString
A reference to the CString object that receives the read line.

Return Value

A pointer to the buffer containing plain data retrieved from the CInternetFile object. Regardless of the data type of the buffer passed to this method, it does not perform any manipulations on the data (for example, conversion to Unicode), so you must map the returned data to the structure you expect, as if the void * type were returned.

NULL if end-of-file was reached without reading any data; or, if boolean, FALSE if end-of-file was reached without reading any data.

Remarks

The function places the resulting line into the memory referenced by the pstr parameter. It stops reading characters when it reaches the maximum number of characters, specified by nMax. The buffer always receives a terminating null character.

If you call ReadString without first calling SetReadBufferSize, you will get a buffer of 4096 bytes.

CInternetFile::Seek

Call this member function to reposition the pointer in a previously opened file.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Parameters

lOffset
Offset in bytes to move the read/write pointer in the file.

nFrom
Relative reference for the offset. Must be one of the following values:

  • CFile::begin Move the file pointer lOff bytes forward from the beginning of the file.

  • CFile::current Move the file pointer lOff bytes from the current position in the file.

  • CFile::end Move the file pointer lOff bytes from the end of the file. lOff must be negative to seek into the existing file; positive values will seek past the end of the file.

Return Value

The new byte offset from the beginning of the file if the requested position is legal; otherwise, the value is undefined and a CInternetException object is thrown.

Remarks

The Seek function permits random access to a file's contents by moving the pointer a specified amount, absolutely or relatively. No data is actually read during the seek.

At this time, a call to this member function is only supported for data associated with CHttpFile objects. It is not supported for FTP or gopher requests. If you call Seek for one of these unsupported services, it will pass back you to the Win32 error code ERROR_INTERNET_INVALID_OPERATION.

When a file is opened, the file pointer is at offset 0, the beginning of the file.

Note

Using Seek may cause an implicit call to Flush.

Example

See the example for the base class implementation ( CFile::Seek).

CInternetFile::SetReadBufferSize

Call this member function to set the size of the temporary read buffer used by a CInternetFile-derived object.

BOOL SetReadBufferSize(UINT nReadSize);

Parameters

nReadSize
The desired buffer size in bytes.

Return Value

Nonzero if successful; otherwise 0. If the call fails, the Win32 function GetLastError may be called to determine the cause of the error.

Remarks

The underlying WinInet APIs do not perform buffering, so choose a buffer size that allows your application to read data efficiently, regardless of the amount of data to be read. If each call to Read normally involves a large aount of data (for example, four or more kilobytes), you should not need a buffer. However, if you call Read to get small chunks of data, or if you use ReadString to read individual lines at a time, then a read buffer improves application performance.

By default, a CInternetFile object does not provide any buffering for reading. If you call this member function, you must be sure that the file has been opened for read access.

You can increase the buffer size at any time, but shrinking the buffer will have no effect. If you call ReadString without first calling SetReadBufferSize, you will get a buffer of 4096 bytes.

CInternetFile::SetWriteBufferSize

Call this member function to set the size of the temporary write buffer used by a CInternetFile-derived object.

BOOL SetWriteBufferSize(UINT nWriteSize);

Parameters

nWriteSize
The size of the buffer in bytes.

Return Value

Nonzero if successful; otherwise 0. If the call fails, the Win32 function GetLastError may be called to determine the cause of the error.

Remarks

The underlying WinInet APIs don't perform buffering, so choose a buffer size that allows your application to write data efficiently regardless of the amount of data to be written. If each call to Write normally involves a large amount of data (for example, four or more kilobytes at a time), you should not need a buffer. However, if you call Write to write small chunks of data, a write buffer improves your application's performance.

By default, a CInternetFile object does not provide any buffering for writing. If you call this member function, you must be sure that the file has been opened for write access. You can change the size of the write buffer at any time, but doing so causes an implicit call to Flush.

CInternetFile::Write

Call this member function to write into the given memory, lpvBuf, the specified number of bytes, nCount.

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

Parameters

lpBuf
A pointer to the first byte to be written.

nCount
Specifies the number of bytes to be written.

Remarks

If any error occurs while writing the data, the function throws a CInternetException object describing the error.

CInternetFile::WriteString

This function writes a null-terminated string to the associated file.

virtual void WriteString(LPCTSTR pstr);

Parameters

pstr
A pointer to a string containing the contents to be written.

Remarks

If any error occurs while writing the data, the function throws a CInternetException object describing the error.

See also

CStdioFile Class
Hierarchy Chart
CInternetConnection Class