La classe CArchive

Vous permet d’enregistrer un réseau complexe d’objets sous une forme binaire permanente (généralement le stockage sur disque) qui persiste une fois ces objets supprimés.

Syntaxe

class CArchive

Membres

Constructeurs publics

Nom	Description
CArchive::CArchive	Crée un objet CArchive.

Méthodes publiques

Nom	Description
CArchive::Abort	Ferme une archive sans lever d’exception.
CArchive::Close	Vide les données non écrites et se déconnecte du CFile.
CArchive::Flush	Vide les données non écrites de la mémoire tampon d’archivage.
CArchive::GetFile	Obtient le pointeur d’objet CFile pour cette archive.
CArchive::GetObjectSchema	Appelé à partir de la Serialize fonction pour déterminer la version de l’objet en cours de désérialisation.
CArchive::IsBufferEmpty	Détermine si la mémoire tampon a été vidée pendant un processus de réception windows Sockets.
CArchive::IsLoading	Détermine si l’archive est chargée.
CArchive::IsStoring	Détermine si l’archive est en cours de stockage.
CArchive::MapObject	Place les objets dans la carte qui ne sont pas sérialisés dans le fichier, mais qui sont disponibles pour les sous-objets à référencer.
CArchive::Read	Lit les octets bruts.
CArchive::ReadClass	Lit une référence de classe précédemment stockée avec WriteClass.
CArchive::ReadObject	Appelle la fonction d’un Serialize objet pour le chargement.
CArchive::ReadString	Lit une seule ligne de texte.
CArchive::SerializeClass	Lit ou écrit la référence de classe à l’objet CArchive en fonction de la direction du CArchive.
CArchive::SetLoadParams	Définit la taille à laquelle le tableau de charge augmente. Doit être appelé avant le chargement ou l’appel d’un MapObjectReadObject objet.
CArchive::SetObjectSchema	Définit le schéma d’objet stocké dans l’objet archive.
CArchive::SetStoreParams	Définit la taille de la table de hachage et la taille de bloc de la carte utilisée pour identifier des objets uniques pendant le processus de sérialisation.
CArchive::Write	Écrit des octets bruts.
CArchive::WriteClass	Écrit une référence à l’objet CRuntimeClassCArchive.
CArchive::WriteObject	Appelle la fonction d’un Serialize objet pour le stockage.
CArchive::WriteString	Écrit une seule ligne de texte.

Opérateurs publics

Nom	Description
CArchive::operator <<	Stocke les objets et les types primitifs dans l’archive.
CArchive::operator >>	Charge des objets et des types primitifs à partir de l’archive.

Membres de données publics

Nom	Description
CArchive::m_pDocument

Notes

CArchive n’a pas de classe de base.

Plus tard, vous pouvez charger les objets à partir du stockage persistant, les reconstituer en mémoire. Ce processus de persistance des données est appelé « sérialisation ».

Vous pouvez considérer un objet archive comme un type de flux binaire. Comme un flux d’entrée/sortie, une archive est associée à un fichier et autorise l’écriture tampon et la lecture des données vers et depuis le stockage. Un flux d’entrée/sortie traite des séquences de caractères ASCII, mais une archive traite les données d’objet binaire dans un format efficace et nonundant.

Vous devez créer un CFile objet avant de pouvoir créer un CArchive objet. En outre, vous devez vous assurer que l’état de chargement/magasin de l’archive est compatible avec le mode d’ouverture du fichier. Vous êtes limité à une archive active par fichier.

Lorsque vous construisez un CArchive objet, vous l’attachez à un objet de classe (ou une classe CFile dérivée) qui représente un fichier ouvert. Vous spécifiez également si l’archive sera utilisée pour le chargement ou le stockage. Un CArchive objet peut traiter non seulement les types primitifs, mais également les objets de CObjectclasses dérivées conçues pour la sérialisation. Une classe sérialisable a généralement une Serialize fonction membre et utilise généralement les macros et IMPLEMENT_SERIAL les DECLARE_SERIAL macros, comme décrit dans la classe CObject.

Les opérateurs d’extraction surchargé ( >>) et d’insertion () <<sont des interfaces de programmation d’archive pratiques qui prennent en charge les types primitifs et CObjectles classes dérivées.

CArchive prend également en charge la programmation avec les classes CSocket Windows Sockets MFC et CSocketFile. La IsBufferEmpty fonction membre prend en charge cette utilisation.

Pour plus d’informations sur CArchive, consultez les articles Sérialisation et Windows Sockets : Utilisation de sockets avec archives.

Hiérarchie d'héritage

CArchive

Spécifications

En-têteafx.h:

CArchive::Abort

Appelez cette fonction pour fermer l’archive sans lever d’exception.

void Abort ();

Notes

Le CArchive destructeur appelle Closenormalement , qui vide toutes les données qui n’ont pas été enregistrées dans l’objet associé CFile . Cela peut entraîner des exceptions.

Lors de l’interception de ces exceptions, il est judicieux d’utiliser Abort, afin que la destruction de l’objet CArchive ne provoque pas d’autres exceptions. Lors de la gestion des exceptions, CArchive::Abort ne lève pas d’exception sur les défaillances, car, contrairement CArchive::Closeà ce qui est le cas, Abort ignore les échecs.

Si vous avez utilisé new pour allouer l’objet CArchive sur le tas, vous devez le supprimer après avoir fermé le fichier.

Exemple

Consultez l’exemple pour CArchive::WriteClass.

CArchive::CArchive

Construit un CArchive objet et spécifie s’il sera utilisé pour le chargement ou le stockage d’objets.

CArchive(
    CFile* pFile,
    UINT nMode,
    int nBufSize = 4096,
    void* lpBuf = NULL);

Paramètres

pFile
Pointeur vers l’objet CFile qui est la source ou la destination ultime des données persistantes.

nMode
Indicateur qui spécifie si les objets seront chargés ou stockés dans l’archive. Le nMode paramètre doit avoir l’une des valeurs suivantes :

• CArchive::load Charge les données de l’archive. Nécessite uniquement CFile l’autorisation de lecture.

• CArchive::store Enregistre les données dans l’archive. Nécessite une CFile autorisation d’écriture.

• CArchive::bNoFlushOnDelete Empêche l’archivage d’appeler Flush automatiquement lorsque le destructeur d’archive est appelé. Si vous définissez cet indicateur, vous êtes responsable de l’appel Close explicite avant que le destructeur soit appelé. Si ce n’est pas le cas, vos données seront endommagées.

nBufSize
Entier qui spécifie la taille de la mémoire tampon de fichier interne, en octets. Notez que la taille de mémoire tampon par défaut est de 4 096 octets. Si vous archivez régulièrement des objets volumineux, vous améliorerez les performances si vous utilisez une plus grande taille de mémoire tampon qui est un multiple de la taille de la mémoire tampon de fichier.

lpBuf
Pointeur facultatif vers une mémoire tampon fournie par l’utilisateur de taille nBufSize. Si vous ne spécifiez pas ce paramètre, l’archive alloue une mémoire tampon à partir du tas local et la libère lorsque l’objet est détruit. L’archive ne libère pas une mémoire tampon fournie par l’utilisateur.

Notes

Vous ne pouvez pas modifier cette spécification après avoir créé l’archive.

Vous n’utilisez peut-être pas d’opérations CFile pour modifier l’état du fichier tant que vous n’avez pas fermé l’archive. Toute opération de ce type endommagera l’intégrité de l’archive. Vous pouvez accéder à la position du pointeur de fichier à tout moment pendant la sérialisation en obtenant l’objet de fichier de l’archive à partir de la GetFile fonction membre, puis en utilisant la CFile::GetPosition fonction. Vous devez appeler CArchive::Flush avant d’obtenir la position du pointeur de fichier.

Exemple

CFile file;
TCHAR szBuf[512];
if (!file.Open(_T("CArchive__test__file.txt"),
               CFile::modeCreate | CFile::modeWrite))
{
#ifdef _DEBUG
   AFXDUMP(_T("Unable to open file\n"));
   exit(1);
#endif
}
CArchive ar(&file, CArchive::store, 512, szBuf);

CArchive::Close

Vide toutes les données restantes dans la mémoire tampon, ferme l’archive et déconnecte l’archive du fichier.

void Close();

Notes

Aucune autre opération sur l’archive n’est autorisée. Après avoir fermé une archive, vous pouvez créer une autre archive pour le même fichier ou fermer le fichier.

La fonction Close membre garantit que toutes les données sont transférées de l’archive vers le fichier et rendent l’archive indisponible. Pour effectuer le transfert du fichier vers le support de stockage, vous devez d’abord utiliser CFile::Close et détruire l’objet CFile .

Exemple

Consultez l’exemple de CArchive ::WriteString.

CArchive::Flush

Force l’écriture de toutes les données restantes dans la mémoire tampon d’archivage dans le fichier.

void Flush();

Notes

La fonction Flush membre garantit que toutes les données sont transférées de l’archive au fichier. Vous devez appeler CFile::Close pour terminer le transfert du fichier vers le support de stockage.

Exemple

CFile myFile(_T("CArchive__test__file.txt"),
             CFile::modeCreate | CFile::modeWrite);
CArchive ar(&myFile, CArchive::store);

// Write a string to the archive.
ar.WriteString(_T("My string."));

// Flush all of the data to the file.
ar.Flush();

CArchive::GetFile

Obtient le pointeur d’objet CFile pour cette archive.

CFile* GetFile() const;

Valeur de retour

Pointeur constant vers l’objet en cours d’utilisation CFile .

Notes

Vous devez vider l’archive avant d’utiliser GetFile.

Exemple

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Appelez cette fonction à partir de la Serialize fonction pour déterminer la version de l’objet actuellement désérialisé.

UINT GetObjectSchema();

Valeur de retour

Lors de la désérialisation, la version de l’objet en cours de lecture.

Notes

L’appel de cette fonction n’est valide que lorsque l’objet CArchive est en cours de chargement ( CArchive::IsLoading retourne non zéro). Il doit s’agir du premier appel dans la Serialize fonction et appelé une seule fois. Une valeur de retour (UINT)-1 indique que le numéro de version est inconnu.

Une CObjectclasse dérivée peut utiliser VERSIONABLE_SCHEMA combinée (à l’aide du bit « ou » (|)) avec la version de schéma elle-même (dans la IMPLEMENT_SERIAL macro) pour créer un « objet pouvant être versionnable », autrement dit un objet dont Serialize la fonction membre peut lire plusieurs versions. La fonctionnalité d’infrastructure par défaut (sans VERSIONABLE_SCHEMA) consiste à lever une exception lorsque la version est incompatible.

Exemple

IMPLEMENT_SERIAL(CSchemaObject, CObject, VERSIONABLE_SCHEMA | 1)

void CSchemaObject::Serialize(CArchive &ar)
{
   CObject::Serialize(ar);

   if (ar.IsLoading())
   {
      int nVersion = ar.GetObjectSchema();

      switch (nVersion)
      {
      case 0:
         // read in previous version of
         // this object
         break;
      case 1:
         // read in current version of
         // this object
         break;
      default:
         // report unknown version of
         // this object
         break;
      }
   }
   else
   {
      // Normal storing code goes here
   }
}

CArchive::IsBufferEmpty

Appelez cette fonction membre pour déterminer si la mémoire tampon interne de l’objet archive est vide.

BOOL IsBufferEmpty() const;

Valeur de retour

Différent de zéro si la mémoire tampon de l’archive est vide ; sinon 0.

Notes

Cette fonction est fournie pour prendre en charge la programmation avec la classe CSocketFileWindows Sockets MFC. Vous n’avez pas besoin de l’utiliser pour une archive associée à un CFile objet.

La raison de l’utilisation IsBufferEmpty d’une archive associée à un CSocketFile objet est que la mémoire tampon de l’archive peut contenir plusieurs messages ou enregistrements. Après avoir reçu un message, vous devez utiliser IsBufferEmpty pour contrôler une boucle qui continue de recevoir des données jusqu’à ce que la mémoire tampon soit vide. Pour plus d’informations, consultez la Receive fonction membre de la classe CAsyncSocket, qui montre comment utiliser IsBufferEmpty.

Pour plus d’informations, consultez Windows Sockets : Utilisation de sockets avec archives.

CArchive::IsLoading

Détermine si l’archive charge les données.

BOOL IsLoading() const;

Valeur de retour

Différent de zéro si l’archive est actuellement utilisée pour le chargement ; sinon 0.

Notes

Cette fonction membre est appelée par les Serialize fonctions des classes archivées.

Exemple

int i = 0;
if (ar.IsLoading())
   ar >> i;
else
   ar << i;

CArchive::IsStoring

Détermine si l’archive stocke des données.

BOOL IsStoring() const;

Valeur de retour

Différent de zéro si l’archive est actuellement utilisée pour le stockage ; sinon 0.

Notes

Cette fonction membre est appelée par les Serialize fonctions des classes archivées.

Si l’état IsStoring d’une archive n’est pas zéro, son IsLoading état est 0, et vice versa.

Exemple

int i = 0;
if (ar.IsStoring())
   ar << i;
else
   ar >> i;

CArchive::MapObject

Appelez cette fonction membre pour placer des objets dans la carte qui ne sont pas vraiment sérialisés dans le fichier, mais qui sont disponibles pour les sous-objets à référencer.

void MapObject(const CObject* pOb);

Paramètres

pOb
Pointeur constant vers l’objet stocké.

Notes

Par exemple, vous ne sérialisez peut-être pas un document, mais vous sérialisez les éléments qui font partie du document. En appelant MapObject, vous autorisez ces éléments ou sous-objets à référencer le document. En outre, les sous-éléments sérialisés peuvent sérialiser leur m_pDocument pointeur arrière.

Vous pouvez appeler MapObject quand vous stockez et chargez à partir de l’objet CArchive . MapObject ajoute l’objet spécifié aux structures de données internes conservées par l’objet pendant la CArchive sérialisation et la désérialisation, mais contrairement ReadObject à et WriteObject, il n’appelle pas sérialiser sur l’objet.

Exemple

//MyDocument.h
class CMyDocument : public CDocument
{
public:
   DECLARE_SERIAL(CMyDocument)

   CObList m_listOfSubItems;

   virtual void Serialize(CArchive &ar);
};

 

//MyDocument.cpp
IMPLEMENT_SERIAL(CMyDocument, CDocument, 1)

void CMyDocument::Serialize(CArchive& ar)
{
   CDocument::Serialize(ar);

   if (ar.IsStoring())
   {
      // TODO: add storing code here
   }
   else
   {
      // TODO: add loading code here
   }

   ar.MapObject(this);

   //serialize the subitems in the document;
   //they will be able to serialize their m_pDoc
   //back pointer
   m_listOfSubItems.Serialize(ar);
}

 

//SubItem.h
class CSubItem : public CObject
{
   DECLARE_SERIAL(CSubItem)
   CSubItem() : m_i(0){};

public:
   CSubItem(CMyDocument *pDoc)
   {
      m_pDoc = pDoc;
   }

   // back pointer to owning document
   CMyDocument *m_pDoc;
   WORD m_i; // other item data

   virtual void Serialize(CArchive &ar);
};

 

//SubItem.cpp
IMPLEMENT_SERIAL(CSubItem, CObject, 1);

void CSubItem::Serialize(CArchive &ar)

{
   if (ar.IsStoring())
   {
      // will serialize a reference
      // to the "mapped" document pointer
      ar << (CObject *)m_pDoc;
      ar << m_i;
   }
   else
   {
      // Will load a reference to
      // the "mapped" document pointer
      ar >> (CObject *&)m_pDoc;
      ar >> m_i;
   }
}

CArchive::m_pDocument

NULL Défini par défaut, ce pointeur vers un CDocument peut être défini sur n’importe quel élément souhaité par l’utilisateur de l’instanceCArchive.

CDocument* m_pDocument;

Notes

Une utilisation courante de ce pointeur consiste à transmettre des informations supplémentaires sur le processus de sérialisation à tous les objets sérialisés. Pour ce faire, initialisez le pointeur avec le document (une CDocumentclasse dérivée) sérialisé, de telle sorte que les objets du document puissent accéder au document si nécessaire. Ce pointeur est également utilisé par COleClientItem les objets lors de la sérialisation.

L’infrastructure définit m_pDocument le document sérialisé lorsqu’un utilisateur émet une commande Ouvrir ou Enregistrer un fichier. Si vous sérialisez un document de conteneur OLE (Object Linking and Embedding) pour des raisons autres que File Open ou Save, vous devez définir m_pDocumentexplicitement . Par exemple, vous devez le faire lors de la sérialisation d’un document conteneur dans le Presse-papiers.

Exemple

CFile myFile(_T("My__test__file.dat"),
             CFile::modeCreate | CFile::modeWrite);
CArchive ar(&myFile, CArchive::store);
CMyDocument mydoc;
ar.m_pDocument = &mydoc;

// Serialize the document to the archive.
if (ar.m_pDocument != NULL)
   ar.m_pDocument->Serialize(ar);

CArchive::operator <<

Stocke l’objet ou le type primitif indiqué dans l’archive.

friend CArchive& operator<<(
    CArchive& ar,
    const CObject* pOb);

throw(
    CArchiveException*,
    CFileException*);

CArchive& AFXAPI operator<<(
    CArchive& ar,
    const RECT& rect);

CArchive& AFXAPI operator<<(
    CArchive& ar,
    POINT point);

CArchive& AFXAPI operator<<(
    CArchive& ar,
    SIZE size);

template<typename BaseType,
    class StringTraits> CArchive& operator<<(
    const ATL::CStringT<BaseType,
    StringTraits>& str);

CArchive& operator<<(BYTE by);
CArchive& operator<<(WORD w);
CArchive& operator<<(LONG l);
CArchive& operator<<(DWORD dw);
CArchive& operator<<(float f);
CArchive& operator<<(double d);
CArchive& operator<<(int i);
CArchive& operator<<(short w);
CArchive& operator<<(char ch);
CArchive& operator<<(wchar_t ch);
CArchive& operator<<(unsigned u);
CArchive& operator<<(bool b);
CArchive& operator<<(ULONGLONG dwdw);
CArchive& operator<<(LONGLONG dwdw);

Valeur de retour

Référence CArchive qui active plusieurs opérateurs d’insertion sur une seule ligne.

Notes

Les deux dernières versions ci-dessus sont spécifiquement destinées au stockage d’entiers 64 bits.

Si vous avez utilisé la IMPLEMENT_SERIAL macro dans votre implémentation de classe, l’opérateur d’insertion surchargé pour CObject les appels protégés WriteObject. Cette fonction appelle à son tour la Serialize fonction de la classe.

L’opérateur d’insertion (<<) prend en charge le CStringT dumping de diagnostic et le stockage dans une archive.

Exemples

Cet exemple illustre l’utilisation de l’opérateur CArchive<< d’insertion avec les types et long les int types.

long l = 5;
int i = 10;
if (ar.IsStoring())
   ar << l << i;

Cet exemple illustre l’utilisation de l’opérateur CArchive<< d’insertion avec le CStringT type.

CString s("abc");
ar << s; // Prints the value (abc)

CArchive::operator >>

Charge l’objet ou le type primitif indiqué à partir de l’archive.

friend CArchive& operator>>(
    CArchive& ar,
    CObject *& pOb);

throw(
    CArchiveException*,
    CFileException*,
    CMemoryException*);

friend CArchive& operator>>(
    CArchive& ar,
    const CObject *& pOb);

throw(
    CArchiveException*,
    CFileException*,
    CMemoryException*);

CArchive& AFXAPI operator>>(
    CArchive& ar,
    const RECT& rect);

CArchive& AFXAPI operator>>(
    CArchive& ar,
    POINT point);

CArchive& AFXAPI operator>>(
    CArchive& ar,
    SIZE size);

template<typename BaseType,
    class StringTraits> CArchive& operator>>(
    ATL::CStringT<BaseType,
    StringTraits>& str);

CArchive& operator>>(BYTE& by);
CArchive& operator>>(WORD& w);
CArchive& operator>>(int& i);
CArchive& operator>>(LONG& l);
CArchive& operator>>(DWORD& dw);
CArchive& operator>>(float& f);
CArchive& operator>>(double& d);
CArchive& operator>>(short& w);
CArchive& operator>>(char& ch);
CArchive& operator>>(wchar_t& ch);
CArchive& operator>>(unsigned& u);
CArchive& operator>>(bool& b);
CArchive& operator>>(ULONGLONG& dwdw);
CArchive& operator>>(LONGLONG& dwdw);

Valeur de retour

Référence CArchive qui active plusieurs opérateurs d’extraction sur une seule ligne.

Notes

Les deux dernières versions ci-dessus sont spécifiquement destinées au chargement d’entiers 64 bits.

Si vous avez utilisé la IMPLEMENT_SERIAL macro dans votre implémentation de classe, les opérateurs d’extraction surchargés pour CObject appeler la fonction protégée ReadObject (avec un pointeur de classe d’exécution différent de zéro). Cette fonction appelle à son tour la Serialize fonction de la classe.

L’opérateur d’extraction (>>) prend en charge le CStringT chargement à partir d’une archive.

Exemples

Cet exemple illustre l’utilisation de l’opérateur CArchive>> d’extraction avec le int type.

long l;
int i;
if (ar.IsLoading())
   ar >> l >> i;

Cet exemple illustre l’utilisation des CArchive opérateurs << d’insertion et d’extraction et >> avec le CStringT type.

CString s;
if (ar.IsLoading())
   ar >> s;

CArchive::Read

Lit un nombre spécifié d’octets de l’archive.

UINT Read(void* lpBuf, UINT nMax);

Paramètres

lpBuf
Pointeur vers une mémoire tampon fournie par l’utilisateur qui doit recevoir les données lues à partir de l’archive.

nMax
Entier non signé spécifiant le nombre d’octets à lire à partir de l’archive.

Valeur de retour

Entier non signé contenant le nombre d’octets réellement lus. Si la valeur de retour est inférieure au nombre demandé, la fin du fichier a été atteinte. Aucune exception n’est levée sur la condition de fin de fichier.

Notes

L’archive n’interprète pas les octets.

Vous pouvez utiliser la Read fonction membre dans votre Serialize fonction pour lire des structures ordinaires contenues dans vos objets.

Exemple

char pbRead[100];
ar.Read(pbRead, 100);

CArchive::ReadClass

Appelez cette fonction membre pour lire une référence à une classe précédemment stockée avec WriteClass.

CRuntimeClass* ReadClass(
    const CRuntimeClass* pClassRefRequested = NULL,
    UINT* pSchema = NULL,
    DWORD* pObTag = NULL);

Paramètres

pClassRefRequested
Pointeur vers la CRuntimeClass structure qui correspond à la référence de classe demandée. Peut être NULL.

pSchema
Pointeur vers un schéma de la classe d’exécution précédemment stockée.

pObTag
Nombre qui fait référence à la balise unique d’un objet. Utilisé en interne par l’implémentation de ReadObject. Exposé uniquement pour la programmation avancée ; pObTag normalement doit être NULL.

Valeur de retour

Pointeur vers la CRuntimeClass structure.

Notes

Si pClassRefRequested ce n’est pas NULLle cas, ReadClass vérifie que les informations de classe archivées sont compatibles avec votre classe runtime. S’il n’est pas compatible, ReadClass lève un CArchiveException.

Votre classe runtime doit utiliser DECLARE_SERIAL et IMPLEMENT_SERIAL; sinon, ReadClass lève un CNotSupportedException.

Si pSchema c’est NULLle cas, le schéma de la classe stockée peut être récupéré en appelant CArchive::GetObjectSchema; sinon, *pSchema contient le schéma de la classe d’exécution précédemment stockée.

Vous pouvez utiliser SerializeClass au lieu de ReadClass, qui gère à la fois la lecture et l’écriture de la référence de classe.

Exemple

Consultez l’exemple pour CArchive::WriteClass.

CArchive::ReadObject

Lit les données d’objet de l’archive et construit un objet du type approprié.

CObject* ReadObject(const CRuntimeClass* pClass);

Paramètres

pClass
Pointeur constant vers la CRuntimeClass structure qui correspond à l’objet que vous attendez à lire.

Valeur de retour

Pointeur CObject qui doit être converti en toute sécurité vers la classe dérivée correcte à l’aide CObject::IsKindOfde .

Notes

Cette fonction est normalement appelée par l’opérateur CArchive d’extraction ( >>) surchargé pour un CObject pointeur. ReadObject, à son tour, appelle la Serialize fonction de la classe archivée.

Si vous fournissez un paramètre différent de zéro pClass , obtenu par la RUNTIME_CLASS macro, la fonction vérifie la classe d’exécution de l’objet archivé. Cela suppose que vous avez utilisé la IMPLEMENT_SERIAL macro dans l’implémentation de la classe.

Exemple

Consultez l’exemple pour CArchive::WriteObject.

CArchive::ReadString

Appelez cette fonction membre pour lire les données de texte dans une mémoire tampon à partir du fichier associé à l’objet CArchive .

BOOL ReadString(CString& rString);
LPTSTR ReadString(LPTSTR lpsz, UINT nMax);

Paramètres

rString
Référence à une CString chaîne qui contiendra la chaîne résultante une fois qu’elle est lue à partir du fichier associé à l’objet CArchive .

lpsz
Spécifie un pointeur vers une mémoire tampon fournie par l’utilisateur qui recevra une chaîne de texte terminée par null.

nMax
Spécifie le nombre maximal de caractères à lire. Doit être inférieur à la taille de la lpsz mémoire tampon.

Valeur de retour

Dans la version qui retourne BOOL, TRUE si elle réussit ; FALSE sinon.

Dans la version qui retourne un LPTSTRpointeur vers la mémoire tampon contenant les données texte ; NULL si la fin du fichier a été atteinte.

Notes

Dans la version de la fonction membre avec le nMax paramètre, la mémoire tampon conserve jusqu’à une limite de - nMax 1 caractères. La lecture est arrêtée par une paire d’alimentation chariot de ligne de retour. Les caractères de ligne de fin sont toujours supprimés. Un NULL caractère ('\0') est ajouté dans les deux cas.

CArchive::Read est également disponible pour l’entrée en mode texte, mais elle ne se termine pas sur une paire de flux de retour chariot.

Exemple

Consultez l’exemple pour CArchive::WriteString.

CArchive::SerializeClass

Appelez cette fonction membre lorsque vous souhaitez stocker et charger les informations de version d’une classe de base.

void SerializeClass(const CRuntimeClass* pClassRef);

Paramètres

pClassRef
Pointeur vers un objet de classe run-time pour la classe de base.

Notes

SerializeClass lit ou écrit la référence à une classe dans l’objet CArchive , en fonction de la direction du CArchive. Utilisez SerializeClass à la place et WriteClass comme moyen pratique de sérialiser des objets de classe de base ; SerializeClass nécessite moins de ReadClass code et moins de paramètres.

Comme ReadClass, SerializeClass vérifie que les informations de classe archivées sont compatibles avec votre classe runtime. S’il n’est pas compatible, SerializeClass lève un CArchiveException.

Votre classe runtime doit utiliser DECLARE_SERIAL et IMPLEMENT_SERIAL; sinon, SerializeClass lève un CNotSupportedException.

Utilisez la RUNTIME_CLASS macro pour récupérer la valeur du pRuntimeClass paramètre. La classe de base doit avoir utilisé la IMPLEMENT_SERIAL macro.

Exemple

class CBaseClass : public CObject
{
   DECLARE_SERIAL(CBaseClass);
};
class CDerivedClass : public CBaseClass
{
public:
   virtual void Serialize(CArchive &ar);
};
void CDerivedClass::Serialize(CArchive &ar)
{
   if (ar.IsStoring())
   {
      //normal code for storing contents
      //of this object
   }
   else
   {
      //normal code for reading contents
      //of this object
   }

   //allow the base class to serialize along
   //with its version information
   ar.SerializeClass(RUNTIME_CLASS(CBaseClass));
   CBaseClass::Serialize(ar);
}

CArchive::SetLoadParams

Appelez SetLoadParams quand vous allez lire un grand nombre d’objets CObjectdérivés d’une archive.

void SetLoadParams(UINT nGrowBy = 1024);

Paramètres

nGrowBy
Nombre minimal d’emplacements d’élément à allouer si une augmentation de taille est nécessaire.

Notes

CArchive utilise un tableau de charge pour résoudre les références aux objets stockés dans l’archive. SetLoadParams vous permet de définir la taille à laquelle le tableau de charge augmente.

Vous ne devez pas appeler SetLoadParams une fois qu’un objet est chargé, ou après MapObject ou ReadObject appelé.

Exemple

class CMyLargeDocument : public CDocument
{
public:
   virtual void Serialize(CArchive &ar);
};
void CMyLargeDocument::Serialize(CArchive &ar)
{
   if (ar.IsStoring())
      ar.SetStoreParams(); // use large defaults
   else
      ar.SetLoadParams();

   if (ar.IsStoring())
   {
      // code for storing CMyLargeDocument
   }
   else
   {
      // code for loading CMyLargeDocument
   }
}

CArchive::SetObjectSchema

Appelez cette fonction membre pour définir le schéma d’objet stocké dans l’objet archive sur nSchema.

void SetObjectSchema(UINT nSchema);

Paramètres

nSchema
Spécifie le schéma de l’objet.

Notes

L’appel suivant pour GetObjectSchema renvoyer la valeur stockée dans nSchema.

Utiliser SetObjectSchema pour le contrôle de version avancé ; par exemple, lorsque vous souhaitez forcer la lecture d’une version particulière dans une Serialize fonction d’une classe dérivée.

Exemple

ar.SetObjectSchema(2);
ASSERT(2 == ar.GetObjectSchema());

CArchive::SetStoreParams

Utilisez cette méthode SetStoreParams lors du stockage d’un grand nombre d’objets CObjectdérivés dans une archive.

void SetStoreParams(UINT nHashSize = 2053, UINT nBlockSize = 128);

Paramètres

nHashSize
Taille de la table de hachage pour les mappages de pointeur d’interface. Doit être un nombre premier.

nBlockSize
Spécifie la granularité d’allocation de mémoire pour étendre les paramètres. Doit être une puissance de 2 pour les meilleures performances.

Notes

SetStoreParams vous permet de définir la taille de la table de hachage et la taille de bloc de la carte utilisée pour identifier des objets uniques pendant le processus de sérialisation.

Vous ne devez pas appeler SetStoreParams une fois les objets stockés, ou après MapObject ou WriteObject appelé.

Exemple

class CMyLargeDocument : public CDocument
{
public:
   virtual void Serialize(CArchive &ar);
};
void CMyLargeDocument::Serialize(CArchive &ar)
{
   if (ar.IsStoring())
      ar.SetStoreParams(); // use large defaults
   else
      ar.SetLoadParams();

   if (ar.IsStoring())
   {
      // code for storing CMyLargeDocument
   }
   else
   {
      // code for loading CMyLargeDocument
   }
}

CArchive::Write

Écrit un nombre spécifié d’octets dans l’archive.

void Write(const void* lpBuf, INT nMax);

Paramètres

lpBuf
Pointeur vers une mémoire tampon fournie par l’utilisateur qui contient les données à écrire dans l’archive.

nMax
Entier qui spécifie le nombre d’octets à écrire dans l’archive.

Notes

L’archive ne met pas en forme les octets.

Vous pouvez utiliser la Write fonction membre dans votre Serialize fonction pour écrire des structures ordinaires contenues dans vos objets.

Exemple

char pbWrite[100];
memset(pbWrite, 'a', 100);
ar.Write(pbWrite, 100);

CArchive::WriteClass

Permet WriteClass de stocker les informations de version et de classe d’une classe de base pendant la sérialisation de la classe dérivée.

void WriteClass(const CRuntimeClass* pClassRef);

Paramètres

pClassRef
Pointeur vers la CRuntimeClass structure qui correspond à la référence de classe demandée.

Notes

WriteClass écrit une référence à la CRuntimeClass classe de base dans le CArchive. Permet CArchive::ReadClass de récupérer la référence.

WriteClass vérifie que les informations de classe archivées sont compatibles avec votre classe runtime. S’il n’est pas compatible, WriteClass lève un CArchiveException.

Votre classe runtime doit utiliser DECLARE_SERIAL et IMPLEMENT_SERIAL; sinon, WriteClass lève un CNotSupportedException.

Vous pouvez utiliser SerializeClass au lieu de WriteClass, qui gère à la fois la lecture et l’écriture de la référence de classe.

Exemple

CFile myFile(_T("My__test__file.dat"),
             CFile::modeCreate | CFile::modeReadWrite);

// Create a storing archive.
CArchive arStore(&myFile, CArchive::store);

// Store the class CAge in the archive.
arStore.WriteClass(RUNTIME_CLASS(CAge));

// Close the storing archive.
arStore.Close();

// Create a loading archive.
myFile.SeekToBegin();
CArchive arLoad(&myFile, CArchive::load);

// Load a class from the archive.
CRuntimeClass *pClass = arLoad.ReadClass();
if (!pClass->IsDerivedFrom(RUNTIME_CLASS(CAge)))
{
   arLoad.Abort();
}

CArchive::WriteObject

Stocke le fichier spécifié CObject dans l’archive.

void WriteObject(const CObject* pOb);

Paramètres

pOb
Pointeur constant vers l’objet stocké.

Notes

Cette fonction est normalement appelée par l’opérateur CArchive d’insertion ( <<) surchargé pour CObject. WriteObject, à son tour, appelle la Serialize fonction de la classe archivée.

Vous devez utiliser la IMPLEMENT_SERIAL macro pour activer l’archivage. WriteObject écrit le nom de la classe ASCII dans l’archive. Ce nom de classe est validé ultérieurement pendant le processus de chargement. Un schéma d’encodage spécial empêche la duplication inutile du nom de classe pour plusieurs objets de la classe. Ce schéma empêche également le stockage redondant d’objets cibles de plusieurs pointeurs.

La méthode d’encodage d’objet exacte (y compris la présence du nom de classe ASCII) est un détail d’implémentation et peut changer dans les futures versions de la bibliothèque.

Remarque

Terminez la création, la suppression et la mise à jour de tous vos objets avant de commencer à les archiver. Votre archive est endommagée si vous mélangez l’archivage avec la modification de l’objet.

Exemple

Pour obtenir une définition de la classe CAge, consultez l’exemple pour CObList::CObList.

CFile myFile(_T("My__test__file.dat"),
             CFile::modeCreate | CFile::modeReadWrite);
CAge age(21), *pAge;

// Create a storing archive.
CArchive arStore(&myFile, CArchive::store);

// Write the object to the archive
arStore.WriteObject(&age);

// Close the storing archive
arStore.Close();

// Create a loading archive.
myFile.SeekToBegin();
CArchive arLoad(&myFile, CArchive::load);

// Verify the object is in the archive.
pAge = (CAge *)arLoad.ReadObject(RUNTIME_CLASS(CAge));
ASSERT(age == *pAge);

CArchive::WriteString

Utilisez cette fonction membre pour écrire des données d’une mémoire tampon dans le fichier associé à l’objet CArchive .

void WriteString(LPCTSTR lpsz);

Paramètres

lpsz
Spécifie un pointeur vers une mémoire tampon contenant une chaîne de texte terminée par null.

Notes

Le caractère null de fin ('\0') n’est pas écrit dans le fichier ; ni n’est-ce qu’une ligne de nouvelle ligne automatiquement écrite.

WriteString lève une exception en réponse à plusieurs conditions, y compris la condition complète du disque.

Write est également disponible, mais plutôt que de terminer sur un caractère Null, il écrit le nombre demandé d’octets dans le fichier.

Exemple

CFile myFile(_T("My__test__file.dat"),
             CFile::modeCreate | CFile::modeReadWrite);
CString str1("String1"), str2("String2"), str;

// Create a storing archive.
CArchive arStore(&myFile, CArchive::store);

// Write str1 and str2 to the archive
arStore.WriteString(str1);
arStore.WriteString(_T("\n"));
arStore.WriteString(str2);
arStore.WriteString(_T("\n"));

// Close the storing archive
arStore.Close();

// Create a loading archive.
myFile.SeekToBegin();
CArchive arLoad(&myFile, CArchive::load);

// Verify the two strings are in the archive.
arLoad.ReadString(str);
ASSERT(str == str1);
arLoad.ReadString(str);
ASSERT(str == str2);

Voir aussi

Graphique hiérarchique
CFile Classe
CObject Classe
CSocket Classe
CSocketFile Classe