CArchive-Klasse

  • Artikel

Ermöglicht es Ihnen, ein komplexes Netzwerk von Objekten in einer dauerhaften Binärform (in der Regel Datenträgerspeicher) zu speichern, die nach dem Löschen dieser Objekte beibehalten werden.

Syntax

class CArchive

Member

Öffentliche Konstruktoren

Name Beschreibung
CArchive::CArchive Erstellt ein CArchive-Objekt.

Öffentliche Methoden

Name Beschreibung
CArchive::Abort Schließt ein Archiv, ohne eine Ausnahme zu auslösen.
CArchive::Close Löscht ungeschriebene Daten und trennt sie von der CFile.
CArchive::Flush Löscht ungeschriebene Daten aus dem Archivpuffer.
CArchive::GetFile Ruft den CFile Objektzeiger für dieses Archiv ab.
CArchive::GetObjectSchema Wird von der Serialize Funktion aufgerufen, um die Version des objekts zu bestimmen, das deserialisiert wird.
CArchive::IsBufferEmpty Bestimmt, ob der Puffer während eines Windows Sockets-Empfangsvorgangs geleert wurde.
CArchive::IsLoading Bestimmt, ob das Archiv geladen wird.
CArchive::IsStoring Bestimmt, ob das Archiv gespeichert wird.
CArchive::MapObject Platziert Objekte in der Zuordnung, die nicht in die Datei serialisiert werden, aber für Unterobjekte verfügbar sind, auf die verwiesen werden kann.
CArchive::Read Liest unformatierte Bytes.
CArchive::ReadClass Liest einen Zuvor gespeicherten Klassenverweis mit WriteClass.
CArchive::ReadObject Ruft die Funktion eines Objekts Serialize zum Laden auf.
CArchive::ReadString Liest eine einzelne Textzeile vor.
CArchive::SerializeClass Liest oder schreibt den Klassenverweis auf das CArchive Objekt abhängig von der Richtung der CArchive.
CArchive::SetLoadParams Legt die Größe fest, auf die das Ladearray wächst. Muss aufgerufen werden, bevor ein Objekt geladen oder vor oder vor MapObject oder ReadObject aufgerufen wird.
CArchive::SetObjectSchema Legt das im Archivobjekt gespeicherte Objektschema fest.
CArchive::SetStoreParams Legt die Größe der Hashtabelle und die Blockgröße der Karte fest, die zum Identifizieren eindeutiger Objekte während des Serialisierungsprozesses verwendet wird.
CArchive::Write Schreibt unformatierte Bytes.
CArchive::WriteClass Schreibt einen Verweis auf die CRuntimeClass CArchive.
CArchive::WriteObject Ruft die Funktion eines Objekts Serialize zum Speichern auf.
CArchive::WriteString Schreibt eine einzelne Textzeile.

Öffentliche Operatoren

Name Beschreibung
CArchive::operator << Speichert Objekte und Grundtypen im Archiv.
CArchive::operator >> Lädt Objekte und Grundtypen aus dem Archiv.

Öffentliche Datenmember

Name Beschreibung
CArchive::m_pDocument

Hinweise

CArchive besitzt keine Basisklasse.

Später können Sie die Objekte aus dem beständigen Speicher laden und sie im Arbeitsspeicher neu erstellen. Dieser Prozess der dauerhaften Datenerstellung wird als "Serialisierung" bezeichnet.

Sie können sich ein Archivobjekt als eine Art binärer Datenstrom vorstellen. Wie ein Eingabe-/Ausgabedatenstrom ist ein Archiv einer Datei zugeordnet und ermöglicht das pufferte Schreiben und Lesen von Daten in und aus dem Speicher. Ein Eingabe-/Ausgabedatenstrom verarbeitet Sequenzen von ASCII-Zeichen, aber ein Archiv verarbeitet binäre Objektdaten in einem effizienten, nicht umsetzbaren Format.

Sie müssen ein CFile Objekt erstellen, bevor Sie ein CArchive Objekt erstellen können. Darüber hinaus müssen Sie sicherstellen, dass der Lade-/Speicherstatus des Archivs mit dem Geöffneten Modus der Datei kompatibel ist. Sie sind auf ein aktives Archiv pro Datei beschränkt.

Wenn Sie ein CArchive Objekt erstellen, fügen Sie es an ein Objekt der Klasse CFile (oder eine abgeleitete Klasse) an, das eine geöffnete Datei darstellt. Außerdem geben Sie an, ob das Archiv zum Laden oder Speichern verwendet wird. Ein CArchive Objekt kann nicht nur primitive Typen, sondern auch Objekte von abgeleiteten Klassen verarbeiten, die CObjectfür die Serialisierung entwickelt wurden. Eine serialisierbare Klasse verfügt in der Regel über eine Serialize Memberfunktion, und sie verwendet in der Regel die DECLARE_SERIAL und IMPLEMENT_SERIAL Makros, wie unter klasse CObjectbeschrieben.

Die überladenen Extraktionsoperatoren ( >>) und Einfügung ( <<) sind praktische Archivprogrammierschnittstellen, die sowohl primitive Typen als CObjectauch abgeleitete Klassen unterstützen.

CArchive unterstützt auch die Programmierung mit den MFC Windows Sockets-Klassen CSocket und CSocketFile. Die IsBufferEmpty Memberfunktion unterstützt diese Verwendung.

Weitere Informationen CArchivefinden Sie in den Artikeln Serialisierung und Windows Sockets: Verwenden von Sockets mit Archiven.

Vererbungshierarchie

CArchive

Anforderungen

Header: afx.h

CArchive::Abort

Rufen Sie diese Funktion auf, um das Archiv zu schließen, ohne eine Ausnahme auszuwerfen.

void Abort ();

Hinweise

Der CArchive Destruktor ruft normalerweise auf, wodurch alle Daten geleert Closewerden, die nicht im zugeordneten CFile Objekt gespeichert wurden. Dies kann zu Ausnahmen führen.

Beim Abfangen dieser Ausnahmen empfiehlt es sich, diese Ausnahmen zu verwenden Abort, sodass das Destruktieren des CArchive Objekts keine weiteren Ausnahmen verursacht. Bei der Behandlung von Ausnahmen wird bei Fehlern keine Ausnahme ausgelöst, CArchive::Abort da im Gegensatz dazu CArchive::CloseAbort Fehler ignoriert werden.

Wenn Sie new das CArchive Objekt für den Heap zugeordnet haben, müssen Sie es nach dem Schließen der Datei löschen.

Beispiel

Ein Beispiel hierfür finden Sie unter CArchive::WriteClass.

CArchive::CArchive

Erstellt ein CArchive Objekt und gibt an, ob es zum Laden oder Speichern von Objekten verwendet wird.

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

Parameter

pFile
Ein Zeiger auf das CFile Objekt, das die ultimative Quelle oder das Ziel der persistenten Daten ist.

nMode
Ein Kennzeichen, das angibt, ob Objekte aus dem Archiv geladen oder gespeichert werden sollen. Der nMode Parameter muss einen der folgenden Werte aufweisen:

  • CArchive::load Lädt Daten aus dem Archiv. Erfordert nur CFile Leseberechtigungen.

  • CArchive::store Speichert Daten im Archiv. Erfordert CFile Schreibberechtigungen.

  • CArchive::bNoFlushOnDelete Verhindert, dass das Archiv automatisch aufgerufen Flush wird, wenn der Archivdestruktor aufgerufen wird. Wenn Sie dieses Kennzeichen festlegen, sind Sie dafür verantwortlich, explizit aufzurufen Close , bevor der Destruktor aufgerufen wird. Wenn Sie dies nicht tun, werden Ihre Daten beschädigt.

nBufSize
Eine ganze Zahl, die die Größe des internen Dateipuffers in Byte angibt. Beachten Sie, dass die Standardpuffergröße 4.096 Byte beträgt. Wenn Sie große Objekte routinemäßig archiviert haben, verbessern Sie die Leistung, wenn Sie eine größere Puffergröße verwenden, die ein Vielfaches der Dateipuffergröße ist.

lpBuf
Ein optionaler Zeiger auf einen vom Benutzer bereitgestellten Puffer der Größe nBufSize. Wenn Sie diesen Parameter nicht angeben, weist das Archiv einen Puffer vom lokalen Heap zu und gibt ihn frei, wenn das Objekt zerstört wird. Das Archiv gibt keinen vom Benutzer bereitgestellten Puffer frei.

Hinweise

Sie können diese Spezifikation nicht ändern, nachdem Sie das Archiv erstellt haben.

Sie dürfen vorgänge nicht verwenden CFile , um den Status der Datei zu ändern, bis Sie das Archiv geschlossen haben. Jede solche Operation beschädigt die Integrität des Archivs. Sie können jederzeit während der Serialisierung auf die Position des Dateizeigers zugreifen, indem Sie das Dateiobjekt des Archivs aus der GetFile Memberfunktion abrufen und dann die CFile::GetPosition Funktion verwenden. Sie sollten vor dem Abrufen der Position des Dateizeigers aufrufen CArchive::Flush .

Beispiel

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

Löscht alle im Puffer verbleibenden Daten, schließt das Archiv und trennt das Archiv von der Datei.

void Close();

Hinweise

Es sind keine weiteren Vorgänge im Archiv zulässig. Nachdem Sie ein Archiv geschlossen haben, können Sie ein weiteres Archiv für dieselbe Datei erstellen oder die Datei schließen.

Die Memberfunktion Close stellt sicher, dass alle Daten aus dem Archiv in die Datei übertragen werden und das Archiv nicht verfügbar macht. Um die Übertragung von der Datei auf das Speichermedium abzuschließen, müssen Sie zuerst das CFile Objekt verwenden CFile::Close und dann zerstören.

Beispiel

Siehe das Beispiel für CArchive::WriteString.

CArchive::Flush

Erzwingt, dass alle im Archivpuffer verbleibenden Daten in die Datei geschrieben werden.

void Flush();

Hinweise

Die Memberfunktion Flush stellt sicher, dass alle Daten aus dem Archiv in die Datei übertragen werden. Sie müssen aufrufen CFile::Close , um die Übertragung von der Datei auf das Speichermedium abzuschließen.

Beispiel

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

Ruft den CFile Objektzeiger für dieses Archiv ab.

CFile* GetFile() const;

Rückgabewert

Ein konstanter Zeiger auf das CFile verwendete Objekt.

Hinweise

Sie müssen das Archiv vor der Verwendung GetFileleeren.

Beispiel

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Rufen Sie diese Funktion aus der Serialize Funktion auf, um die Version des Objekts zu ermitteln, das derzeit deserialisiert wird.

UINT GetObjectSchema();

Rückgabewert

Während der Deserialisierung wird die Version des zu lesenden Objekts gelesen.

Hinweise

Das Aufrufen dieser Funktion ist nur gültig, wenn das CArchive Objekt geladen wird ( CArchive::IsLoading gibt nonzero zurück). Es sollte der erste Aufruf in der Serialize Funktion sein und nur einmal aufgerufen werden. Ein Rückgabewert von ( UINT)-1 gibt an, dass die Versionsnummer unbekannt ist.

Eine CObjectabgeleitete Klasse kann VERSIONABLE_SCHEMA kombiniert (mit bitweisem "oder" (|)) mit der Schemaversion selbst (im IMPLEMENT_SERIAL Makro) ein "versionsfähiges Objekt" erstellen, d. h. ein Objekt, dessen Serialize Memberfunktion mehrere Versionen lesen kann. Die Standardframeworkfunktionalität (ohne VERSIONABLE_SCHEMA) besteht darin, eine Ausnahme auszuwerfen, wenn die Version nicht übereinstimmen.

Beispiel

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

Rufen Sie diese Memberfunktion auf, um zu bestimmen, ob der interne Puffer des Archivobjekts leer ist.

BOOL IsBufferEmpty() const;

Rückgabewert

Nonzero, wenn der Puffer des Archivs leer ist; andernfalls 0.

Hinweise

Diese Funktion wird bereitgestellt, um die Programmierung mit der MFC Windows Sockets-Klasse CSocketFilezu unterstützen. Sie müssen es nicht für ein Archiv verwenden, das einem CFile Objekt zugeordnet ist.

Der Grund für die Verwendung IsBufferEmpty mit einem Archiv, das einem CSocketFile Objekt zugeordnet ist, besteht darin, dass der Puffer des Archivs mehrere Nachrichten oder Datensätze enthalten kann. Nach dem Empfangen einer Nachricht sollten IsBufferEmpty Sie eine Schleife steuern, die weiterhin Daten empfängt, bis der Puffer leer ist. Weitere Informationen finden Sie in der Receive Memberfunktion der Klasse CAsyncSocket, die zeigt, wie sie verwendet IsBufferEmptywird.

Weitere Informationen finden Sie unter Windows Sockets: Verwenden von Sockets mit Archiven.

CArchive::IsLoading

Bestimmt, ob das Archiv Daten lädt.

BOOL IsLoading() const;

Rückgabewert

Nonzero, wenn das Archiv zurzeit zum Laden verwendet wird; andernfalls 0.

Hinweise

Diese Memberfunktion wird von den Serialize Funktionen der archivierten Klassen aufgerufen.

Beispiel

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

CArchive::IsStoring

Bestimmt, ob das Archiv Daten speichert.

BOOL IsStoring() const;

Rückgabewert

Nonzero, wenn das Archiv zurzeit zum Speichern verwendet wird; andernfalls 0.

Hinweise

Diese Memberfunktion wird von den Serialize Funktionen der archivierten Klassen aufgerufen.

Wenn der IsStoring Status eines Archivs "nonzero" ist, lautet der IsLoading Status "0" und umgekehrt.

Beispiel

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

CArchive::MapObject

Rufen Sie diese Memberfunktion auf, um Objekte in der Zuordnung zu platzieren, die nicht wirklich serialisiert sind, aber für Unterobjekte verfügbar sind, auf die verwiesen werden kann.

void MapObject(const CObject* pOb);

Parameter

pOb
Ein konstanter Zeiger auf das objekt, das gespeichert wird.

Hinweise

Beispielsweise können Sie ein Dokument nicht serialisieren, sondern die Elemente serialisieren, die Teil des Dokuments sind. Durch Aufrufen MapObjectvon Elementen oder Unterobjekten können Sie auf das Dokument verweisen. Außerdem können serialisierte Unterelemente ihren m_pDocument Rückzeiger serialisieren.

Sie können aufrufen MapObject , wenn Sie das CArchive Objekt speichern und laden. MapObject fügt das angegebene Objekt den internen Datenstrukturen hinzu, die während der CArchive Serialisierung und Deserialisierung vom Objekt verwaltet werden, im Gegensatz zu ReadObject und WriteObject, es wird jedoch keine Serialisierung für das Objekt aufgerufen.

Beispiel

//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 Dieser Zeiger kann standardmäßig auf ein CDocument Beliebiges festgelegt werden, das der Benutzer der CArchive Instanz möchte.

CDocument* m_pDocument;

Hinweise

Eine häufige Verwendung dieses Zeigers besteht darin, zusätzliche Informationen zum Serialisierungsprozess für alle Objekte zu übermitteln, die serialisiert werden. Dies wird erreicht, indem der Zeiger mit dem Dokument (eine CDocumentabgeleitete Klasse) initialisiert wird, die serialisiert wird, sodass Objekte im Dokument bei Bedarf auf das Dokument zugreifen können. Dieser Zeiger wird auch von COleClientItem Objekten während der Serialisierung verwendet.

Das Framework wird auf das Dokument festgelegt m_pDocument , das serialisiert wird, wenn ein Benutzer einen Befehl "Datei öffnen" oder "Speichern" ausgibt. Wenn Sie ein OLE-Containerdokument (Object Linking and Embedding) aus anderen Gründen als "Datei öffnen" oder "Speichern" serialisieren, müssen Sie explizit festlegen m_pDocument. Dies würden Sie beispielsweise tun, wenn Sie ein Containerdokument in die Zwischenablage serialisieren.

Beispiel

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

Speichert das angegebene Objekt oder den primitiven Typ im Archiv.

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

Rückgabewert

Ein CArchive Verweis, der mehrere Einfügeoperatoren in einer einzelnen Zeile ermöglicht.

Hinweise

Die beiden obigen Versionen dienen speziell zum Speichern von 64-Bit-Ganzzahlen.

Wenn Sie das IMPLEMENT_SERIAL Makro in der Klassenimplementierung verwendet haben, wird der Einfügeoperator für CObject Aufrufe der geschützten WriteObjectKlasse überladen. Diese Funktion ruft wiederum die Serialize Funktion der Klasse auf.

Der CStringT Einfügeoperator (<<) unterstützt Diagnosedumping und -speicherung in einem Archiv.

Beispiele

In diesem Beispiel wird die Verwendung des CArchive Einfügeoperators << mit den int Und-Typen long veranschaulicht.

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

In diesem Beispiel wird die Verwendung des CArchive Einfügeoperators << mit dem CStringT Typ veranschaulicht.

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

CArchive::operator >>

Lädt den angegebenen Objekt- oder Grundtyp aus dem Archiv.

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

Rückgabewert

Ein CArchive Verweis, der mehrere Extraktionsoperatoren in einer einzelnen Zeile ermöglicht.

Hinweise

Die letzten beiden obigen Versionen beziehen sich speziell auf das Laden von 64-Bit-Ganzzahlen.

Wenn Sie das IMPLEMENT_SERIAL Makro in der Klassenimplementierung verwendet haben, werden die Extraktionsoperatoren überladen, um CObject die geschützte ReadObject Funktion aufzurufen (mit einem Nichtzero-Laufzeitklassenzeiger). Diese Funktion ruft wiederum die Serialize Funktion der Klasse auf.

Der CStringT Extraktionsoperator (>>) unterstützt das Laden aus einem Archiv.

Beispiele

In diesem Beispiel wird die Verwendung des CArchive Extraktionsoperators >> mit dem int Typ veranschaulicht.

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

In diesem Beispiel wird die Verwendung der CArchive Einfüge- und Extraktionsoperatoren << und >> mit dem CStringT Typ veranschaulicht.

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

CArchive::Read

Liest eine angegebene Anzahl von Bytes aus dem Archiv.

UINT Read(void* lpBuf, UINT nMax);

Parameter

lpBuf
Ein Zeiger auf einen vom Benutzer bereitgestellten Puffer, der die aus dem Archiv gelesenen Daten empfängt.

nMax
Eine nicht signierte ganze Zahl, die die Anzahl der Bytes angibt, die aus dem Archiv gelesen werden sollen.

Rückgabewert

Eine nicht signierte ganze Zahl, die die Anzahl der tatsächlich gelesenen Bytes enthält. Wenn der Rückgabewert kleiner als die angeforderte Zahl ist, wurde das Ende der Datei erreicht. Für die End-of-File-Bedingung wird keine Ausnahme ausgelöst.

Hinweise

Das Archiv interpretiert die Bytes nicht.

Sie können die Read Memberfunktion in Ihrer Serialize Funktion verwenden, um gewöhnliche Strukturen zu lesen, die in Ihren Objekten enthalten sind.

Beispiel

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

CArchive::ReadClass

Rufen Sie diese Memberfunktion auf, um einen Verweis auf eine klasse zu lesen, die zuvor mit WriteClass.

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

Parameter

pClassRefRequested
Ein Zeiger auf die Struktur, die CRuntimeClass dem angeforderten Klassenverweis entspricht. Kann NULL sein.

pSchema
Ein Zeiger auf ein Schema der zuvor gespeicherten Laufzeitklasse.

pObTag
Eine Zahl, die auf das eindeutige Tag eines Objekts verweist. Wird intern von der Implementierung von ReadObject. Nur für die erweiterte Programmierung verfügbar gemacht; pObTag sollte normalerweise sein NULL.

Rückgabewert

Ein Zeiger auf die CRuntimeClass Struktur.

Hinweise

Falls pClassRefRequested nicht NULL, überprüft, ReadClass ob die archivierten Klasseninformationen mit Ihrer Laufzeitklasse kompatibel sind. Wenn sie nicht kompatibel ist, ReadClass wird ein CArchiveException.

Ihre Laufzeitklasse muss und DECLARE_SERIAL IMPLEMENT_SERIAL; andernfalls ReadClass wird ein CNotSupportedException.

Wenn pSchema jaNULL, *pSchema kann das Schema der gespeicherten Klasse durch Aufrufen CArchive::GetObjectSchemaabgerufen werden. Andernfalls enthält das Schema der zuvor gespeicherten Laufzeitklasse.

Sie können SerializeClass anstelle von ReadClass", die sowohl das Lesen als auch das Schreiben des Klassenverweises behandelt.

Beispiel

Ein Beispiel hierfür finden Sie unter CArchive::WriteClass.

CArchive::ReadObject

Liest Objektdaten aus dem Archiv und erstellt ein Objekt des entsprechenden Typs.

CObject* ReadObject(const CRuntimeClass* pClass);

Parameter

pClass
Ein konstanter Zeiger auf die Struktur, die CRuntimeClass dem Objekt entspricht, das Sie lesen möchten.

Rückgabewert

Ein CObject Zeiger, der sicher in die richtige abgeleitete Klasse umgewandelt werden muss.CObject::IsKindOf

Hinweise

Diese Funktion wird normalerweise von dem Extraktionsoperator ( >>) aufgerufen, der CArchive für einen CObject Zeiger überladen ist. ReadObjectwiederum ruft die Serialize Funktion der archivierten Klasse auf.

Wenn Sie einen Nonzero-Parameter pClass angeben, der RUNTIME_CLASS vom Makro abgerufen wird, überprüft die Funktion die Laufzeitklasse des archivierten Objekts. Dabei wird davon ausgegangen, dass Sie das IMPLEMENT_SERIAL Makro in der Implementierung der Klasse verwendet haben.

Beispiel

Ein Beispiel hierfür finden Sie unter CArchive::WriteObject.

CArchive::ReadString

Rufen Sie diese Memberfunktion auf, um Textdaten in einen Puffer aus der Datei zu lesen, die dem CArchive Objekt zugeordnet ist.

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

Parameter

rString
Ein Verweis auf eine CString , die die resultierende Zeichenfolge enthält, nachdem sie aus der Datei gelesen wurde, die dem CArchive Objekt zugeordnet ist.

lpsz
Gibt einen Zeiger auf einen vom Benutzer bereitgestellten Puffer an, der eine mit Null beendete Textzeichenfolge empfängt.

nMax
Gibt die maximale Anzahl der zu lesenden Zeichen an. Sollte ein Kleiner als die Größe des lpsz Puffers sein.

Rückgabewert

In der Version, die BOOL zurückgibt, TRUE wenn dies erfolgreich ist; FALSE andernfalls.

In der Version, die einen LPTSTRZeiger auf den Puffer zurückgibt, der die Textdaten enthält; NULL wenn das Ende der Datei erreicht wurde.

Hinweise

In der Version der Memberfunktion mit dem nMax Parameter hält der Puffer bis zu einem Grenzwert von nMax - 1 Zeichen. Das Lesen wird durch ein Wagenrückleitungsvorschubpaar beendet. Nachfolgende Neuzeilenzeichen werden immer entfernt. Ein NULL Zeichen ('\0') wird in beiden Fällen angefügt.

CArchive::Read ist auch für Textmoduseingaben verfügbar, wird jedoch nicht bei einem Wagenrücklauf-Zeilenvorschubpaar beendet.

Beispiel

Ein Beispiel hierfür finden Sie unter CArchive::WriteString.

CArchive::SerializeClass

Rufen Sie diese Memberfunktion auf, wenn Sie die Versionsinformationen einer Basisklasse speichern und laden möchten.

void SerializeClass(const CRuntimeClass* pClassRef);

Parameter

pClassRef
Ein Zeiger auf ein Laufzeitklassenobjekt für die Basisklasse.

Hinweise

SerializeClass liest oder schreibt den Verweis auf eine Klasse in das CArchive Objekt, abhängig von der Richtung der CArchive. Verwenden Sie SerializeClass anstelle und WriteClass als bequeme Möglichkeit zum Serialisieren von ReadClass Basisklassenobjekten; SerializeClass erfordert weniger Code und weniger Parameter.

Überprüft wie ReadClass, SerializeClass ob die archivierten Klasseninformationen mit Ihrer Laufzeitklasse kompatibel sind. Wenn sie nicht kompatibel ist, SerializeClass wird ein CArchiveException.

Ihre Laufzeitklasse muss und DECLARE_SERIAL IMPLEMENT_SERIAL; andernfalls SerializeClass wird ein CNotSupportedException.

Verwenden Sie das RUNTIME_CLASS Makro, um den Wert für den pRuntimeClass Parameter abzurufen. Die Basisklasse muss das IMPLEMENT_SERIAL Makro verwendet haben.

Beispiel

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

Rufen Sie auf SetLoadParams , wenn Sie eine große Anzahl von CObjectabgeleiteten Objekten aus einem Archiv lesen möchten.

void SetLoadParams(UINT nGrowBy = 1024);

Parameter

nGrowBy
Die Mindestanzahl der Elementplätze, die zugewiesen werden sollen, wenn eine Größenerhöhung erforderlich ist.

Hinweise

CArchive verwendet ein Ladearray, um Verweise auf objekte aufzulösen, die im Archiv gespeichert sind. SetLoadParams ermöglicht es Ihnen, die Größe festzulegen, auf die das Ladearray wächst.

Sie dürfen nicht aufrufen SetLoadParams , nachdem ein Objekt geladen oder aufgerufen MapObject ReadObject wurde.

Beispiel

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

Rufen Sie diese Memberfunktion auf, um das im Archivobjekt gespeicherte Objektschema auf festzulegen nSchema.

void SetObjectSchema(UINT nSchema);

Parameter

nSchema
Gibt das Schema des Objekts an.

Hinweise

Der nächste Aufruf gibt GetObjectSchema den in nSchema.

Wird für die erweiterte Versionsverwaltung verwendet SetObjectSchema , z. B. wenn Sie erzwingen möchten, dass eine bestimmte Version in einer Serialize Funktion einer abgeleiteten Klasse gelesen wird.

Beispiel

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

CArchive::SetStoreParams

Wird beim Speichern einer großen Anzahl von CObjectabgeleiteten Objekten in einem Archiv verwendetSetStoreParams.

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

Parameter

nHashSize
Die Größe der Hashtabelle für Schnittstellenzeigerzuordnungen. Sollte eine Primzahl sein.

nBlockSize
Gibt die Granularität der Speicherzuweisung für die Erweiterung der Parameter an. Sollte eine Leistung von 2 sein, um die beste Leistung zu erzielen.

Hinweise

SetStoreParams ermöglicht es Ihnen, die Größe der Hashtabelle und die Blockgröße der Karte festzulegen, die zum Identifizieren eindeutiger Objekte während des Serialisierungsprozesses verwendet wird.

Sie dürfen nicht aufrufen SetStoreParams , nachdem Objekte gespeichert oder aufgerufen MapObject WriteObject wurden.

Beispiel

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

Schreibt eine angegebene Anzahl von Bytes in das Archiv.

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

Parameter

lpBuf
Ein Zeiger auf einen vom Benutzer bereitgestellten Puffer, der die daten enthält, die in das Archiv geschrieben werden sollen.

nMax
Eine ganze Zahl, die die Anzahl der Bytes angibt, die in das Archiv geschrieben werden sollen.

Hinweise

Das Archiv formatiert die Bytes nicht.

Sie können die Write Memberfunktion in Ihrer Serialize Funktion verwenden, um gewöhnliche Strukturen zu schreiben, die in Ihren Objekten enthalten sind.

Beispiel

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

CArchive::WriteClass

Wird verwendet WriteClass , um die Versions- und Klasseninformationen einer Basisklasse während der Serialisierung der abgeleiteten Klasse zu speichern.

void WriteClass(const CRuntimeClass* pClassRef);

Parameter

pClassRef
Ein Zeiger auf die Struktur, die CRuntimeClass dem angeforderten Klassenverweis entspricht.

Hinweise

WriteClass schreibt einen Verweis auf die CRuntimeClass Basisklasse in die CArchive. Dient CArchive::ReadClass zum Abrufen des Verweises.

WriteClass Überprüft, ob die archivierten Klasseninformationen mit Ihrer Laufzeitklasse kompatibel sind. Wenn sie nicht kompatibel ist, WriteClass wird ein CArchiveException.

Ihre Laufzeitklasse muss und DECLARE_SERIAL IMPLEMENT_SERIAL; andernfalls WriteClass wird ein CNotSupportedException.

Sie können SerializeClass anstelle von WriteClass", die sowohl das Lesen als auch das Schreiben des Klassenverweises behandelt.

Beispiel

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

Speichert das angegebene CObject Objekt im Archiv.

void WriteObject(const CObject* pOb);

Parameter

pOb
Ein konstanter Zeiger auf das objekt, das gespeichert wird.

Hinweise

Diese Funktion wird normalerweise durch den einfüge ( <<) Operator aufgerufen, der CArchive überladen istCObject. WriteObjectwiederum ruft die Serialize Funktion der archivierten Klasse auf.

Sie müssen das Makro verwenden, um die IMPLEMENT_SERIAL Archivierung zu aktivieren. WriteObject schreibt den ASCII-Klassennamen in das Archiv. Dieser Klassenname wird später während des Ladevorgangs überprüft. Ein spezielles Codierungsschema verhindert unnötige Duplizierung des Klassennamens für mehrere Objekte der Klasse. Dieses Schema verhindert auch den redundanten Speicher von Objekten, die auf mehrere Zeiger ausgerichtet sind.

Die genaue Objektcodierungsmethode (einschließlich des Vorhandenseins des ASCII-Klassennamens) ist ein Implementierungsdetail und kann sich in zukünftigen Versionen der Bibliothek ändern.

Hinweis

Beenden Sie das Erstellen, Löschen und Aktualisieren aller Objekte, bevor Sie mit der Archivierung beginnen. Ihr Archiv wird beschädigt, wenn Sie die Archivierung mit Objektänderungen kombinieren.

Beispiel

Eine Definition der Klasse CAgefinden Sie im Beispiel für 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

Verwenden Sie diese Memberfunktion, um Daten aus einem Puffer in die dem CArchive Objekt zugeordnete Datei zu schreiben.

void WriteString(LPCTSTR lpsz);

Parameter

lpsz
Gibt einen Zeiger auf einen Puffer an, der eine mit Null beendete Textzeichenfolge enthält.

Hinweise

Das beendende Nullzeichen ('\0') wird nicht in die Datei geschrieben; es ist auch nicht automatisch eine Neuzeile geschrieben.

WriteString löst eine Ausnahme als Reaktion auf mehrere Bedingungen aus, einschließlich der Datenträger-Vollbedingung.

Write ist auch verfügbar, aber anstatt auf einem NULL-Zeichen zu beenden, schreibt es die angeforderte Anzahl von Bytes in die Datei.

Beispiel

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

Siehe auch

Hierarchiediagramm
CFile Klasse
CObject Klasse
CSocket Klasse
CSocketFile Klasse