`CArchive` クラス

[アーティクル]
07/05/2024

オブジェクトが削除された後も保持される永続的なバイナリ形式 (通常はディスクストレージ) でオブジェクトの複雑なネットワークを保存できます。

構文

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

`CArchive::Abort`

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

void Abort ();

解説

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

これらの例外をキャッチするときは、 Abortを使用することをお勧めします。そのため、 CArchive オブジェクトを破棄してもそれ以上例外は発生しません。例外を処理する場合、CArchive::Closeとは異なり、Abortはエラーを無視するため、CArchive::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
内部ファイルバッファーのサイズをバイト単位で指定する整数。既定のバッファーサイズは 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派生クラスでは、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
   }
}

`CArchive::IsBufferEmpty`

このメンバー関数を呼び出して、アーカイブオブジェクトの内部バッファーが空かどうかを判断します。

BOOL IsBufferEmpty() const;

戻り値

アーカイブのバッファーが空の場合は 0 以外。それ以外の場合は 0。

解説

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

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

詳細については、「 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 に設定すると、 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);

戻り値

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)

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

戻り値

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;

`CArchive::Read`

指定したバイト数をアーカイブから読み取ります。

UINT Read(void* lpBuf, UINT nMax);

パラメーター

lpBuf
アーカイブから読み取られたデータを受信する、ユーザーが指定したバッファーへのポインター。

nMax
アーカイブから読み取るバイト数を指定する符号なし整数。

戻り値

実際に読み取られたバイト数を含む符号なし整数。戻り値が要求された数より小さい場合、ファイルの末尾に達しました。ファイルの末尾の条件では例外はスローされません。

解説

アーカイブはバイトを解釈しません。

Serialize関数内の Read メンバー関数を使用して、オブジェクトに含まれる通常の構造体を読み取ることができます。

例

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::IsKindOfを使用して適切な派生クラスに安全にキャストする必要があるCObject ポインター。

解説

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

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

例

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

`CArchive::ReadString`

このメンバー関数を呼び出して、 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 の例を参照してください。

`CArchive::SerializeClass`

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

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

`CArchive::SetLoadParams`

アーカイブから多数の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
   }
}

`CArchive::SetObjectSchema`

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

void SetObjectSchema(UINT nSchema);

パラメーター

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

解説

次に GetObjectSchema を呼び出すと、 nSchemaに格納されている値が返されます。

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

例

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

`CArchive::SetStoreParams`

多数の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
   }
}

`CArchive::Write`

指定したバイト数をアーカイブに書き込みます。

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

パラメーター

lpBuf
アーカイブに書き込むデータを含むユーザー指定のバッファーへのポインター。

nMax
アーカイブに書き込むバイト数を指定する整数。

解説

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

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

例

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
格納されているオブジェクトへの定数ポインター。

解説

この関数は、通常、CObjectに対してオーバーロードされたCArchive挿入 (<<) 演算子によって呼び出されます。 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`