CArchive
クラス
オブジェクトが削除された後も保持される永続的なバイナリ形式 (通常はディスク ストレージ) でオブジェクトの複雑なネットワークを保存できます。
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 |
1 行のテキストを読み取ります。 |
CArchive::SerializeClass |
CArchive の方向に応じて、CArchive オブジェクトへのクラス参照を読み書きします。 |
CArchive::SetLoadParams |
読み込み配列のサイズを設定します。 オブジェクトが読み込まれる前、または MapObject または ReadObject が呼び出される前に呼び出す必要があります。 |
CArchive::SetObjectSchema |
アーカイブ オブジェクトに格納されているオブジェクト スキーマを設定します。 |
CArchive::SetStoreParams |
シリアル化プロセス中に一意のオブジェクトを識別するために使用されるマップのハッシュ テーブル サイズとブロック サイズを設定します。 |
CArchive::Write |
生バイトを書き込みます。 |
CArchive::WriteClass |
CRuntimeClass への参照をCArchive に書き込みます。 |
CArchive::WriteObject |
格納するオブジェクトの Serialize 関数を呼び出します。 |
CArchive::WriteString |
1 行のテキストを書き込みます。 |
名前 | 説明 |
---|---|
CArchive::operator << |
オブジェクトとプリミティブ型をアーカイブに格納します。 |
CArchive::operator >> |
アーカイブからオブジェクトとプリミティブ型を読み込みます。 |
名前 | 説明 |
---|---|
CArchive::m_pDocument |
CArchive
には基底クラスはありません。
後で永続ストレージからオブジェクトを読み込み、メモリ内で再構成することができます。 データを永続的にするこのプロセスは、"シリアル化" と呼ばれます。
アーカイブ オブジェクトは、バイナリ ストリームの一種と考えることができます。 入出力ストリームと同様に、アーカイブはファイルに関連付けられるので、ストレージとの間でバッファーに格納されたデータの書き込みと読み取りが可能になります。 入力/出力ストリームは ASCII 文字のシーケンスを処理しますが、アーカイブは効率的な非保証形式でバイナリ オブジェクト データを処理します。
CArchive
オブジェクトを作成する前に、CFile
オブジェクトを作成する必要があります。 さらに、アーカイブの読み込み/ストアの状態がファイルの開いているモードと互換性があることを確認する必要があります。 ファイルごとに 1 つのアクティブなアーカイブに制限されています。
CArchive
オブジェクトを構築するときは、開いているファイルを表すクラス CFile
(または派生クラス) のオブジェクトにアタッチします。 また、アーカイブを読み込みまたは格納に使用するかどうかを指定します。 CArchive
オブジェクトは、プリミティブ型だけでなく、シリアル化用に設計されたCObject
派生クラスのオブジェクトも処理できます。 シリアル化可能なクラスには通常、Serialize
メンバー関数があり、クラス CObject
で説明されているように、通常はDECLARE_SERIAL
マクロとIMPLEMENT_SERIAL
マクロを使用します。
オーバーロードされた抽出 ( >>
) 演算子と挿入 ( <<
) 演算子は、プリミティブ型と CObject
派生クラスの両方をサポートする便利なアーカイブ プログラミング インターフェイスです。
CArchive
では、MFC Windows ソケット クラスの CSocket
と CSocketFile
を使用したプログラミングもサポートされています。 IsBufferEmpty
メンバー関数は、その使用をサポートしています。
CArchive
の詳細については、「SerializationおよびWindows ソケット: アーカイブでのソケットの使用に関する記事を参照してください。
CArchive
ヘッダー: afx.h
例外をスローせずにアーカイブを閉じるには、この関数を呼び出します。
void Abort ();
通常、 CArchive
デストラクターは Close
を呼び出し、関連付けられている CFile
オブジェクトに保存されていないデータをフラッシュします。 これにより、例外が発生する可能性があります。
これらの例外をキャッチするときは、 Abort
を使用することをお勧めします。そのため、 CArchive
オブジェクトを破棄してもそれ以上例外は発生しません。 例外を処理する場合、CArchive::Close
とは異なり、Abort
はエラーを無視するため、CArchive::Abort
はエラー時に例外をスローしません。
new
を使用してCArchive
オブジェクトをヒープに割り当てた場合は、ファイルを閉じた後に削除する必要があります。
CArchive::WriteClass
の例を参照してください。
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
内部ファイル バッファーのサイズをバイト単位で指定する整数。 既定のバッファー サイズは 4,096 バイトであることに注意してください。 大きなオブジェクトを定期的にアーカイブする場合は、ファイル バッファー サイズの倍数である大きなバッファー サイズを使用すると、パフォーマンスが向上します。
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);
バッファーに残っているデータをフラッシュし、アーカイブを閉じて、ファイルからアーカイブを切断します。
void Close();
アーカイブに対するそれ以上の操作は許可されません。 アーカイブを閉じた後は、同じファイル用に別のアーカイブを作成するか、ファイルを閉じます。
メンバー関数 Close
により、すべてのデータがアーカイブからファイルに転送され、アーカイブが使用できなくなります。 ファイルからストレージ メディアへの転送を完了するには、最初に CFile::Close
を使用してから、 CFile
オブジェクトを破棄する必要があります。
CArchive::WriteString の例を参照してください。
アーカイブ バッファーに残っているデータを強制的にファイルに書き込みます。
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();
このアーカイブの CFile
オブジェクト ポインターを取得します。
CFile* GetFile() const;
使用中の CFile
オブジェクトへの定数ポインター。
GetFile
を使用する前に、アーカイブをフラッシュする必要があります。
const CFile *fp = ar.GetFile();
Serialize
関数からこの関数を呼び出して、現在逆シリアル化されているオブジェクトのバージョンを確認します。
UINT GetObjectSchema();
逆シリアル化中に、読み取られるオブジェクトのバージョン。
この関数の呼び出しは、 CArchive
オブジェクトが読み込まれている場合にのみ有効です ( CArchive::IsLoading
は 0 以外を返します)。 Serialize
関数の最初の呼び出しで、1 回だけ呼び出す必要があります。 戻り値 (UINT)-1 は、バージョン番号が不明であることを示します。
CObject
派生クラスでは、VERSIONABLE_SCHEMA
(ビットごとの "or" (|
) を使用) とスキーマ バージョン自体 (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
}
}
このメンバー関数を呼び出して、アーカイブ オブジェクトの内部バッファーが空かどうかを判断します。
BOOL IsBufferEmpty() const;
アーカイブのバッファーが空の場合は 0 以外。それ以外の場合は 0。
この関数は、MFC Windows Sockets クラス CSocketFile
を使用したプログラミングをサポートするために提供されます。 CFile
オブジェクトに関連付けられているアーカイブに使用する必要はありません。
CSocketFile
オブジェクトに関連付けられたアーカイブでIsBufferEmpty
を使用する理由は、アーカイブのバッファーに複数のメッセージまたはレコードが含まれている可能性があるためです。 1 つのメッセージを受信したら、 IsBufferEmpty
を使用して、バッファーが空になるまでデータの受信を続行するループを制御する必要があります。 詳細については、IsBufferEmpty
の使用方法を示すクラス CAsyncSocket
のReceive
メンバー関数を参照してください。
詳細については、「 Windows ソケット: アーカイブでのソケットの使用」を参照してください。
アーカイブがデータを読み込むかどうかを判断します。
BOOL IsLoading() const;
アーカイブが現在読み込みに使用されている場合は 0 以外。それ以外の場合は 0。
このメンバー関数は、アーカイブされたクラスの Serialize
関数によって呼び出されます。
int i = 0;
if (ar.IsLoading())
ar >> i;
else
ar << i;
アーカイブにデータが格納されているかどうかを判断します。
BOOL IsStoring() const;
アーカイブが現在格納に使用されている場合は 0 以外。それ以外の場合は 0。
このメンバー関数は、アーカイブされたクラスの Serialize
関数によって呼び出されます。
アーカイブの IsStoring
状態が 0 以外の場合、 IsLoading
の状態は 0 になり、その逆も同様です。
int i = 0;
if (ar.IsStoring())
ar << i;
else
ar >> i;
このメンバー関数を呼び出して、実際にはファイルにシリアル化されていないが、サブオブジェクトが参照できるオブジェクトをマップに配置します。
void MapObject(const CObject* pOb);
pOb
格納されているオブジェクトへの定数ポインター。
たとえば、ドキュメントをシリアル化しない場合は、ドキュメントの一部であるアイテムをシリアル化します。 MapObject
を呼び出すと、それらのアイテムまたはサブオブジェクトがドキュメントを参照できるようになります。 また、シリアル化されたサブ項目は、 m_pDocument
戻るポインターをシリアル化できます。
CArchive
オブジェクトに格納して読み込むときに、MapObject
を呼び出すことができます。 MapObject
は、シリアル化と逆シリアル化の間に CArchive
オブジェクトによって保持される内部データ構造に指定されたオブジェクトを追加しますが、 ReadObject
や WriteObject
とは異なり、オブジェクトに対してシリアル化を呼び出しません。
//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;
}
}
既定では、 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);
指定されたオブジェクトまたはプリミティブ型をアーカイブに格納します。
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);
1 行に複数の挿入演算子を有効にする CArchive
参照。
上記の最後の 2 つのバージョンは、64 ビット整数を格納するためのものです。
クラス実装で IMPLEMENT_SERIAL
マクロを使用した場合、 CObject
に対してオーバーロードされた挿入演算子によって、保護された WriteObject
が呼び出されます。 この関数は、クラスの Serialize
関数を呼び出します。
CStringT
挿入演算子 (<<
) は、診断ダンプとアーカイブへの格納をサポートします。
この例では、int
型とlong
型で<<
CArchive
挿入演算子を使用する方法を示します。
long l = 5;
int i = 10;
if (ar.IsStoring())
ar << l << i;
この例では、CStringT
型でCArchive
挿入演算子<<
を使用する方法を示します。
CString s("abc");
ar << s; // Prints the value (abc)
指定されたオブジェクトまたはプリミティブ型をアーカイブから読み込みます。
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);
1 行で複数の抽出演算子を有効にする CArchive
参照。
上記の最後の 2 つのバージョンは、64 ビット整数を読み込むためのバージョンです。
クラス実装で IMPLEMENT_SERIAL
マクロを使用した場合、 CObject
に対してオーバーロードされた抽出演算子は、保護された ReadObject
関数を呼び出します (0 以外のランタイム クラス ポインターを使用)。 この関数は、クラスの Serialize
関数を呼び出します。
CStringT
抽出演算子 (>>
) は、アーカイブからの読み込みをサポートしています。
この例では、int
型でCArchive
抽出演算子>>
を使用する方法を示します。
long l;
int i;
if (ar.IsLoading())
ar >> l >> i;
この例では、CStringT
型で<<
および>>
CArchive
挿入および抽出演算子を使用する方法を示します。
CString s;
if (ar.IsLoading())
ar >> s;
指定したバイト数をアーカイブから読み取ります。
UINT Read(void* lpBuf, UINT nMax);
lpBuf
アーカイブから読み取られたデータを受信する、ユーザーが指定したバッファーへのポインター。
nMax
アーカイブから読み取るバイト数を指定する符号なし整数。
実際に読み取られたバイト数を含む符号なし整数。 戻り値が要求された数より小さい場合、ファイルの末尾に達しました。 ファイルの末尾の条件では例外はスローされません。
アーカイブはバイトを解釈しません。
Serialize
関数内の Read
メンバー関数を使用して、オブジェクトに含まれる通常の構造体を読み取ることができます。
char pbRead[100];
ar.Read(pbRead, 100);
このメンバー関数を呼び出して、以前に 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
の例を参照してください。
アーカイブからオブジェクト データを読み取り、適切な型のオブジェクトを構築します。
CObject* ReadObject(const CRuntimeClass* pClass);
pClass
読み取るオブジェクトに対応する CRuntimeClass
構造体への定数ポインター。
CObject::IsKindOf
を使用して適切な派生クラスに安全にキャストする必要があるCObject
ポインター。
通常、この関数は、CObject
ポインターに対してオーバーロードされたCArchive
抽出 (>>
) 演算子によって呼び出されます。 ReadObject
次に、アーカイブされたクラスの Serialize
関数を呼び出します。
RUNTIME_CLASS
マクロによって取得される 0 以外の pClass
パラメーターを指定した場合、関数はアーカイブオブジェクトのランタイム クラスを検証します。 これは、クラスの実装で IMPLEMENT_SERIAL
マクロを使用していることを前提としています。
CArchive::WriteObject
の例を参照してください。
このメンバー関数を呼び出して、 CArchive
オブジェクトに関連付けられているファイルからバッファーにテキスト データを読み取ります。
BOOL ReadString(CString& rString);
LPTSTR ReadString(LPTSTR lpsz, UINT nMax);
rString
CArchive
オブジェクトに関連付けられているファイルから読み取られた後に結果の文字列を格納するCString
への参照。
lpsz
null で終わるテキスト文字列を受け取る、ユーザー指定のバッファーへのポインターを指定します。
nMax
読み取る最大文字数を指定します。 lpsz
バッファーのサイズより 1 小さい値にする必要があります。
BOOL を返すバージョンでは、成功した場合は TRUE
。それ以外の場合 FALSE
。
LPTSTR
を返すバージョンでは、テキスト データを含むバッファーへのポインター。ファイルの末尾に達した場合にNULL
。
nMax
パラメーターを持つメンバー関数のバージョンでは、バッファーは最大 nMax
- 1 文字の制限を保持します。 読み取りは、復帰ライン フィードペアによって停止されます。 末尾の改行文字は常に削除されます。 どちらの場合も、 NULL
文字 ('\0') が追加されます。
CArchive::Read
はテキスト モード入力でも使用できますが、復帰改行ペアでは終了しません。
CArchive::WriteString
の例を参照してください。
基底クラスのバージョン情報を格納して読み込む場合は、このメンバー関数を呼び出します。
void SerializeClass(const CRuntimeClass* pClassRef);
pClassRef
基底クラスのランタイム クラス オブジェクトへのポインター。
SerializeClass
は、CArchive
の方向に応じて、CArchive
オブジェクトへのクラスへの参照を読み書きします。 基底クラス オブジェクトをシリアル化する便利な方法として、ReadClass
とWriteClass
の代わりにSerializeClass
を使用します。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);
}
アーカイブから多数のCObject
派生オブジェクトを読み取る場合は、SetLoadParams
を呼び出します。
void SetLoadParams(UINT nGrowBy = 1024);
nGrowBy
サイズの増加が必要な場合に割り当てる要素スロットの最小数。
CArchive
では、load 配列を使用して、アーカイブに格納されているオブジェクトへの参照を解決します。 SetLoadParams
では、読み込み配列が拡大するサイズを設定できます。
オブジェクトが読み込まれた後、またはMapObject
またはReadObject
が呼び出された後に、SetLoadParams
を呼び出してはなりません。
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
}
}
このメンバー関数を呼び出して、アーカイブ オブジェクトに格納されているオブジェクト スキーマを nSchema
に設定します。
void SetObjectSchema(UINT nSchema);
nSchema
オブジェクトのスキーマを指定します。
次に GetObjectSchema
を呼び出すと、 nSchema
に格納されている値が返されます。
高度なバージョン管理には SetObjectSchema
を使用します。たとえば、派生クラスの Serialize
関数で特定のバージョンを強制的に読み取る場合などです。
ar.SetObjectSchema(2);
ASSERT(2 == ar.GetObjectSchema());
多数のCObject
派生オブジェクトをアーカイブに格納する場合は、SetStoreParams
を使用します。
void SetStoreParams(UINT nHashSize = 2053, UINT nBlockSize = 128);
nHashSize
インターフェイス ポインター マップのハッシュ テーブルのサイズ。 素数にする必要があります。
nBlockSize
パラメーターを拡張するためのメモリ割り当ての粒度を指定します。 最適なパフォーマンスを得るための 2 の累乗である必要があります。
SetStoreParams
では、シリアル化プロセス中に一意のオブジェクトを識別するために使用されるマップのハッシュ テーブル サイズとブロック サイズを設定できます。
オブジェクトが格納された後、またはMapObject
またはWriteObject
が呼び出された後に、SetStoreParams
を呼び出してはなりません。
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
}
}
指定したバイト数をアーカイブに書き込みます。
void Write(const void* lpBuf, INT nMax);
lpBuf
アーカイブに書き込むデータを含むユーザー指定のバッファーへのポインター。
nMax
アーカイブに書き込むバイト数を指定する整数。
アーカイブはバイトの書式を設定しません。
Serialize
関数内で Write
メンバー関数を使用して、オブジェクトに含まれる通常の構造体を記述できます。
char pbWrite[100];
memset(pbWrite, 'a', 100);
ar.Write(pbWrite, 100);
派生クラスのシリアル化中に基底クラスのバージョンとクラス情報を格納するには、 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();
}
指定した CObject
をアーカイブに格納します。
void WriteObject(const CObject* pOb);
pOb
格納されているオブジェクトへの定数ポインター。
この関数は、通常、CObject
に対してオーバーロードされたCArchive
挿入 (<<
) 演算子によって呼び出されます。 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
オブジェクトに関連付けられているファイルにデータを書き込むには、このメンバー関数を使用します。
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);