CInternetFile, classe

Autorise l’accès aux fichiers sur des systèmes distants qui utilisent des protocoles Internet.

Syntaxe

class CInternetFile : public CStdioFile

Membres

Constructeurs protégés

Méthodes publiques

Opérateurs publics

Membres de données protégés

Notes

Fournit une classe de base pour les classes de fichier CHttpFile et CGopherFile . Vous ne créez jamais d’objet CInternetFile directement. Créez plutôt un objet de l’une de ses classes dérivées en appelant CGopherConnection ::OpenFile ou CHttpConnection ::OpenRequest. Vous pouvez également créer un CInternetFile objet en appelant CFtpConnection ::OpenFile.

Les CInternetFile fonctions Openmembres , , UnlockRangeLockRangeet Duplicate ne sont pas implémentées pour CInternetFile. Si vous appelez ces fonctions sur un CInternetFile objet, vous obtiendrez une exception CNotSupportedException.

Pour en savoir plus sur CInternetFile l’utilisation des autres classes Internet MFC, consultez l’article Programmation Internet avec WinInet.

Hiérarchie d'héritage

CObject

CFile

CStdioFile

CInternetFile

Spécifications

En-tête : afxinet.h

CInternetFile ::Abort

Ferme le fichier associé à cet objet et rend le fichier indisponible pour la lecture ou l’écriture.

virtual void Abort();

Notes

Si vous n’avez pas fermé le fichier avant de détruire l’objet, le destructeur le ferme pour vous.

Lors de la gestion des exceptions, Abort diffère de Close de deux manières importantes. Tout d’abord, la Abort fonction ne lève pas d’exception sur les échecs, car elle ignore les échecs. Deuxièmement, Abort ne déclare pas si le fichier n’a pas été ouvert ou a été fermé précédemment.

CInternetFile ::CInternetFile

Cette fonction membre est appelée lorsqu’un objet CInternetFile est créé.

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

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

Paramètres

hFile
Handle vers un fichier Internet.

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

pConnection
Pointeur vers un objet CInternetConnection .

bReadMode
Indique si le fichier est en lecture seule.

hSession
Handle vers une session Internet.

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

dwContext
Identificateur de contexte de l’objet CInternetFile . Pour plus d’informations sur l’identificateur de contexte, consultez WinInet Basics .

Notes

Vous ne créez jamais d’objet CInternetFile directement. Créez plutôt un objet de l’une de ses classes dérivées en appelant CGopherConnection ::OpenFile ou CHttpConnection ::OpenRequest. Vous pouvez également créer un CInternetFile objet en appelant CFtpConnection ::OpenFile.

CInternetFile ::Close

Ferme et CInternetFile libère toutes ses ressources.

virtual void Close();

Notes

Si le fichier a été ouvert pour l’écriture, il existe un appel implicite à Flush pour garantir que toutes les données mises en mémoire tampon sont écrites sur l’hôte. Vous devez appeler Close une fois que vous avez terminé d’utiliser un fichier.

CInternetFile ::Flush

Appelez cette fonction membre pour vider le contenu de la mémoire tampon d’écriture.

virtual void Flush();

Notes

Utilisez cette option Flush pour vous assurer que toutes les données en mémoire ont été écrites sur l’ordinateur cible et que votre transaction avec l’ordinateur hôte a été terminée. Flush n’est efficace que sur CInternetFile les objets ouverts pour l’écriture.

CInternetFile ::GetLength

Retourne la taille du fichier.

virtual ULONGLONG GetLength() const;

CInternetFile ::m_hFile

Handle du fichier associé à cet objet.

HINTERNET m_hFile;

CInternetFile ::operator HINTERNET

Utilisez cet opérateur pour obtenir le descripteur Windows pour la session Internet active.

operator HINTERNET() const;

CInternetFile ::Read

Appelez cette fonction membre pour lire dans la mémoire donnée, en commençant à lpvBuf, le nombre spécifié d’octets, nCount.

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

Paramètres

lpBuf
Pointeur désignant une adresse mémoire où sont lues des données de fichier.

nCount
Nombre d'octets à écrire.

Valeur de retour

Nombre d'octets transférés dans la mémoire tampon. La valeur de retour peut être inférieure à nCount si la fin du fichier a été atteinte.

Notes

La fonction retourne le nombre d’octets réellement lus , un nombre qui peut être inférieur à nCount si le fichier se termine. Si une erreur se produit lors de la lecture du fichier, la fonction lève un objet CInternetException qui décrit l’erreur. Notez que la lecture au-delà de la fin du fichier n'est pas considérée comme une erreur et aucune exception n'est levée.

Pour vous assurer que toutes les données sont récupérées, une application doit continuer à appeler la CInternetFile::Read méthode jusqu’à ce que la méthode retourne zéro.

CInternetFile ::ReadString

Appelez cette fonction membre pour lire un flux de caractères jusqu’à ce qu’elle trouve un caractère de ligne.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Paramètres

pstr
Pointeur vers une chaîne qui recevra la ligne en cours de lecture.

nMax
Nombre maximal de caractères à lire.

rString
Référence à l’objet CString qui reçoit la ligne de lecture.

Valeur de retour

Pointeur vers la mémoire tampon contenant des données simples récupérées à partir de l’objet CInternetFile . Quel que soit le type de données de la mémoire tampon passée à cette méthode, il n’effectue aucune manipulation sur les données (par exemple, conversion en Unicode), vous devez mapper les données retournées à la structure attendue, comme si le void * type a été retourné.

NULL si la fin du fichier a été atteinte sans lire de données ; ou, si booléen, FALSE si la fin du fichier a été atteinte sans lire de données.

Notes

La fonction place la ligne résultante dans la mémoire référencée par le paramètre pstr . Il cesse de lire des caractères lorsqu’il atteint le nombre maximal de caractères, spécifié par nMax. La mémoire tampon reçoit toujours un caractère null de fin.

Si vous appelez sans appeler ReadString SetReadBufferSize, vous obtiendrez une mémoire tampon de 4 096 octets.

CInternetFile ::Seek

Appelez cette fonction membre pour repositionner le pointeur dans un fichier précédemment ouvert.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Paramètres

lOffset
Décalage en octets pour déplacer le pointeur en lecture/écriture dans le fichier.

nFrom
Référence relative pour le décalage. Il doit s’agir de l’une des valeurs suivantes :

• CFile::begin Déplacez le pointeur du fichier vers l’avant à partir du début du fichier.

• CFile::current Déplacez le pointeur de fichier lOff octets de la position actuelle dans le fichier.

• CFile::endDéplacez les octets lOff du pointeur de fichier à partir de la fin du fichier. lOff doit être négatif pour rechercher dans le fichier existant ; les valeurs positives recherchent au-delà de la fin du fichier.

Valeur de retour

Le nouveau décalage d’octets depuis le début du fichier si la position demandée est légale ; sinon, la valeur n’est pas définie et un objet CInternetException est levée.

Notes

La Seek fonction autorise l’accès aléatoire au contenu d’un fichier en déplaçant le pointeur d’une quantité spécifiée, absolument ou relativement. Aucune donnée n’est réellement lue pendant la recherche.

À ce stade, un appel à cette fonction membre est pris en charge uniquement pour les données associées aux CHttpFile objets. Il n’est pas pris en charge pour les requêtes FTP ou gopher. Si vous appelez Seek l’un de ces services non pris en charge, il vous renvoie au code d’erreur Win32 ERROR_INTERNET_INVALID_OPERATION.

Lorsqu’un fichier est ouvert, le pointeur de fichier est au décalage 0, au début du fichier.

Exemple

Consultez l’exemple d’implémentation de la classe de base ( CFile ::Seek).

CInternetFile ::SetReadBufferSize

Appelez cette fonction membre pour définir la taille de la mémoire tampon de lecture temporaire utilisée par un CInternetFileobjet dérivé.

BOOL SetReadBufferSize(UINT nReadSize);

Paramètres

nReadSize
Taille de la mémoire tampon voulue en octets.

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 API WinInet sous-jacentes n’effectuent pas de mise en mémoire tampon. Choisissez donc une taille de mémoire tampon qui permet à votre application de lire efficacement les données, quelle que soit la quantité de données à lire. Si chaque appel à Lire implique normalement une grande quantité de données (par exemple, quatre ou plusieurs kilo-octets), vous n’avez pas besoin d’une mémoire tampon. Toutefois, si vous appelez Read pour obtenir de petits blocs de données ou si vous utilisez ReadString pour lire des lignes individuelles à la fois, une mémoire tampon de lecture améliore les performances de l’application.

Par défaut, un CInternetFile objet ne fournit aucune mise en mémoire tampon pour la lecture. Si vous appelez cette fonction membre, vous devez être sûr que le fichier a été ouvert pour l’accès en lecture.

Vous pouvez augmenter la taille de la mémoire tampon à tout moment, mais la réduction de la mémoire tampon n’aura aucun effet. Si vous appelez ReadString sans d’abord appeler SetReadBufferSize, vous obtenez une mémoire tampon de 4 096 octets.

CInternetFile ::SetWriteBufferSize

Appelez cette fonction membre pour définir la taille de la mémoire tampon d’écriture temporaire utilisée par un CInternetFileobjet dérivé.

BOOL SetWriteBufferSize(UINT nWriteSize);

Paramètres

nWriteSize
Taille de la mémoire tampon en octets.

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 API WinInet sous-jacentes n’effectuent pas de mise en mémoire tampon. Choisissez donc une taille de mémoire tampon qui permet à votre application d’écrire efficacement des données, quelle que soit la quantité de données à écrire. Si chaque appel à Écrire implique normalement une grande quantité de données (par exemple, quatre ou plus kilo-octets à la fois), vous n’avez pas besoin d’une mémoire tampon. Toutefois, si vous appelez Écriture pour écrire de petits blocs de données, une mémoire tampon d’écriture améliore les performances de votre application.

Par défaut, un CInternetFile objet ne fournit aucune mise en mémoire tampon pour l’écriture. Si vous appelez cette fonction membre, vous devez être sûr que le fichier a été ouvert pour l’accès en écriture. Vous pouvez modifier la taille de la mémoire tampon d’écriture à tout moment, mais cela entraîne un appel implicite à Flush.

CInternetFile ::Write

Appelez cette fonction membre pour écrire dans la mémoire donnée, lpvBuf, le nombre spécifié d’octets, nCount.

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

Paramètres

lpBuf
Pointeur vers le premier octet à écrire.

nCount
Spécifie le nombre d’octets à écrire.

Notes

Si une erreur se produit lors de l’écriture des données, la fonction lève un objet CInternetException décrivant l’erreur.

CInternetFile ::WriteString

Cette fonction écrit une chaîne terminée par null dans le fichier associé.

virtual void WriteString(LPCTSTR pstr);

Paramètres

pstr
Pointeur vers une chaîne contenant le contenu à écrire.

Notes

Si une erreur se produit lors de l’écriture des données, la fonction lève un objet CInternetException décrivant l’erreur.

Voir aussi

CStdioFile, classe
Graphique hiérarchique
CInternetConnection, classe