Класс `CArchive`

Статья
06/16/2023

Позволяет сохранять сложную сеть объектов в постоянной двоичной форме (обычно дисковое хранилище), которая сохраняется после удаления этих объектов.

Синтаксис

class CArchive

Участники

Открытые конструкторы

Имя	Описание
`CArchive::CArchive`	Создает объект `CArchive`.

Открытые методы

Имя	Описание
`CArchive::Abort`	Закрывает архив без исключения.
`CArchive::Close`	Очищает незаписанные данные и отключает от нее `CFile`.
`CArchive::Flush`	Очистка незаписанных данных из архивного буфера.
`CArchive::GetFile`	Возвращает указатель объекта для этого архива `CFile` .
`CArchive::GetObjectSchema`	Вызывается из `Serialize` функции, чтобы определить версию объекта, десериализируемого.
`CArchive::IsBufferEmpty`	Определяет, очищается ли буфер во время процесса получения сокетов Windows.
`CArchive::IsLoading`	Определяет, загружается ли архив.
`CArchive::IsStoring`	Определяет, хранится ли архив.
`CArchive::MapObject`	Помещает объекты в карту, которая не сериализована в файл, но доступна для ссылок на вложенные объекты.
`CArchive::Read`	Считывает необработанные байты.
`CArchive::ReadClass`	Считывает ссылку на класс, ранее хранящуюся в `WriteClass`.
`CArchive::ReadObject`	Вызывает функцию объекта `Serialize` для загрузки.
`CArchive::ReadString`	Считывает одну строку текста.
`CArchive::SerializeClass`	Считывает или записывает ссылку класса на `CArchive` объект в зависимости от направления `CArchive`объекта.
`CArchive::SetLoadParams`	Задает размер, к которому растет массив нагрузки. Необходимо вызывать перед загрузкой или вызовом `MapObjectReadObject` любого объекта.
`CArchive::SetObjectSchema`	Задает схему объекта, хранящуюся в архивном объекте.
`CArchive::SetStoreParams`	Задает размер хэш-таблицы и размер блока карты, используемой для идентификации уникальных объектов во время процесса сериализации.
`CArchive::Write`	Записывает необработанные байты.
`CArchive::WriteClass`	Записывает ссылку на `CRuntimeClass` объект `CArchive`.
`CArchive::WriteObject`	Вызывает функцию объекта `Serialize` для хранения.
`CArchive::WriteString`	Записывает одну строку текста.

Открытые операторы

Имя	Описание
`CArchive::operator <<`	Хранит объекты и примитивные типы в архив.
`CArchive::operator >>`	Загружает объекты и примитивные типы из архива.

Открытые члены данных

Имя	Описание
`CArchive::m_pDocument`

Примечания

CArchive не имеет базового класса.

Позже вы можете загрузить объекты из постоянного хранилища, повторно создав их в памяти. Этот процесс создания постоянных данных называется сериализации.

Архивный объект можно рассматривать как двоичный поток. Как и входной или выходной поток, архив связан с файлом и разрешает буферизованное запись и чтение данных в хранилище и из нее. Поток ввода и вывода обрабатывает последовательности символов ASCII, но архив обрабатывает данные двоичного объекта в эффективном нередундантном формате.

Перед созданием объекта необходимо создать CFileCArchive объект. Кроме того, необходимо убедиться, что состояние загрузки и хранения архива совместимо с открытым режимом файла. Для каждого файла требуется только один активный архив.

При создании CArchive объекта вы присоединяете его к объекту класса CFile (или производного класса), представляющего открытый файл. Вы также указываете, будет ли архив использоваться для загрузки или хранения. CArchive Объект может обрабатывать не только примитивные типы, но и объекты производных классов, предназначенных CObjectдля сериализации. Сериализуемый класс обычно имеет Serialize функцию-член, и обычно использует DECLARE_SERIAL макросы и IMPLEMENT_SERIAL макросы, как описано в классе CObject.

Перегруженные операторы извлечения ( >>) и вставки ( <<) являются удобными интерфейсами программирования архива, поддерживающими как примитивные типы, так и CObjectпроизводные классы.

CArchive также поддерживает программирование с помощью классов CSocket сокетов Windows MFC и CSocketFile. Функция-член IsBufferEmpty поддерживает это использование.

Дополнительные сведения CArchiveсм. в статьях сериализация и сокеты Windows: использование сокетов с архивами.

Иерархия наследования

CArchive

Требования

Заголовок.afx.h

`CArchive::Abort`

Вызовите эту функцию, чтобы закрыть архив без исключения.

void Abort ();

Замечания

CArchive Деструктор обычно вызываетClose, что приведет к очистке любых данных, которые не были сохранены в связанном CFile объекте. Это может привести к исключениям.

При перехвате этих исключений рекомендуется использовать Abort, чтобы деструкция CArchive объекта не приводила к дальнейшим исключениям. При обработке исключений не будет возникать исключение при сбоях, CArchive::Abort так как, в отличие CArchive::Closeот ошибок, Abort игнорируется.

Если вы использовали new для выделения CArchive объекта в куче, его необходимо удалить после закрытия файла.

Пример

Пример см. в примере CArchive::WriteClass.

`CArchive::CArchive`

CArchive Создает объект и указывает, будет ли он использоваться для загрузки или хранения объектов.

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

Параметры

pFile
Указатель на CFile объект, который является конечным источником или назначением постоянных данных.

nMode
Флаг, указывающий, будут ли объекты загружаться из архива или храниться в нем. Параметр nMode должен иметь одно из следующих значений:

CArchive::load Загружает данные из архива. Требуется только CFile разрешение на чтение.
CArchive::store Сохраняет данные в архив. Требуется CFile разрешение на запись.
CArchive::bNoFlushOnDelete Предотвращает автоматический вызов Flush архива при вызове деструктора архива. Если этот флаг задан, вы несете ответственность за явное вызов Close перед вызовом деструктора. Если это не так, данные будут повреждены.

nBufSize
Целое число, указывающее размер внутреннего буфера файла в байтах. Обратите внимание, что размер буфера по умолчанию составляет 4096 байт. Если вы обычно архивируйте большие объекты, вы улучшите производительность при использовании большего размера буфера, который является нескольким размером буфера файла.

lpBuf
Необязательный указатель на предоставленный пользователем буфер размера nBufSize. Если этот параметр не указан, архив выделяет буфер из локальной кучи и освобождает его при уничтожении объекта. Архив не освобождает предоставленный пользователем буфер.

Замечания

Эту спецификацию нельзя изменить после создания архива.

Вы не можете использовать CFile операции для изменения состояния файла, пока вы не закрыли архив. Любая такая операция повредит целостность архива. Вы можете получить доступ к позиции указателя файла в любое время во время сериализации, получив объект файла архива из GetFile функции-члена, а затем используя функцию CFile::GetPosition . Перед получением позиции указателя файла необходимо вызвать CArchive::Flush вызов.

Пример

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`

Удаляет все данные, оставшиеся в буфере, закрывает архив и отключает архив от файла.

void Close();

Замечания

Дальнейшие операции с архивом не разрешены. После закрытия архива можно создать другой архив для того же файла или закрыть файл.

Функция-член Close гарантирует, что все данные передаются из архива в файл, и он делает архив недоступным. Чтобы завершить передачу из файла в носитель хранилища, сначала необходимо использовать CFile::Close , а затем уничтожить CFile объект.

Пример

См. пример CArchive ::WriteString.

`CArchive::Flush`

Принудительно записывает все данные, оставшиеся в буфере архива, в файл.

void Flush();

Замечания

Функция-член Flush гарантирует, что все данные передаются из архива в файл. Чтобы завершить передачу из файла в носитель хранилища, необходимо выполнить вызов CFile::Close .

Пример

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 .

CFile* GetFile() const;

Возвращаемое значение

Константный указатель на используемый CFile объект.

Замечания

Перед использованием GetFileнеобходимо очистить архив.

Пример

const CFile *fp = ar.GetFile();

`CArchive::GetObjectSchema`

Вызовите эту функцию из Serialize функции, чтобы определить версию объекта, который в настоящее время десериализирован.

UINT GetObjectSchema();

Возвращаемое значение

Во время десериализации версия объекта, считываемого.

Замечания

Вызов этой функции действителен только при CArchive загрузке объекта ( CArchive::IsLoading возвращает ненулевое значение). Это должен быть первый вызов функции Serialize и вызываться только один раз. Возвращаемое значение (UINT)-1 указывает, что номер версии неизвестен.

Производный CObjectкласс может использовать VERSIONABLE_SCHEMA объединенный (с побитовой "или" (|)) с самой версией схемы (в IMPLEMENT_SERIAL макросе) для создания "объект, доступный для версий", то есть объект, функция-член которого Serialize может считывать несколько версий. Функциональные возможности платформы по умолчанию (без VERSIONABLE_SCHEMA) создают исключение при несоответствии версии.

Пример

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`

Вызовите эту функцию-член, чтобы определить, является ли внутренний буфер архивного объекта пустым.

BOOL IsBufferEmpty() const;

Возвращаемое значение

Ненулевое значение, если буфер архива пуст; в противном случае — 0.

Замечания

Эта функция предоставляется для поддержки программирования с помощью класса CSocketFileсокетов Windows MFC. Его не нужно использовать для архива, связанного CFile с объектом.

Причина использования IsBufferEmpty архива, связанного с CSocketFile объектом, заключается в том, что буфер архива может содержать несколько сообщений или записей. После получения одного сообщения следует использовать IsBufferEmpty для управления циклом, который продолжает получать данные, пока буфер не пуст. Дополнительные сведения см. в Receive функции-члене класса CAsyncSocket, в которой показано, как использовать IsBufferEmpty.

Дополнительные сведения см. в статье "Сокеты Windows: использование сокетов с архивами".

`CArchive::IsLoading`

Определяет, загружается ли архив данных.

BOOL IsLoading() const;

Возвращаемое значение

Ненулевое значение, если архив в настоящее время используется для загрузки; в противном случае — 0.

Замечания

Эта функция-член вызывается Serialize функциями архивированных классов.

Пример

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

`CArchive::IsStoring`

Определяет, хранится ли архив данных.

BOOL IsStoring() const;

Возвращаемое значение

Ненулевое значение, если архив в настоящее время используется для хранения; в противном случае — 0.

Замечания

Эта функция-член вызывается Serialize функциями архивированных классов.

IsStoring Если состояние архива ненулевое, его IsLoading состояние равно 0 и наоборот.

Пример

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

`CArchive::MapObject`

Вызовите эту функцию-член, чтобы поместить объекты в карту, которая не сериализована в файл, но доступна для ссылок на вложенные объекты.

void MapObject(const CObject* pOb);

Параметры

pOb
Константный указатель на сохраненный объект.

Замечания

Например, можно не сериализовать документ, но сериализовать элементы, которые являются частью документа. Вызывая MapObjectэти элементы или вложенные объекты, можно ссылаться на документ. Кроме того, сериализованные дочерние элементы могут сериализовать их m_pDocument обратный указатель.

Можно вызывать MapObject при хранении и загрузке CArchive из объекта. MapObject добавляет указанный объект во внутренние структуры данных, поддерживаемые CArchive объектом во время сериализации и десериализации, но в отличие ReadObjectWriteObjectот этого, он не вызывает сериализацию объекта.

Пример

//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 По умолчанию этот указатель CDocument можно задать для пользователя экземпляраCArchive.

CDocument* m_pDocument;

Замечания

Обычное использование этого указателя заключается в передаче дополнительных сведений о процессе сериализации для всех объектов, сериализованных. Это достигается путем инициализации указателя с документом CDocument(производным классом), который сериализуется, таким образом, чтобы объекты в документе могли получить доступ к документу при необходимости. Этот указатель также используется объектами COleClientItem во время сериализации.

Платформа задает m_pDocument документу, сериализуемого при выполнении пользователем команды "Открыть файл" или "Сохранить". Если вы сериализуете документ контейнера для связывания объектов и внедрения (OLE) по причинам, отличным от открытия файла или сохранения, необходимо явно задать m_pDocument. Например, это можно сделать при сериализации документа контейнера в буфер обмена.

Пример

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

Сохраняет указанный объект или примитивный тип в архив.

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

Возвращаемое значение

Ссылка CArchive , которая включает несколько операторов вставки в одной строке.

Замечания

Последние две версии выше предназначены специально для хранения 64-разрядных целых чисел.

Если макрос использовался IMPLEMENT_SERIAL в реализации класса, то оператор вставки перегружен для CObject вызовов защищенных WriteObject. Эта функция, в свою очередь, вызывает Serialize функцию класса.

Оператор CStringT вставки (<<) поддерживает дамп диагностики и хранение в архиве.

Примеры

В этом примере демонстрируется использование CArchive оператора << вставки с int типами и типами long .

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

В этом примере показано использование CArchive оператора << вставки с типом CStringT .

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

`CArchive::operator >>`

Загружает указанный объект или примитивный тип из архива.

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

Возвращаемое значение

Ссылка CArchive , которая включает несколько операторов извлечения в одной строке.

Замечания

Последние две версии выше предназначены для загрузки 64-разрядных целых чисел.

Если в реализации класса использовался IMPLEMENT_SERIAL макрос, операторы извлечения перегружены для CObject вызова защищенной ReadObject функции (с указателем класса ненулевого времени выполнения). Эта функция, в свою очередь, вызывает Serialize функцию класса.

Оператор CStringT извлечения (>>) поддерживает загрузку из архива.

Примеры

В этом примере демонстрируется использование CArchive оператора >> извлечения с типом int .

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

В этом примере демонстрируется использование CArchive операторов << вставки и извлечения и >> типа CStringT .

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

`CArchive::Read`

Считывает указанное число байтов из архива.

UINT Read(void* lpBuf, UINT nMax);

Параметры

lpBuf
Указатель на предоставленный пользователем буфер, который получает данные, считываемые из архива.

nMax
Целое число без знака, указывающее число байтов для чтения из архива.

Возвращаемое значение

Целое число без знака, содержащее количество байтов, которые фактически считываются. Если возвращаемое значение меньше запрошенного числа, достигнуто окончание файла. Исключение не возникает в условии окончания файла.

Замечания

Архив не интерпретирует байты.

Функцию-член Read в Serialize функции можно использовать для чтения обычных структур, содержащихся в объектах.

Пример

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

`CArchive::ReadClass`

Вызовите эту функцию-член, чтобы прочитать ссылку на класс, сохраненный WriteClassранее.

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

Параметры

pClassRefRequested
Указатель на CRuntimeClass структуру, соответствующую запрошенной ссылке класса. Может иметь значение NULL.

pSchema
Указатель на схему ранее сохраненного класса времени выполнения.

pObTag
Число, которое ссылается на уникальный тег объекта. Используется внутри реализации ReadObject. Предоставляется только для расширенного программирования; pObTag обычно должно быть NULL.

Возвращаемое значение

Указатель на структуру CRuntimeClass .

Замечания

Если pClassRefRequested это не NULLтак, ReadClass проверяет, совместим ли архивная информация о классе среды выполнения. Если оно несовместимо, ReadClass вызовет CArchiveExceptionисключение.

Класс среды выполнения должен использовать DECLARE_SERIAL и IMPLEMENT_SERIAL; в противном случае ReadClass вызовет CNotSupportedExceptionисключение.

Если pSchema это NULLтак, схема сохраненного класса может быть получена путем вызова CArchive::GetObjectSchema; *pSchema в противном случае будет содержать схему класса времени выполнения, который ранее хранился.

Вместо этого ReadClassможно использоватьSerializeClass, который обрабатывает как чтение, так и запись ссылки на класс.

Пример

Пример см. в примере CArchive::WriteClass.

`CArchive::ReadObject`

Считывает данные объекта из архива и создает объект соответствующего типа.

CObject* ReadObject(const CRuntimeClass* pClass);

Параметры

pClass
Константный указатель на CRuntimeClass структуру, соответствующую объекту, который требуется прочитать.

Возвращаемое значение

Указатель CObject , который должен быть безопасно приведение к правильному производного класса с помощью CObject::IsKindOf.

Замечания

Эта функция обычно вызывается оператором CArchive извлечения ( >>) перегруженным для CObject указателя. ReadObjectв свою очередь вызывает Serialize функцию архивированного класса.

Если вы предоставляете ненулевой pClass параметр, полученный RUNTIME_CLASS макросом, функция проверяет класс времени выполнения архивированного объекта. Предполагается, что макрос использовался IMPLEMENT_SERIAL в реализации класса.

Пример

Пример см. в примере CArchive::WriteObject.

`CArchive::ReadString`

Вызовите эту функцию-член, чтобы считывать текстовые данные в буфер из файла, связанного CArchive с объектом.

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

Параметры

rString
Ссылка на CString строку, которая будет содержать результирующую строку после того, как она будет считываться из файла, связанного CArchive с объектом.

lpsz
Указывает указатель на предоставленный пользователем буфер, который получит текстовую строку, завершающую значение NULL.

nMax
Задает максимальное число символов для чтения. Должно быть меньше размера буфера lpsz .

Возвращаемое значение

В версии, которая возвращает boOL, если выполнено успешно; TRUEFALSE в противном случае.

В версии, которая возвращает LPTSTRуказатель на буфер, содержащий текстовые данные; NULL если достигнут конец файла.

Замечания

В версии функции-члена с nMax параметром буфер будет содержать не более nMax 1 символов. Чтение останавливается парой канала возврата каретки. Конечные новые символы всегда удаляются. Символ NULL ('\0') добавляется в любом случае.

CArchive::Read также доступен для ввода в текстовом режиме, но он не завершается парой канала возвращаемой строки каретки.

Пример

Пример см. в примере CArchive::WriteString.

`CArchive::SerializeClass`

Вызовите эту функцию-член, когда вы хотите хранить и загружать сведения о версии базового класса.

void SerializeClass(const CRuntimeClass* pClassRef);

Параметры

pClassRef
Указатель на объект класса времени выполнения для базового класса.

Замечания

SerializeClass считывает или записывает ссылку на класс в CArchive объект в зависимости от направления CArchiveобъекта. Используйте SerializeClass вместо ReadClass и WriteClass как удобный способ сериализации объектов базового класса; SerializeClass требует меньше кода и меньше параметров.

Например ReadClass, SerializeClass проверяет, совместим ли архивная информация о классе среды выполнения. Если оно несовместимо, SerializeClass вызовет CArchiveExceptionисключение.

Класс среды выполнения должен использовать DECLARE_SERIAL и IMPLEMENT_SERIAL; в противном случае SerializeClass вызовет CNotSupportedExceptionисключение.

RUNTIME_CLASS Используйте макрос для получения значения параметраpRuntimeClass. Базовый IMPLEMENT_SERIAL класс должен использовать макрос.

Пример

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`

Вызов при SetLoadParams чтении большого количества производных CObjectобъектов из архива.

void SetLoadParams(UINT nGrowBy = 1024);

Параметры

nGrowBy
Минимальное количество слотов элементов, выделяемых при необходимости увеличения размера.

Замечания

CArchive использует массив нагрузки для разрешения ссылок на объекты, хранящиеся в архиве. SetLoadParams позволяет задать размер, на который увеличивается массив нагрузки.

Не следует вызывать SetLoadParams после загрузки любого объекта или после MapObject вызова ReadObject .

Пример

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`

Вызовите эту функцию-член, чтобы задать схему объекта, хранящуюся в архивном объекте nSchema.

void SetObjectSchema(UINT nSchema);

Параметры

nSchema
Указывает схему объекта.

Замечания

Следующий вызов GetObjectSchema возвращает значение, хранящееся в nSchema.

Используйте SetObjectSchema для расширенного управления версиями, например, если требуется принудительно считывать определенную версию в Serialize функции производного класса.

Пример

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

`CArchive::SetStoreParams`

Используется SetStoreParams при хранении большого количества производных CObjectобъектов в архиве.

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

Параметры

nHashSize
Размер хэш-таблицы для карт указателя интерфейса. Должно быть простым числом.

nBlockSize
Указывает степень детализации выделения памяти для расширения параметров. Должен быть мощностью 2 для оптимальной производительности.

Замечания

SetStoreParams позволяет задать размер хэш-таблицы и размер блока карты, используемой для идентификации уникальных объектов во время процесса сериализации.

Не следует вызывать SetStoreParams после хранения объектов или после или WriteObject после MapObject вызова.

Пример

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`

Записывает указанное число байтов в архив.

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

Параметры

lpBuf
Указатель на предоставленный пользователем буфер, содержащий данные для записи в архив.

nMax
Целое число, указывающее число байтов, записываемых в архив.

Замечания

Архив не форматировать байты.

Функцию-член Write в Serialize функции можно использовать для записи обычных структур, содержащихся в объектах.

Пример

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

`CArchive::WriteClass`

Используется WriteClass для хранения сведений о версии и классе базового класса во время сериализации производного класса.

void WriteClass(const CRuntimeClass* pClassRef);

Параметры

pClassRef
Указатель на CRuntimeClass структуру, соответствующую запрошенной ссылке класса.

Замечания

WriteClassзаписывает ссылку на CRuntimeClass базовый класс в .CArchive Используется CArchive::ReadClass для получения ссылки.

WriteClass Проверяет, совместим ли архивная информация о классе среды выполнения. Если оно несовместимо, WriteClass вызовет CArchiveExceptionисключение.

Класс среды выполнения должен использовать DECLARE_SERIAL и IMPLEMENT_SERIAL; в противном случае WriteClass вызовет CNotSupportedExceptionисключение.

Вместо этого WriteClassможно использоватьSerializeClass, который обрабатывает как чтение, так и запись ссылки на класс.

Пример

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`

Сохраняет указанный CObject в архиве.

void WriteObject(const CObject* pOb);

Параметры

pOb
Константный указатель на сохраненный объект.

Замечания

Обычно эта функция вызывается оператором CArchive вставки ( <<) перегруженным для CObject. WriteObjectв свою очередь вызывает Serialize функцию архивированного класса.

Для включения архивации необходимо использовать IMPLEMENT_SERIAL макрос. WriteObject записывает имя класса ASCII в архив. Это имя класса проверяется позже во время загрузки. Специальная схема кодирования предотвращает ненужное дублирование имени класса для нескольких объектов класса. Эта схема также предотвращает избыточное хранилище объектов, предназначенных для нескольких указателей.

Точный метод кодирования объектов (включая наличие имени класса ASCII) — это сведения о реализации и может измениться в будущих версиях библиотеки.

Примечание.

Завершите создание, удаление и обновление всех объектов, прежде чем начать архивировать их. Архив будет поврежден, если вы смешаете архивацию с изменением объекта.

Пример

Определение класса CAgeсм. в примере.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`

Эта функция-член используется для записи данных из буфера в файл, связанный CArchive с объектом.

void WriteString(LPCTSTR lpsz);

Параметры

lpsz
Указывает указатель на буфер, содержащий текстовую строку, завершающую значение NULL.

Замечания

Завершающий символ NULL ('\0') не записывается в файл; не записывается новая строка автоматически.

WriteString создает исключение в ответ на несколько условий, включая полное условие диска.

Write также доступен, но вместо того, чтобы завершать символ null, он записывает запрошенное число байтов в файл.

Пример

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

См. также

Диаграмма иерархии
CFile Класса
CObject Класса
CSocket Класса
CSocketFile Класса

Класс 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`

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