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

Класс CFtpConnection

  • Статья

Управляет подключением FTP к Интернет-серверу и позволяет напрямую управлять каталогами и файлами на этом сервере.

Синтаксис

class CFtpConnection : public CInternetConnection

Участники

Открытые конструкторы

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

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

Имя Описание
CFtpConnection::Command Отправляет команду напрямую на FTP-сервер.
CFtpConnection::CreateDirectory Создает каталог на сервере.
CFtpConnection::GetCurrentDirectory Возвращает текущий каталог для этого подключения.
CFtpConnection::GetCurrentDirectoryAsURL Возвращает текущий каталог для этого подключения в качестве URL-адреса.
CFtpConnection::GetFile Возвращает файл с подключенного сервера
CFtpConnection::OpenFile Открывает файл на подключенном сервере.
CFtpConnection::P utFile Помещает файл на сервер.
CFtpConnection::Remove Удаляет файл с сервера.
CFtpConnection::RemoveDirectory Удаляет указанный каталог с сервера.
CFtpConnection::Rename Переименовывает файл на сервере.
CFtpConnection::SetCurrentDirectory Задает текущий каталог FTP.

Замечания

FTP является одним из трех интернет-служб, распознанных классами MFC WinInet.

Чтобы взаимодействовать с FTP-сервером Интернета, необходимо сначала создать экземпляр CInternetSession, а затем создать CFtpConnection объект. Объект никогда не создается напрямую CFtpConnection . Вместо этого вызовите CInternetSession::GetFtpConnection, который создает CFtpConnection объект и возвращает указатель на него.

Дополнительные сведения о CFtpConnection работе с другими классами Интернета MFC см. в статье "Интернет-программирование с помощью WinInet". Дополнительные сведения о взаимодействии с двумя другими поддерживаемыми службами, HTTP и gopher, см. в классах CHttpConnection и CGopherConnection.

Пример

См. пример в обзоре класса CFtpFileFind .

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

CObject

CInternetConnection

CFtpConnection

Требования

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

CFtpConnection::CFtpConnection

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

CFtpConnection(
    CInternetSession* pSession,
    HINTERNET hConnected,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext);

CFtpConnection(
    CInternetSession* pSession,
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    DWORD_PTR dwContext = 0,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    BOOL bPassive = FALSE);

Параметры

pSession
Указатель на связанный объект CInternetSession .

hConnected
Дескриптор Windows текущего сеанса Интернета.

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

dwContext
Идентификатор контекста для операции. dwContext определяет сведения о состоянии операции, возвращаемые CInternetSession::OnStatusCallback. Значение по умолчанию равно 1; однако можно явно назначить определенный идентификатор контекста для операции. Объект и любая работа, которую она выполняет, будет связана с этим идентификатором контекста.

pstrUserName
Указатель на строку, завершающуюся значением NULL, которая указывает имя пользователя для входа. Если значение NULL, значение по умолчанию является анонимным.

pstrPassword
Указатель на строку, завершающуюся значением NULL, которая указывает пароль, используемый для входа. Если для pstrPassword и pstrUserName задано значение NULL, анонимный пароль по умолчанию — это имя электронной почты пользователя. Если pstrPassword имеет значение NULL (или пустая строка), но pstrUserName не равно NULL, используется пустой пароль. В следующей таблице описывается поведение четырех возможных параметров pstrUserName и pstrPassword:

pstrUserName pstrPassword Имя пользователя, отправленное на FTP-сервер Пароль, отправленный на FTP-сервер
NULL или " NULL или " "анонимный" Имя электронной почты пользователя
Строка, отличной от NULL NULL или " pstrUserName " "
Строка NULL, отличной от NULL ОШИБКА ОШИБКА
Строка, отличной от NULL Строка, отличной от NULL pstrUserName pstrPassword

nPort
Число, определяющее порт TCP/IP для использования на сервере.

bPassive
Указывает пассивный или активный режим для этого сеанса FTP. Если задано значение TRUE, он задает для dwFlag API Win32 значение INTERNET_FLAG_PASSIVE.

Замечания

Вы никогда не создаете объект напрямую CFtpConnection . Вместо этого вызовите CInternetSession::GetFtpConnection, который создает CFptConnection объект.

CFtpConnection::Command

Отправляет команду напрямую на FTP-сервер.

CInternetFile* Command(
    LPCTSTR pszCommand,
    CmdResponseType eResponse = CmdRespNone,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Параметры

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

eResponse
Указывает, ожидается ли ответ от FTP-сервера. Может использоваться одно из следующих значений:

  • CmdRespNone Ответ не ожидается.
  • CmdRespRead Ожидается ответ.
  • CmdRespWrite Не используется.

CmdResponseType является членом CFtpConnection, определенным в afxinet.h.

dwFlags
Значение, содержащее флаги, управляющие этой функцией. Полный список см. в разделе FTPCommand.

dwContext
Указатель на значение, содержащее определяемое приложением значение, используемое для идентификации контекста приложения в обратных вызовах.

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

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Эта функция-член эмулирует функциональные возможности функции функции FTPCommand , как описано в пакете SDK для Windows.

При возникновении ошибки MFC создает исключение типа CInternetException.

CFtpConnection::CreateDirectory

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

BOOL CreateDirectory(LPCTSTR pstrDirName);

Параметры

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

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

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

Замечания

Используется GetCurrentDirectory для определения текущего рабочего каталога для этого подключения к серверу. Не предполагайте, что удаленная система подключила вас к корневому каталогу.

Параметр pstrDirName может быть частично или полным именем файла относительно текущего каталога. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. CreateDirectory Преобразует разделители имен каталога в соответствующие символы перед их использованием.

CFtpConnection::GetCurrentDirectory

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

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

Параметры

strDirName
Ссылка на строку, которая получит имя каталога.

pstrDirName
Указатель на строку, которая получит имя каталога.

lpdwLen
Указатель на DWORD, содержащий следующие сведения:

В записи: размер буфера, на который ссылается pstrDirName.

При возврате: количество символов, хранящихся в pstrDirName. Если функция-член завершается ошибкой и возвращается ERROR_INSUFFICIENT_BUFFER, lpdwLen содержит количество байтов, которые приложение должно выделить для получения строки.

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

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

Замечания

Чтобы получить имя каталога в качестве URL-адреса, вызовите GetCurrentDirectoryAsURL.

Параметры pstrDirName или strDirName могут быть частично квалифицированными именами файлов относительно текущего каталога или полностью. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. GetCurrentDirectory Преобразует разделители имен каталога в соответствующие символы перед их использованием.

CFtpConnection::GetCurrentDirectoryAsURL

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

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

Параметры

strDirName
Ссылка на строку, которая получит имя каталога.

pstrDirName
Указатель на строку, которая получит имя каталога.

lpdwLen
Указатель на DWORD, содержащий следующие сведения:

В записи: размер буфера, на который ссылается pstrDirName.

При возврате: количество символов, хранящихся в pstrDirName. Если функция-член завершается ошибкой и возвращается ERROR_INSUFFICIENT_BUFFER, lpdwLen содержит количество байтов, которые приложение должно выделить для получения строки.

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

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

Замечания

GetCurrentDirectoryAsURL ведет себя так же, как GetCurrentDirectory

Параметр strDirName может быть частично квалифицированным именем файла относительно текущего каталога или полного. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. GetCurrentDirectoryAsURL Преобразует разделители имен каталога в соответствующие символы перед их использованием.

CFtpConnection::GetFile

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

BOOL GetFile(
    LPCTSTR pstrRemoteFile,
    LPCTSTR pstrLocalFile,
    BOOL bFailIfExists = TRUE,
    DWORD dwAttributes = FILE_ATTRIBUTE_NORMAL,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Параметры

pstrRemoteFile
Указатель на строку, завершающуюся значением NULL, содержащую имя файла, извлекаемого с FTP-сервера.

pstrLocalFile
Указатель на строку, завершающуюся значением NULL, содержащую имя файла, создаваемого в локальной системе.

bFailIfExists
Указывает, может ли имя файла уже использоваться существующим файлом. Если имя локального файла уже существует, и этот параметр имеет значение TRUE, GetFile завершается ошибкой. GetFile В противном случае удалите существующую копию файла.

dwAttributes
Указывает атрибуты файла. Это может быть любое сочетание следующих флагов FILE_ATTRIBUTE_*.

  • FILE_ATTRIBUTE_ARCHIVE Файл является архивным файлом. Приложения используют этот атрибут, чтобы отмечать файлы для резервного копирования или удаления.

  • FILE_ATTRIBUTE_COMPRESSED сжатие файла или каталога. Для файла сжатие означает, что все данные в файле сжимаются. Для каталога сжатие используется по умолчанию для только что созданных файлов и подкаталогов.

  • FILE_ATTRIBUTE_DIRECTORY Файл является каталогом.

  • FILE_ATTRIBUTE_NORMAL Файл не имеет других атрибутов. При использовании этого атрибута не допускается использование других атрибутов. Все остальные атрибуты файла переопределяют FILE_ATTRIBUTE_NORMAL:

  • FILE_ATTRIBUTE_HIDDEN Файл скрыт. Не следует включать в обычный список каталогов.

  • FILE_ATTRIBUTE_READONLY Файл доступен только для чтения. Приложения могут считывать файл, но не могут записывать в него или удалять его.

  • FILE_ATTRIBUTE_SYSTEM Файл является частью или используется исключительно операционной системой.

  • FILE_ATTRIBUTE_TEMPORARY Файл используется для временного хранилища. Приложения должны записывать в файл только при необходимости. Большая часть данных файла остается в памяти, не сбрасываясь на носитель, так как файл скоро будет удален.

dwFlags
Указывает условия, при которых происходит передача. Этот параметр может быть любым из значений dwFlags , описанных в FtpGetFile в пакете SDK для Windows.

dwContext
Идентификатор контекста для извлечения файла. Дополнительные сведения о dwContext см. в примечаниях.

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

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

Замечания

GetFile — это высокоуровневая подпрограмма, которая обрабатывает все затраты, связанные с чтением файла с FTP-сервера и его хранением локально. Приложения, которые получают только данные файлов или требуют тесного управления передачей файлов, должны использовать OpenFile и CInternetFile::Read .

Если dwFlags FILE_TRANSFER_TYPE_ASCII, перевод данных файла также преобразует символы управления и форматирования в эквиваленты Windows. Передача по умолчанию — это двоичный режим, в котором файл загружается в том же формате, что и на сервере.

Как pstrRemoteFile, так и pstrLocalFile могут быть частично квалифицированными именами файлов относительно текущего каталога или полностью. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. GetFile Преобразует разделители имен каталога в соответствующие символы перед их использованием.

Переопределите dwContext по умолчанию, чтобы задать идентификатор контекста для выбранного значения. Идентификатор контекста связан с этой конкретной операцией объекта, созданного CFtpConnection объектом CInternetSession . Значение возвращается в CInternetSession::OnStatusCallback , чтобы предоставить состояние операции, с которой она определена. Дополнительные сведения об идентификаторе контекста см. в статье Internet First Steps: WinInet .

CFtpConnection::OpenFile

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

CInternetFile* OpenFile(
    LPCTSTR pstrFileName,
    DWORD dwAccess = GENERIC_READ,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Параметры

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

dwAccess
Определяет способ доступа к файлу. Может быть либо GENERIC_READ, либо GENERIC_WRITE, но не оба.

dwFlags
Указывает условия, при которых выполняются последующие передачи. Это может быть любая из следующих констант FTP_TRANSFER_*:

  • FTP_TRANSFER_TYPE_ASCII Передача файлов с помощью метода передачи FTP ASCII (Type A). Преобразует сведения об элементе управления и форматировании в локальные эквиваленты.

  • FTP_TRANSFER_TYPE_BINARY Файл передает данные с помощью метода передачи образа FTP (Type I). Файл передает данные точно так же, как он существует, без изменений. Это метод передачи по умолчанию.

dwContext
Идентификатор контекста для открытия файла. Дополнительные сведения о dwContext см. в примечаниях.

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

Указатель на объект CInternetFile .

Замечания

OpenFile следует использовать в следующих ситуациях:

  • Приложение содержит данные, которые должны быть отправлены и созданы в виде файла на FTP-сервере, но данные не в локальном файле. После OpenFile открытия файла приложение использует CInternetFile::Write для отправки данных FTP-файла на сервер.

  • Приложение должно получить файл с сервера и поместить его в управляемое приложением памяти, а не записывать его на диск. Приложение использует CInternetFile::Read после открытия OpenFile файла.

  • Приложению необходим прекрасный уровень контроля над передачей файлов. Например, приложению может потребоваться отобразить элемент управления хода выполнения, указывающий ход выполнения состояния передачи файлов при скачивании файла.

После вызова и до вызова CInternetFile::CloseOpenFile приложение может вызывать только CInternetFile::Read, CInternetFile::Write, CInternetConnection::Closeили CFtpFileFind::FindFile. Вызовы других функций FTP для того же сеанса FTP завершаются ошибкой и задают код ошибки FTP_ETRANSFER_IN_PROGRESS.

Параметр pstrFileName может быть частично квалифицированным именем файла относительно текущего каталога или полного имени. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. OpenFile Преобразует разделители имен каталога в соответствующие символы перед его использованием.

Переопределите dwContext по умолчанию, чтобы задать идентификатор контекста для выбранного значения. Идентификатор контекста связан с этой конкретной операцией объекта, созданного CFtpConnection объектом CInternetSession . Значение возвращается в CInternetSession::OnStatusCallback , чтобы предоставить состояние операции, с которой она определена. Дополнительные сведения об идентификаторе контекста см. в статье Internet First Steps: WinInet .

CFtpConnection::P utFile

Вызовите эту функцию-член, чтобы сохранить файл на FTP-сервере.

BOOL PutFile(
    LPCTSTR pstrLocalFile,
    LPCTSTR pstrRemoteFile,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

Параметры

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

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

dwFlags
Указывает условия, при которых происходит передача файла. Может быть любой из констант FTP_TRANSFER_*, описанных в OpenFile.

dwContext
Идентификатор контекста для размещения файла. Дополнительные сведения о dwContext см. в примечаниях.

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

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

Замечания

PutFile — это высокоуровневая подпрограмма, которая обрабатывает все операции, связанные с хранением файла на FTP-сервере. Приложения, которые отправляют только данные или требуют более тесного контроля над передачей файлов, должны использовать OpenFile и CInternetFile::Write.

Переопределите dwContext значение по умолчанию, чтобы задать идентификатор контекста для выбранного значения. Идентификатор контекста связан с этой конкретной операцией объекта, созданного CFtpConnection объектом CInternetSession . Значение возвращается в CInternetSession::OnStatusCallback , чтобы предоставить состояние операции, с которой она определена. Дополнительные сведения об идентификаторе контекста см. в статье Internet First Steps: WinInet .

CFtpConnection::Remove

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

BOOL Remove(LPCTSTR pstrFileName);

Параметры

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

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

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

Замечания

Параметр pstrFileName может быть частично квалифицированным именем файла относительно текущего каталога или полного имени. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. Функция Remove преобразует разделители имен каталога в соответствующие символы перед их использованием.

CFtpConnection::RemoveDirectory

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

BOOL RemoveDirectory(LPCTSTR pstrDirName);

Параметры

pstrDirName
Указатель на строку, содержащую каталог, который необходимо удалить.

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

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

Замечания

Используйте GetCurrentDirectory , чтобы определить текущий рабочий каталог сервера. Не предполагайте, что удаленная система подключила вас к корневому каталогу.

Параметр pstrDirName может быть частично или полным именем файла относительно текущего каталога. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. RemoveDirectory Преобразует разделители имен каталога в соответствующие символы перед их использованием.

CFtpConnection::Rename

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

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

Параметры

pstrExisting
Указатель на строку, содержащую текущее имя файла, который необходимо переименовать.

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

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

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

Замечания

Параметры pstrExisting и pstrNew могут быть частично квалифицированными именами файлов относительно текущего каталога или полного имени. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. Rename Преобразует разделители имен каталога в соответствующие символы перед их использованием.

CFtpConnection::SetCurrentDirectory

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

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

Параметры

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

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

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

Замечания

Параметр pstrDirName может быть частично или полным именем файла относительно текущего каталога. Обратная косая черта (\) или косая черта (/) можно использовать в качестве разделителя каталогов для любого имени. SetCurrentDirectory Преобразует разделители имен каталога в соответствующие символы перед их использованием.

Используйте GetCurrentDirectory для определения текущего рабочего каталога FTP-сервера. Не предполагайте, что удаленная система подключила вас к корневому каталогу.

См. также

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