CArchive-Klasse

Ermöglicht es Ihnen, ein komplexes Netzwerk von Objekten in einer permanenten binären Form (in der Regel Datenträgerspeicher) zu speichern, die nach dem Löschen dieser Objekte beibehalten wird.

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	Leert ungeschriebene Daten und trennt die Verbindung mit .CFile
CArchive::Flush	Leert 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-Empfangsprozesses 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, aber für Unterobjekte verfügbar sind, auf die verwiesen werden kann.
CArchive::Read	Liest unformatierte Bytes.
CArchive::ReadClass	Liest einen Klassenverweis, der zuvor mit WriteClassgespeichert wurde.
CArchive::ReadObject	Ruft die Funktion eines Objekts Serialize zum Laden auf.
CArchive::ReadString	Liest eine einzelne Textzeile.
CArchive::SerializeClass	Liest oder schreibt den Klassenverweis abhängig von der CArchive Richtung des auf das CArchive-Objekt.
CArchive::SetLoadParams	Legt die Größe fest, auf die das Ladearray vergrößert wird. Muss aufgerufen werden, bevor ein Objekt geladen wird oder bevor 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 Zuordnung fest, die zum Identifizieren eindeutiger Objekte während des Serialisierungsprozesses verwendet wird.
CArchive::Write	Schreibt unformatierte Bytes.
CArchive::WriteClass	Schreibt einen Verweis auf den CRuntimeClass in den 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 primitive Typen im Archiv.
CArchive::operator >>	Lädt Objekte und primitive Typen aus dem Archiv.

Öffentliche Datenmember

Name	BESCHREIBUNG
CArchive::m_pDocument

Bemerkungen

CArchive verfügt nicht über eine Basisklasse.

Später können Sie die Objekte aus dem persistenten Speicher laden und im Arbeitsspeicher zuordnen. Dieser Vorgang zum Dauerhaften von Daten wird als "Serialisierung" bezeichnet.

Sie können sich ein Archivobjekt als eine Art binären Datenstrom vorstellen. Wie ein Eingabe-/Ausgabestream wird ein Archiv einer Datei zugeordnet und ermöglicht das gepufferte Schreiben und Lesen von Daten in und aus dem Speicher. Ein Eingabe-/Ausgabestream verarbeitet Sequenzen von ASCII-Zeichen, aber ein Archiv verarbeitet binäre Objektdaten in einem effizienten, nicht überdundanten 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öffnet-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 einer abgeleiteten 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 verarbeiten, sondern auch Objekte von von CObjectabgeleiteten Klassen, die für die Serialisierung entwickelt wurden. Eine serialisierbare Klasse verfügt normalerweise über eine Serialize Memberfunktion und verwendet normalerweise die DECLARE_SERIAL Makros und IMPLEMENT_SERIAL , wie unter Klasse CObjectbeschrieben.

Die überladenen Extraktions- und >>Einfügeoperatoren ( <<) sind praktische Archivprogrammierschnittstellen, die sowohl primitive Typen CObjectals auch von abgeleitete Klassen unterstützen.

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

Weitere Informationen zu 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 auszu auslösen.

void Abort ();

Hinweise

Der CArchive Destruktor ruft normalerweise auf Close, wodurch alle Daten geleert werden, die nicht im zugeordneten CFile Objekt gespeichert wurden. Dies kann Ausnahmen verursachen.

Beim Abfangen dieser Ausnahmen empfiehlt es sich, zu verwenden Abort, damit die Destruktion des CArchive Objekts keine weiteren Ausnahmen verursacht. Bei der Behandlung von Ausnahmen CArchive::Abort löst keine Ausnahme bei Fehlern aus, da im Gegensatz zu CArchive::Closefehler Abort ignoriert.

Wenn Sie das Objekt auf dem CArchive Heap zugeordnet habennew, müssen Sie es nach dem Schließen der Datei löschen.

Beispiel

Weitere Informationen finden Sie im Beispiel für 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 endgültige Quelle oder das endgültige Ziel der persistenten Daten ist.

nMode
Ein Flag, das angibt, ob Objekte aus dem Archiv geladen oder in das Archiv gespeichert werden. 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 die CFile Schreibberechtigung.

• CArchive::bNoFlushOnDelete Verhindert, dass das Archiv automatisch aufruft Flush , wenn der Archivdetruktor aufgerufen wird. Wenn Sie dieses Flag festlegen, müssen Sie explizit aufrufen Close , bevor der Destruktor aufgerufen wird. Wenn sie dies nicht tun, sind Ihre Daten beschädigt.

nBufSize
Eine ganze Zahl, die die Größe des internen Dateipuffers in Bytes angibt. Beachten Sie, dass die Standardpuffergröße 4.096 Bytes beträgt. Wenn Sie routinemäßig große Objekte archivieren, 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, ordnet das Archiv einen Puffer aus dem 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 mehr ändern, nachdem Sie das Archiv erstellt haben.

Sie dürfen keine Vorgänge verwenden CFile , um den Zustand der Datei zu ändern, bis Sie das Archiv geschlossen haben. Ein solcher Vorgang beschädigt die Integrität des Archivs. Sie können während der Serialisierung jederzeit auf die Position des Dateizeigers zugreifen, indem Sie das Dateiobjekt des Archivs von der GetFile Memberfunktion abrufen und dann die CFile::GetPosition -Funktion verwenden. Sie sollten aufrufen CArchive::Flush , bevor Sie die Position des Dateizeigers abrufen.

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

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

void Close();

Hinweise

Weitere Vorgänge im Archiv sind nicht 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 macht das Archiv nicht verfügbar. Um die Übertragung von der Datei auf das Speichermedium abschließen zu können, CFile::Close müssen Sie zuerst verwenden und dann das Objekt CFile zerstören.

Beispiel

Weitere Informationen finden Sie im Beispiel für CArchive::WriteString.

CArchive::Flush

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

void Flush();

Hinweise

Die Memberfunktion stellt Flush 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 abschließen zu können.

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 Objektzeiger CFile für dieses Archiv ab.

CFile* GetFile() const;

Rückgabewert

Ein konstanter Zeiger auf das objekt CFile , das verwendet wird.

Hinweise

Sie müssen das Archiv leeren, bevor Sie verwenden GetFile.

Beispiel

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Rufen Sie diese Funktion aus der -Funktion Serialize auf, um die Version des Objekts zu bestimmen, das gerade deserialisiert wird.

UINT GetObjectSchema();

Rückgabewert

Während der Deserialisierung die Version des objekts, das gelesen wird.

Hinweise

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

CObjectEine von abgeleitete VERSIONABLE_SCHEMA Klasse kann kombiniert (mit bitweisem "or" (|)) mit der Schemaversion selbst (im IMPLEMENT_SERIAL Makro) verwenden, um ein "versionsfähiges Objekt" zu erstellen, d. h. ein Objekt, Serialize dessen Memberfunktion mehrere Versionen lesen kann. Die Standardframeworkfunktionalität (ohne VERSIONABLE_SCHEMA) besteht im Auslösen einer Ausnahme, 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

Ungleich 0 (null), wenn der Puffer des Archivs leer ist; andernfalls 0.

Hinweise

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

Der Grund für die Verwendung von IsBufferEmpty mit einem Einem CSocketFile -Objekt zugeordneten Archiv ist, dass der Puffer des Archivs möglicherweise mehr als eine Nachricht oder einen Datensatz enthält. Nach dem Empfang einer Nachricht sollten Sie verwenden IsBufferEmpty , um eine Schleife zu steuern, die weiterhin Daten empfängt, bis der Puffer leer ist. Weitere Informationen finden Sie in der Memberfunktion Receive der -Klasse CAsyncSocket, in der die Verwendung von veranschaulicht wird IsBufferEmpty.

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

Ungleich 0 (null), wenn das Archiv derzeit zum Laden verwendet wird. andernfalls 0.

Hinweise

Diese Memberfunktion wird von den Funktionen Serialize 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

Ungleich 0 (null), wenn das Archiv derzeit zum Speichern verwendet wird. andernfalls 0.

Hinweise

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

Wenn der IsStoring Status eines Archivs ungleich 0 (null) ist, IsLoading ist der 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 in die Datei 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 zu speichernde Objekt.

Hinweise

Beispielsweise können Sie ein Dokument nicht serialisieren, aber Sie würden die Elemente serialisieren, die Teil des Dokuments sind. Durch Aufrufen von MapObjectermöglichen Sie diesen Elementen oder Unterobjekten, auf das Dokument zu verweisen. Außerdem können serialisierte Unteritems ihren Rückzeiger m_pDocument serialisieren.

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

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

Standardmäßig auf NULL festgelegt, kann dieser Zeiger auf CDocument einen auf einen festgelegt werden, der vom Benutzer der Instanz verwendet CArchive werden soll.

CDocument* m_pDocument;

Hinweise

Dieser Zeiger wird häufig verwendet, um zusätzliche Informationen über den Serialisierungsprozess an alle zu serialisierten Objekte zu übermitteln. Dies wird erreicht, indem der Zeiger mit dem zu serialisierenden Dokument ( CDocumenteiner von abgeleiteten Klasse) so initialisiert wird, dass Objekte im Dokument bei Bedarf auf das Dokument zugreifen können. Dieser Zeiger wird auch von -Objekten während COleClientItem der Serialisierung verwendet.

Das Framework legt auf m_pDocument das Zu serialisierte Dokument fest, wenn ein Benutzer einen Datei öffnen- oder Speichern-Befehl aus gibt. 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 letzten beiden oben genannten Versionen sind speziell für das Speichern von 64-Bit-Ganzzahlen.

Wenn Sie das Makro in der IMPLEMENT_SERIAL Klassenimplementierung verwendet haben, ruft der für CObject überladene Einfügeoperator den geschützten auf WriteObject. Diese Funktion ruft wiederum die -Funktion Serialize der -Klasse auf.

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

Beispiele

In diesem Beispiel wird die Verwendung des Einfügeoperator CArchive mit << den Typen und intlong veranschaulicht.

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

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

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

CArchive::operator >>

Lädt das angegebene Objekt oder den primitiven Typ 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 oben genannten Versionen sind speziell für das Laden von 64-Bit-Ganzzahlen.

Wenn Sie das Makro IMPLEMENT_SERIAL in Ihrer Klassenimplementierung verwendet haben, CObjectReadObject rufen die extraktionsoperatoren, die für den Aufruf der geschützten Funktion überladen sind (mit einem Laufzeitklassenzeiger ungleich 0( ) auf. Diese Funktion ruft wiederum die -Funktion Serialize der -Klasse auf.

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

Beispiele

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

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

In diesem Beispiel wird die Verwendung der Einfüge- CArchive und Extraktionsoperatoren << und mit >> dem -Typ CStringT 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 empfangen soll.

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

Rückgabewert

Eine ganze Zahl ohne Vorzeichen, 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 WriteClassgespeichert wurde.

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

Parameter

pClassRefRequested
Ein Zeiger auf die CRuntimeClass -Struktur, die 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 ReadObjectverwendet. Nur für erweiterte Programmierung verfügbar gemacht; pObTag sollte normalerweise sein NULL.

Rückgabewert

Ein Zeiger auf die CRuntimeClass -Struktur.

Hinweise

Wenn pClassRefRequested nicht NULList, ReadClass wird überprüft, ob die archivierten Klasseninformationen mit Ihrer Laufzeitklasse kompatibel sind. Wenn sie nicht kompatibel ist, ReadClass löst eine CArchiveExceptionaus.

Ihre Laufzeitklasse muss und IMPLEMENT_SERIALverwendenDECLARE_SERIAL. ReadClass Andernfalls löst eine CNotSupportedExceptionaus.

Wenn pSchema ist NULL, kann das Schema der gespeicherten Klasse durch Aufrufen CArchive::GetObjectSchemavon abgerufen werden. *pSchema Andernfalls enthält das Schema der zuvor gespeicherten Laufzeitklasse.

Sie können anstelle von ReadClassverwendenSerializeClass, das sowohl das Lesen als auch das Schreiben des Klassenverweis verarbeitet.

Beispiel

Weitere Informationen finden Sie im Beispiel für 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 CRuntimeClass -Struktur, die dem Objekt entspricht, das Sie lesen möchten.

Rückgabewert

Ein CObject Zeiger, der mithilfe CObject::IsKindOfvon sicher in die richtige abgeleitete Klasse umgeleitet werden muss.

Hinweise

Diese Funktion wird normalerweise vom Extraktionsoperator ( >>) aufgerufen, der CArchive für einen CObject Zeiger überladen ist. ReadObjectruft wiederum die Serialize Funktion der archivierten Klasse auf.

Wenn Sie einen Parameter ungleich 0 (null pClass ) angeben, der RUNTIME_CLASS vom Makro abgerufen wird, überprüft die Funktion die Laufzeitklasse des archivierten Objekts. Dies setzt voraus, dass Sie das IMPLEMENT_SERIAL Makro in der Implementierung der -Klasse verwendet haben.

Beispiel

Weitere Informationen finden Sie im Beispiel für CArchive::WriteObject.

CArchive::ReadString

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

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 auf NULL endende 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, falls erfolgreich, TRUEFALSE andernfalls .

In der Version, die zurückgibt, LPTSTRein Zeiger auf den Puffer, der die Textdaten enthält, NULL , wenn das Dateiende erreicht wurde.

Hinweise

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

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

Beispiel

Weitere Informationen finden Sie im Beispiel für 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 abhängig von der CArchive Richtung des in das CArchive-Objekt. Verwenden Sie SerializeClass anstelle von und WriteClass als praktische Möglichkeit zum Serialisieren von ReadClass Basisklassenobjekten; SerializeClass erfordert weniger Code und weniger Parameter.

Wie ReadClassüberprüft , SerializeClass ob die archivierten Klasseninformationen mit Ihrer Laufzeitklasse kompatibel sind. Wenn sie nicht kompatibel ist, SerializeClass löst eine CArchiveExceptionaus.

Ihre Laufzeitklasse muss und IMPLEMENT_SERIALverwendenDECLARE_SERIAL. SerializeClass Andernfalls löst eine CNotSupportedExceptionaus.

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 von CObjectabgeleiteten Objekten aus einem Archiv lesen möchten.

void SetLoadParams(UINT nGrowBy = 1024);

Parameter

nGrowBy
Die Mindestanzahl von Elementslots, die zugeordnet werden sollen, wenn eine Größenerhöhung erforderlich ist.

Hinweise

CArchive verwendet ein Ladearray, um Verweise auf im Archiv gespeicherte Objekte aufzulösen. 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 wurde, oder nachdem MapObject oder ReadObject aufgerufen 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 nSchemafestzulegen.

void SetObjectSchema(UINT nSchema);

Parameter

nSchema
Gibt das Schema des Objekts an.

Hinweise

Der nächste Aufruf von GetObjectSchema gibt den in nSchemagespeicherten Wert zurück.

Verwenden Sie SetObjectSchema für die erweiterte Versionierung, 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

Verwenden Sie SetStoreParams , wenn eine große Anzahl von von abgeleiteten CObjectObjekten in einem Archiv gespeichert wird.

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 Speicherbelegung zum Erweitern der Parameter an. Sollte eine Potenz 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 Zuordnung festzulegen, die verwendet wird, um eindeutige Objekte während des Serialisierungsprozesses zu identifizieren.

Sie dürfen nicht aufrufen SetStoreParams , nachdem Objekte gespeichert wurden, oder nachdem MapObject oder WriteObject aufgerufen 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::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 in das Archiv zu schreibenden Daten enthält.

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

Verwenden Sie 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 CRuntimeClass -Struktur, die dem angeforderten Klassenverweis entspricht.

Hinweise

WriteClass schreibt einen Verweis auf die CRuntimeClass für die Basisklasse in die CArchive. Verwenden Sie CArchive::ReadClass , um den Verweis abzurufen.

WriteClass überprüft, ob die archivierten Klasseninformationen mit Ihrer Laufzeitklasse kompatibel sind. Wenn sie nicht kompatibel ist, WriteClass löst eine CArchiveExceptionaus.

Ihre Laufzeitklasse muss und IMPLEMENT_SERIALverwendenDECLARE_SERIAL. WriteClass Andernfalls löst eine CNotSupportedExceptionaus.

Sie können anstelle von WriteClassverwendenSerializeClass, das sowohl das Lesen als auch das Schreiben des Klassenverweis verarbeitet.

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 den angegebenen CObject im Archiv.

void WriteObject(const CObject* pOb);

Parameter

pOb
Ein konstanter Zeiger auf das gespeicherte Objekt.

Hinweise

Diese Funktion wird normalerweise vom Einfügeoperator ( <<) aufgerufen, der CArchive für CObjectüberladen ist. WriteObjectruft wiederum 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 die redundante Speicherung von Objekten, die Ziele mehrerer Zeiger 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 ist beschädigt, wenn Sie die Archivierung mit der Objektänderung 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 Datei zu schreiben, die dem -Objekt zugeordnet ist CArchive .

void WriteString(LPCTSTR lpsz);

Parameter

lpsz
Gibt einen Zeiger auf einen Puffer an, der eine auf NULL endende Textzeichenfolge enthält.

Hinweise

Das abschließende NULL-Zeichen ("\0") wird nicht in die Datei geschrieben. noch wird automatisch eine Neueinleitung geschrieben.

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

Write ist auch verfügbar, aber anstatt ein 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);

Weitere Informationen

Hierarchiediagramm
CFile Klasse
CObject Klasse
CSocket Klasse
CSocketFile Klasse