Класс CInternetFile

Статья
10/12/2023

Разрешает доступ к файлам в удаленных системах, использующих протоколы Интернета.

Синтаксис

class CInternetFile : public CStdioFile

Участники

Защищенные конструкторы

Имя	Описание
CInternetFile::CInternetFile	Формирует объект `CInternetFile`.

Открытые методы

Имя	Описание
CInternetFile::Abort	Закрывает файл, игнорируя все предупреждения и ошибки.
CInternetFile::Close	`CInternetFile` Закрывает и освобождает свои ресурсы.
CInternetFile::Flush	Очищает содержимое буфера записи и гарантирует, что данные в памяти записываются на целевой компьютер.
CInternetFile::GetLength	Возвращает размер файла.
CInternetFile::Read	Считывает количество указанных байтов.
CInternetFile::ReadString	Считывает поток символов.
CInternetFile::Seek	Переместит указатель в открытый файл.
CInternetFile::SetReadBufferSize	Задает размер буфера, в котором будут считываться данные.
CInternetFile::SetWriteBufferSize	Задает размер буфера, в котором будут записываться данные.
CInternetFile::Write	Записывает количество указанных байтов.
CInternetFile::WriteString	Записывает строку, завершаемую значением NULL, в файл.

Открытые операторы

Имя	Описание
CInternetFile::operator HINTERNET	Оператор приведения для дескриптора Интернета.

Защищенные члены данных

Имя	Описание
CInternetFile::m_hFile	Дескриптор файла.

Замечания

Предоставляет базовый класс для классов файлов CHttpFile и CGopherFile . Вы никогда не создаете объект напрямую CInternetFile . Вместо этого создайте объект одного из производных классов путем вызова CGopher Подключение ion::OpenFile или CHttp Подключение ion::OpenRequest. Вы также можете создать CInternetFile объект, вызвав CFtp Подключение ion::OpenFile.

CInternetFile Функции-члены Open, UnlockRangeLockRangeи Duplicate не реализуются для CInternetFile. При вызове CInternetFile этих функций в объекте вы получите CNotSupportedException.

Дополнительные сведения о CInternetFile работе с другими классами Интернета MFC см. в статье "Интернет-программирование с помощью WinInet".

Иерархия наследования

CObject

Cfile

Cstdiofile

CInternetFile

Требования

Заголовок: afxinet.h

CInternetFile::Abort

Закрывает файл, связанный с этим объектом, и делает файл недоступным для чтения или записи.

virtual void Abort();

Замечания

Если вы еще не закрыли файл перед уничтожением объекта, деструктор закрывает его для вас.

При обработке исключений отличается Abort от Close двумя важными способами. Во-первых, функция не создает исключение при сбоях, Abort так как она игнорирует сбои. Во-вторых, не УТВЕРЖДАЕТ, Abort если файл не был открыт или закрыт ранее.

CInternetFile::CInternetFile

Эта функция-член вызывается при CInternetFile создании объекта.

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

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

Параметры

hFile
Дескриптор к интернет-файлу.

pstrFileName
Указатель на строку, содержащую имя файла.

p Подключение ion
Указатель на объект CInternet Подключение ion.

bReadMode
Указывает, доступен ли файл только для чтения.

hSession
Дескриптор сеанса Интернета.

pstrServer
Указатель на строку, содержащую имя сервера.

Dwcontext
Идентификатор контекста CInternetFile для объекта. Дополнительные сведения об идентификаторе контекста см. в статье "Основы WinInet".

Замечания

Вы никогда не создаете объект напрямую CInternetFile . Вместо этого создайте объект одного из производных классов путем вызова CGopher Подключение ion::OpenFile или CHttp Подключение ion::OpenRequest. Вы также можете создать CInternetFile объект, вызвав CFtp Подключение ion::OpenFile.

CInternetFile::Close

CInternetFile Закрывает и освобождает любой из своих ресурсов.

virtual void Close();

Замечания

Если файл был открыт для записи, существует неявный вызов Flush , чтобы убедиться, что все буферные данные записываются на узел. После завершения работы с файлом необходимо вызвать Close вызов.

CInternetFile::Flush

Вызовите эту функцию-член, чтобы очистить содержимое буфера записи.

virtual void Flush();

Замечания

Используйте для Flush обеспечения того, чтобы все данные в памяти были записаны на целевой компьютер и для обеспечения выполнения транзакции с хост-компьютером. Flush действует только для объектов, открытых CInternetFile для записи.

CInternetFile::GetLength

Возвращает размер файла.

virtual ULONGLONG GetLength() const;

CInternetFile::m_hFile

Дескриптор файла, связанного с этим объектом.

HINTERNET m_hFile;

CInternetFile::operator HINTERNET

Используйте этот оператор, чтобы получить дескриптор Windows для текущего сеанса Интернета.

operator HINTERNET() const;

CInternetFile::Read

Вызовите эту функцию-член для чтения в заданной памяти, начиная с lpvBuf, указанного числа байтов, nCount.

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

Параметры

lpBuf
Указатель на адрес в памяти, по которому считываются данные из файла.

Ncount
Число записываемых байтов.

Возвращаемое значение

Количество байтов, переданных в буфер. Возвращаемое значение может быть меньше nCount , если достигнут конец файла.

Замечания

Функция возвращает количество фактически считываемых байтов — число, которое может быть меньше nCount , если файл заканчивается. Если при чтении файла возникает ошибка, функция создает объект CInternetException , описывающий ошибку. Обратите внимание, что чтение после завершения файла не является ошибкой и не может быть причиной выдачи исключения.

Чтобы убедиться, что все данные извлекаются, приложение должно продолжать вызывать CInternetFile::Read метод, пока метод не возвращает ноль.

CInternetFile::ReadString

Вызовите эту функцию-член для чтения потока символов, пока не будет найден новый символ.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Параметры

pstr
Указатель на строку, которая получит считываемую строку.

nMax
Максимальное число символов для чтения.

rString
Ссылка на объект CString , получающий строку чтения.

Возвращаемое значение

Указатель на буфер, содержащий обычные данные, полученные из объекта CInternetFile . Независимо от типа данных буфера, переданного этому методу, он не выполняет никаких манипуляций с данными (например, преобразование в Юникод), поэтому необходимо сопоставить возвращаемые данные с ожидаемой структурой, как если void* бы тип возвращался.

ЗНАЧЕНИЕ NULL, если конечный файл достигнут без чтения данных; или, если логическое значение, значение FALSE, если конечный путь к файлу достигнут без чтения данных.

Замечания

Функция помещает результирующая строка в память, на которую ссылается параметр pstr . При достижении максимального количества символов, указанных в nMax, он перестает читать символы. Буфер всегда получает конечный символ NULL.

При вызове без первого вызова ReadStringSetReadBufferSize вы получите буфер размером 4096 байт.

CInternetFile::Seek

Вызовите эту функцию-член, чтобы изменить положение указателя в ранее открывшемся файле.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Параметры

lOffset
Смещение в байтах для перемещения указателя на чтение и запись в файле.

nFrom
Относительная ссылка на смещение. Необходимо установить одно из следующих значений.

CFile::begin Переместите указатель файла lOff байт вперед с начала файла.
CFile::current Переместите указатель файла lOff байт из текущей позиции в файле.
CFile::end Переместите указатель файла lOff байт из конца файла. LOff должен быть отрицательным для поиска в существующем файле; положительные значения будут искать в конце файла.

Возвращаемое значение

Новое смещение байтов с начала файла, если запрошенная позиция является законной; в противном случае значение не определено, и создается объект CInternetException .

Замечания

Функция Seek разрешает случайный доступ к содержимому файла путем перемещения указателя на указанный объем, абсолютно или относительно. Данные на самом деле не считываются во время поиска.

В настоящее время вызов этой функции-члена поддерживается только для данных, связанных с CHttpFile объектами. Он не поддерживается для запросов FTP или gopher. Если вы вызываете Seek одну из этих неподдерживаемых служб, она передаст код ошибки Win32 ERROR_INTERNET_INVALID_OPERATION.

При открытии файла указатель файла находится в смещение 0, начало файла.

Примечание.

Использование Seek может вызвать неявный вызов Flush.

Пример

Пример реализации базового класса ( CFile::Seek).

CInternetFile::SetReadBufferSize

Вызовите эту функцию-член, чтобы задать размер временного буфера чтения, используемого производным CInternetFileобъектом.

BOOL SetReadBufferSize(UINT nReadSize);

Параметры

nReadSize
Требуемый размер буфера в байтах.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0. Если вызов завершается ошибкой, можно вызвать функцию GetLastError Win32, чтобы определить причину ошибки.

Замечания

Базовые API WinInet не выполняют буферизацию, поэтому выберите размер буфера, позволяющий приложению эффективно считывать данные независимо от объема считываемых данных. Если каждый вызов чтения обычно включает большую тетю данных (например, четыре или более килобайтов), вам не нужно буфер. Однако при вызове Read получения небольших фрагментов данных или при использовании ReadString для чтения отдельных строк за раз буфер чтения повышает производительность приложения.

По умолчанию CInternetFile объект не предоставляет буферизацию для чтения. При вызове этой функции-члена необходимо убедиться, что файл был открыт для доступа на чтение.

Вы можете в любой момент увеличить размер буфера, но сжатие буфера не будет иметь эффекта. При вызове ReadString без первого вызова SetReadBufferSizeвы получите буфер размером 4096 байт.

CInternetFile::SetWriteBufferSize

Вызовите эту функцию-член, чтобы задать размер временного буфера записи, используемого производным CInternetFileобъектом.

BOOL SetWriteBufferSize(UINT nWriteSize);

Параметры

nWriteSize
Размер буфера в байтах.

Возвращаемое значение

Замечания

Базовые API WinInet не выполняют буферизацию, поэтому выберите размер буфера, позволяющий приложению эффективно записывать данные независимо от объема записываемых данных. Если каждый вызов записи обычно включает в себя большой объем данных (например, четыре или более килобайт за раз), вам не нужно буфер. Однако при вызове записи для записи небольших фрагментов данных буфер записи повышает производительность приложения.

По умолчанию CInternetFile объект не предоставляет буферизацию для записи. При вызове этой функции-члена необходимо убедиться, что файл был открыт для доступа на запись. Размер буфера записи можно изменить в любое время, но это приводит к неявным вызовам Flush.

CInternetFile::Write

Вызовите эту функцию-член для записи в заданную память, lpvBuf, указанное число байтов, nCount.

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

Параметры

lpBuf
Указатель на первый байт, который нужно записать.

Ncount
Указывает число записываемых байтов.

Замечания

Если при записи данных возникает какая-либо ошибка, функция создает объект CInternetException , описывающий ошибку.

CInternetFile::WriteString

Эта функция записывает строку, завершаемую значением NULL, в связанный файл.

virtual void WriteString(LPCTSTR pstr);

Параметры

pstr
Указатель на строку, содержащую содержимое, записываемое.

Замечания

Если при записи данных возникает какая-либо ошибка, функция создает объект CInternetException , описывающий ошибку.

См. также

Класс CStdioFile
Диаграмма иерархии
Класс CInternetConnection

Поделиться через

Класс CInternetFile

Синтаксис

Участники

Защищенные конструкторы

Открытые методы

Открытые операторы

Защищенные члены данных

Замечания

Иерархия наследования

Требования

CInternetFile::Abort

Замечания

CInternetFile::CInternetFile

Параметры

Замечания

CInternetFile::Close

Замечания

CInternetFile::Flush

Замечания

CInternetFile::GetLength

CInternetFile::m_hFile

CInternetFile::operator HINTERNET

CInternetFile::Read

Параметры

Возвращаемое значение

Замечания

CInternetFile::ReadString

Параметры

Возвращаемое значение

Замечания

CInternetFile::Seek

Параметры

Возвращаемое значение

Замечания

Пример

CInternetFile::SetReadBufferSize

Параметры

Возвращаемое значение

Замечания

CInternetFile::SetWriteBufferSize

Параметры

Возвращаемое значение

Замечания

CInternetFile::Write

Параметры

Замечания

CInternetFile::WriteString

Параметры

Замечания

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы