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

如果您提供非零 pClass 參數，這是由 RUNTIME_CLASS 巨集取得，則函式會驗證封存對象的運行時間類別。這假設您已在類別的實作中使用 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

參數