`CArchive` Kelas

Artikel
06/16/2023

Memungkinkan Anda menyimpan jaringan objek yang kompleks dalam bentuk biner permanen (biasanya penyimpanan disk) yang bertahan setelah objek tersebut dihapus.

Sintaks

class CArchive

Anggota

Konstruktor Publik

Nama	Deskripsi
`CArchive::CArchive`	`CArchive` Membuat objek.

Metode Publik

Nama	Deskripsi
`CArchive::Abort`	Menutup arsip tanpa melemparkan pengecualian.
`CArchive::Close`	Menghapus data yang tidak ditulis dan memutuskan sambungan dari `CFile`.
`CArchive::Flush`	Menghapus data yang tidak ditulis dari buffer arsip.
`CArchive::GetFile`	`CFile` Mendapatkan penunjuk objek untuk arsip ini.
`CArchive::GetObjectSchema`	Dipanggil dari `Serialize` fungsi untuk menentukan versi objek yang sedang dideserialisasi.
`CArchive::IsBufferEmpty`	Menentukan apakah buffer telah dikosongkan selama proses penerimaan Windows Sockets.
`CArchive::IsLoading`	Menentukan apakah arsip sedang dimuat.
`CArchive::IsStoring`	Menentukan apakah arsip disimpan.
`CArchive::MapObject`	Tempatkan objek dalam peta yang tidak diserialisasikan ke file, tetapi yang tersedia untuk dirujuk oleh subobjek.
`CArchive::Read`	Membaca byte mentah.
`CArchive::ReadClass`	Membaca referensi kelas yang sebelumnya disimpan dengan `WriteClass`.
`CArchive::ReadObject`	Memanggil fungsi objek `Serialize` untuk dimuat.
`CArchive::ReadString`	Membaca satu baris teks.
`CArchive::SerializeClass`	Membaca atau menulis referensi kelas ke `CArchive` objek tergantung pada arah `CArchive`.
`CArchive::SetLoadParams`	Mengatur ukuran pertumbuhan array beban. Harus dipanggil sebelum objek dimuat atau sebelum `MapObject` atau `ReadObject` dipanggil.
`CArchive::SetObjectSchema`	Mengatur skema objek yang disimpan dalam objek arsip.
`CArchive::SetStoreParams`	Mengatur ukuran tabel hash dan ukuran blok peta yang digunakan untuk mengidentifikasi objek unik selama proses serialisasi.
`CArchive::Write`	Menulis byte mentah.
`CArchive::WriteClass`	Menulis referensi ke `CRuntimeClass` ke `CArchive`.
`CArchive::WriteObject`	Memanggil fungsi objek `Serialize` untuk menyimpan.
`CArchive::WriteString`	Menulis satu baris teks.

Operator Publik

Nama	Deskripsi
`CArchive::operator <<`	Menyimpan objek dan jenis primitif ke arsip.
`CArchive::operator >>`	Memuat objek dan jenis primitif dari arsip.

Anggota Data Publik

Nama	Deskripsi
`CArchive::m_pDocument`

Keterangan

CArchive tidak memiliki kelas dasar.

Nantinya Anda dapat memuat objek dari penyimpanan persisten, menyusunnya kembali dalam memori. Proses pembuatan data persisten ini disebut "serialisasi."

Anda dapat menganggap objek arsip sebagai semacam aliran biner. Seperti aliran input/output, arsip dikaitkan dengan file dan mengizinkan penulisan dan pembacaan data yang di-buffer ke dan dari penyimpanan. Aliran input/output memproses urutan karakter ASCII, tetapi arsip memproses data objek biner dalam format yang efisien dan tidak berlebihan.

Anda harus membuat CFile objek sebelum dapat membuat CArchive objek. Selain itu, Anda harus memastikan bahwa status beban/penyimpanan arsip kompatibel dengan mode buka file. Anda dibatasi untuk satu arsip aktif per file.

Saat Anda membuat CArchive objek, Anda melampirkannya ke objek kelas CFile (atau kelas turunan) yang mewakili file terbuka. Anda juga menentukan apakah arsip akan digunakan untuk memuat atau menyimpan. Objek CArchive dapat memproses tidak hanya jenis primitif tetapi juga objek kelas -turunan CObjectyang dirancang untuk serialisasi. Kelas yang dapat diserialisasikan biasanya memiliki Serialize fungsi anggota, dan biasanya menggunakan makro dan IMPLEMENT_SERIAL , seperti yang dijelaskan di bawah kelas CObject.DECLARE_SERIAL

Operator ekstraksi berlebih ( >>) dan penyisipan ( <<) adalah antarmuka pemrograman arsip yang nyaman yang mendukung jenis primitif dan CObjectkelas turunan.

CArchive juga mendukung pemrograman dengan kelas CSocket MFC Windows Sockets dan CSocketFile. Fungsi anggota mendukung penggunaan tersebut IsBufferEmpty .

Untuk informasi selengkapnya tentang CArchive, lihat artikel Serialisasi dan Soket Windows: Menggunakan Soket dengan Arsip.

Hierarki Warisan

CArchive

Persyaratan

Header: afx.h

`CArchive::Abort`

Panggil fungsi ini untuk menutup arsip tanpa melemparkan pengecualian.

void Abort ();

Keterangan

CArchive Destruktor biasanya akan memanggil Close, yang akan menghapus data apa pun yang belum disimpan ke objek terkaitCFile. Ini dapat menyebabkan pengecualian.

Saat menangkap pengecualian ini, ada baiknya menggunakan Abort, sehingga merusak CArchive objek tidak menyebabkan pengecualian lebih lanjut. Saat menangani pengecualian, CArchive::Abort tidak akan melemparkan pengecualian pada kegagalan karena, tidak seperti CArchive::Close, Abort mengabaikan kegagalan.

Jika Anda terbiasa new mengalokasikan CArchive objek pada heap, maka Anda harus menghapusnya setelah menutup file.

Contoh

Lihat contoh untuk CArchive::WriteClass.

`CArchive::CArchive`

Membuat CArchive objek dan menentukan apakah objek akan digunakan untuk memuat atau menyimpan objek.

CArchive(
    CFile* pFile,
    UINT nMode,
    int nBufSize = 4096,
    void* lpBuf = NULL);

Parameter

pFile
Penunjuk ke CFile objek yang merupakan sumber utama atau tujuan data persisten.

nMode
Bendera yang menentukan apakah objek akan dimuat dari atau disimpan ke arsip. Parameter nMode harus memiliki salah satu nilai berikut:

CArchive::load Memuat data dari arsip. Hanya CFile memerlukan izin baca.
CArchive::store Menyimpan data ke arsip. CFile Memerlukan izin tulis.
CArchive::bNoFlushOnDelete Mencegah arsip dipanggil Flush secara otomatis saat destruktor arsip dipanggil. Jika Anda mengatur bendera ini, Anda bertanggung jawab untuk secara eksplisit memanggil Close sebelum destruktor dipanggil. Jika tidak, data Anda akan rusak.

nBufSize
Bilangan bulat yang menentukan ukuran buffer file internal, dalam byte. Perhatikan bahwa ukuran buffer default adalah 4.096 byte. Jika Anda secara rutin mengarsipkan objek besar, Anda akan meningkatkan performa jika Anda menggunakan ukuran buffer yang lebih besar yang merupakan kelipatan ukuran buffer file.

lpBuf
Penunjuk opsional ke buffer ukuran nBufSizeyang disediakan pengguna . Jika Anda tidak menentukan parameter ini, arsip mengalokasikan buffer dari tumpukan lokal dan membebaskannya ketika objek dihancurkan. Arsip tidak membebaskan buffer yang disediakan pengguna.

Keterangan

Anda tidak dapat mengubah spesifikasi ini setelah membuat arsip.

Anda tidak boleh menggunakan CFile operasi untuk mengubah status file hingga Anda menutup arsip. Setiap operasi tersebut akan merusak integritas arsip. Anda dapat mengakses posisi penunjuk file kapan saja selama serialisasi dengan mendapatkan objek file arsip dari GetFile fungsi anggota lalu menggunakan CFile::GetPosition fungsi . Anda harus memanggil CArchive::Flush sebelum mendapatkan posisi penunjuk file.

Contoh

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`

Menghapus data apa pun yang tersisa di buffer, menutup arsip, dan memutuskan sambungan arsip dari file.

void Close();

Keterangan

Tidak ada operasi lebih lanjut pada arsip yang diizinkan. Setelah menutup arsip, Anda dapat membuat arsip lain untuk file yang sama atau Anda dapat menutup file.

Fungsi Close anggota memastikan bahwa semua data ditransfer dari arsip ke file, dan membuat arsip tidak tersedia. Untuk menyelesaikan transfer dari file ke media penyimpanan, Anda harus terlebih dahulu menggunakan CFile::Close lalu menghancurkan CFile objek.

Contoh

Lihat contoh untuk CArchive::WriteString.

`CArchive::Flush`

Memaksa data apa pun yang tersisa dalam buffer arsip untuk ditulis ke file.

void Flush();

Keterangan

Fungsi Flush anggota memastikan bahwa semua data ditransfer dari arsip ke file. Anda harus memanggil CFile::Close untuk menyelesaikan transfer dari file ke media penyimpanan.

Contoh

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 Mendapatkan penunjuk objek untuk arsip ini.

CFile* GetFile() const;

Tampilkan Nilai

Penunjuk konstan ke objek yang CFile digunakan.

Keterangan

Anda harus menghapus arsip sebelum menggunakan GetFile.

Contoh

const CFile *fp = ar.GetFile();

`CArchive::GetObjectSchema`

Panggil fungsi ini dari Serialize fungsi untuk menentukan versi objek yang saat ini sedang dideserialisasi.

UINT GetObjectSchema();

Tampilkan Nilai

Selama deserialisasi, versi objek sedang dibaca.

Keterangan

Memanggil fungsi ini hanya valid ketika CArchive objek sedang dimuat ( CArchive::IsLoading mengembalikan bukan nol). Ini harus menjadi panggilan pertama dalam Serialize fungsi dan hanya dipanggil sekali. Nilai pengembalian ( UINT)-1 menunjukkan bahwa nomor versi tidak diketahui.

Kelas CObject-turunan dapat menggunakan VERSIONABLE_SCHEMA gabungan (menggunakan bitwise "atau" (|)) dengan versi skema itu sendiri (dalam IMPLEMENT_SERIAL makro) untuk membuat "objek yang dapat diverifikasi," yaitu, objek yang fungsi anggotanya Serialize dapat membaca beberapa versi. Fungsionalitas kerangka kerja default (tanpa VERSIONABLE_SCHEMA) adalah melemparkan pengecualian ketika versi tidak cocok.

Contoh

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`

Panggil fungsi anggota ini untuk menentukan apakah buffer internal objek arsip kosong.

BOOL IsBufferEmpty() const;

Tampilkan Nilai

Bukan nol jika buffer arsip kosong; jika tidak, 0.

Keterangan

Fungsi ini disediakan untuk mendukung pemrograman dengan kelas CSocketFileMFC Windows Sockets . Anda tidak perlu menggunakannya untuk arsip yang terkait dengan CFile objek.

Alasan penggunaan IsBufferEmpty dengan arsip yang terkait dengan CSocketFile objek adalah bahwa buffer arsip mungkin berisi lebih dari satu pesan atau rekaman. Setelah menerima satu pesan, Anda harus menggunakan IsBufferEmpty untuk mengontrol perulangan yang terus menerima data hingga buffer kosong. Untuk informasi selengkapnya, lihat Receive fungsi anggota kelas CAsyncSocket, yang menunjukkan cara menggunakan IsBufferEmpty.

Untuk informasi selengkapnya, lihat Soket Windows: Menggunakan Soket dengan Arsip.

`CArchive::IsLoading`

Menentukan apakah arsip memuat data.

BOOL IsLoading() const;

Tampilkan Nilai

Bukan nol jika arsip saat ini sedang digunakan untuk memuat; jika tidak, 0.

Keterangan

Fungsi anggota ini dipanggil oleh Serialize fungsi kelas yang diarsipkan.

Contoh

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

`CArchive::IsStoring`

Menentukan apakah arsip menyimpan data.

BOOL IsStoring() const;

Tampilkan Nilai

Bukan nol jika arsip saat ini sedang digunakan untuk menyimpan; jika tidak, 0.

Keterangan

Fungsi anggota ini dipanggil oleh Serialize fungsi kelas yang diarsipkan.

IsStoring Jika status arsip bukan nol, maka statusnya IsLoading adalah 0, dan sebaliknya.

Contoh

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

`CArchive::MapObject`

Panggil fungsi anggota ini untuk menempatkan objek di peta yang tidak benar-benar diserialisasikan ke file, tetapi yang tersedia untuk subobjek untuk dirujuk.

void MapObject(const CObject* pOb);

Parameter

pOb
Penunjuk konstan ke objek yang disimpan.

Keterangan

Misalnya, Anda mungkin tidak membuat serialisasi dokumen, tetapi Anda akan membuat serialisasi item yang merupakan bagian dari dokumen. Dengan memanggil MapObject, Anda mengizinkan item tersebut, atau subobjek, untuk mereferensikan dokumen. Selain itu, subitem berseri dapat menserialisasikan penunjuk belakang mereka m_pDocument .

Anda dapat memanggil MapObject saat menyimpan dan memuat dari CArchive objek. MapObject menambahkan objek yang ditentukan ke struktur data internal yang dikelola oleh CArchive objek selama serialisasi dan deserialisasi, tetapi tidak seperti ReadObject dan WriteObject, tidak memanggil serialisasi pada objek.

Contoh

//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`

Atur ke NULL secara default, penunjuk ini ke CDocument dapat diatur ke apa pun yang diinginkan pengguna CArchive instans.

CDocument* m_pDocument;

Keterangan

Penggunaan umum pointer ini adalah untuk menyampaikan informasi tambahan tentang proses serialisasi ke semua objek yang sedang diserialisasikan. Hal ini dicapai dengan menginisialisasi penunjuk dengan dokumen ( CDocumentkelas turunan) yang sedang diserialisasikan, singgahnya objek dalam dokumen dapat mengakses dokumen jika perlu. Pointer ini juga digunakan oleh COleClientItem objek selama serialisasi.

Kerangka kerja diatur ke dokumen yang sedang diserialisasikan m_pDocument saat pengguna mengeluarkan perintah Buka atau Simpan File. Jika Anda membuat serial dokumen kontainer Object Linking and Embedding (OLE) karena alasan selain Buka File atau Simpan, Anda harus secara eksplisit mengatur m_pDocument. Misalnya, Anda akan melakukan ini saat membuat serial dokumen kontainer ke Clipboard.

Contoh

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

Menyimpan objek yang ditunjukkan atau jenis primitif ke arsip.

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

Tampilkan Nilai

Referensi CArchive yang memungkinkan beberapa operator penyisipan pada satu baris.

Keterangan

Dua versi terakhir di atas khusus untuk menyimpan bilangan bulat 64-bit.

Jika Anda menggunakan IMPLEMENT_SERIAL makro dalam implementasi kelas Anda, maka operator penyisipan kelebihan beban untuk CObject memanggil yang dilindungi WriteObject. Fungsi ini, pada gilirannya Serialize , memanggil fungsi kelas.

Operator CStringT penyisipan (<<) mendukung pembuangan diagnostik dan penyimpanan ke arsip.

Contoh

Contoh ini menunjukkan penggunaan CArchive operator << penyisipan dengan int jenis dan long .

long l = 5;
int i = 10;
if (ar.IsStoring())
   ar << l << i;

Contoh ini menunjukkan penggunaan CArchive operator << penyisipan dengan jenis .CStringT

CString s("abc");
ar << s; // Prints the value (abc)

`CArchive::operator >>`

Memuat objek yang ditunjukkan atau jenis primitif dari arsip.

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

Tampilkan Nilai

Referensi CArchive yang memungkinkan beberapa operator ekstraksi pada satu baris.

Keterangan

Dua versi terakhir di atas khusus untuk memuat bilangan bulat 64-bit.

Jika Anda menggunakan IMPLEMENT_SERIAL makro dalam implementasi kelas Anda, maka operator ekstraksi kelebihan beban untuk CObject memanggil fungsi yang dilindungi ReadObject (dengan penunjuk kelas run-time nonzero). Fungsi ini, pada gilirannya Serialize , memanggil fungsi kelas.

Operator CStringT ekstraksi (>>) mendukung pemuatan dari arsip.

Contoh

Contoh ini menunjukkan penggunaan CArchive operator >> ekstraksi dengan jenis .int

long l;
int i;
if (ar.IsLoading())
   ar >> l >> i;

Contoh ini menunjukkan penggunaan CArchive operator << penyisipan dan ekstraksi dan >> dengan jenisnya CStringT .

CString s;
if (ar.IsLoading())
   ar >> s;

`CArchive::Read`

Membaca jumlah byte tertentu dari arsip.

UINT Read(void* lpBuf, UINT nMax);

Parameter

lpBuf
Penunjuk ke buffer yang disediakan pengguna yaitu menerima data yang dibaca dari arsip.

nMax
Bilangan bulat yang tidak ditandatangani yang menentukan jumlah byte yang akan dibaca dari arsip.

Tampilkan Nilai

Bilangan bulat yang tidak ditandatangani yang berisi jumlah byte yang benar-benar dibaca. Jika nilai yang dikembalikan kurang dari angka yang diminta, akhir file telah tercapai. Tidak ada pengecualian yang dilemparkan pada kondisi akhir file.

Keterangan

Arsip tidak menginterpretasikan byte.

Anda dapat menggunakan Read fungsi anggota dalam fungsi Anda Serialize untuk membaca struktur biasa yang terkandung dalam objek Anda.

Contoh

char pbRead[100];
ar.Read(pbRead, 100);

`CArchive::ReadClass`

Panggil fungsi anggota ini untuk membaca referensi ke kelas yang sebelumnya disimpan dengan WriteClass.

CRuntimeClass* ReadClass(
    const CRuntimeClass* pClassRefRequested = NULL,
    UINT* pSchema = NULL,
    DWORD* pObTag = NULL);

Parameter

pClassRefRequested
Penunjuk ke CRuntimeClass struktur yang sesuai dengan referensi kelas yang diminta. Bisa jadi NULL.

pSchema
Penunjuk ke skema kelas run-time yang sebelumnya disimpan.

pObTag
Angka yang mengacu pada tag unik objek. Digunakan secara internal oleh implementasi ReadObject. Hanya diekspos untuk pemrograman tingkat lanjut; pObTag biasanya harus NULL.

Tampilkan Nilai

Penunjuk ke CRuntimeClass struktur.

Keterangan

Jika pClassRefRequested tidak NULL, ReadClass verifikasi bahwa informasi kelas yang diarsipkan kompatibel dengan kelas runtime Anda. Jika tidak kompatibel, ReadClass akan melempar .CArchiveException

Kelas runtime Anda harus menggunakan DECLARE_SERIAL dan IMPLEMENT_SERIAL; jika tidak, ReadClass akan melempar .CNotSupportedException

Jika pSchema adalah NULL, skema kelas yang disimpan dapat diambil dengan memanggil CArchive::GetObjectSchema; jika tidak, *pSchema akan berisi skema kelas run-time yang sebelumnya disimpan.

Anda dapat menggunakan SerializeClass alih-alih ReadClass, yang menangani pembacaan dan penulisan referensi kelas.

Contoh

Lihat contoh untuk CArchive::WriteClass.

`CArchive::ReadObject`

Membaca data objek dari arsip dan membuat objek dengan jenis yang sesuai.

CObject* ReadObject(const CRuntimeClass* pClass);

Parameter

pClass
Penunjuk konstan ke CRuntimeClass struktur yang sesuai dengan objek yang Anda harapkan untuk dibaca.

Tampilkan Nilai

CObject Pointer yang harus dilemparkan dengan aman ke kelas turunan yang benar dengan menggunakan CObject::IsKindOf.

Keterangan

Fungsi ini biasanya dipanggil oleh CArchive operator ekstraksi ( >>) yang kelebihan beban untuk pointer CObject . ReadObject, pada gilirannya Serialize , memanggil fungsi kelas yang diarsipkan.

Jika Anda menyediakan parameter nonzero pClass , yang diperoleh oleh RUNTIME_CLASS makro, maka fungsi memverifikasi kelas run-time objek yang diarsipkan. Ini mengasumsikan Anda telah menggunakan IMPLEMENT_SERIAL makro dalam implementasi kelas.

Contoh

Lihat contoh untuk CArchive::WriteObject.

`CArchive::ReadString`

Panggil fungsi anggota ini untuk membaca data teks ke dalam buffer dari file yang terkait dengan CArchive objek.

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

Parameter

rString
Referensi ke yang CString akan berisi string yang dihasilkan setelah dibaca dari file yang terkait dengan CArchive objek.

lpsz
Menentukan penunjuk ke buffer yang disediakan pengguna yang akan menerima string teks null-terminated.

nMax
Menentukan jumlah maksimum karakter yang akan dibaca. Harus kurang dari lpsz ukuran buffer.

Tampilkan Nilai

Dalam versi yang mengembalikan BOOL, TRUE jika berhasil; FALSE jika tidak.

Dalam versi yang mengembalikan LPTSTR, penunjuk ke buffer yang berisi data teks; NULL jika akhir file tercapai.

Keterangan

Dalam versi fungsi anggota dengan nMax parameter , buffer akan menahan hingga batas nMax - 1 karakter. Pembacaan dihentikan oleh pasangan umpan kembali-baris pengangkutan. Karakter baris baru berikutnya selalu dihapus. Karakter NULL ('\0') ditambahkan dalam kedua kasus.

CArchive::Read juga tersedia untuk input mode teks, tetapi tidak berakhir pada pasangan umpan baris kembali pengangkutan.

Contoh

Lihat contoh untuk CArchive::WriteString.

`CArchive::SerializeClass`

Panggil fungsi anggota ini saat Anda ingin menyimpan dan memuat informasi versi kelas dasar.

void SerializeClass(const CRuntimeClass* pClassRef);

Parameter

pClassRef
Penunjuk ke objek kelas run-time untuk kelas dasar.

Keterangan

SerializeClass membaca atau menulis referensi ke kelas ke CArchive objek, tergantung pada arah CArchive. Gunakan SerializeClass sebagai ganti ReadClass dan WriteClass sebagai cara mudah untuk membuat serialisasi objek kelas dasar; SerializeClass membutuhkan lebih sedikit kode dan lebih sedikit parameter.

Seperti ReadClass, SerializeClass memverifikasi bahwa informasi kelas yang diarsipkan kompatibel dengan kelas runtime Anda. Jika tidak kompatibel, SerializeClass akan melempar .CArchiveException

Kelas runtime Anda harus menggunakan DECLARE_SERIAL dan IMPLEMENT_SERIAL; jika tidak, SerializeClass akan melempar .CNotSupportedException

RUNTIME_CLASS Gunakan makro untuk mengambil nilai untuk pRuntimeClass parameter . Kelas dasar harus menggunakan IMPLEMENT_SERIAL makro.

Contoh

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`

Hubungi SetLoadParams ketika Anda akan membaca sejumlah CObjectbesar objek -turunan dari arsip.

void SetLoadParams(UINT nGrowBy = 1024);

Parameter

nGrowBy
Jumlah minimum slot elemen untuk dialokasikan jika peningkatan ukuran diperlukan.

Keterangan

CArchive menggunakan array beban untuk mengatasi referensi ke objek yang disimpan dalam arsip. SetLoadParams memungkinkan Anda mengatur ukuran pertumbuhan array beban.

Anda tidak boleh memanggil SetLoadParams setelah objek dimuat, atau setelah MapObject atau ReadObject dipanggil.

Contoh

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`

Panggil fungsi anggota ini untuk mengatur skema objek yang disimpan dalam objek arsip ke nSchema.

void SetObjectSchema(UINT nSchema);

Parameter

nSchema
Menentukan skema objek.

Keterangan

Panggilan berikutnya ke GetObjectSchema akan mengembalikan nilai yang disimpan di nSchema.

Gunakan SetObjectSchema untuk penerapan versi tingkat lanjut; misalnya, ketika Anda ingin memaksa versi tertentu untuk dibaca dalam Serialize fungsi kelas turunan.

Contoh

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

`CArchive::SetStoreParams`

Gunakan SetStoreParams saat menyimpan sejumlah CObjectbesar objek -turunan dalam arsip.

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

Parameter

nHashSize
Ukuran tabel hash untuk peta penunjuk antarmuka. Harus nomor utama.

nBlockSize
Menentukan granularitas alokasi memori untuk memperluas parameter. Harus menjadi kekuatan 2 untuk performa terbaik.

Keterangan

SetStoreParams memungkinkan Anda mengatur ukuran tabel hash dan ukuran blok peta yang digunakan untuk mengidentifikasi objek unik selama proses serialisasi.

Anda tidak boleh memanggil SetStoreParams setelah objek apa pun disimpan, atau setelah MapObject atau WriteObject dipanggil.

Contoh

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`

Menulis jumlah byte yang ditentukan ke arsip.

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

Parameter

lpBuf
Penunjuk ke buffer yang disediakan pengguna yang berisi data yang akan ditulis ke arsip.

nMax
Bilangan bulat yang menentukan jumlah byte yang akan ditulis ke arsip.

Keterangan

Arsip tidak memformat byte.

Anda dapat menggunakan Write fungsi anggota dalam fungsi Anda Serialize untuk menulis struktur biasa yang terkandung dalam objek Anda.

Contoh

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

`CArchive::WriteClass`

Gunakan WriteClass untuk menyimpan informasi versi dan kelas kelas dasar selama serialisasi kelas turunan.

void WriteClass(const CRuntimeClass* pClassRef);

Parameter

pClassRef
Penunjuk ke CRuntimeClass struktur yang sesuai dengan referensi kelas yang diminta.

Keterangan

WriteClass menulis referensi ke CRuntimeClass untuk kelas dasar ke CArchive. Gunakan CArchive::ReadClass untuk mengambil referensi.

WriteClass memverifikasi bahwa informasi kelas yang diarsipkan kompatibel dengan kelas runtime Anda. Jika tidak kompatibel, WriteClass akan melempar .CArchiveException

Kelas runtime Anda harus menggunakan DECLARE_SERIAL dan IMPLEMENT_SERIAL; jika tidak, WriteClass akan melempar .CNotSupportedException

Anda dapat menggunakan SerializeClass alih-alih WriteClass, yang menangani pembacaan dan penulisan referensi kelas.

Contoh

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`

Menyimpan yang ditentukan CObject ke arsip.

void WriteObject(const CObject* pOb);

Parameter

pOb
Penunjuk konstan ke objek yang disimpan.

Keterangan

Fungsi ini biasanya dipanggil oleh CArchive operator insertion ( <<) kelebihan beban untuk CObject. WriteObject, pada gilirannya Serialize , memanggil fungsi kelas yang diarsipkan.

Anda harus menggunakan IMPLEMENT_SERIAL makro untuk mengaktifkan pengarsipan. WriteObject menulis nama kelas ASCII ke arsip. Nama kelas ini divalidasi nanti selama proses pemuatan. Skema pengodean khusus mencegah duplikasi nama kelas yang tidak perlu untuk beberapa objek kelas. Skema ini juga mencegah penyimpanan objek berlebihan yang merupakan target lebih dari satu pointer.

Metode pengodean objek yang tepat (termasuk keberadaan nama kelas ASCII) adalah detail implementasi dan dapat berubah dalam versi pustaka di masa mendatang.

Catatan

Selesaikan pembuatan, penghapusan, dan pembaruan semua objek Anda sebelum Anda mulai mengarsipkannya. Arsip Anda akan rusak jika Anda mencampur pengarsipan dengan modifikasi objek.

Contoh

Untuk definisi kelas CAge, lihat contoh untuk 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`

Gunakan fungsi anggota ini untuk menulis data dari buffer ke file yang terkait dengan CArchive objek.

void WriteString(LPCTSTR lpsz);

Parameter

lpsz
Menentukan penunjuk ke buffer yang berisi string teks null-terminated.

Keterangan

Karakter null penghentian ('\0') tidak ditulis ke file; juga bukan baris baru yang ditulis secara otomatis.

WriteString memberikan pengecualian sebagai respons terhadap beberapa kondisi, termasuk kondisi penuh disk.

Write juga tersedia, tetapi daripada mengakhiri karakter null, ia menulis jumlah byte yang diminta ke file.

Contoh

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

Lihat juga

Bagan Hierarki
CFile Kelas
CObject Kelas
CSocket Kelas
CSocketFile Kelas

Bagikan melalui

CArchive Kelas

Sintaks

Anggota

Konstruktor Publik

Metode Publik

Operator Publik

Anggota Data Publik

Keterangan

Hierarki Warisan

Persyaratan

CArchive::Abort

Keterangan

Contoh

CArchive::CArchive

Parameter

Keterangan

Contoh

CArchive::Close

Keterangan

Contoh

CArchive::Flush

Keterangan

Contoh

CArchive::GetFile

Tampilkan Nilai

Keterangan

Contoh

CArchive::GetObjectSchema

Tampilkan Nilai

Keterangan

Contoh

CArchive::IsBufferEmpty

Tampilkan Nilai

Keterangan

CArchive::IsLoading

Tampilkan Nilai

Keterangan

Contoh

CArchive::IsStoring

Tampilkan Nilai

Keterangan

Contoh

CArchive::MapObject

Parameter

Keterangan

Contoh

CArchive::m_pDocument

Keterangan

Contoh

CArchive::operator <<

Tampilkan Nilai

Keterangan

Contoh

CArchive::operator >>

Tampilkan Nilai

Keterangan

Contoh

CArchive::Read

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArchive::ReadClass

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArchive::ReadObject

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArchive::ReadString

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArchive::SerializeClass

Parameter

`CArchive` Kelas

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