`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 Sockets 接收程式期間清空。
`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 字元的序列，但封存會以有效率、非不健全的格式處理二進位物件資料。

您必須先建立 CFile 物件，才能建立 CArchive 物件。此外，您必須確定封存的載入/存放區狀態與檔案的開啟模式相容。每個檔案只能有一個使用中封存檔。

當您建構 CArchive 物件時，會將它附加至代表開啟檔案的類別 CFile 物件（或衍生類別）。您也會指定封存是否會用於載入或儲存。 CArchive物件不僅可以處理基本類型，還可以處理專為序列化所設計之衍生類別的物件 CObject 。可序列化類別通常具有 Serialize 成員函式，而且通常會使用 DECLARE_SERIAL 和 IMPLEMENT_SERIAL 宏，如類別 CObject 中所述。

多載擷取（）和插入（ >><< ）運算子是方便封存程式設計介面，可同時支援基本類型和 CObject 衍生類別。

CArchive 也支援使用 MFC Windows Sockets 類別 CSocket 和 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
整數，指定內部檔案緩衝區的大小，以位元組為單位。請注意，預設緩衝區大小為 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 傳回非零）。它應該是函式中的 Serialize 第一個呼叫，而且只呼叫一次。傳回值（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。

備註

此函式提供以支援使用 MFC Windows Sockets 類別 CSocketFile 的程式設計。您不需要將它用於與 CFile 物件相關聯的封存。

與物件相關聯的 CSocketFile 封存使用 IsBufferEmpty 的原因是封存的緩衝區可能包含多個訊息或記錄。收到一則訊息之後，您應該使用 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 背面指標。

您可以在儲存和載入 CArchive 物件時呼叫 MapObject 。 MapObject在序列化和還原序列化期間，將指定的物件加入物件所維護 CArchive 的內部資料結構，但與和 WriteObject 不同 ReadObject ，它不會在物件上呼叫序列化。

範例

//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 取運算子（ >> ）支援從封存載入。

範例

此範例示範搭配 int 型別使用 CArchive 擷取運算子 >> 。

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 封存類別的函式。

如果您提供由宏取得 RUNTIME_CLASS 的非零 pClass 參數，則函式會驗證封存物件的執行時間類別。這假設您已在類別的實作中使用 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 的版本中，如果成功， TRUE 則為， FALSE 否則為。

在傳回 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 可讓您設定載入陣列成長的大小。

在載入任何物件或呼叫或 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 值。

用於 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 可讓您設定雜湊表大小，以及用來在序列化程式期間識別唯一物件的對應區塊大小。

在儲存任何物件或呼叫或 WriteObject 之後 MapObject ，您不得呼叫 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
整數，指定要寫入封存的位元組數目。

備註

封存不會格式化位元組。

您可以使用 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
所儲存物件的常數指標。

備註

這個函式通常由針對 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::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

參數