`CArchive` クラス

[アーティクル]
10/12/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`	1 行のテキストを読み取ります。
`CArchive::SerializeClass`	の方向に応じて、オブジェクトへのクラス参照を `CArchive` 読み書きします `CArchive`。
`CArchive::SetLoadParams`	読み込み配列のサイズを設定します。オブジェクトが読み込まれる前または前に呼び出されるか、呼`ReadObject`び出される前に`MapObject`呼び出す必要があります。
`CArchive::SetObjectSchema`	アーカイブオブジェクトに格納されているオブジェクトスキーマを設定します。
`CArchive::SetStoreParams`	シリアル化プロセス中に一意のオブジェクトを識別するために使用されるマップのハッシュテーブルサイズとブロックサイズを設定します。
`CArchive::Write`	生バイトを書き込みます。
`CArchive::WriteClass`	への参照を`CRuntimeClassCArchive`書き込みます。
`CArchive::WriteObject`	格納するオブジェクトの `Serialize` 関数を呼び出します。
`CArchive::WriteString`	1 行のテキストを書き込みます。

パブリック演算子

名前	説明
`CArchive::operator <<`	オブジェクトとプリミティブ型をアーカイブに格納します。
`CArchive::operator >>`	アーカイブからオブジェクトとプリミティブ型を読み込みます。

パブリックデータメンバー

名前	説明
`CArchive::m_pDocument`

解説

CArchive には基底クラスはありません。

後で永続ストレージからオブジェクトを読み込み、メモリ内で再構成することができます。データを永続的にするこのプロセスは、"シリアル化" と呼ばれます。

アーカイブオブジェクトは、バイナリストリームの一種と考えることができます。入出力ストリームと同様に、アーカイブはファイルに関連付けられるので、ストレージとの間でバッファーに格納されたデータの書き込みと読み取りが可能になります。入力/出力ストリームは ASCII 文字のシーケンスを処理しますが、アーカイブは効率的な非保証形式でバイナリオブジェクトデータを処理します。

オブジェクトを CFile 作成する前に、オブジェクトを作成する CArchive 必要があります。さらに、アーカイブの読み込み/ストアの状態がファイルの開いているモードと互換性があることを確認する必要があります。ファイルごとに 1 つのアクティブなアーカイブに制限されています。

オブジェクトを CArchive 構築するときは、開いているファイルを表すクラス CFile (または派生クラス) のオブジェクトにアタッチします。また、アーカイブを読み込みまたは格納に使用するかどうかを指定します。オブジェクトは CArchive 、プリミティブ型だけでなく、シリアル化用に設計された -derived クラスの CObjectオブジェクトも処理できます。シリアル化可能なクラスにはSerialize通常、メンバー関数があり、クラスで説明CObjectされているように、通常は、およびIMPLEMENT_SERIALマクロをDECLARE_SERIAL使用します。

オーバーロードされた抽出 ( >>) 演算子と挿入 ( <<) 演算子は、プリミティブ型と CObject-派生クラスの両方をサポートする便利なアーカイブプログラミングインターフェイスです。

CArchive MFC Windows ソケットクラス CSocket を使用したプログラミングもサポートしています CSocketFile。メンバー関数は IsBufferEmpty 、その使用をサポートしています。

詳細についてはCArchive、シリアル化と Windows ソケット: アーカイブでのソケットの使用に関する記事を参照してください。

継承階層

CArchive

必要条件

ヘッダー:afx.h

`CArchive::Abort`

例外をスローせずにアーカイブを閉じるには、この関数を呼び出します。

void Abort ();

解説

デストラクターはCArchive通常、関連付けられたCFileオブジェクトに保存されていないデータをフラッシュする呼び出しCloseを行います。これにより、例外が発生する可能性があります。

これらの例外をキャッチするときは、オブジェクトを破棄CArchiveしてもそれ以上例外が発生しないように、使用Abortすることをお勧めします。例外を処理する場合、エラーとは異なりCArchive::CloseAbort、CArchive::Abortエラーが無視されるため、エラー時に例外はスローされません。

ヒープにオブジェクトをCArchive割り当てた場合newは、ファイルを閉じた後にオブジェクトを削除する必要があります。

例

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
内部ファイルバッファーのサイズをバイト単位で指定する整数。既定のバッファーサイズは 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);

`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 0 以外の値を返します)。これは関数の最初の呼び出しで Serialize 、1 回だけ呼び出す必要があります。戻り値 (UINT)-1 は、バージョン番号が不明であることを示します。

CObject派生クラスは、スキーマバージョン自体 IMPLEMENT_SERIAL (マクロ内) と組み合わせて (ビットごとの "or" (|)) を使用VERSIONABLE_SCHEMAして、"バージョン管理可能なオブジェクト" を作成できます。つまり、メンバー関数が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 以外。それ以外の場合は 0。

解説

この関数は、MFC Windows ソケットクラス CSocketFileを使用したプログラミングをサポートするために提供されます。オブジェクトに関連付 CFile けられているアーカイブに使用する必要はありません。

オブジェクトに関連付けられたCSocketFileアーカイブと共に使用IsBufferEmptyする理由は、アーカイブのバッファーに複数のメッセージまたはレコードが含まれている可能性があるためです。 1 つのメッセージを受信した後、バッファーが空になるまでデータの受信を続行するループを制御するために使用 IsBufferEmpty する必要があります。詳細については、使用する方法を Receive 示すクラス CAsyncSocketのメンバー関数を IsBufferEmpty参照してください。

詳細については、「Windows ソケット: アーカイブでのソケットの使用」を参照してください。

`CArchive::IsLoading`

アーカイブがデータを読み込むかどうかを判断します。

BOOL IsLoading() const;

戻り値

アーカイブが現在読み込みに使用されている場合は 0 以外。それ以外の場合は 0。

解説

このメンバー関数は、アーカイブされたクラスの関数によって Serialize 呼び出されます。

例

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

`CArchive::IsStoring`

アーカイブにデータが格納されているかどうかを判断します。

BOOL IsStoring() const;

戻り値

アーカイブが現在格納に使用されている場合は 0 以外。それ以外の場合は 0。

解説

このメンバー関数は、アーカイブされたクラスの関数によって Serialize 呼び出されます。

アーカイブの IsStoring 状態が 0 以外の場合、その IsLoading 状態は 0 になり、その逆も同様です。

例

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

`CArchive::MapObject`

このメンバー関数を呼び出して、実際にはファイルにシリアル化されていないが、サブオブジェクトが参照できるオブジェクトをマップに配置します。

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

`CArchive::m_pDocument`

NULL既定では、このポインターを a 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 1 行で複数の挿入演算子を有効にする参照。

解説

上記の最後の 2 つのバージョンは、64 ビット整数を格納するためのものです。

クラス実装でマクロを使用したIMPLEMENT_SERIAL場合、保護WriteObjectされた呼び出しに対してCObjectオーバーロードされた挿入演算子。この関数は、クラスの関数を Serialize 呼び出します。

挿入演算子 (<<) はCStringT、診断ダンプとアーカイブへの格納をサポートします。

例

この例では、挿入演算子<<と型をCArchive使用する方法をlongint示します。

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 1 行で複数の抽出演算子を有効にする参照。

解説

上記の最後の 2 つのバージョンは、64 ビット整数を読み込むためのバージョンです。

クラス実装でマクロを IMPLEMENT_SERIAL 使用した場合、保護された関数の呼び出しに対して CObject オーバーロードされた ReadObject 抽出演算子 (0 以外のランタイムクラスポインターを使用)。この関数は、クラスの関数を 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 構造体へのポインター。

解説

そうでないNULL場合pClassRefRequestedは、ReadClassアーカイブされたクラス情報がランタイムクラスと互換性があることを確認します。互換性がない場合は、 ReadClassCArchiveException.

ランタイムクラスは使用DECLARE_SERIALする必要があり、IMPLEMENT_SERIALReadClassそれ以外の場合は CNotSupportedException.

存在する場合はNULL、格納されているクラスのスキーマを呼び出CArchive::GetObjectSchemaすことによって取得できます。それ以外の場合pSchemaは、*pSchema以前に格納されていたランタイムクラスのスキーマが含まれます。

代わりに、 SerializeClass クラス参照の ReadClass読み取りと書き込みの両方を処理します。

例

CArchive::WriteClass の例を参照してください。

`CArchive::ReadObject`

アーカイブからオブジェクトデータを読み取り、適切な型のオブジェクトを構築します。

CObject* ReadObject(const CRuntimeClass* pClass);

パラメーター

pClass
読み取る CRuntimeClass オブジェクトに対応する構造体への定数ポインター。

戻り値

を CObject 使用 CObject::IsKindOfして正しい派生クラスに安全にキャストする必要があるポインター。

解説

この関数は通常、ポインターに対CObjectしてCArchiveオーバーロードされた抽出 ( >>) 演算子によって呼び出されます。 ReadObject次に、アーカイブされたクラスの関数を呼び出します Serialize 。

マクロによって取得される 0 以外 pClass のパラメーターを RUNTIME_CLASS 指定すると、関数はアーカイブされたオブジェクトの実行時クラスを検証します。これは、クラスの実装でマクロを IMPLEMENT_SERIAL 使用していることを前提としています。

例

CArchive::WriteObject の例を参照してください。

`CArchive::ReadString`

このメンバー関数を呼び出して、オブジェクトに関連付けられているファイルからバッファーにテキストデータを CArchive 読み取ります。

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

パラメーター

rString
オブジェクトに関連付CArchiveけられているファイルから読み取られた後に、結果の文字列を格納する a へのCString参照。

lpsz
null で終わるテキスト文字列を受け取る、ユーザー指定のバッファーへのポインターを指定します。

nMax
読み取る最大文字数を指定します。バッファーのサイズより 1 小さい値にする lpsz 必要があります。

戻り値

成功FALSEした場合は BOOL を返すバージョン。TRUEそれ以外の場合。

テキストデータNULLを含むバッファーへのポインター (ファイルの末尾に達した場合) を返すLPTSTRバージョン。

解説

パラメーターを持つ nMax メンバー関数のバージョンでは、バッファーは最大 1 文字の nMax 制限を保持します。読み取りは、復帰ラインフィードペアによって停止されます。末尾の改行文字は常に削除されます。 NULLどちらの場合も、文字 ('\0') が追加されます。

CArchive::Read はテキストモード入力でも使用できますが、復帰改行ペアでは終了しません。

例

CArchive::WriteString の例を参照してください。

`CArchive::SerializeClass`

基底クラスのバージョン情報を格納して読み込む場合は、このメンバー関数を呼び出します。

void SerializeClass(const CRuntimeClass* pClassRef);

パラメーター

pClassRef
基底クラスのランタイムクラスオブジェクトへのポインター。

解説

SerializeClass の方向に応じて、クラスへの参照を CArchive オブジェクトに読み書きします CArchive。基底クラスオブジェクトSerializeClassをReadClassWriteClassシリアル化する便利な方法として、代わりに使用SerializeClassします。必要なコードが少なく、パラメーターも少なくなります。

同様 ReadClassに、 SerializeClass アーカイブされたクラス情報がランタイムクラスと互換性があることを確認します。互換性がない場合は、 SerializeClassCArchiveException.

ランタイムクラスは使用DECLARE_SERIALする必要があり、IMPLEMENT_SERIALSerializeClassそれ以外の場合は 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`

アーカイブから多数のCObject派生オブジェクトを読み取るときに呼び出SetLoadParamsします。

void SetLoadParams(UINT nGrowBy = 1024);

パラメーター

nGrowBy
サイズの増加が必要な場合に割り当てる要素スロットの最小数。

解説

CArchive では、load 配列を使用して、アーカイブに格納されているオブジェクトへの参照を解決します。 SetLoadParams では、読み込み配列が拡大するサイズを設定できます。

オブジェクトが読み込まれた後、または呼び出された後、またはReadObject呼び出された後MapObjectに呼び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
   }
}

`CArchive::SetObjectSchema`

このメンバー関数を呼び出して、アーカイブオブジェクトに格納されているオブジェクトスキーマを次の値に nSchema設定します。

void SetObjectSchema(UINT nSchema);

パラメーター

nSchema
オブジェクトのスキーマを指定します。

解説

次の呼び出し GetObjectSchema では、格納されている nSchema値が返されます。

高度なバージョン管理に使用します。たとえば、派生クラスの関数でSerialize特定のバージョンを強制的に読み取る場合に使用SetObjectSchemaします。

例

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

`CArchive::SetStoreParams`

多数のCObject派生オブジェクトをアーカイブに格納する場合に使用SetStoreParamsします。

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

パラメーター

nHashSize
インターフェイスポインターマップのハッシュテーブルのサイズ。素数にする必要があります。

nBlockSize
パラメーターを拡張するためのメモリ割り当ての粒度を指定します。最適なパフォーマンスを得るための 2 の累乗である必要があります。

解説

SetStoreParams では、シリアル化プロセス中に一意のオブジェクトを識別するために使用されるマップのハッシュテーブルサイズとブロックサイズを設定できます。

オブジェクトが格納された後、または呼び出された後、またはWriteObject呼びSetStoreParams出された後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
アーカイブに書き込むバイト数を指定する整数。

解説

アーカイブはバイトの書式を設定しません。

関数内でメンバー関数をWriteSerialize使用して、オブジェクトに含まれる通常の構造体を記述できます。

例

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

`CArchive::WriteClass`

派生クラスのシリアル化中に基底クラスのバージョンとクラス情報を格納するために使用 WriteClass します。

void WriteClass(const CRuntimeClass* pClassRef);

パラメーター

pClassRef
要求された CRuntimeClass クラス参照に対応する構造体へのポインター。

解説

WriteClassへの基底クラスCArchiveへのCRuntimeClass参照を書き込みます。参照を取得するために使用 CArchive::ReadClass します。

WriteClass は、アーカイブされたクラス情報がランタイムクラスと互換性があることを確認します。互換性がない場合は、 WriteClassCArchiveException.

ランタイムクラスは使用DECLARE_SERIALする必要があり、IMPLEMENT_SERIALWriteClassそれ以外の場合は CNotSupportedException.

代わりに、 SerializeClass クラス参照の WriteClass読み取りと書き込みの両方を処理します。

例

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 クラス名の存在を含む) は実装の詳細であり、今後のバージョンのライブラリで変更される可能性があります。

Note

アーカイブを開始する前に、すべてのオブジェクトの作成、削除、および更新を完了します。アーカイブとオブジェクトの変更を組み合わせた場合、アーカイブは破損します。

例

クラス 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);

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`