Classe `CArchive`

Articolo
10/12/2023

Consente di salvare una rete complessa di oggetti in un formato binario permanente (in genere l'archiviazione su disco) che persiste dopo l'eliminazione di tali oggetti.

Sintassi

class CArchive

Membri

Costruttori pubblici

Nome	Descrizione
`CArchive::CArchive`	Crea un oggetto `CArchive`.

Metodi pubblici

Nome	Descrizione
`CArchive::Abort`	Chiude un archivio senza generare un'eccezione.
`CArchive::Close`	Scarica i dati non scritti e si disconnette da `CFile`.
`CArchive::Flush`	Scarica i dati non scritti dal buffer di archiviazione.
`CArchive::GetFile`	Ottiene il puntatore all'oggetto per l'archivio `CFile` .
`CArchive::GetObjectSchema`	Chiamato dalla `Serialize` funzione per determinare la versione dell'oggetto da deserializzare.
`CArchive::IsBufferEmpty`	Determina se il buffer è stato svuotato durante un processo di ricezione di Windows Sockets.
`CArchive::IsLoading`	Determina se l'archivio è in fase di caricamento.
`CArchive::IsStoring`	Determina se l'archivio viene archiviato.
`CArchive::MapObject`	Inserisce gli oggetti nella mappa che non vengono serializzati nel file, ma disponibili per i sottooggetti a cui fare riferimento.
`CArchive::Read`	Legge i byte non elaborati.
`CArchive::ReadClass`	Legge un riferimento di classe archiviato in precedenza con `WriteClass`.
`CArchive::ReadObject`	Chiama la funzione di `Serialize` un oggetto per il caricamento.
`CArchive::ReadString`	Legge una singola riga di testo.
`CArchive::SerializeClass`	Legge o scrive il riferimento della classe all'oggetto `CArchive` a seconda della direzione dell'oggetto `CArchive`.
`CArchive::SetLoadParams`	Imposta le dimensioni in base alle quali aumenta la matrice di carico. Deve essere chiamato prima che venga caricato qualsiasi oggetto o prima `MapObject` o `ReadObject` venga chiamato .
`CArchive::SetObjectSchema`	Imposta lo schema dell'oggetto archiviato nell'oggetto archivio.
`CArchive::SetStoreParams`	Imposta le dimensioni della tabella hash e le dimensioni del blocco della mappa utilizzate per identificare oggetti univoci durante il processo di serializzazione.
`CArchive::Write`	Scrive byte non elaborati.
`CArchive::WriteClass`	Scrive un riferimento all'oggetto `CRuntimeClass` nell'oggetto `CArchive`.
`CArchive::WriteObject`	Chiama la funzione di `Serialize` un oggetto per l'archiviazione.
`CArchive::WriteString`	Scrive una singola riga di testo.

Operatori pubblici

Nome	Descrizione
`CArchive::operator <<`	Archivia oggetti e tipi primitivi nell'archivio.
`CArchive::operator >>`	Carica oggetti e tipi primitivi dall'archivio.

Membri dati pubblici

Nome	Descrizione
`CArchive::m_pDocument`

Note

CArchive non dispone di una classe di base.

Successivamente è possibile caricare gli oggetti dall'archiviazione permanente, ricostituendoli in memoria. Questo processo di rendere persistenti i dati è denominato "serializzazione".

È possibile considerare un oggetto archivio come un tipo di flusso binario. Come un flusso di input/output, un archivio è associato a un file e consente la scrittura e la lettura dei dati memorizzati nel buffer da e verso l'archiviazione. Un flusso di input/output elabora sequenze di caratteri ASCII, ma un archivio elabora i dati degli oggetti binari in un formato efficiente e nonundante.

È necessario creare un CFile oggetto prima di poter creare un CArchive oggetto . Inoltre, è necessario assicurarsi che lo stato di caricamento/archivio dell'archivio sia compatibile con la modalità aperta del file. Si è limitati a un archivio attivo per ogni file.

Quando si costruisce un CArchive oggetto, lo si collega a un oggetto di classe (o una classe CFile derivata) che rappresenta un file aperto. Specificare anche se l'archivio verrà usato per il caricamento o l'archiviazione. Un CArchive oggetto può elaborare non solo tipi primitivi, ma anche oggetti di CObjectclassi derivate da progettate per la serializzazione. Una classe serializzabile ha in genere una Serialize funzione membro e in genere usa le DECLARE_SERIAL macro e IMPLEMENT_SERIAL , come descritto nella classe CObject.

Gli operatori di estrazione di overload ( >>) e di inserimento ( <<) sono interfacce di programmazione di archivio utili che supportano sia i tipi CObjectprimitivi che le classi derivate da .

CArchive supporta anche la programmazione con le classi CSocket MFC Windows Sockets e CSocketFile. La IsBufferEmpty funzione membro supporta tale utilizzo.

Per altre informazioni su CArchive, vedere gli articoli Serializzazione e Windows Sockets: Uso di socket con archivi.

Gerarchia di ereditarietà

CArchive

Requisiti

Intestazione: afx.h

`CArchive::Abort`

Chiamare questa funzione per chiudere l'archivio senza generare un'eccezione.

void Abort ();

Osservazioni:

Il CArchive distruttore chiamerà Closein genere , che scarica tutti i dati che non sono stati salvati nell'oggetto associato CFile . Ciò può causare eccezioni.

Quando si rilevano queste eccezioni, è consigliabile usare Abort, in modo che la decostruzione dell'oggetto CArchive non causi ulteriori eccezioni. Quando si gestiscono le eccezioni, CArchive::Abort non genererà un'eccezione in caso di errori perché, a differenza CArchive::Closedi , Abort ignora gli errori.

Se è stato usato new per allocare l'oggetto nell'heap CArchive , è necessario eliminarlo dopo la chiusura del file.

Esempio

Vedere l'esempio per CArchive::WriteClass.

`CArchive::CArchive`

Costruisce un CArchive oggetto e specifica se verrà utilizzato per il caricamento o l'archiviazione di oggetti.

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

Parametri

pFile
Puntatore all'oggetto che rappresenta l'origine CFile o la destinazione finale dei dati persistenti.

nMode
Flag che specifica se gli oggetti verranno caricati da o archiviati nell'archivio. Il nMode parametro deve avere uno dei valori seguenti:

CArchive::load Carica i dati dall'archivio. Richiede solo CFile l'autorizzazione di lettura.
CArchive::store Salva i dati nell'archivio. Richiede CFile l'autorizzazione di scrittura.
CArchive::bNoFlushOnDelete Impedisce all'archivio di chiamare Flush automaticamente quando viene chiamato il distruttore di archivio. Se si imposta questo flag, è necessario chiamare Close in modo esplicito prima che venga chiamato il distruttore. In caso contrario, i dati verranno danneggiati.

nBufSize
Intero che specifica le dimensioni del buffer interno del file, espresso in byte. Si noti che la dimensione predefinita del buffer è di 4.096 byte. Se si archivia regolarmente oggetti di grandi dimensioni, si miglioreranno le prestazioni se si usano dimensioni del buffer maggiori che sono multiple delle dimensioni del buffer del file.

lpBuf
Puntatore facoltativo a un buffer di dimensioni nBufSizefornito dall'utente. Se non si specifica questo parametro, l'archivio alloca un buffer dall'heap locale e lo libera quando l'oggetto viene eliminato definitivamente. L'archivio non libera un buffer fornito dall'utente.

Osservazioni:

Non è possibile modificare questa specifica dopo aver creato l'archivio.

Non è possibile utilizzare CFile operazioni per modificare lo stato del file fino a quando non si chiude l'archivio. Qualsiasi operazione di questo tipo danneggia l'integrità dell'archivio. È possibile accedere alla posizione del puntatore al file in qualsiasi momento durante la serializzazione ottenendo l'oggetto file dell'archivio dalla GetFile funzione membro e quindi usando la CFile::GetPosition funzione . È necessario chiamare CArchive::Flush prima di ottenere la posizione del puntatore al file.

Esempio

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`

Scarica tutti i dati rimanenti nel buffer, chiude l'archivio e disconnette l'archivio dal file.

void Close();

Osservazioni:

Non sono consentite ulteriori operazioni sull'archivio. Dopo aver chiuso un archivio, è possibile creare un altro archivio per lo stesso file oppure chiudere il file.

La funzione Close membro garantisce che tutti i dati vengano trasferiti dall'archivio al file e che l'archivio non sia disponibile. Per completare il trasferimento dal file al supporto di archiviazione, è prima necessario usare CFile::Close e quindi eliminare definitivamente l'oggetto CFile .

Esempio

Vedere l'esempio per CArchive::WriteString.

`CArchive::Flush`

Forza la scrittura di tutti i dati rimanenti nel buffer di archiviazione nel file.

void Flush();

Osservazioni:

La funzione Flush membro garantisce che tutti i dati vengano trasferiti dall'archivio al file. È necessario chiamare CFile::Close per completare il trasferimento dal file al supporto di archiviazione.

Esempio

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`

Ottiene il puntatore all'oggetto per l'archivio CFile .

CFile* GetFile() const;

Valore restituito

Puntatore costante all'oggetto CFile in uso.

Osservazioni:

È necessario scaricare l'archivio prima di usare GetFile.

Esempio

const CFile *fp = ar.GetFile();

`CArchive::GetObjectSchema`

Chiamare questa funzione dalla Serialize funzione per determinare la versione dell'oggetto in corso di deserializzazione.

UINT GetObjectSchema();

Valore restituito

Durante la deserializzazione, la versione dell'oggetto letto.

Osservazioni:

La chiamata a questa funzione è valida solo quando l'oggetto CArchive viene caricato ( CArchive::IsLoading restituisce diverso da zero). Deve essere la prima chiamata nella Serialize funzione e chiamata una sola volta. Un valore restituito di ( UINT)-1 indica che il numero di versione è sconosciuto.

Una CObjectclasse derivata da -può usare VERSIONABLE_SCHEMA combinata (usando "or" bit per bit (|)) con la versione dello schema stessa (nella IMPLEMENT_SERIAL macro) per creare un "oggetto con controllo delle versioni", ovvero un oggetto la cui Serialize funzione membro può leggere più versioni. La funzionalità del framework predefinita (senza VERSIONABLE_SCHEMA) consiste nel generare un'eccezione quando la versione non corrisponde.

Esempio

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`

Chiamare questa funzione membro per determinare se il buffer interno dell'oggetto archivio è vuoto.

BOOL IsBufferEmpty() const;

Valore restituito

Diverso da zero se il buffer dell'archivio è vuoto; in caso contrario, 0.

Osservazioni:

Questa funzione viene fornita per supportare la programmazione con la classe CSocketFileMFC Windows Sockets . Non è necessario usarlo per un archivio associato a un CFile oggetto .

Il motivo dell'uso IsBufferEmpty di con un archivio associato a un CSocketFile oggetto è che il buffer dell'archivio può contenere più di un messaggio o un record. Dopo aver ricevuto un messaggio, è consigliabile usare IsBufferEmpty per controllare un ciclo che continua a ricevere dati fino a quando il buffer non è vuoto. Per altre informazioni, vedere la Receive funzione membro della classe CAsyncSocket, che illustra come usare IsBufferEmpty.

Per altre informazioni, vedere Windows Sockets: Using Sockets with Archives .For more information, see Windows Sockets: Using Sockets with Archives.

`CArchive::IsLoading`

Determina se l'archivio sta caricando i dati.

BOOL IsLoading() const;

Valore restituito

Diverso da zero se l'archivio è attualmente in uso per il caricamento; in caso contrario, 0.

Osservazioni:

Questa funzione membro viene chiamata dalle Serialize funzioni delle classi archiviate.

Esempio

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

`CArchive::IsStoring`

Determina se l'archivio archivia i dati.

BOOL IsStoring() const;

Valore restituito

Diverso da zero se l'archivio è attualmente in uso per l'archiviazione; in caso contrario, 0.

Osservazioni:

Questa funzione membro viene chiamata dalle Serialize funzioni delle classi archiviate.

Se lo IsStoring stato di un archivio è diverso da zero, lo IsLoading stato è 0 e viceversa.

Esempio

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

`CArchive::MapObject`

Chiamare questa funzione membro per inserire gli oggetti nella mappa che non sono realmente serializzati nel file, ma disponibili per i sottooggetti a cui fare riferimento.

void MapObject(const CObject* pOb);

Parametri

pOb
Puntatore costante all'oggetto archiviato.

Osservazioni:

Ad esempio, è possibile non serializzare un documento, ma serializzare gli elementi che fanno parte del documento. MapObjectChiamando , è possibile consentire a tali elementi, o sottooggetti, di fare riferimento al documento. Inoltre, gli elementi secondari serializzati possono serializzare il puntatore m_pDocument indietro.

È possibile chiamare MapObject quando si archivia e si carica dall'oggetto CArchive . MapObject aggiunge l'oggetto specificato alle strutture di dati interne gestite dall'oggetto durante la CArchive serializzazione e la deserializzazione, ma a differenza ReadObject di e WriteObject, non chiama serializzare sull'oggetto .

Esempio

//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 Impostare su per impostazione predefinita, questo puntatore a un CDocument può essere impostato su qualsiasi elemento desiderato dall'utente dell'istanzaCArchive.

CDocument* m_pDocument;

Osservazioni:

Un uso comune di questo puntatore consiste nel trasmettere informazioni aggiuntive sul processo di serializzazione a tutti gli oggetti da serializzare. Questo risultato viene ottenuto inizializzando il puntatore con il documento (una CDocumentclasse derivata da ) che viene serializzato, in modo tale che gli oggetti all'interno del documento possano accedere al documento, se necessario. Questo puntatore viene usato anche dagli COleClientItem oggetti durante la serializzazione.

Il framework imposta m_pDocument il documento da serializzare quando un utente rilascia un comando Apri file o Salva. Se si serializza un documento contenitore OLE (Object Linking and Embedding) per motivi diversi da File Open o Save, è necessario impostare m_pDocumentin modo esplicito . Ad esempio, questa operazione viene eseguita durante la serializzazione di un documento contenitore negli Appunti.

Esempio

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

Archivia l'oggetto o il tipo primitivo indicato nell'archivio.

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

Valore restituito

Riferimento CArchive che abilita più operatori di inserimento su una singola riga.

Osservazioni:

Le ultime due versioni precedenti sono in particolare per l'archiviazione di interi a 64 bit.

Se è stata usata la macro nell'implementazione della IMPLEMENT_SERIAL classe, l'operatore di inserimento è stato sottoposto a overload per CObject chiamare l'oggetto protetto WriteObject. Questa funzione, a sua volta, chiama la Serialize funzione della classe .

L'operatore CStringT di inserimento (<<) supporta il dump diagnostico e l'archiviazione in un archivio.

Esempi

In questo esempio viene illustrato l'uso dell'operatore CArchive << di inserimento con i int tipi e long .

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

In questo esempio viene illustrato l'uso dell'operatore CArchive << di inserimento con il CStringT tipo .

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

`CArchive::operator >>`

Carica l'oggetto o il tipo primitivo indicato dall'archivio.

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

Valore restituito

Riferimento CArchive che abilita più operatori di estrazione su una singola riga.

Osservazioni:

Le ultime due versioni precedenti sono specificamente per il caricamento di interi a 64 bit.

Se è stata usata la IMPLEMENT_SERIAL macro nell'implementazione della classe, gli operatori di estrazione sono in overload per CObject chiamare la funzione protetta ReadObject (con un puntatore di classe di runtime diverso da zero). Questa funzione, a sua volta, chiama la Serialize funzione della classe .

L'operatore CStringT di estrazione (>>) supporta il caricamento da un archivio.

Esempi

In questo esempio viene illustrato l'uso dell'operatore CArchive >> di estrazione con il int tipo .

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

In questo esempio viene illustrato l'uso degli operatori << di CArchive inserimento ed estrazione e >> con il CStringT tipo .

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

`CArchive::Read`

Legge un numero specificato di byte dall'archivio.

UINT Read(void* lpBuf, UINT nMax);

Parametri

lpBuf
Puntatore a un buffer fornito dall'utente che deve ricevere i dati letti dall'archivio.

nMax
Intero senza segno che specifica il numero di byte da leggere dall'archivio.

Valore restituito

Intero senza segno contenente il numero di byte effettivamente letti. Se il valore restituito è minore del numero richiesto, è stata raggiunta la fine del file. Non viene generata alcuna eccezione nella condizione di fine del file.

Osservazioni:

L'archivio non interpreta i byte.

È possibile usare la funzione membro all'interno della Read Serialize funzione per leggere le strutture normali contenute negli oggetti.

Esempio

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

`CArchive::ReadClass`

Chiamare questa funzione membro per leggere un riferimento a una classe archiviata in precedenza con WriteClass.

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

Parametri

pClassRefRequested
Puntatore alla CRuntimeClass struttura che corrisponde al riferimento alla classe richiesta. Può essere NULL.

pSchema
Puntatore a uno schema della classe di runtime archiviata in precedenza.

pObTag
Numero che fa riferimento al tag univoco di un oggetto. Usato internamente dall'implementazione di ReadObject. Esposto solo per la programmazione avanzata; pObTag normalmente deve essere NULL.

Valore restituito

Puntatore alla CRuntimeClass struttura.

Osservazioni:

Se pClassRefRequested non NULLè , ReadClass verifica che le informazioni sulla classe archiviata siano compatibili con la classe di runtime. Se non è compatibile, ReadClass genererà un'eccezione CArchiveException.

La classe di runtime deve usare DECLARE_SERIAL e IMPLEMENT_SERIAL; in caso contrario, ReadClass genererà un'eccezione CNotSupportedException.

Se pSchema è NULL, lo schema della classe archiviata può essere recuperato chiamando CArchive::GetObjectSchema; in caso contrario, *pSchema conterrà lo schema della classe di runtime archiviata in precedenza.

È possibile usare SerializeClass invece di ReadClass, che gestisce sia la lettura che la scrittura del riferimento alla classe.

Esempio

Vedere l'esempio per CArchive::WriteClass.

`CArchive::ReadObject`

Legge i dati dell'oggetto dall'archivio e costruisce un oggetto del tipo appropriato.

CObject* ReadObject(const CRuntimeClass* pClass);

Parametri

pClass
Puntatore costante alla CRuntimeClass struttura che corrisponde all'oggetto che si prevede di leggere.

Valore restituito

Puntatore CObject che deve essere eseguito in modo sicuro per la classe derivata corretta tramite CObject::IsKindOf.

Osservazioni:

Questa funzione viene in genere chiamata dall'operatore CArchive di estrazione ( >>) sottoposto a overload per un CObject puntatore. ReadObject, a sua volta, chiama la Serialize funzione della classe archiviata.

Se si specifica un parametro diverso da zero, ottenuto pClass dalla RUNTIME_CLASS macro, la funzione verifica la classe di runtime dell'oggetto archiviato. Si presuppone che sia stata usata la IMPLEMENT_SERIAL macro nell'implementazione della classe .

Esempio

Vedere l'esempio per CArchive::WriteObject.

`CArchive::ReadString`

Chiamare questa funzione membro per leggere i dati di testo in un buffer dal file associato all'oggetto CArchive .

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

Parametri

rString
Riferimento a un CString oggetto che conterrà la stringa risultante dopo la lettura dal file associato all'oggetto CArchive .

lpsz
Specifica un puntatore a un buffer fornito dall'utente che riceverà una stringa di testo con terminazione Null.

nMax
Specifica il numero massimo di caratteri da leggere. Deve essere inferiore alla dimensione del lpsz buffer.

Valore restituito

Nella versione che restituisce BOOL, TRUE se ha esito positivo; FALSE in caso contrario, .

Nella versione che restituisce un puntatore LPTSTRal buffer contenente i dati di testo; NULL se è stata raggiunta la fine del file.

Osservazioni:

Nella versione della funzione membro con il nMax parametro , il buffer conterrà fino a un limite di nMax - 1 caratteri. La lettura viene arrestata da una coppia di avanzamenti ritorno a capo. I caratteri di nuova riga finali vengono sempre rimossi. In entrambi i casi viene aggiunto un NULL carattere ('\0').

CArchive::Read è disponibile anche per l'input in modalità testo, ma non termina in una coppia di avanzamento ritorno a capo.

Esempio

Vedere l'esempio per CArchive::WriteString.

`CArchive::SerializeClass`

Chiamare questa funzione membro quando si desidera archiviare e caricare le informazioni sulla versione di una classe di base.

void SerializeClass(const CRuntimeClass* pClassRef);

Parametri

pClassRef
Puntatore a un oggetto classe di runtime per la classe di base.

Osservazioni:

SerializeClass legge o scrive il riferimento a una classe nell'oggetto CArchive , a seconda della direzione dell'oggetto CArchive. Usare SerializeClass al posto di ReadClass e WriteClass come modo pratico per serializzare oggetti di classe base. SerializeClass Richiede meno codice e meno parametri.

Come ReadClass, SerializeClass verifica che le informazioni sulla classe archiviata siano compatibili con la classe di runtime. Se non è compatibile, SerializeClass genererà un'eccezione CArchiveException.

La classe di runtime deve usare DECLARE_SERIAL e IMPLEMENT_SERIAL; in caso contrario, SerializeClass genererà un'eccezione CNotSupportedException.

Utilizzare la RUNTIME_CLASS macro per recuperare il valore per il pRuntimeClass parametro . La classe di base deve avere utilizzato la IMPLEMENT_SERIAL macro.

Esempio

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`

Chiamare SetLoadParams quando si legge un numero elevato di CObjectoggetti derivati da un archivio.

void SetLoadParams(UINT nGrowBy = 1024);

Parametri

nGrowBy
Numero minimo di slot di elemento da allocare se è necessario un aumento delle dimensioni.

Osservazioni:

CArchive usa una matrice di carico per risolvere i riferimenti agli oggetti archiviati nell'archivio. SetLoadParams consente di impostare le dimensioni in base alle quali aumenta la matrice di carico.

Non è necessario chiamare SetLoadParams dopo il caricamento di qualsiasi oggetto o dopo MapObject o ReadObject viene chiamato .

Esempio

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`

Chiamare questa funzione membro per impostare lo schema dell'oggetto archiviato nell'oggetto archivio su nSchema.

void SetObjectSchema(UINT nSchema);

Parametri

nSchema
Specifica lo schema dell'oggetto.

Osservazioni:

La chiamata successiva a GetObjectSchema restituirà il valore archiviato in nSchema.

Usare SetObjectSchema per il controllo delle versioni avanzate, ad esempio quando si desidera forzare la lettura di una determinata versione in una Serialize funzione di una classe derivata.

Esempio

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

`CArchive::SetStoreParams`

Usare SetStoreParams quando si archivia un numero elevato di CObjectoggetti derivati da -in un archivio.

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

Parametri

nHashSize
Dimensioni della tabella hash per le mappe del puntatore dell'interfaccia. Deve essere un numero primo.

nBlockSize
Specifica la granularità di allocazione della memoria per estendere i parametri. Dovrebbe essere una potenza di 2 per ottenere prestazioni ottimali.

Osservazioni:

SetStoreParams consente di impostare le dimensioni della tabella hash e le dimensioni del blocco della mappa usate per identificare oggetti univoci durante il processo di serializzazione.

Non è necessario chiamare SetStoreParams dopo l'archiviazione di oggetti o dopo MapObject o WriteObject la chiamata.

Esempio

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`

Scrive un numero specificato di byte nell'archivio.

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

Parametri

lpBuf
Puntatore a un buffer fornito dall'utente che contiene i dati da scrivere nell'archivio.

nMax
Intero che specifica il numero di byte da scrivere nell'archivio.

Osservazioni:

L'archivio non formatta i byte.

È possibile usare la funzione membro all'interno della Write Serialize funzione per scrivere strutture normali contenute negli oggetti.

Esempio

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

`CArchive::WriteClass`

Usare WriteClass per archiviare le informazioni sulla versione e sulla classe di una classe di base durante la serializzazione della classe derivata.

void WriteClass(const CRuntimeClass* pClassRef);

Parametri

pClassRef
Puntatore alla CRuntimeClass struttura che corrisponde al riferimento alla classe richiesta.

Osservazioni:

WriteClass scrive un riferimento a CRuntimeClass per la classe base in CArchive. Usare CArchive::ReadClass per recuperare il riferimento.

WriteClass verifica che le informazioni sulla classe archiviata siano compatibili con la classe di runtime. Se non è compatibile, WriteClass genererà un'eccezione CArchiveException.

La classe di runtime deve usare DECLARE_SERIAL e IMPLEMENT_SERIAL; in caso contrario, WriteClass genererà un'eccezione CNotSupportedException.

È possibile usare SerializeClass invece di WriteClass, che gestisce sia la lettura che la scrittura del riferimento alla classe.

Esempio

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`

Archivia l'oggetto specificato CObject nell'archivio.

void WriteObject(const CObject* pOb);

Parametri

pOb
Puntatore costante all'oggetto archiviato.

Osservazioni:

Questa funzione viene in genere chiamata dall'operatore CArchive di inserimento ( <<) sottoposto a overload per CObject. WriteObject, a sua volta, chiama la Serialize funzione della classe archiviata.

È necessario utilizzare la macro per abilitare l'archiviazione IMPLEMENT_SERIAL . WriteObject scrive il nome della classe ASCII nell'archivio. Questo nome di classe viene convalidato in un secondo momento durante il processo di caricamento. Uno schema di codifica speciale impedisce la duplicazione non necessaria del nome della classe per più oggetti della classe. Questo schema impedisce inoltre l'archiviazione ridondante di oggetti che sono destinazioni di più di un puntatore.

Il metodo di codifica dell'oggetto esatto (inclusa la presenza del nome della classe ASCII) è un dettaglio di implementazione e potrebbe cambiare nelle versioni future della libreria.

Nota

Completare la creazione, l'eliminazione e l'aggiornamento di tutti gli oggetti prima di iniziare ad archiviarli. L'archivio verrà danneggiato se si combina l'archiviazione con la modifica dell'oggetto.

Esempio

Per una definizione della classe CAge, vedere l'esempio per 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`

Utilizzare questa funzione membro per scrivere dati da un buffer al file associato all'oggetto CArchive .

void WriteString(LPCTSTR lpsz);

Parametri

lpsz
Specifica un puntatore a un buffer contenente una stringa di testo con terminazione Null.

Osservazioni:

Il carattere null di terminazione ('\0') non viene scritto nel file; né è una nuova riga scritta automaticamente.

WriteString genera un'eccezione in risposta a diverse condizioni, inclusa la condizione completa del disco.

Write è disponibile anche, ma anziché terminare su un carattere Null, scrive il numero di byte richiesto nel file.

Esempio

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

Vedi anche

Grafico della gerarchia
CFile Classe
CObject Classe
CSocket Classe
CSocketFile Classe

Condividi tramite

Classe CArchive

Sintassi

Membri

Costruttori pubblici

Metodi pubblici

Operatori pubblici

Membri dati pubblici

Note

Gerarchia di ereditarietà

Requisiti

CArchive::Abort

Osservazioni:

Esempio

CArchive::CArchive

Parametri

Osservazioni:

Esempio

CArchive::Close

Osservazioni:

Esempio

CArchive::Flush

Osservazioni:

Esempio

CArchive::GetFile

Valore restituito

Osservazioni:

Esempio

CArchive::GetObjectSchema

Valore restituito

Osservazioni:

Esempio

CArchive::IsBufferEmpty

Valore restituito

Osservazioni:

CArchive::IsLoading

Valore restituito

Osservazioni:

Esempio

CArchive::IsStoring

Valore restituito

Osservazioni:

Esempio

CArchive::MapObject

Parametri

Osservazioni:

Esempio

CArchive::m_pDocument

Osservazioni:

Esempio

CArchive::operator <<

Valore restituito

Osservazioni:

Esempi

CArchive::operator >>

Valore restituito

Osservazioni:

Esempi

CArchive::Read

Parametri

Valore restituito

Osservazioni:

Esempio

CArchive::ReadClass

Parametri

Valore restituito

Osservazioni:

Esempio

CArchive::ReadObject

Parametri

Valore restituito

Osservazioni:

Esempio

CArchive::ReadString

Parametri

Valore restituito

Osservazioni:

Esempio

CArchive::SerializeClass

Parametri

Classe `CArchive`

`CArchive::Abort`

`CArchive::CArchive`

`CArchive::Close`

`CArchive::Flush`

`CArchive::GetFile`

`CArchive::GetObjectSchema`

`CArchive::IsBufferEmpty`

`CArchive::IsLoading`

`CArchive::IsStoring`

`CArchive::MapObject`

`CArchive::m_pDocument`

`CArchive::operator <<`

`CArchive::operator >>`

`CArchive::Read`

`CArchive::ReadClass`

`CArchive::ReadObject`

`CArchive::ReadString`

`CArchive::SerializeClass`

`CArchive::SetLoadParams`

`CArchive::SetObjectSchema`

`CArchive::SetStoreParams`

`CArchive::Write`

`CArchive::WriteClass`

`CArchive::WriteObject`

`CArchive::WriteString`