Функции-члены класса

Archive (CFile* pFile, UINT nMode, int nBufSize = 4096, void* lpBuf= NULL); throw (CMemoryException, CArchiveException, CFileException);

Конструктор класса. Параметры:

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

nMode - флажок, определяющий статус архива: загрузка данных из архива или сохранение данных. Этот параметр может принимать следующие зна­чения:

CArchive::Ioad - загрузка данных из архива. Объект CFile должен быть дос­тупен на чтение; CArchive::store - сохранение данных в архиве. Объект CFile должен быть

доступен на запись;

CArchive::bNoFlushOnDelete - предотвращает автоматический вызов метода Flush при выполнении деструктора. Отметим, что при установке данного флажка необходимо напрямую вызывать метод Close до вызова деструк­тора.

nBufSize - размер в байтах внутреннего файлового буфера. По умолчанию этот размер равен 4096 байт.

ipBuf - необязательный параметр, который позволяет передать методу опре­деленный пользователем указатель на буфер размера nBufSize. Если этот па­раметр не указан, то буфер размещается в динамически распределяемой области памяти, называемой также кучей. В этом случае память будет осво­бождена сразу при разрушении объекта. Отметим, что область памяти, ука­занная пользователем через данный параметр, не освобождается автомати­чески при разрушении объекта.

Конструктор создает объект CArchive и определяет статус его использо­вания: для загрузки или для сохранения объекта. Статус архива нельзя из­менить после его создания. Также до закрытия архива нельзя использовать операции CFile для изменения его состояния.

Пример:

extern char* pFileName; CFile f; charbuf!512]; if( !f.Open( pFileName, CFile::modeCreate | CFile::modeWrite )) { #ifdef_DEBUG afxDump << "Нельзя открыть файл" << "\n"; exit( 1 ); #endif

} CArchive ar(&f, CArchive::store, 512, buf);

void Abort ( );

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

void Close( ); throw( CArchiveException, CFileException );

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

void Flush( ); throw( CFileException );

Инициирует запись (сброс) в файл оставшихся в архиве данных. CFile* GetFile( ) const;

Метод возвращает указатель на используемый объект типа CFile. Отме­тим, что до вызова данного метода следует сбросить архив.

Пример:

extern CArchive ar; [const CFile* fp = ar.GetFileQ;

UINT GetObjectSchema();

Метод возвращает читаемую во время сериализации версию объекта. Этот метод вызывается из метода Serialize и доступен, только если в архив! выполнена загрузка. Если версия не определена, то метод возвращает зна-1 чение (UINT)-l. Пример:

Ц Реализация "версионного" объекта

IMPLEMENT_SERIAL(CMyObject, CObject, VERSIONABLE_SCHEMA|1) void CMyObject.:Serialize(CArchive& ar) // Переопределение метода Serialize

{ if (ar.IsLoading()) // Была выполнена загрузка данных в архив!

{

int nVersion = ar.GetObjectSchema();

switch(nVersion)

{ case 0:

// Чтение предыдущей версии данного объекта

break; case 1:

// Чтение текущей версии

break; default:

// Получен неизвестный номер версии

break; }

} .

else

{

// Программный код для записи переменных в архив

} } BOOL IsBufferEmpty( ) const;

В случае пустого буфера метод возвращает ненулевое значение, и 0 - в противном случае. Эта функция используется для объектов класса CSocketFile.

Так как буфер архива, присоединенного к объекту CSocketFile, может содержать более одного сообщения или записи, то после получения каж­дого сообщения следует проверять, все ли сообщения переданы.

BOOL IsLoading( ) const;

Если текущий архив используется для загрузки данных (чтения из архива), то метод возвращает ненулевое значение, и 0 - в противном случае.

Этот метод вызывается, как правило, из метода Serialize для определе­ния статуса архива.

Пример:

int i; extern CArchive ar; if( ar.IsLoading()) ar » ц ' // Чтение из архива else __ar << i; // Запись в архив

BOOL IsStoring( ) const;

Если текущий архив используется для сохранения данных (записи в ар­хив), то метод возвращает ненулевое значение, и 0 - в противном случае.

Этот метод вызывается, как правило, из метода Serialize для определен] ния статуса архива.

void MapObject( const CObject*^0Z>);

Этот метод позволяет размещать в таблице объекты и в дальнейшем ис-| пользовать их для ссылки на документ. Как правило, это используется в том случае, если документ подлежит сериализации не непосредственно, а как отдельный элемент (подобъект).

Параметры:

рОЪ - указатель на сохраняемый объект. Пример:

II Файл MyDoc.h

// Для документа следует указать DECLARE_SERIAL и IMPLEMENT_SERIAL

class CMyDocument: public CDocument

{ CObList mJistOfSubltems;

DECLARE_SERIAL(CMyDocument)

};

// Файл MyDoc.cpp IMPLEMENT_SERIAL(CMyDocument, CObject, 1)

void CMyDocument::Serialize(CArchive& ar)

{

if (ar.IsStoringO) {

// TODO: add storing code here

// TODO: add loading code here ar.MapObject(this);

// Файл Subltem.h

class CSubltem : public CObject

public:

CSubItem(CMyDocument * pDoc)

{ m_pDoc = pDoc; } // Обратный указатель на документ CMyDocument* m_pDoc; WORD mi; // Другой элемент данных virtual void Serialize(CArchive& ar);

};

// Файл Subltem.cpp

void CSubItem::Serialize(CArchive& ar)

{

if (ar.IsStoringO) {

ar << m_pDoc; ar << m_i; }

else {

ar » m_pDoc; ar » rh_i; } } UINT Read( void* ipBuf, UINT nMax); throw( CFileException );

Метод возвращает число прочитанных байт. Если возвращаемое значе­ние меньше указанного параметром, то, следовательно, достигнут конец файла.

Параметры:

IpBuf- указатель буфера, в который производится чтение данных из архива. пМах - количество читаемых их архива байт. Пример:

extern CArchive ar; char pbuf[ 100]; UINT nr = ar.Read( pbuf, 100 );

CRuntimeClass* ReadClass (const CRuntimeClass* pClassRefRequested = NULL, UINT* pSchema = NULL, DWORD* obTag = NULL); Throw CArchiveException; Throw CNotSupportedException;

Метод возвращает указатель на структуру CRuntimeClass. Этот метод следует использовать для получения ссылки на класс, ранее сохраненный методом WriteClass.

CObject* ReadObject (const CRuntimeClass* pClass);

throw (CFileException, CArchiveException, CMemoryException );

Метод читает из архива данные объекта и создает объект соответствую­щего типа, возвращая указатель CObject.

Параметры:

Р Class - указатель структуры CRuntimeClass, соответствующей читаемому объекту.

Bool ReadString(CString& rString);

LPTSTR ReadString( LPTSTR Ipsz, UINT nMax ); throw( CArchiveException);

При успешном чтении строки первый метод возвращает значение TRUE, а второй - указатель на буфер, содержащий текстовые данные. В противном случае первый метод возвращает значение FALSE, а вто­рой - NULL (достигнут конец файла).

Параметры:

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

Ipsz - указатель буфера, в который будет записана читаемая строка. пМах - максимальное количество читаемых символов. void SerializeCIass( const CRuntimeClass* pRuntimeClass );

Этот метод используется для сохранения или загрузки информации ба­зового класса. Он читает или записывает в объект CArchive. Пример:

class CBaseClass : public CObject {... };

class CDerivedClass : public CBaseClass { ... };

void CDerivedClass::Serialize(CArchive& ar) // Переопределение метода

Serialize

{

if(ar.IsStoring())

{ // Код, сохраняющий объект

}

else

{ // Код, читающий объект

}

ar.SerializeClass(RUNTIME_CLASS(CBaseClass)); CBaseClass:: Serialize(ar); } void SetLoadParams( UINT nGrowBy = 1024 );

Этот метод следует использовать в том случае, если требуется, прочитать из архива большое количество объектов, производных от класса CObject. CArchive использует для ссылок на объекты, хранимые в архиве, загружае­мый массив. Данный метод позволяет увеличить размер этого массива. От­метим, что если какой-либо объект уже был загружен или были вызваны ме­тоды MapObject или ReadObject, то использовать данный метод уже нельзя. Пример:

class CMyLargeDocument : public CDocument { ... }; void CMyLargeDocument::Serialize(CArchive& ar)

{

if (ar.IsStoringO)

ar. SetStoreParams(); else

ar. SetLoadParamsO;

if (ar.IsStoringO)

{

// Код для сохранения CMyLargeDocument }

else {

// Код для загрузки CMyLargeDocument } } void SetObjectSchema( UINT nSchema );

Параметры:

nSchema - определяет схему объекта. void SetStoreParams (UINT nHashSize = 2053, UINT nBlockSize = 128);

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

void Write (const void* ipBuf, UINT nMax); throw (CFileException);

Метод выполняет запись в архив указанного количества байт.

Параметры:

IpBuf- буфер, содержащий данные, записываемые в архив. пМах - количество записываемых байт.