CArchive Klasa

Umożliwia zapisanie złożonej sieci obiektów w postaci trwałej binarnej (zwykle magazynu dyskowego), która jest utrwalana po usunięciu tych obiektów.

Składnia

class CArchive

Elementy członkowskie

Konstruktory publiczne

Nazwa/nazwisko	opis
CArchive::CArchive	Tworzy obiekt CArchive.

Metody publiczne

Nazwa/nazwisko	opis
CArchive::Abort	Zamyka archiwum bez zgłaszania wyjątku.
CArchive::Close	Opróżnia niepisane dane i rozłącza się z elementem CFile.
CArchive::Flush	Opróżnia niepisane dane z buforu archiwum.
CArchive::GetFile	CFile Pobiera wskaźnik obiektu dla tego archiwum.
CArchive::GetObjectSchema	Wywoływana Serialize z funkcji w celu określenia wersji obiektu, który jest deserializowany.
CArchive::IsBufferEmpty	Określa, czy bufor został opróżniony podczas procesu odbierania gniazd systemu Windows.
CArchive::IsLoading	Określa, czy trwa ładowanie archiwum.
CArchive::IsStoring	Określa, czy archiwum jest przechowywane.
CArchive::MapObject	Umieszcza obiekty na mapie, które nie są serializowane do pliku, ale są dostępne dla podobiektów do odwołania.
CArchive::Read	Odczytuje nieprzetworzone bajty.
CArchive::ReadClass	Odczytuje odwołanie do klasy wcześniej przechowywane za pomocą WriteClasspolecenia .
CArchive::ReadObject	Wywołuje funkcję obiektu Serialize do ładowania.
CArchive::ReadString	Odczytuje pojedynczy wiersz tekstu.
CArchive::SerializeClass	Odczytuje lub zapisuje odwołanie do klasy do CArchive obiektu w zależności od kierunku CArchive.
CArchive::SetLoadParams	Ustawia rozmiar, do którego rośnie tablica obciążenia. Należy wywołać element przed załadowaniem lub wywołaniem MapObject ReadObject dowolnego obiektu.
CArchive::SetObjectSchema	Ustawia schemat obiektu przechowywany w obiekcie archiwum.
CArchive::SetStoreParams	Ustawia rozmiar tabeli skrótów i rozmiar bloku mapy używanej do identyfikowania unikatowych obiektów podczas procesu serializacji.
CArchive::Write	Zapisuje nieprzetworzone bajty.
CArchive::WriteClass	Zapisuje odwołanie do CRuntimeClass .CArchive
CArchive::WriteObject	Wywołuje funkcję obiektu Serialize do przechowywania.
CArchive::WriteString	Zapisuje pojedynczy wiersz tekstu.

Operatory publiczne

Nazwa/nazwisko	opis
CArchive::operator <<	Przechowuje obiekty i typy pierwotne do archiwum.
CArchive::operator >>	Ładuje obiekty i typy pierwotne z archiwum.

Publiczne elementy członkowskie danych

Nazwa/nazwisko	opis
CArchive::m_pDocument

Uwagi

CArchive nie ma klasy bazowej.

Później można załadować obiekty z magazynu trwałego, ponownie ich odtworzenie w pamięci. Ten proces wprowadzania danych trwałych jest nazywany "serializacji".

Obiekt archiwum można traktować jako rodzaj strumienia binarnego. Podobnie jak strumień wejściowy/wyjściowy, archiwum jest skojarzone z plikiem i zezwala na buforowane zapisywanie i odczytywanie danych do i z magazynu. Strumień wejściowy/wyjściowy przetwarza sekwencje znaków ASCII, ale archiwum przetwarza dane obiektów binarnych w wydajnym, niedysantnym formacie.

Przed utworzeniem CFile CArchive obiektu należy utworzyć obiekt. Ponadto należy upewnić się, że stan ładowania/przechowywania archiwum jest zgodny z trybem otwierania pliku. Istnieje ograniczenie do jednego aktywnego archiwum na plik.

Podczas konstruowania CArchive obiektu należy dołączyć go do obiektu klasy (lub klasy CFile pochodnej), który reprezentuje otwarty plik. Określasz również, czy archiwum będzie używane do ładowania lub przechowywania. CArchive Obiekt może przetwarzać nie tylko typy pierwotne, ale także obiekty CObjectklas pochodnych przeznaczonych do serializacji. Klasa z możliwością serializacji zwykle ma funkcję składową Serialize i zwykle używa DECLARE_SERIAL makr i IMPLEMENT_SERIAL zgodnie z opisem w klasie CObject.

Przeciążone operatory wyodrębniania ( ) i wstawiania ( >><<) to wygodne interfejsy programowania archiwum, które obsługują zarówno typy pierwotne, jak i CObjectklasy pochodne.

CArchive Obsługuje również programowanie przy użyciu klas CSocket MFC Windows Sockets i CSocketFile. Funkcja IsBufferEmpty składowa obsługuje to użycie.

Aby uzyskać więcej informacji na temat CArchiveprogramu , zobacz artykuły Serialization and Windows Sockets: Using Sockets with Archives (Serializacja i gniazda systemu Windows: używanie gniazd z archiwami).

Hierarchia dziedziczenia

CArchive

Wymagania

Nagłówek: afx.h

CArchive::Abort

Wywołaj tę funkcję, aby zamknąć archiwum bez zgłaszania wyjątku.

void Abort ();

Uwagi

Destruktor CArchive zwykle wywołuje Closemetodę , co spowoduje opróżnienie wszystkich danych, które nie zostały zapisane w skojarzonym CFile obiekcie. Może to spowodować wyjątki.

Podczas przechwytywania tych wyjątków dobrym pomysłem jest użycie Abortelementu , aby destrukcja CArchive obiektu nie powodowała dalszych wyjątków. W przypadku obsługi wyjątków nie zgłasza wyjątku w przypadku awarii, CArchive::Abort ponieważ w przeciwieństwie do CArchive::CloseAbort parametru ignoruje błędy.

Jeśli został użyty new do przydzielenia CArchive obiektu na stercie, należy go usunąć po zamknięciu pliku.

Przykład

Zobacz przykład dla elementu CArchive::WriteClass.

CArchive::CArchive

CArchive Tworzy obiekt i określa, czy będzie używany do ładowania lub przechowywania obiektów.

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

Parametry

pFile
Wskaźnik do CFile obiektu, który jest ostatecznym źródłem lub miejscem docelowym danych trwałych.

nMode
Flaga określająca, czy obiekty będą ładowane z archiwum, czy przechowywane. Parametr nMode musi mieć jedną z następujących wartości:

• CArchive::load Ładuje dane z archiwum. Wymaga tylko CFile uprawnień do odczytu.

• CArchive::store Zapisuje dane w archiwum. Wymaga CFile uprawnień do zapisu.

• CArchive::bNoFlushOnDelete Zapobiega automatycznemu wywoływaniu Flush funkcji destruktora archiwum. Jeśli ustawisz tę flagę, odpowiadasz za jawne wywołanie przed wywołaniem Close destruktora. Jeśli tego nie zrobisz, twoje dane zostaną uszkodzone.

nBufSize
Liczba całkowita określająca rozmiar wewnętrznego buforu plików w bajtach. Należy pamiętać, że domyślny rozmiar buforu to 4096 bajtów. Jeśli rutynowo archiwizowasz duże obiekty, zwiększysz wydajność, jeśli używasz większego rozmiaru buforu, który jest wielokrotnym rozmiarem buforu plików.

lpBuf
Opcjonalny wskaźnik do buforu dostarczonego przez użytkownika o rozmiarze nBufSize. Jeśli nie określisz tego parametru, archiwum przydziela bufor z stosu lokalnego i zwalnia go, gdy obiekt zostanie zniszczony. Archiwum nie zwalnia buforu dostarczonego przez użytkownika.

Uwagi

Nie można zmienić tej specyfikacji po utworzeniu archiwum.

Operacje mogą nie być używane CFile do zmiany stanu pliku do momentu zamknięcia archiwum. Każda taka operacja spowoduje uszkodzenie integralności archiwum. Dostęp do położenia wskaźnika pliku można uzyskać w dowolnym momencie podczas serializacji, uzyskując obiekt pliku archiwum z GetFile funkcji składowej CFile::GetPosition , a następnie używając funkcji . Przed uzyskaniem pozycji wskaźnika pliku należy wywołać metodę CArchive::Flush .

Przykład

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

Opróżnia wszystkie dane pozostające w buforze, zamyka archiwum i odłącza archiwum od pliku.

void Close();

Uwagi

Nie są dozwolone żadne dalsze operacje na archiwum. Po zamknięciu archiwum możesz utworzyć inne archiwum dla tego samego pliku lub zamknąć plik.

Funkcja Close składowa zapewnia, że wszystkie dane są przesyłane z archiwum do pliku i sprawia, że archiwum jest niedostępne. Aby ukończyć transfer z pliku do nośnika magazynu, należy najpierw użyć CFile::Close polecenia , a następnie zniszczyć CFile obiekt.

Przykład

Zobacz przykład CArchive::WriteString.

CArchive::Flush

Wymusza zapisanie wszystkich danych w buforze archiwum.

void Flush();

Uwagi

Funkcja Flush składowa zapewnia, że wszystkie dane są przesyłane z archiwum do pliku. Musisz wywołać metodę CFile::Close , aby ukończyć transfer z pliku do nośnika magazynu.

Przykład

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

CFile Pobiera wskaźnik obiektu dla tego archiwum.

CFile* GetFile() const;

Wartość zwracana

Stały wskaźnik do CFile obiektu w użyciu.

Uwagi

Przed użyciem polecenia GetFilenależy opróżnić archiwum.

Przykład

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Wywołaj tę funkcję z Serialize funkcji, aby określić wersję obiektu, który jest obecnie deserializowany.

UINT GetObjectSchema();

Wartość zwracana

Podczas deserializacji wersja odczytywanego obiektu.

Uwagi

Wywoływanie tej funkcji jest prawidłowe tylko wtedy, gdy CArchive obiekt jest ładowany ( CArchive::IsLoading zwraca wartość niezerową). Powinno to być pierwsze wywołanie funkcji Serialize i wywoływane tylko raz. Zwracana wartość (UINT)-1 wskazuje, że numer wersji jest nieznany.

Klasa -pochodna CObjectmoże używać VERSIONABLE_SCHEMA połączonego (przy użyciu bitowego "lub" (|)) z samą wersją schematu (w makrze IMPLEMENT_SERIAL ) w celu utworzenia "obiektu możliwego do obsługi wersji", czyli obiektu, którego Serialize funkcja składowa może odczytywać wiele wersji. Domyślną funkcją platformy (bez VERSIONABLE_SCHEMA) jest zgłaszanie wyjątku, gdy wersja jest niezgodna.

Przykład

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

Wywołaj tę funkcję składową, aby określić, czy wewnętrzny bufor obiektu archiwum jest pusty.

BOOL IsBufferEmpty() const;

Wartość zwracana

Nonzero, jeśli bufor archiwum jest pusty; w przeciwnym razie 0.

Uwagi

Ta funkcja jest dostarczana do obsługi programowania z klasą CSocketFileMFC Windows Sockets . Nie trzeba go używać do archiwum skojarzonego z obiektem CFile .

Przyczyną użycia IsBufferEmpty z archiwum skojarzonym z obiektem CSocketFile jest to, że bufor archiwum może zawierać więcej niż jeden komunikat lub rekord. Po otrzymaniu jednego komunikatu należy użyć IsBufferEmpty do kontrolowania pętli, która kontynuuje odbieranie danych, dopóki bufor nie będzie pusty. Aby uzyskać więcej informacji, zobacz Receive funkcję składową klasy CAsyncSocket, która pokazuje, jak używać klasy IsBufferEmpty.

Aby uzyskać więcej informacji, zobacz Windows Sockets: Using Sockets with Archives (Gniazda systemu Windows: używanie gniazd z archiwami).

CArchive::IsLoading

Określa, czy archiwum ładuje dane.

BOOL IsLoading() const;

Wartość zwracana

Niezerowe, jeśli archiwum jest obecnie używane do ładowania; w przeciwnym razie 0.

Uwagi

Ta funkcja składowa jest wywoływana przez Serialize funkcje zarchiwizowanych klas.

Przykład

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

CArchive::IsStoring

Określa, czy archiwum przechowuje dane.

BOOL IsStoring() const;

Wartość zwracana

Niezerowe, jeśli archiwum jest obecnie używane do przechowywania; w przeciwnym razie 0.

Uwagi

Ta funkcja składowa jest wywoływana przez Serialize funkcje zarchiwizowanych klas.

IsStoring Jeśli stan archiwum jest niezerowy, jego IsLoading stan to 0 i na odwrót.

Przykład

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

CArchive::MapObject

Wywołaj tę funkcję składową, aby umieścić obiekty na mapie, które nie są tak naprawdę serializowane do pliku, ale są dostępne dla podobiektów do odwołania.

void MapObject(const CObject* pOb);

Parametry

pOb
Stały wskaźnik do przechowywanego obiektu.

Uwagi

Na przykład nie można serializować dokumentu, ale można serializować elementy, które są częścią dokumentu. Wywołając metodę MapObject, zezwalasz tym elementom lub podobiektom na odwołowanie się do dokumentu. Ponadto serializowane subitems mogą serializować wskaźnik m_pDocument wsteczny.

Wywołanie metody MapObject podczas przechowywania i ładowania z CArchive obiektu. MapObject Dodaje określony obiekt do wewnętrznych struktur danych utrzymywanych przez CArchive obiekt podczas serializacji i deserializacji, ale w przeciwieństwie do ReadObject i WriteObject, nie wywołuje serializacji na obiekcie.

Przykład

//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 Domyślnie ten wskaźnik CDocument może być ustawiony na dowolny element, którego chce użytkownik CArchive wystąpienia.

CDocument* m_pDocument;

Uwagi

Typowym zastosowaniem tego wskaźnika jest przekazanie dodatkowych informacji o procesie serializacji do wszystkich obiektów, które są serializowane. Jest to osiągane przez zainicjowanie wskaźnika przy użyciu dokumentu ( CDocumentklasy pochodnej), który jest serializowany, w taki sposób, aby obiekty w dokumencie mogły uzyskać dostęp do dokumentu w razie potrzeby. Ten wskaźnik jest również używany przez COleClientItem obiekty podczas serializacji.

Platforma ustawia dokument m_pDocument serializowany, gdy użytkownik wystawia polecenie Otwórz plik lub Zapisz. Jeśli serializujesz dokument kontenera Object Linking and Embedding (OLE) ze względów innych niż Plik otwórz lub zapisz, musisz jawnie ustawić wartość m_pDocument. Można to zrobić na przykład podczas serializacji dokumentu kontenera do Schowka.

Przykład

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

Przechowuje wskazany obiekt lub typ pierwotny do archiwum.

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

Wartość zwracana

Odwołanie CArchive , które umożliwia korzystanie z wielu operatorów wstawiania w jednym wierszu.

Uwagi

Ostatnie dwie powyższe wersje dotyczą przechowywania 64-bitowych liczb całkowitych.

Jeśli w implementacji klasy użyto makra IMPLEMENT_SERIAL , operator wstawiania został przeciążony dla CObject wywołań chronionego WriteObjectelementu . Ta funkcja z kolei wywołuje Serialize funkcję klasy .

CStringT Operator wstawiania (<<) obsługuje dumping diagnostyczny i przechowywanie w archiwum.

Przykłady

W tym przykładzie pokazano użycie CArchive operatora << wstawiania z typami int i long .

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

W tym przykładzie pokazano użycie CArchive operatora << wstawiania z typem CStringT .

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

CArchive::operator >>

Ładuje wskazany obiekt lub typ pierwotny z archiwum.

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

Wartość zwracana

Odwołanie CArchive , które umożliwia wielu operatorów wyodrębniania w jednym wierszu.

Uwagi

Ostatnie dwie powyższe wersje dotyczą ładowania 64-bitowych liczb całkowitych.

Jeśli w implementacji klasy użyto makra IMPLEMENT_SERIAL , operatory wyodrębniania przeciążone do CObject wywołania funkcji chronionej ReadObject (ze wskaźnikiem klasy uruchomieniowej innej niżzerowa). Ta funkcja z kolei wywołuje Serialize funkcję klasy .

CStringT Operator wyodrębniania (>>) obsługuje ładowanie z archiwum.

Przykłady

W tym przykładzie pokazano użycie CArchive operatora >> wyodrębniania z typem int .

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

W tym przykładzie pokazano użycie CArchive operatorów << wstawiania i wyodrębniania oraz >> z typem CStringT .

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

CArchive::Read

Odczytuje określoną liczbę bajtów z archiwum.

UINT Read(void* lpBuf, UINT nMax);

Parametry

lpBuf
Wskaźnik do buforu dostarczonego przez użytkownika, który ma odbierać dane odczytane z archiwum.

nMax
Liczba całkowita bez znaku określająca liczbę bajtów do odczytania z archiwum.

Wartość zwracana

Liczba całkowita bez znaku zawierająca liczbę bajtów rzeczywiście odczytanych. Jeśli wartość zwracana jest mniejsza niż żądana liczba, osiągnięto koniec pliku. Żaden wyjątek nie jest zgłaszany w warunku końca pliku.

Uwagi

Archiwum nie interpretuje bajtów.

Funkcji składowej Read w Serialize funkcji można używać do odczytywania zwykłych struktur zawartych w obiektach.

Przykład

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

CArchive::ReadClass

Wywołaj tę funkcję składową, aby odczytać odwołanie do klasy wcześniej przechowywanej za pomocą WriteClasspolecenia .

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

Parametry

pClassRefRequested
Wskaźnik do CRuntimeClass struktury odpowiadającej żądanej odwołaniu do klasy. Może to być NULL.

pSchema
Wskaźnik do schematu wcześniej przechowywanej klasy czasu wykonywania.

pObTag
Liczba, która odwołuje się do unikatowego tagu obiektu. Używane wewnętrznie przez implementację programu ReadObject. Uwidocznione tylko w przypadku programowania zaawansowanego; pObTag zwykle powinna mieć wartość NULL.

Wartość zwracana

Wskaźnik do CRuntimeClass struktury.

Uwagi

Jeśli pClassRefRequested nie NULLjest , ReadClass sprawdza, czy zarchiwizowane informacje o klasie środowiska uruchomieniowego są zgodne. Jeśli nie jest zgodny, ReadClass zostanie zgłoszony błąd CArchiveException.

Klasa środowiska uruchomieniowego musi używać wartości DECLARE_SERIAL i IMPLEMENT_SERIAL; w przeciwnym razie ReadClass zgłosi wartość CNotSupportedException.

Jeśli pSchema parametr ma NULLwartość , schemat przechowywanej klasy można pobrać przez wywołanie metody CArchive::GetObjectSchema; w przeciwnym razie *pSchema będzie zawierać schemat klasy czasu wykonywania, która była wcześniej przechowywana.

Można użyć zamiast SerializeClass ReadClass, który obsługuje zarówno odczytywanie, jak i zapisywanie odwołania do klasy.

Przykład

Zobacz przykład dla elementu CArchive::WriteClass.

CArchive::ReadObject

Odczytuje dane obiektu z archiwum i konstruuje obiekt odpowiedniego typu.

CObject* ReadObject(const CRuntimeClass* pClass);

Parametry

pClass
Stały wskaźnik do CRuntimeClass struktury odpowiadającej obiektowi, który ma być odczytywany.

Wartość zwracana

Wskaźnik CObject , który musi być bezpiecznie rzutowany do poprawnej klasy pochodnej przy użyciu metody CObject::IsKindOf.

Uwagi

Ta funkcja jest zwykle wywoływana CArchive przez operator wyodrębniania ( >>) przeciążony dla CObject wskaźnika. ReadObjectz kolei wywołuje Serialize funkcję zarchiwizowanej klasy.

Jeśli podasz parametr niezerowy pClass , który jest uzyskiwany przez RUNTIME_CLASS makro, funkcja weryfikuje klasę czasu wykonywania zarchiwizowanego obiektu. Przyjęto założenie, że w implementacji klasy użyto IMPLEMENT_SERIAL makra.

Przykład

Zobacz przykład dla elementu CArchive::WriteObject.

CArchive::ReadString

Wywołaj tę funkcję składową, aby odczytać dane tekstowe do buforu z pliku skojarzonego z obiektem CArchive .

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

Parametry

rString
Odwołanie do elementu CString , które będzie zawierać wynikowy ciąg po jego odczytaniu z pliku skojarzonego z obiektem CArchive .

lpsz
Określa wskaźnik do buforu dostarczonego przez użytkownika, który będzie otrzymywać ciąg tekstowy o wartości null.

nMax
Określa maksymalną liczbę znaków do odczytania. Powinna być mniejsza niż rozmiar buforu lpsz .

Wartość zwracana

W wersji, która zwraca wartość LOGICZNĄ, TRUE jeśli się powiedzie; FALSE w przeciwnym razie.

W wersji, która zwraca LPTSTRwartość , wskaźnik do buforu zawierającego dane tekstowe; NULL jeśli osiągnięto koniec pliku.

Uwagi

W wersji funkcji składowej z parametrem nMax bufor będzie przechowywać maksymalnie nMax 1 znak. Odczyt jest zatrzymywany przez parę karetki ze strumieniem zwrotnym. Końcowe znaki nowego wiersza są zawsze usuwane. Znak NULL ("\0") jest dołączany w obu przypadkach.

CArchive::Read Jest również dostępny dla danych wejściowych w trybie tekstowym, ale nie kończy się na parze zestawienia powrotnego karetki.

Przykład

Zobacz przykład dla elementu CArchive::WriteString.

CArchive::SerializeClass

Wywołaj tę funkcję składową, gdy chcesz przechowywać i ładować informacje o wersji klasy bazowej.

void SerializeClass(const CRuntimeClass* pClassRef);

Parametry

pClassRef
Wskaźnik do obiektu klasy czasu wykonywania dla klasy bazowej.

Uwagi

SerializeClass odczytuje lub zapisuje odwołanie do klasy do CArchive obiektu w zależności od kierunku CArchive. Użyj SerializeClass zamiast ReadClass i WriteClass jako wygodnego sposobu serializacji obiektów klasy bazowej; SerializeClass wymaga mniej kodu i mniejszej liczby parametrów.

Podobnie jak ReadClass, SerializeClass sprawdza, czy zarchiwizowane informacje o klasie środowiska uruchomieniowego są zgodne. Jeśli nie jest zgodny, SerializeClass zostanie zgłoszony błąd CArchiveException.

Klasa środowiska uruchomieniowego musi używać wartości DECLARE_SERIAL i IMPLEMENT_SERIAL; w przeciwnym razie SerializeClass zgłosi wartość CNotSupportedException.

Użyj makra RUNTIME_CLASS , aby pobrać wartość parametru pRuntimeClass . Klasa bazowa musi używać makra IMPLEMENT_SERIAL .

Przykład

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

Wywołaj metodę SetLoadParams , gdy odczytasz dużą liczbę CObjectobiektów pochodnych z archiwum.

void SetLoadParams(UINT nGrowBy = 1024);

Parametry

nGrowBy
Minimalna liczba miejsc elementów do przydzielenia, jeśli wymagany jest wzrost rozmiaru.

Uwagi

CArchive używa tablicy obciążenia do rozpoznawania odwołań do obiektów przechowywanych w archiwum. SetLoadParams Umożliwia ustawienie rozmiaru, do którego rośnie tablica obciążenia.

Nie można wywołać wywołania SetLoadParams po załadowaniu obiektu lub po MapObject wywołaniu lub ReadObject wywołaniu.

Przykład

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

Wywołaj tę funkcję składową, aby ustawić schemat obiektu przechowywany w obiekcie archiwum na nSchemawartość .

void SetObjectSchema(UINT nSchema);

Parametry

nSchema
Określa schemat obiektu.

Uwagi

Następne wywołanie metody GetObjectSchema zwróci wartość przechowywaną w nSchemapliku .

Służy SetObjectSchema do zaawansowanego przechowywania wersji, na przykład gdy chcesz wymusić odczytanie określonej wersji w Serialize funkcji klasy pochodnej.

Przykład

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

CArchive::SetStoreParams

Użyj SetStoreParams podczas przechowywania dużej liczby CObjectobiektów pochodnych w archiwum.

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

Parametry

nHashSize
Rozmiar tabeli skrótów dla map wskaźników interfejsu. Powinna być liczbą pierwszą.

nBlockSize
Określa stopień szczegółowości alokacji pamięci na potrzeby rozszerzania parametrów. Powinna być mocą 2, aby zapewnić najlepszą wydajność.

Uwagi

SetStoreParams Umożliwia ustawienie rozmiaru tabeli skrótów i rozmiaru bloku mapy używanej do identyfikowania unikatowych obiektów podczas procesu serializacji.

Nie można wywołać wywołania SetStoreParams po przechowywaniu żadnych obiektów ani po MapObject wywołaniu lub WriteObject wywołaniu.

Przykład

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

Zapisuje określoną liczbę bajtów w archiwum.

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

Parametry

lpBuf
Wskaźnik do buforu dostarczonego przez użytkownika, który zawiera dane do zapisania w archiwum.

nMax
Liczba całkowita określająca liczbę bajtów do zapisania w archiwum.

Uwagi

Archiwum nie formatuje bajtów.

Za pomocą funkcji składowej Write w funkcji Serialize można zapisywać zwykłe struktury, które znajdują się w obiektach.

Przykład

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

CArchive::WriteClass

Służy WriteClass do przechowywania informacji o wersji i klasie klasy bazowej podczas serializacji klasy pochodnej.

void WriteClass(const CRuntimeClass* pClassRef);

Parametry

pClassRef
Wskaźnik do CRuntimeClass struktury odpowiadającej żądanej odwołaniu do klasy.

Uwagi

WriteClass zapisuje odwołanie do CRuntimeClass klasy bazowej w obiekcie CArchive. Użyj polecenia CArchive::ReadClass , aby pobrać odwołanie.

WriteClass Sprawdza, czy zarchiwizowane informacje o klasie środowiska uruchomieniowego są zgodne. Jeśli nie jest zgodny, WriteClass zostanie zgłoszony błąd CArchiveException.

Klasa środowiska uruchomieniowego musi używać wartości DECLARE_SERIAL i IMPLEMENT_SERIAL; w przeciwnym razie WriteClass zgłosi wartość CNotSupportedException.

Można użyć zamiast SerializeClass WriteClass, który obsługuje zarówno odczytywanie, jak i zapisywanie odwołania do klasy.

Przykład

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

Przechowuje określone CObject w archiwum.

void WriteObject(const CObject* pOb);

Parametry

pOb
Stały wskaźnik do przechowywanego obiektu.

Uwagi

Ta funkcja jest zwykle wywoływana CArchive przez operator insertion ( <<) przeciążony dla .CObject WriteObjectz kolei wywołuje Serialize funkcję zarchiwizowanej klasy.

Aby włączyć archiwizowanie, należy użyć IMPLEMENT_SERIAL makra. WriteObject zapisuje nazwę klasy ASCII w archiwum. Ta nazwa klasy jest weryfikowana później podczas procesu ładowania. Specjalny schemat kodowania uniemożliwia niepotrzebne duplikowanie nazwy klasy dla wielu obiektów klasy. Ten schemat zapobiega również nadmiarowemu magazynowi obiektów, które są obiektami docelowymi więcej niż jednego wskaźnika.

Dokładna metoda kodowania obiektów (w tym obecność nazwy klasy ASCII) jest szczegółem implementacji i może ulec zmianie w przyszłych wersjach biblioteki.

Uwaga

Przed rozpoczęciem archiwizowania zakończ tworzenie, usuwanie i aktualizowanie wszystkich obiektów. Archiwum zostanie uszkodzone w przypadku wymieszania archiwizacji z modyfikacją obiektu.

Przykład

Aby uzyskać definicję klasy CAge, zobacz przykład dla CObList::CObListelementu .

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

Ta funkcja składowa służy do zapisywania danych z buforu do pliku skojarzonego z obiektem CArchive .

void WriteString(LPCTSTR lpsz);

Parametry

lpsz
Określa wskaźnik do buforu zawierającego ciąg tekstowy zakończony o wartości null.

Uwagi

Znak null zakończenia ("\0") nie jest zapisywany w pliku; nie jest automatycznie zapisywany nowy wiersz.

WriteString zgłasza wyjątek w odpowiedzi na kilka warunków, w tym warunek pełny dysku.

Write jest również dostępny, ale zamiast przerywać na znaku null, zapisuje żądaną liczbę bajtów do pliku.

Przykład

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

Zobacz też

Wykres hierarchii
CFile Klasa
CObject Klasa
CSocket Klasa
CSocketFile Klasa