CArchive Třída

Umožňuje uložit složitou síť objektů v trvalé binární podobě (obvykle diskové úložiště), která po odstranění těchto objektů přetrvává.

Syntaxe

class CArchive

Členové

Veřejné konstruktory

Jméno	popis
CArchive::CArchive	CArchive Vytvoří objekt.

Veřejné metody

Jméno	popis
CArchive::Abort	Zavře archiv bez vyvolání výjimky.
CArchive::Close	Vyprázdní nepřepsaná data a odpojí se od objektu CFile.
CArchive::Flush	Vyprázdní nepřepsaná data z archivní vyrovnávací paměti.
CArchive::GetFile	Získá ukazatel objektu CFile pro tento archiv.
CArchive::GetObjectSchema	Volané z Serialize funkce k určení verze objektu, který je deserializován.
CArchive::IsBufferEmpty	Určuje, zda byla vyrovnávací paměť vyprázdněna během procesu příjmu rozhraní Windows Sockets.
CArchive::IsLoading	Určuje, zda se archiv načítá.
CArchive::IsStoring	Určuje, zda se archiv ukládá.
CArchive::MapObject	Umístí objekty do mapy, které nejsou serializovány do souboru, ale jsou k dispozici pro podobjekty odkazované.
CArchive::Read	Čte nezpracované bajty.
CArchive::ReadClass	Přečte odkaz na třídu, který byl dříve uložen s WriteClass.
CArchive::ReadObject	Volá funkci objektu Serialize pro načtení.
CArchive::ReadString	Přečte jeden řádek textu.
CArchive::SerializeClass	Čte nebo zapisuje odkaz třídy na CArchive objekt v závislosti na směru objektu CArchive.
CArchive::SetLoadParams	Nastaví velikost, na kterou se pole zatížení zvětšuje. Musí být volána před načtením nebo před MapObject načtením objektu nebo před nebo ReadObject je volána.
CArchive::SetObjectSchema	Nastaví schéma objektů uložené v archivačním objektu.
CArchive::SetStoreParams	Nastaví velikost tabulky hash a velikost bloku mapy použité k identifikaci jedinečných objektů během procesu serializace.
CArchive::Write	Zapisuje nezpracované bajty.
CArchive::WriteClass	Zapíše odkaz na odkaz na CRuntimeClass .CArchive
CArchive::WriteObject	Volá funkci objektu Serialize pro ukládání.
CArchive::WriteString	Zapíše jeden řádek textu.

Veřejné operátory

Jméno	popis
CArchive::operator <<	Ukládá objekty a primitivní typy do archivu.
CArchive::operator >>	Načte objekty a primitivní typy z archivu.

Veřejné datové členy

Jméno	popis
CArchive::m_pDocument

Poznámky

CArchive nemá základní třídu.

Později můžete objekty načíst z trvalého úložiště a rekonstituovat je v paměti. Tento proces vytváření trvalých dat se nazývá serializace.

Archivní objekt si můžete představit jako druh binárního streamu. Stejně jako vstupní/výstupní datový proud je archiv přidružený k souboru a umožňuje ukládání dat do a z úložiště ukládat do vyrovnávací paměti a číst je. Vstupní/výstupní datový proud zpracovává sekvence znaků ASCII, ale archiv zpracovává data binárních objektů v efektivním neredundant formátu.

Před vytvořením CArchive objektu CFile je nutné vytvořit objekt. Kromě toho musíte zajistit, aby byl stav načítání a úložiště archivu kompatibilní s režimem otevření souboru. Počet aktivních archivů na soubor je omezený.

Při vytváření objektu CArchive jej připojíte k objektu třídy CFile (nebo odvozené třídy), který představuje otevřený soubor. Určíte také, jestli se archiv použije k načítání nebo ukládání. Objekt CArchive může zpracovávat nejen primitivní typy, ale také objekty -odvozených tříd určených CObjectpro serializaci. Serializovatelná třída má obvykle členská Serialize funkce a obvykle používá DECLARE_SERIAL a IMPLEMENT_SERIAL makra, jak je popsáno v rámci třídy CObject.

Operátory přetížené extrakce () a vložení (>><<) jsou praktická archivní programovací rozhraní, která podporují primitivní typy i CObjectodvozené třídy.

CArchive podporuje také programování pomocí tříd CSocket rozhraní WINDOWS Sockets mfc a CSocketFile. Členová IsBufferEmpty funkce toto použití podporuje.

Další informace o CArchive, naleznete v článcích Serializace a Windows Sockets: Použití soketů s archivy.

Hierarchie dědičnosti

CArchive

Požadavky

Záhlaví:afx.h

CArchive::Abort

Voláním této funkce zavřete archiv bez vyvolání výjimky.

void Abort ();

Poznámky

Destruktor CArchive bude normálně volat Close, což vyprázdní všechna data, která nebyla uložena do přidruženého CFile objektu. To může způsobit výjimky.

Při zachytávání těchto výjimek je vhodné použít Abort, aby destrukce CArchive objektu nezpůsobila další výjimky. Při zpracování výjimek nevyvolá výjimku při selhání, CArchive::Abort protože na rozdíl od CArchive::Close, Abort ignoruje selhání.

Pokud jste objekt new přidělil CArchive na haldě, musíte ho po zavření souboru odstranit.

Příklad

Podívejte se na příklad pro CArchive::WriteClass.

CArchive::CArchive

CArchive Vytvoří objekt a určuje, zda se použije k načítání nebo ukládání objektů.

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

Parametry

pFile
Ukazatel na CFile objekt, který je konečným zdrojem nebo cílem trvalých dat.

nMode
Příznak, který určuje, zda budou objekty načteny z archivu nebo uloženy do archivu. Parametr nMode musí mít jednu z následujících hodnot:

• CArchive::load Načte data z archivu. Vyžaduje pouze CFile oprávnění ke čtení.

• CArchive::store Uloží data do archivu. Vyžaduje CFile oprávnění k zápisu.

• CArchive::bNoFlushOnDelete Zabrání automatickému volání Flush archivu při volání destruktoru archivu. Pokud tento příznak nastavíte, zodpovídáte za explicitní volání Close před voláním destruktoru. Pokud ne, data budou poškozena.

nBufSize
Celé číslo, které určuje velikost interní vyrovnávací paměti souboru v bajtech. Všimněte si, že výchozí velikost vyrovnávací paměti je 4 096 bajtů. Pokud pravidelně archivujete velké objekty, zvýšíte výkon, pokud použijete větší velikost vyrovnávací paměti, která je násobkem velikosti vyrovnávací paměti souboru.

lpBuf
Volitelný ukazatel na uživatelsky zadanou vyrovnávací paměť velikosti nBufSize. Pokud tento parametr nezadáte, archiv přidělí vyrovnávací paměť z místní haldy a uvolní ji při zničení objektu. Archiv neuvolní uživatelsky zadanou vyrovnávací paměť.

Poznámky

Po vytvoření archivu nelze tuto specifikaci změnit.

Operace se nemusejí používat CFile ke změně stavu souboru, dokud archiv nezavřete. Jakákoli taková operace poškodí integritu archivu. Umístění ukazatele souboru můžete kdykoliv během serializace získat objekt souboru archivu z GetFile členské funkce a pak použít CFile::GetPosition funkci. Před získáním pozice ukazatele souboru byste měli zavolat CArchive::Flush .

Příklad

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

Vyprázdní všechna data zbývající ve vyrovnávací paměti, zavře archiv a odpojí archiv ze souboru.

void Close();

Poznámky

Nejsou povoleny žádné další operace v archivu. Po zavření archivu můžete vytvořit další archiv pro stejný soubor nebo ho můžete zavřít.

Členová funkce Close zajistí, že se všechna data přenesou z archivu do souboru a zpřístupní archiv. Chcete-li dokončit přenos ze souboru do úložného média, musíte nejprve použít CFile::Close a poté zničit CFile objekt.

Příklad

Podívejte se na příklad pro CArchive::WriteString.

CArchive::Flush

Vynutí zápis všech dat z archivní vyrovnávací paměti do souboru.

void Flush();

Poznámky

Členová funkce Flush zajistí, že se všechna data přenesou z archivu do souboru. K dokončení přenosu ze souboru do úložného média musíte volat CFile::Close .

Příklad

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

Získá ukazatel objektu CFile pro tento archiv.

CFile* GetFile() const;

Vrácená hodnota

Konstantní ukazatel na objekt, který CFile se používá.

Poznámky

Před použitím GetFilemusíte archiv vyprázdnět .

Příklad

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Voláním této funkce z Serialize funkce určíte verzi objektu, který je aktuálně deserializován.

UINT GetObjectSchema();

Vrácená hodnota

Během deserializace verze objektu, který se čte.

Poznámky

Volání této funkce je platné pouze při načítání objektu CArchive ( CArchive::IsLoading vrátí nenulové). Mělo by to být první volání funkce Serialize a volá se pouze jednou. Návratová hodnota (UINT)-1 označuje, že číslo verze je neznámé.

CObject-odvozená třída může použít VERSIONABLE_SCHEMA kombinaci (pomocí bitové "or" (|)) se samotnou verzí schématu (v IMPLEMENT_SERIAL makre) k vytvoření "objektu s možností správy verzí", tj. objekt, jehož Serialize členová funkce může číst více verzí. Výchozí funkce architektury (bez VERSIONABLE_SCHEMA) je vyvolání výjimky v případech, kdy se verze neshoduje.

Příklad

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

Voláním této členské funkce určíte, zda je vnitřní vyrovnávací paměť archivu objektu prázdná.

BOOL IsBufferEmpty() const;

Vrácená hodnota

Nenulové, pokud je vyrovnávací paměť archivu prázdná; jinak 0.

Poznámky

Tato funkce je poskytována pro podporu programování pomocí třídy MFC Windows Sockets CSocketFile. Nemusíte ho používat pro archiv přidružený k objektu CFile .

Důvodem použití IsBufferEmpty s archivem přidruženým k objektu CSocketFile je, že vyrovnávací paměť archivu může obsahovat více než jednu zprávu nebo záznam. Po přijetí jedné zprávy byste měli použít IsBufferEmpty k řízení smyčky, která pokračuje v přijímání dat, dokud vyrovnávací paměť nebude prázdná. Další informace naleznete v Receive členské funkci třídy CAsyncSocket, která ukazuje, jak používat IsBufferEmpty.

Další informace naleznete v tématu Windows Sockets: Použití soketů s archivy.

CArchive::IsLoading

Určuje, zda archiv načítá data.

BOOL IsLoading() const;

Vrácená hodnota

Nenulové, pokud se archiv aktuálně používá k načítání; jinak 0.

Poznámky

Tato členová funkce je volána Serialize funkcemi archivovaných tříd.

Příklad

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

CArchive::IsStoring

Určuje, zda archiv ukládá data.

BOOL IsStoring() const;

Vrácená hodnota

Nenulové, pokud se archiv aktuálně používá k ukládání; jinak 0.

Poznámky

Tato členová funkce je volána Serialize funkcemi archivovaných tříd.

IsStoring Pokud je stav archivu nenulový, je jeho IsLoading stav 0 a naopak.

Příklad

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

CArchive::MapObject

Voláním této členské funkce umístíte objekty do mapy, které nejsou ve skutečnosti serializovány do souboru, ale které jsou k dispozici pro podobjekty odkazované.

void MapObject(const CObject* pOb);

Parametry

pOb
Konstantní ukazatel na uložený objekt.

Poznámky

Můžete například serializovat dokument, ale serializovat položky, které jsou součástí dokumentu. MapObjectZavoláním povolíte těmto položkám nebo podobjektům odkazovat na dokument. Serializované subitemy mohou také serializovat jejich m_pDocument zadní ukazatel.

Při ukládání a načítání z objektu CArchive můžete volatMapObject. MapObject přidá zadaný objekt do vnitřních datových struktur udržovaných objektem CArchive během serializace a deserializace, ale na rozdíl od ReadObject a WriteObject, nevolá serializaci objektu.

Příklad

//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 Tento ukazatel na CDocument hodnotu lze nastavit na cokoli, co chce uživatel CArchive instance.

CDocument* m_pDocument;

Poznámky

Běžným použitím tohoto ukazatele je sdělit další informace o procesu serializace všem objektům, které jsou serializovány. Toho lze dosáhnout inicializací ukazatele s dokumentem (odvozenou CDocumenttřídou), která je serializována, způsobem, jakým objekty v dokumentu mohou v případě potřeby přistupovat k dokumentu. Tento ukazatel je také používán COleClientItem objekty během serializace.

Architektura se nastaví m_pDocument na dokument serializovaný, když uživatel vydá příkaz Otevřít soubor nebo Uložit. Pokud serializujete dokument kontejneru ole (Object Linking and Embedding) z jiných důvodů než Soubor Otevřít nebo Uložit, musíte explicitně nastavit m_pDocument. To byste například udělali při serializaci dokumentu kontejneru do schránky.

Příklad

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

Uloží označený objekt nebo primitivní typ do archivu.

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

Vrácená hodnota

Odkaz CArchive , který umožňuje více operátorů vložení na jeden řádek.

Poznámky

Poslední dvě výše uvedené verze jsou určené speciálně pro ukládání 64bitových celých čísel.

Pokud jste makro použili IMPLEMENT_SERIAL v implementaci třídy, pak operátor vložení přetížený pro CObject volání chráněné WriteObject. Tato funkce zase volá Serialize funkci třídy.

Operátor CStringT vložení (<<) podporuje výpis diagnostiky a ukládání do archivu.

Příklady

Tento příklad ukazuje použití operátoru CArchive<< vložení s typy int a long typy.

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

Tento příklad ukazuje použití operátoru CArchive<< vložení s typem CStringT .

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

CArchive::operator >>

Načte označený objekt nebo primitivní typ z archivu.

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

Vrácená hodnota

Odkaz CArchive , který umožňuje více operátorů extrakce na jednom řádku.

Poznámky

Poslední dvě výše uvedené verze jsou určené speciálně pro načítání 64bitových celých čísel.

Pokud jste makro použili IMPLEMENT_SERIAL v implementaci třídy, operátory extrakce přetížené pro CObject volání chráněné ReadObject funkce (s nenulovým ukazatelem třídy za běhu). Tato funkce zase volá Serialize funkci třídy.

Operátor CStringT extrakce (>>) podporuje načítání z archivu.

Příklady

Tento příklad ukazuje použití operátoru CArchive>> extrakce s typem int .

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

Tento příklad ukazuje použití CArchive operátorů << vložení a extrakce a >> s typem CStringT .

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

CArchive::Read

Načte zadaný počet bajtů z archivu.

UINT Read(void* lpBuf, UINT nMax);

Parametry

lpBuf
Ukazatel na uživatelsky zadanou vyrovnávací paměť, která přijímá data načtená z archivu.

nMax
Celé číslo bez znaménka určující počet bajtů, které se mají číst z archivu.

Vrácená hodnota

Celé číslo bez znaménka obsahující počet bajtů, které se skutečně čtou. Pokud je vrácená hodnota menší než požadované číslo, bylo dosaženo konce souboru. V podmínce end-of-file se nevyvolá žádná výjimka.

Poznámky

Archiv neinterpretuje bajty.

Členovou funkci v rámci funkce Serialize můžete použít Read ke čtení běžných struktur obsažených v objektech.

Příklad

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

CArchive::ReadClass

Voláním této členské funkce přečtete odkaz na třídu, která byla dříve uložena s WriteClass.

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

Parametry

pClassRefRequested
Ukazatel na CRuntimeClass strukturu, která odpovídá požadovanému odkazu na třídu. Může to být NULL.

pSchema
Ukazatel na schéma třídy runtime, která byla dříve uložena.

pObTag
Číslo, které odkazuje na jedinečnou značku objektu. Interně používáno prováděním .ReadObject Vystaveno pouze pro pokročilé programování; pObTag normálně by měla být NULL.

Vrácená hodnota

Ukazatel na CRuntimeClass strukturu.

Poznámky

Pokud pClassRefRequested není NULL, ReadClass ověří, že archivované informace o třídě jsou kompatibilní s vaší třídou runtime. Pokud není kompatibilní, ReadClass vyvolá chybu CArchiveException.

Vaše třída modulu runtime musí používat DECLARE_SERIAL a IMPLEMENT_SERIALv opačném případě ReadClass vyvolá výjimku CNotSupportedException.

Pokud pSchema ano NULL, schéma uložené třídy lze načíst voláním CArchive::GetObjectSchema; jinak *pSchema bude obsahovat schéma třídy runtime, která byla dříve uložena.

Místo toho můžete použít SerializeClassReadClass, který zpracovává čtení i zápis odkazu na třídu.

Příklad

Podívejte se na příklad pro CArchive::WriteClass.

CArchive::ReadObject

Načte data objektu z archivu a vytvoří objekt odpovídajícího typu.

CObject* ReadObject(const CRuntimeClass* pClass);

Parametry

pClass
Konstantní ukazatel na CRuntimeClass strukturu, která odpovídá objektu, který očekáváte číst.

Vrácená hodnota

CObject Ukazatel, který musí být bezpečně přetypován na správnou odvozenou třídu pomocí CObject::IsKindOf.

Poznámky

Tuto funkci obvykle volá CArchive operátor extrakce ( >>) přetížený pro CObject ukazatel. ReadObject, dále volá Serialize funkci archivované třídy.

Pokud zadáte nenulový pClass parametr, který získá RUNTIME_CLASS makro, funkce ověří třídu runtime archivovaného objektu. Předpokládá se, že jste makro použili IMPLEMENT_SERIAL při implementaci třídy.

Příklad

Podívejte se na příklad pro CArchive::WriteObject.

CArchive::ReadString

Voláním této členské funkce načtěte textová data do vyrovnávací paměti ze souboru přidruženého k objektu CArchive .

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

Parametry

rString
Odkaz na CString takový, který bude obsahovat výsledný řetězec po načtení ze souboru přidruženého k objektu CArchive .

lpsz
Určuje ukazatel na uživatelsky zadanou vyrovnávací paměť, která obdrží textový řetězec s ukončenou hodnotou null.

nMax
Určuje maximální počet znaků, které se mají přečíst. Měla by být jedna menší než velikost lpsz vyrovnávací paměti.

Vrácená hodnota

Ve verzi, která vrátí logickou hodnotu BOOL, TRUE pokud je úspěšná, FALSE jinak.

Ve verzi, která vrací LPTSTRukazatel na vyrovnávací paměť obsahující textová data; NULL pokud bylo dosaženo konce souboru.

Poznámky

Ve verzi členské funkce s parametrem nMax bude vyrovnávací paměť obsahovat limit až nMax 1 znaků. Čtení je zastaveno dvojicí návratového kanálu řádku na řádku. Koncové znaky nového řádku jsou vždy odebrány. Znak NULL (\0) se připojí v obou případech.

CArchive::Read je také k dispozici pro vstup v textovém režimu, ale neukončí se u dvojice návratového kanálu řádku řádku.

Příklad

Podívejte se na příklad pro CArchive::WriteString.

CArchive::SerializeClass

Tuto členskou funkci zavolejte, pokud chcete uložit a načíst informace o verzi základní třídy.

void SerializeClass(const CRuntimeClass* pClassRef);

Parametry

pClassRef
Ukazatel na objekt třídy run-time pro základní třídu.

Poznámky

SerializeClass přečte nebo zapíše odkaz na třídu do objektu CArchive v závislosti na směru objektu CArchive. Místo SerializeClass a WriteClass jako pohodlný způsob serializace objektů základní třídy; SerializeClass vyžaduje méně kódu ReadClass a méně parametrů.

Podobně jako ReadClass, SerializeClass ověřuje, že archivované informace třídy jsou kompatibilní s vaší třídou runtime. Pokud není kompatibilní, SerializeClass vyvolá chybu CArchiveException.

Vaše třída modulu runtime musí používat DECLARE_SERIAL a IMPLEMENT_SERIALv opačném případě SerializeClass vyvolá výjimku CNotSupportedException.

RUNTIME_CLASS Pomocí makra načtěte hodnotu parametrupRuntimeClass. Základní třída musí makro použít IMPLEMENT_SERIAL .

Příklad

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

Volání SetLoadParams , když budete číst velký počet -odvozených CObjectobjektů z archivu.

void SetLoadParams(UINT nGrowBy = 1024);

Parametry

nGrowBy
Minimální počet slotů prvků, které se mají přidělit, pokud je potřeba zvětšit velikost.

Poznámky

CArchive používá k překladu odkazů na objekty uložené v archivu pole zatížení. SetLoadParams umožňuje nastavit velikost, na kterou se pole zatížení zvětšuje.

Po načtení nebo volání MapObjectReadObject žádného objektu nesmíte volatSetLoadParams.

Příklad

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

Voláním této členské funkce nastavíte schéma objektu uloženého v archivačním objektu na nSchemahodnotu .

void SetObjectSchema(UINT nSchema);

Parametry

nSchema
Určuje schéma objektu.

Poznámky

Další volání GetObjectSchema vrátí hodnotu uloženou v nSchema.

Slouží SetObjectSchema k rozšířené správě verzí, například pokud chcete vynutit čtení určité verze ve Serialize funkci odvozené třídy.

Příklad

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

CArchive::SetStoreParams

Používá se SetStoreParams při ukládání velkého počtu odvozených CObjectobjektů do archivu.

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

Parametry

nHashSize
Velikost hashovací tabulky pro mapy ukazatelů rozhraní. Mělo by to být základní číslo.

nBlockSize
Určuje členitost přidělení paměti pro rozšíření parametrů. Pro zajištění nejlepšího výkonu by měl být výkon 2.

Poznámky

SetStoreParams umožňuje nastavit velikost tabulky hash a velikost bloku mapy sloužící k identifikaci jedinečných objektů během procesu serializace.

Po uložení nebo volání MapObjectWriteObject objektů nesmíte volatSetStoreParams.

Příklad

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

Zapíše zadaný počet bajtů do archivu.

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

Parametry

lpBuf
Ukazatel na vyrovnávací paměť zadanou uživatelem, která obsahuje data, která se mají zapisovat do archivu.

nMax
Celé číslo, které určuje počet bajtů, které mají být zapsány do archivu.

Poznámky

Archiv nenaformátuje bajty.

Členovou funkci v rámci funkce Serialize můžete použít k zápisu Write běžných struktur, které jsou obsaženy v objektech.

Příklad

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

CArchive::WriteClass

Slouží WriteClass k uložení informací o verzi a třídě základní třídy během serializace odvozené třídy.

void WriteClass(const CRuntimeClass* pClassRef);

Parametry

pClassRef
Ukazatel na CRuntimeClass strukturu, která odpovídá požadovanému odkazu na třídu.

Poznámky

WriteClass zapíše odkaz na CRuntimeClass základní třídu do objektu CArchive. Slouží CArchive::ReadClass k načtení odkazu.

WriteClass ověřuje, že archivované informace o třídě jsou kompatibilní s vaší třídou runtime. Pokud není kompatibilní, WriteClass vyvolá chybu CArchiveException.

Vaše třída modulu runtime musí používat DECLARE_SERIAL a IMPLEMENT_SERIALv opačném případě WriteClass vyvolá výjimku CNotSupportedException.

Místo toho můžete použít SerializeClassWriteClass, který zpracovává čtení i zápis odkazu na třídu.

Příklad

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

Uloží zadaný CObject do archivu.

void WriteObject(const CObject* pOb);

Parametry

pOb
Konstantní ukazatel na uložený objekt.

Poznámky

Tato funkce je obvykle volána operátorem CArchive vložení ( <<) přetížené pro CObject. WriteObject, dále volá Serialize funkci archivované třídy.

K povolení archivace je nutné použít IMPLEMENT_SERIAL makro. WriteObject zapíše název třídy ASCII do archivu. Tento název třídy se později ověří během procesu načítání. Speciální schéma kódování zabraňuje zbytečné duplikaci názvu třídy pro více objektů třídy. Toto schéma také zabraňuje redundantnímu ukládání objektů, které jsou cílem více než jednoho ukazatele.

Přesná metoda kódování objektů (včetně přítomnosti názvu třídy ASCII) je podrobnosti implementace a mohla by se změnit v budoucích verzích knihovny.

Poznámka

Než začnete archivovat, dokončete vytváření, odstraňování a aktualizaci všech objektů. Archiv se poškodí, pokud archivujete s úpravou objektu.

Příklad

Definice třídy CAgenaleznete v CObList::CObListpříkladu .

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

Tato členová funkce slouží k zápisu dat z vyrovnávací paměti do souboru přidruženého k objektu CArchive .

void WriteString(LPCTSTR lpsz);

Parametry

lpsz
Určuje ukazatel na vyrovnávací paměť obsahující textový řetězec ukončený hodnotou null.

Poznámky

Ukončující znak null (\0) není zapsán do souboru; ani není nový řádek automaticky zapsán.

WriteString vyvolá výjimku v reakci na několik podmínek, včetně podmínky plného disku.

Write je také k dispozici, ale místo ukončení znaku null zapíše požadovaný počet bajtů do souboru.

Příklad

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

Viz také

Graf hierarchie
CFile Třída
CObject Třída
CSocket Třída
CSocketFile Třída