Partager via

CFtpConnection, classe

  • Article

Gère votre connexion FTP à un serveur Internet et permet une manipulation directe des répertoires et des fichiers sur ce serveur.

Syntaxe

class CFtpConnection : public CInternetConnection

Membres

Constructeurs publics

Nom Description
CFtpConnection ::CFtpConnection Construit un objet CFtpConnection.

Méthodes publiques

Nom Description
CFtpConnection ::Command Envoie une commande directement à un serveur FTP.
CFtpConnection ::CreateDirectory Crée un répertoire sur le serveur.
CFtpConnection ::GetCurrentDirectory Obtient le répertoire actif de cette connexion.
CFtpConnection ::GetCurrentDirectoryAsURL Obtient le répertoire actif de cette connexion en tant qu’URL.
CFtpConnection ::GetFile Obtient un fichier à partir du serveur connecté
CFtpConnection ::OpenFile Ouvre un fichier sur le serveur connecté.
CFtpConnection ::P utFile Place un fichier sur le serveur.
CFtpConnection ::Remove Supprime un fichier du serveur.
CFtpConnection ::RemoveDirectory Supprime le répertoire spécifié du serveur.
CFtpConnection ::Rename Renomme un fichier sur le serveur.
CFtpConnection ::SetCurrentDirectory Définit le répertoire FTP actuel.

Notes

FTP est l’un des trois services Internet reconnus par les classes WinInet MFC.

Pour communiquer avec un serveur Internet FTP, vous devez d’abord créer une instance de CInternetSession, puis créer un CFtpConnection objet. Vous ne créez jamais directement un CFtpConnection objet ; appelez plutôt CInternetSession ::GetFtpConnection, qui crée l’objet CFtpConnection et retourne un pointeur vers celui-ci.

Pour en savoir plus sur CFtpConnection l’utilisation des autres classes Internet MFC, consultez l’article Programmation Internet avec WinInet. Pour plus d’informations sur la communication avec les deux autres services pris en charge, HTTP et gopher, consultez les classes CHttpConnection et CGopherConnection.

Exemple

Consultez l’exemple dans la vue d’ensemble de la classe CFtpFileFind .

Hiérarchie d'héritage

CObject

CInternetConnection

CFtpConnection

Spécifications

En-tête : afxinet.h

CFtpConnection ::CFtpConnection

Cette fonction membre est appelée pour construire un CFtpConnection objet.

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);

Paramètres

pSession
Pointeur vers l’objet CInternetSession associé.

hConnected
Handle Windows de la session Internet active.

pstrServer
Pointeur vers une chaîne contenant le nom du serveur FTP.

dwContext
Identificateur de contexte de l’opération. dwContext identifie les informations d’état de l’opération retournées par CInternetSession ::OnStatusCallback. La valeur par défaut est 1, mais vous pouvez affecter explicitement un ID de contexte spécifique pour l’opération. L’objet et tout travail qu’il effectue sera associé à cet ID de contexte.

pstrUserName
Pointeur vers une chaîne terminée par null qui spécifie le nom d’utilisateur pour se connecter. Si la valeur est NULL, la valeur par défaut est anonyme.

pstrPassword
Pointeur vers une chaîne terminée par null qui spécifie le mot de passe à utiliser pour se connecter. Si pstrPassword et pstrUserName sont NULL, le mot de passe anonyme par défaut est le nom de messagerie de l’utilisateur. Si pstrPassword a la valeur NULL (ou une chaîne vide), mais pstrUserName n’est pas NULL, un mot de passe vide est utilisé. Le tableau suivant décrit le comportement des quatre paramètres possibles de pstrUserName et pstrPassword :

pstrUserName pstrPassword Nom d’utilisateur envoyé au serveur FTP Mot de passe envoyé au serveur FTP
NULL ou « » NULL ou « » « anonyme » Nom de l’adresse e-mail de l’utilisateur
Chaîne non NULL NULL ou « » pstrUserName " "
Null Non- Null, chaîne ERROR ERROR
Chaîne non NULL Chaîne non NULL pstrUserName pstrPassword

nPort
Nombre qui identifie le port TCP/IP à utiliser sur le serveur.

bPassive
Spécifie le mode passif ou actif pour cette session FTP. Si la valeur est TRUE, elle définit l’API Win32 dwFlag sur INTERNET_FLAG_PASSIVE.

Notes

Vous ne créez jamais d’objet CFtpConnection directement. Au lieu de cela, appelez CInternetSession ::GetFtpConnection, qui crée l’objet CFptConnection .

CFtpConnection ::Command

Envoie une commande directement à un serveur FTP.

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

Paramètres

pszCommand
Pointeur vers une chaîne contenant la commande à envoyer.

eResponse
Spécifie si une réponse est attendue du serveur FTP. Peut avoir l’une des valeurs suivantes :

  • CmdRespNone Aucune réponse n’est attendue.
  • CmdRespRead Une réponse est attendue.
  • CmdRespWrite Non utilisé.

CmdResponseType est membre de CFtpConnection, défini dans afxinet.h.

dwFlags
Valeur contenant les indicateurs qui contrôlent cette fonction. Pour obtenir une liste complète, consultez FTPCommand.

dwContext
Pointeur vers une valeur contenant une valeur définie par l'application utilisée pour identifier le contexte de l'application dans les rappels.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0.

Notes

Cette fonction membre émule les fonctionnalités de la fonction FTPCommand , comme décrit dans le Kit de développement logiciel (SDK) Windows.

Si une erreur se produit, MFC lève une exception de type CInternetException.

CFtpConnection ::CreateDirectory

Appelez cette fonction membre pour créer un répertoire sur le serveur connecté.

BOOL CreateDirectory(LPCTSTR pstrDirName);

Paramètres

pstrDirName
Pointeur vers une chaîne contenant le nom du répertoire à créer.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Windows GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Permet GetCurrentDirectory de déterminer le répertoire de travail actuel pour cette connexion au serveur. Ne supposez pas que le système distant vous a connecté au répertoire racine.

Le pstrDirName paramètre peut être un nom de fichier partiellement ou complet par rapport au répertoire actif. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. CreateDirectory traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

CFtpConnection ::GetCurrentDirectory

Appelez cette fonction membre pour obtenir le nom du répertoire actif.

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

Paramètres

strDirName
Référence à une chaîne qui recevra le nom du répertoire.

pstrDirName
Pointeur vers une chaîne qui recevra le nom du répertoire.

lpdwLen
Pointeur vers un DWORD qui contient les informations suivantes :

Lors de l’entrée : taille de la mémoire tampon référencée par pstrDirName.

Retour : nombre de caractères stockés dans pstrDirName. Si la fonction membre échoue et ERROR_INSUFFICIENT_BUFFER est retournée, lpdwLen contient le nombre d’octets que l’application doit allouer pour recevoir la chaîne.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Pour obtenir le nom du répertoire en tant qu’URL, appelez GetCurrentDirectoryAsURL.

Les paramètres pstrDirName ou strDirName peuvent être des noms de fichiers partiellement qualifiés par rapport au répertoire actif ou complets. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. GetCurrentDirectory traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

CFtpConnection ::GetCurrentDirectoryAsURL

Appelez cette fonction membre pour obtenir le nom du répertoire actuel en tant qu’URL.

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

Paramètres

strDirName
Référence à une chaîne qui recevra le nom du répertoire.

pstrDirName
Pointeur vers une chaîne qui recevra le nom du répertoire.

lpdwLen
Pointeur vers un DWORD qui contient les informations suivantes :

Lors de l’entrée : taille de la mémoire tampon référencée par pstrDirName.

Retour : nombre de caractères stockés dans pstrDirName. Si la fonction membre échoue et ERROR_INSUFFICIENT_BUFFER est retournée, lpdwLen contient le nombre d’octets que l’application doit allouer pour recevoir la chaîne.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

GetCurrentDirectoryAsURL se comporte de la même façon que GetCurrentDirectory

Le paramètre strDirName peut être des noms de fichiers partiellement qualifiés par rapport au répertoire actif ou complet. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. GetCurrentDirectoryAsURL traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

CFtpConnection ::GetFile

Appelez cette fonction membre pour obtenir un fichier à partir d’un serveur FTP et le stocker sur l’ordinateur 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);

Paramètres

pstrRemoteFile
Pointeur vers une chaîne terminée par null contenant le nom d’un fichier à récupérer à partir du serveur FTP.

pstrLocalFile
Pointeur vers une chaîne terminée par null contenant le nom du fichier à créer sur le système local.

bFailIfExists
Indique si le nom de fichier peut déjà être utilisé par un fichier existant. Si le nom de fichier local existe déjà, et que ce paramètre a la valeur TRUE, GetFile échoue. Sinon, GetFile efface la copie existante du fichier.

dwAttributes
Indique les attributs du fichier. Il peut s’agir de n’importe quelle combinaison des indicateurs FILE_ATTRIBUTE_* suivants.

  • FILE_ATTRIBUTE_ARCHIVE Le fichier est un fichier d’archivage. Les applications utilisent cet attribut pour marquer des fichiers à des fins de sauvegarde ou de suppression.

  • FILE_ATTRIBUTE_COMPRESSED Le fichier ou le répertoire est compressé. Pour un fichier, la compression signifie que toutes les données du fichier sont compressées. Pour un répertoire, la compression est la valeur par défaut pour les fichiers et sous-répertoires nouvellement créés.

  • FILE_ATTRIBUTE_DIRECTORY Le fichier est un répertoire.

  • FILE_ATTRIBUTE_NORMAL Le fichier n’a pas d’autres attributs définis. Cet attribut n’est valide que s’il est utilisé seul. Tous les autres attributs de fichier remplacent FILE_ATTRIBUTE_NORMAL :

  • FILE_ATTRIBUTE_HIDDEN Le fichier est masqué. Il ne doit pas être inclus dans une liste d’annuaires ordinaire.

  • FILE_ATTRIBUTE_READONLY Le fichier est en lecture seule. Les applications peuvent lire le fichier, mais ne peuvent pas y écrire ou les supprimer.

  • FILE_ATTRIBUTE_SYSTEM Le fichier fait partie ou est utilisé exclusivement par le système d’exploitation.

  • FILE_ATTRIBUTE_TEMPORARY Le fichier est utilisé pour le stockage temporaire. Les applications doivent écrire dans le fichier uniquement si nécessaire. La plupart des données du fichier restent en mémoire sans être vidées sur le média, car le fichier sera bientôt supprimé.

dwFlags
Spécifie les conditions dans lesquelles le transfert se produit. Ce paramètre peut être l’une des valeurs dwFlags décrites dans FtpGetFile dans le Kit de développement logiciel (SDK) Windows.

dwContext
Identificateur de contexte pour la récupération de fichiers. Pour plus d’informations sur dwContext, consultez Les remarques.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

GetFile est une routine de haut niveau qui gère toutes les surcharges associées à la lecture d’un fichier à partir d’un serveur FTP et à son stockage localement. Les applications qui récupèrent uniquement des données de fichier, ou qui nécessitent un contrôle étroit sur le transfert de fichiers, doivent utiliser OpenFile et CInternetFile ::Read à la place.

Si dwFlags est FILE_TRANSFER_TYPE_ASCII, la traduction de données de fichier convertit également les caractères de contrôle et de mise en forme en équivalents Windows. Le transfert par défaut est le mode binaire, où le fichier est téléchargé dans le même format qu’il est stocké sur le serveur.

PstrRemoteFile et pstrLocalFile peuvent être des noms de fichiers partiellement qualifiés par rapport au répertoire actif ou complets. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. GetFile traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

Remplacez la valeur par défaut dwContext pour définir l’identificateur de contexte sur une valeur de votre choix. L’identificateur de contexte est associé à cette opération spécifique de l’objet CFtpConnection créé par son objet CInternetSession . La valeur est retournée à CInternetSession ::OnStatusCallback pour fournir l’état de l’opération avec laquelle elle est identifiée. Pour plus d’informations sur l’identificateur de contexte, consultez l’article Sur Internet First Steps : WinInet .

CFtpConnection ::OpenFile

Appelez cette fonction membre pour ouvrir un fichier situé sur un serveur FTP pour la lecture ou l’écriture.

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

Paramètres

pstrFileName
Pointeur vers une chaîne contenant le nom du fichier à ouvrir.

dwAccess
Détermine la façon dont le fichier sera accessible. Peut être GENERIC_READ ou GENERIC_WRITE, mais pas les deux.

dwFlags
Spécifie les conditions dans lesquelles les transferts suivants se produisent. Il peut s’agir de l’une des constantes FTP_TRANSFER_* suivantes :

  • FTP_TRANSFER_TYPE_ASCII Le fichier transfère à l’aide de la méthode de transfert FTP ASCII (Type A). Convertit les informations de contrôle et de mise en forme en équivalents locaux.

  • FTP_TRANSFER_TYPE_BINARY Le fichier transfère les données à l’aide de la méthode de transfert Image (Type I) de FTP. Le fichier transfère exactement les données telles qu’elles existent, sans aucune modification. Il s’agit de la méthode de transfert par défaut.

dwContext
Identificateur de contexte pour l’ouverture du fichier. Pour plus d’informations sur dwContext, consultez Les remarques.

Valeur de retour

Pointeur vers un objet CInternetFile .

Notes

OpenFile doit être utilisé dans les situations suivantes :

  • Une application a des données qui doivent être envoyées et créées en tant que fichier sur le serveur FTP, mais ces données ne se trouvent pas dans un fichier local. Une fois OpenFile le fichier ouvert, l’application utilise CInternetFile ::Write pour envoyer les données du fichier FTP au serveur.

  • Une application doit récupérer un fichier à partir du serveur et le placer dans la mémoire contrôlée par l’application, au lieu de l’écrire sur le disque. L’application utilise CInternetFile ::Read après avoir utilisé OpenFile pour ouvrir le fichier.

  • Une application a besoin d’un niveau de contrôle précis sur un transfert de fichiers. Par exemple, l’application peut souhaiter afficher un contrôle de progression indiquant la progression de l’état de transfert de fichier lors du téléchargement d’un fichier.

Après l’appel et jusqu’à l’appel OpenFile CInternetFile::Close, l’application peut uniquement appeler CInternetFile ::Read, CInternetFile ::Write, CInternetConnection::Closeou CFtpFileFind ::FindFile. Les appels à d’autres fonctions FTP pour la même session FTP échouent et définissent le code d’erreur sur FTP_ETRANSFER_IN_PROGRESS.

Le paramètre pstrFileName peut être un nom de fichier partiellement qualifié par rapport au répertoire actif ou complet. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. OpenFile traduit les séparateurs de noms de répertoire en caractères appropriés avant de l’utiliser.

Remplacez la valeur par défaut dwContext pour définir l’identificateur de contexte sur une valeur de votre choix. L’identificateur de contexte est associé à cette opération spécifique de l’objet CFtpConnection créé par son objet CInternetSession . La valeur est retournée à CInternetSession ::OnStatusCallback pour fournir l’état de l’opération avec laquelle elle est identifiée. Pour plus d’informations sur l’identificateur de contexte, consultez l’article Sur Internet First Steps : WinInet .

CFtpConnection ::P utFile

Appelez cette fonction membre pour stocker un fichier sur un serveur FTP.

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

Paramètres

pstrLocalFile
Pointeur vers une chaîne contenant le nom du fichier à envoyer à partir du système local.

pstrRemoteFile
Pointeur vers une chaîne contenant le nom du fichier à créer sur le serveur FTP.

dwFlags
Spécifie les conditions dans lesquelles le transfert du fichier se produit. Il peut s’agir de l’une des constantes FTP_TRANSFER_* décrites dans OpenFile.

dwContext
Identificateur de contexte pour placer le fichier. Pour plus d’informations sur dwContext, consultez Les remarques.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

PutFile est une routine générale qui gère toutes les opérations associées au stockage d’un fichier sur un serveur FTP. Les applications qui envoient uniquement des données ou qui nécessitent un contrôle plus étroit sur le transfert de fichiers doivent utiliser OpenFile et CInternetFile ::Write.

Remplacez la dwContext valeur par défaut pour définir l’identificateur de contexte sur une valeur de votre choix. L’identificateur de contexte est associé à cette opération spécifique de l’objet CFtpConnection créé par son objet CInternetSession . La valeur est retournée à CInternetSession ::OnStatusCallback pour fournir l’état de l’opération avec laquelle elle est identifiée. Pour plus d’informations sur l’identificateur de contexte, consultez l’article Sur Internet First Steps : WinInet .

CFtpConnection ::Remove

Appelez cette fonction membre pour supprimer le fichier spécifié du serveur connecté.

BOOL Remove(LPCTSTR pstrFileName);

Paramètres

pstrFileName
Pointeur vers une chaîne contenant le nom de fichier à supprimer.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Le paramètre pstrFileName peut être un nom de fichier partiellement qualifié par rapport au répertoire actif ou complet. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. La Remove fonction traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

CFtpConnection ::RemoveDirectory

Appelez cette fonction membre pour supprimer le répertoire spécifié du serveur connecté.

BOOL RemoveDirectory(LPCTSTR pstrDirName);

Paramètres

pstrDirName
Pointeur vers une chaîne contenant le répertoire à supprimer.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Utilisez GetCurrentDirectory pour déterminer le répertoire de travail actuel du serveur. Ne supposez pas que le système distant vous a connecté au répertoire racine.

Le paramètre pstrDirName peut être un nom de fichier partiellement ou complet par rapport au répertoire actif. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. RemoveDirectory traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

CFtpConnection ::Rename

Appelez cette fonction membre pour renommer le fichier spécifié sur le serveur connecté.

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

Paramètres

pstrExisting
Pointeur vers une chaîne contenant le nom actuel du fichier à renommer.

pstrNew
Pointeur vers une chaîne contenant le nouveau nom du fichier.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Les paramètres pstrExisting et pstrNew peuvent être un nom de fichier partiellement qualifié par rapport au répertoire actif ou complet. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. Rename traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

CFtpConnection ::SetCurrentDirectory

Appelez cette fonction membre pour passer à un autre répertoire sur le serveur FTP.

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

Paramètres

pstrDirName
Pointeur vers une chaîne contenant le nom du répertoire.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Le paramètre pstrDirName peut être un nom de fichier partiellement ou complet par rapport au répertoire actif. Une barre oblique inverse (\) ou une barre oblique (/) peut être utilisée comme séparateur de répertoire pour l’un ou l’autre nom. SetCurrentDirectory traduit les séparateurs de noms de répertoire en caractères appropriés avant d’être utilisés.

Utilisez GetCurrentDirectory pour déterminer le répertoire de travail actuel d’un serveur FTP. Ne supposez pas que le système distant vous a connecté au répertoire racine.

Voir aussi

CInternetConnection, classe
Graphique hiérarchique
CInternetConnection, classe
CInternetSession, classe