Compartir a través de

Clase CFtpConnection

  • Artículo

Administra la conexión FTP a un servidor de Internet y permite la manipulación directa de directorios y archivos en ese servidor.

Sintaxis

class CFtpConnection : public CInternetConnection

Miembros

Constructores públicos

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

Métodos públicos

Nombre Descripción
CFtpConnection::Command Envía un comando directamente a un servidor FTP.
CFtpConnection::CreateDirectory Crea un directorio en el servidor.
CFtpConnection::GetCurrentDirectory Obtiene el directorio actual de esta conexión.
CFtpConnection::GetCurrentDirectoryAsURL Obtiene el directorio actual de esta conexión como una dirección URL.
CFtpConnection::GetFile Obtiene un archivo del servidor conectado
CFtpConnection::OpenFile Abre un archivo en el servidor conectado.
CFtpConnection::PutFile Coloca un archivo en el servidor.
CFtpConnection::Remove Quita un archivo del servidor.
CFtpConnection::RemoveDirectory Quita el directorio especificado del servidor.
CFtpConnection::Rename Cambia el nombre de un archivo en el servidor.
CFtpConnection::SetCurrentDirectory Establece el directorio FTP actual.

Comentarios

FTP es uno de los tres servicios de Internet reconocidos por las clases WinInet de MFC.

Para comunicarse con un servidor de Internet FTP, primero debe crear una instancia de CInternetSession y, a continuación, crear un CFtpConnection objeto . Nunca se crea un CFtpConnection objeto directamente; en su lugar, se llama a CInternetSession::GetFtpConnection, que crea el CFtpConnection objeto y devuelve un puntero a él.

Para obtener más información sobre cómo funciona CFtpConnection con las otras clases de Internet de MFC, vea el artículo Programación de Internet con WinInet. Para obtener más información sobre cómo comunicarse con los otros dos servicios compatibles, HTTP y gopher, vea las clases CHttpConnection y CGopherConnection.

Ejemplo

Vea el ejemplo en la información de la clase deCFtpFileFind.

Jerarquía de herencia

CObject

CInternetConnection

CFtpConnection

Requisitos

Encabezado: afxinet.h

CFtpConnection::CFtpConnection

Se llama a esta función miembro para construir un objeto 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);

Parámetros

pSession
Puntero al objeto CInternetSession relacionado.

hConnected
Identificador de Windows de la sesión de Internet actual.

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

dwContext
Identificador de contexto de la operación. dwContext identifica la información de estado de la operación devuelta por CInternetSession::OnStatusCallback. El valor predeterminado se establece en 1; sin embargo, puede asignar explícitamente un identificador de contexto específico para la operación. El objeto y cualquier trabajo que haga se asociarán a ese identificador de contexto.

pstrUserName
Puntero a una cadena terminada en NULL que especifica el nombre del usuario en el que se inicia sesión. Si es NULL, el valor predeterminado es anónimo.

pstrPassword
Puntero a una cadena terminada en NULL que especifica la contraseña que se usará para iniciar sesión. Si tanto pstrPassword como pstrUserName son NULL, la contraseña anónima predeterminada es el nombre de correo electrónico del usuario. Si pstrPassword es NULL (o una cadena vacía) pero pstrUserName no es NULL, se usa una contraseña en blanco. En la tabla siguiente se describe el comportamiento de las cuatro configuraciones posibles de pstrUserName y pstrPassword:

pstrUserName pstrPassword Nombre de usuario enviado al servidor FTP Contraseña enviada al servidor FTP
NULL o " " NULL o " " "anónimo" Nombre de correo electrónico del usuario
Cadena que no es NULL NULL o " " pstrUserName " "
Cadena NULL que no es NULL ERROR ERROR
Cadena que no es NULL Cadena que no es NULL pstrUserName pstrPassword

nPort
Número que identifica el puerto TCP/IP que se usará en el servidor.

bPassive
Especifica el modo pasivo o activo para esta sesión FTP. Si se establece en TRUE, establece la API de Win32 dwFlag en INTERNET_FLAG_PASSIVE.

Comentarios

Nunca se crea un CFtpConnection objeto directamente. En su lugar, llame aCInternetSession::GetFtpConnection, que crea el CFptConnection objeto.

CFtpConnection::Command

Envía un comando directamente a un servidor FTP.

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

Parámetros

pszCommand
Un puntero a una cadena que contiene el comando que se enviará.

eResponse
Especifica si se espera una respuesta del servidor FTP. Puede ser uno de los siguientes valores:

  • CmdRespNone No se espera ninguna respuesta.
  • CmdRespRead Se espera una respuesta.
  • CmdRespWrite No se usa.

CmdResponseType es un miembro de CFtpConnection, definido en afxinet.h.

dwFlags
Un valor que contiene las marcas que controlan esta función. Para obtener una lista completa, vea FTPCommand.

dwContext
Un puntero a un valor que contiene un valor definido por la aplicación, que se utiliza para identificar el contexto de la aplicación en las devoluciones de llamada.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Esta función miembro emula la funcionalidad de la función ftpCommand, como se describe en la Windows SDK.

Si se produce un error, MFC produce una excepción de tipo CInternetException.

CFtpConnection::CreateDirectory

Llame a esta función miembro para crear un directorio en el servidor conectado.

BOOL CreateDirectory(LPCTSTR pstrDirName);

Parámetros

pstrDirName
Puntero apuntando a una cadena que contiene el nombre del directorio que se creará.

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 de WindowsGetLastError para determinar la causa del error.

Comentarios

Use GetCurrentDirectory para determinar el directorio de trabajo actual para esta conexión al servidor. No suponga que el sistema remoto le ha conectado al directorio raíz.

El parámetro pstrDirName puede ser un nombre de archivo completo o parcialmente relativo al directorio actual. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. CreateDirectory convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

CFtpConnection::GetCurrentDirectory

Llame a esta función miembro para obtener el nombre del directorio actual.

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

Parámetros

strDirName
Referencia a una cadena que recibirá el nombre del directorio.

pstrDirName
Puntero a una cadena que recibirá el nombre del directorio.

lpdwLen
Puntero a un DWORD que contiene la siguiente información:

En la entrada: tamaño del búfer al que hace referencia pstrDirName.

En la devolución: número de caracteres almacenados para pstrDirName. Si se produce un error en la función miembro y se devuelve ERROR_INSUFFICIENT_BUFFER, entonces,lpdwLen contiene el número de bytes que la aplicación debe asignar para recibir la cadena.

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

Para obtener el nombre del directorio como una dirección URL en su lugar, llame a GetCurrentDirectoryAsURL.

Los parámetros pstrDirName o strDirName pueden ser nombres de archivo parcialmente calificados con respecto al directorio actual o completos. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. GetCurrentDirectory convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

CFtpConnection::GetCurrentDirectoryAsURL

Llame a esta función miembro para obtener el nombre del directorio actual como una dirección URL.

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

Parámetros

strDirName
Referencia a una cadena que recibirá el nombre del directorio.

pstrDirName
Puntero a una cadena que recibirá el nombre del directorio.

lpdwLen
Puntero a un DWORD que contiene la siguiente información:

En la entrada: tamaño del búfer al que hace referencia pstrDirName.

En la devolución: número de caracteres almacenados para pstrDirName. Si se produce un error en la función miembro y se devuelve ERROR_INSUFFICIENT_BUFFER, entonces,lpdwLen contiene el número de bytes que la aplicación debe asignar para recibir la cadena.

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

GetCurrentDirectoryAsURL se comporta igual que GetCurrentDirectory

El parámetro strDirName pueden ser nombres de archivo parcialmente calificados con respecto al directorio actual o completamente calificados. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. GetCurrentDirectoryAsURL convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

CFtpConnection::GetFile

Llame a esta función miembro para obtener un archivo de un servidor FTP y almacenarlo en el equipo local.

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

Parámetros

pstrRemoteFile
Puntero a una cadena terminada en NULL que contiene el nombre de un archivo que se recuperará del servidor FTP.

pstrLocalFile
Puntero a una cadena terminada en NULL que contiene el nombre del archivo que se creará en el sistema local.

bFailIfExists
Indica si un archivo existente ya puede usar el nombre de archivo. Si el nombre de archivo local ya existe y este parámetro es TRUE, GetFile error. De lo contrario, GetFile borrará la copia existente del archivo.

dwAttributes
Indica los atributos del archivo. Puede ser cualquier combinación de las siguientes marcas FILE_ATTRIBUTE_*.

  • FILE_ATTRIBUTE_ARCHIVE El archivo es un archivo de archivo. Las aplicaciones usan este atributo para marcar los archivos para crear una copia de seguridad o quitarlos.

  • FILE_ATTRIBUTE_COMPRESSED El archivo o directorio está comprimido. Para un archivo, la compresión significa que todos los datos del archivo están comprimidos. Para un directorio, la compresión es el valor predeterminado para los archivos y subdirectorios recién creados.

  • FILE_ATTRIBUTE_DIRECTORY El archivo es un directorio.

  • FILE_ATTRIBUTE_NORMAL El archivo no tiene ningún otro atributo establecido. Este atributo solo es válido si se usa por sí solo. Todos los demás atributos del archivo invalidan FILE_ATTRIBUTE_NORMAL:

  • FILE_ATTRIBUTE_HIDDEN El archivo está oculto. No se debe incluir en una lista de directorios normal.

  • FILE_ATTRIBUTE_READONLY El archivo es de solo lectura. Las aplicaciones pueden leer el archivo, pero no pueden escribir en él ni eliminarlo.

  • FILE_ATTRIBUTE_SYSTEM el archivo forma parte del sistema operativo o este lo usa exclusivamente.

  • FILE_ATTRIBUTE_TEMPORARY El archivo se usa para el almacenamiento temporal. Las aplicaciones solo deben escribir en el archivo si es absolutamente necesario. La mayoría de los datos del archivo permanecen en memoria sin vaciarse en el medio porque el archivo se eliminará pronto.

dwFlags
Especifica las condiciones en las que se produce la transferencia. Este parámetro puede ser cualquiera de los valores dwFlags descritos en ftpGetFile en el Windows SDK.

dwContext
Identificador de contexto para la recuperación de archivos. Vea Comentarios para obtener más información sobre dwContext.

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

GetFile es una rutina de alto nivel que controla toda la sobrecarga asociada a la lectura de un archivo desde un servidor FTP y su almacenamiento local. Las aplicaciones que solo recuperan datos de archivos, o que requieren un control cercano sobre la transferencia de archivos, deben usar OpenFile y CInternetFile::Read en su lugar.

Si dwFlags es FILE_TRANSFER_TYPE_ASCII, la traducción de datos de archivo también convierte los caracteres de control y formato en equivalentes de Windows. La transferencia predeterminada es el modo binario, donde el archivo se descarga en el mismo formato que se almacena en el servidor.

Tanto pstrRemoteFile como pstrLocalFile pueden ser nombres de archivo parcialmente calificados con respecto al directorio actual o completamente calificados. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. GetFile convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

Reemplace el valor predeterminado de dwContextpara establecer el identificador de contexto en un valor que desee. El identificador de contexto está asociado a esta operación específica del objeto CFtpConnection creado por su objeto CInternetSession. El valor se devuelve a CInternetSession::OnStatusCallback para proporcionar el estado de la operación con la que se identifica. Vea el artículo Internet First Steps: WinInet para obtener más información sobre el identificador de contexto.

CFtpConnection::OpenFile

Llame a esta función miembro para abrir un archivo ubicado en un servidor FTP para leer o escribir.

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

Parámetros

pstrFileName
Puntero a una cadena que contiene el nombre del archivo que se va a abrir.

dwAccess
Determina cómo se accederá al archivo. Puede ser GENERIC_READ o GENERIC_WRITE, pero no ambos.

dwFlags
Especifica las condiciones en las que se producen las transferencias posteriores. Puede ser cualquiera de las siguientes constantes FTP_TRANSFER_*:

  • FTP_TRANSFER_TYPE_ASCII El archivo se transfiere mediante el método de transferencia ASCII de FTP (tipo A). Convierte la información de control y formato en equivalentes locales.

  • FTP_TRANSFER_TYPE_BINARY El archivo transfiere datos mediante el método de transferencia Imagen (tipo I) de FTP. El archivo transfiere los datos exactamente como existen, sin cambios. Este es el método de transferencia predeterminado.

dwContext
Identificador de contexto para abrir el archivo. Vea Comentarios para obtener más información sobre dwContext.

Valor devuelto

Puntero a un objeto CInternetFile.

Comentarios

OpenFile debería usarse en las situaciones siguientes:

  • Una aplicación tiene datos que deben enviarse y crearse como un archivo en el servidor FTP, pero los datos no están en un archivo local. Un vez que OpenFile abre un archivo, la aplicación usa CInternetFile::Write para enviar los datos del archivo FTP al servidor.

  • Una aplicación debe recuperar un archivo del servidor y colocarlo en la memoria controlada por la aplicación, en lugar de escribirlo en el disco. La aplicación usa CInternetFile::Read después de OpenFile para abrir el archivo.

  • Una aplicación necesita un nivel de control preciso sobre una transferencia de archivos. Por ejemplo, es posible que la aplicación quiera mostrar un control de progreso que indique el progreso del estado de transferencia de archivos al descargar un archivo.

Después de llamar OpenFile y hasta llamar CInternetFile::Close, la aplicación solo puede llamar CInternetFile::Read, CInternetFile::Write, CInternetConnection::Closeo CFtpFileFind::FindFile. Se producirá un error en las llamadas a otras funciones FTP para la misma sesión FTP y se establecerá el código de error en FTP_ETRANSFER_IN_PROGRESS.

El parámetro pstrFileName puede ser un nombre de archivo parcialmente calificado con respecto al directorio actual o completamente calificado. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. OpenFile convierte los separadores de nombre de directorio en los caracteres adecuados antes de usarlos.

Reemplace el valor predeterminado de dwContextpara establecer el identificador de contexto en un valor que desee. El identificador de contexto está asociado a esta operación específica del objeto CFtpConnection creado por su objeto CInternetSession. El valor se devuelve a CInternetSession::OnStatusCallback para proporcionar el estado de la operación con la que se identifica. Vea el artículo Internet First Steps: WinInet para obtener más información sobre el identificador de contexto.

CFtpConnection::PutFile

Llame a esta función miembro para almacenar un archivo en un servidor FTP.

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

Parámetros

pstrLocalFile
Puntero a una cadena que contiene el nombre del archivo que se enviará desde el sistema local.

pstrRemoteFile
Puntero a una cadena que contiene el nombre del archivo que se creará en el servidor FTP.

dwFlags
Especifica las condiciones en las que se produce la transferencia del archivo. Puede ser cualquiera de las constantes FTP_TRANSFER_* descritas en OpenFile.

dwContext
Identificador de contexto para colocar el archivo. Vea Comentarios para obtener más información sobre dwContext.

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

PutFile es una rutina de alto nivel que controla todas las operaciones asociadas al almacenamiento de un archivo en un servidor FTP. Las aplicaciones que solo envían datos, o que requieren un control más cercano sobre la transferencia de archivos, deben usar OpenFile y CInternetFile::Write.

Reemplace el valor predeterminado de dwContext para establecer el identificador de contexto en un valor que desee. El identificador de contexto está asociado a esta operación específica del objeto CFtpConnection creado por su objeto CInternetSession. El valor se devuelve a CInternetSession::OnStatusCallback para proporcionar el estado de la operación con la que se identifica. Vea el artículo Internet First Steps: WinInet para obtener más información sobre el identificador de contexto.

CFtpConnection::Remove

Llame a esta función miembro para eliminar el archivo especificado del servidor conectado.

BOOL Remove(LPCTSTR pstrFileName);

Parámetros

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

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

El parámetro pstrFileName puede ser un nombre de archivo parcialmente calificado con respecto al directorio actual o completamente calificado. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. La función Remove convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

CFtpConnection::RemoveDirectory

Llame a esta función miembro para quitar el directorio especificado del servidor conectado.

BOOL RemoveDirectory(LPCTSTR pstrDirName);

Parámetros

pstrDirName
Puntero a una cadena que contiene el directorio que se va a quitar.

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 GetCurrentDirectory para determinar el directorio de trabajo actual del servidor. No suponga que el sistema remoto le ha conectado al directorio raíz.

El parámetropstrDirName puede ser un nombre de archivo parcial o completamente calificado con respecto al directorio actual. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. RemoveDirectory convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

CFtpConnection::Rename

Llame a esta función miembro para cambiar el nombre del archivo especificado en el servidor conectado.

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

Parámetros

pstrExisting
Puntero a una cadena que contiene el nombre actual del archivo cuyo nombre se va a cambiar.

pstrNew
Puntero a una cadena que contiene el nuevo nombre del archivo.

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

Los parámetrospstrExisting y pstrNew pueden ser un nombre de archivo parcial o completamente calificados con respecto al directorio actual. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. Rename convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

CFtpConnection::SetCurrentDirectory

Llame a esta función miembro para cambiar a otro directorio en el servidor FTP.

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

Parámetros

pstrDirName
Puntero en una cadena que contiene el nombre del directorio.

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

El parámetropstrDirName puede ser un nombre de archivo parcial o completamente calificado con respecto al directorio actual. Se puede usar una barra diagonal inversa (\) o una barra diagonal (/) como separador de directorios para cualquier nombre. SetCurrentDirectory convierte los separadores de nombre de directorio en los caracteres adecuados antes de que se utilicen.

Use GetCurrentDirectory para determinar el directorio de trabajo actual de un servidor FTP. No suponga que el sistema remoto le ha conectado al directorio raíz.

Consulte también

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