CArchive Classe

Permite salvar uma rede complexa de objetos em uma forma binária permanente (geralmente armazenamento em disco) que persiste depois que esses objetos são excluídos.

Sintaxe

class CArchive

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Membros de Dados Públicos

Observações

CArchive não tem uma classe base.

Mais tarde, você pode carregar os objetos do armazenamento persistente, reconstituindo-os na memória. Esse processo de tornar os dados persistentes é chamado de "serialização".

Você pode pensar em um objeto de arquivo como um tipo de fluxo binário. Como um fluxo de entrada/saída, um arquivo é associado a um arquivo e permite a gravação e leitura em buffer de dados de e para o armazenamento. Um fluxo de entrada/saída processa sequências de caracteres ASCII, mas um arquivo processa dados de objetos binários em um formato eficiente e não redundante.

Você deve criar um CFile objeto antes de poder criar um CArchive objeto. Além disso, você deve garantir que o status de carregamento/armazenamento do arquivo seja compatível com o modo aberto do arquivo. Você está limitado a um arquivo ativo por arquivo.

Ao construir um CArchive objeto, você o anexa a um objeto de classe CFile (ou uma classe derivada) que representa um arquivo aberto. Você também especifica se o arquivo será usado para carregar ou armazenar. Um CArchive objeto pode processar não apenas tipos primitivos, mas também objetos de CObjectclasses derivadas projetadas para serialização. Uma classe serializável geralmente tem uma Serialize função de membro, e geralmente usa as DECLARE_SERIAL macros e IMPLEMENT_SERIAL , conforme descrito em classe CObject.

Os operadores de extração (>>) e inserção (<<) sobrecarregados são interfaces de programação de arquivo conveniente que suportam tipos primitivos e CObjectclasses derivadas.

CArchive também suporta programação com as classes CSocket MFC Windows Sockets e CSocketFile. A IsBufferEmpty função de membro suporta esse uso.

Para obter mais informações sobre CArchiveo , consulte os artigos Serialização e Windows Sockets: Usando soquetes com arquivos.

Hierarquia de herança

CArchive

Requerimentos

Cabeçalho:afx.h

CArchive::Abort

Chame essa função para fechar o arquivo sem lançar uma exceção.

void Abort ();

Observações

O CArchive destruidor normalmente chamará Close, o que liberará todos os dados que não foram salvos no objeto associado CFile . Isso pode causar exceções.

Ao capturar essas exceções, é uma boa ideia usar Aborto , para que a destruição do CArchive objeto não cause mais exceções. Ao lidar com exceções, CArchive::Abort não lançará uma exceção em falhas porque, ao contrário CArchive::Closede , Abort ignora falhas.

Se você usou new para alocar o CArchive objeto na pilha, então você deve excluí-lo depois de fechar o arquivo.

Exemplo

Veja o exemplo para CArchive::WriteClass.

CArchive::CArchive

Constrói um CArchive objeto e especifica se ele será usado para carregar ou armazenar objetos.

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

Parâmetros

pFile
Um ponteiro para o CFile objeto que é a origem ou o destino final dos dados persistentes.

nMode
Um sinalizador que especifica se os objetos serão carregados ou armazenados no arquivo. O nMode parâmetro deve ter um dos seguintes valores:

• CArchive::load Carrega dados do arquivo. Requer apenas CFile permissão de leitura.

• CArchive::store Salva dados no arquivo. Requer CFile permissão de gravação.

• CArchive::bNoFlushOnDelete Impede que o arquivo seja chamado Flush automaticamente quando o destruidor de arquivo é chamado. Se você definir esse sinalizador, será responsável por chamar Close explicitamente antes que o destruidor seja chamado. Se não o fizer, os seus dados serão corrompidos.

nBufSize
Um inteiro que especifica o tamanho do buffer de arquivo interno, em bytes. Observe que o tamanho padrão do buffer é 4.096 bytes. Se você arquivar rotineiramente objetos grandes, melhorará o desempenho se usar um tamanho de buffer maior que seja um múltiplo do tamanho do buffer de arquivos.

lpBuf
Um ponteiro opcional para um buffer de tamanho nBufSizefornecido pelo usuário. Se você não especificar esse parâmetro, o arquivo alocará um buffer do heap local e o liberará quando o objeto for destruído. O arquivo não libera um buffer fornecido pelo usuário.

Observações

Não é possível alterar esta especificação depois de ter criado o arquivo.

Você não pode usar CFile operações para alterar o estado do arquivo até que você tenha fechado o arquivo. Qualquer operação deste tipo prejudicará a integridade do arquivo. Você pode acessar a posição do ponteiro de arquivo a qualquer momento durante a serialização, obtendo o objeto de arquivo do arquivo da função de GetFile membro e, em seguida, usando a CFile::GetPosition função. Você deve ligar CArchive::Flush antes de obter a posição do ponteiro do arquivo.

Exemplo

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

Libera todos os dados restantes no buffer, fecha o arquivo e desconecta o arquivo do arquivo.

void Close();

Observações

Não são permitidas mais operações no arquivo. Depois de fechar um arquivo, você pode criar outro arquivo para o mesmo arquivo ou pode fechá-lo.

A função Close de membro garante que todos os dados sejam transferidos do arquivo para o arquivo e torna o arquivo indisponível. Para concluir a transferência do arquivo para a mídia de armazenamento, você deve primeiro usar CFile::Close e, em seguida, destruir o CFile objeto.

Exemplo

Veja o exemplo de CArchive::WriteString.

CArchive::Flush

Força todos os dados restantes no buffer de arquivo a serem gravados no arquivo.

void Flush();

Observações

A função Flush de membro garante que todos os dados sejam transferidos do arquivo para o arquivo. Você deve ligar CFile::Close para concluir a transferência do arquivo para a mídia de armazenamento.

Exemplo

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

Obtém o ponteiro de CFile objeto para este arquivo.

CFile* GetFile() const;

Valor de retorno

Um ponteiro constante para o CFile objeto em uso.

Observações

Você deve limpar o arquivo antes de usar GetFileo .

Exemplo

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Chame essa função da Serialize função para determinar a versão do objeto que está sendo desserializado no momento.

UINT GetObjectSchema();

Valor de retorno

Durante a desserialização, a versão do objeto que está sendo lida.

Observações

Chamar essa função só é válido quando o CArchive objeto está sendo carregado ( CArchive::IsLoading retorna diferente de zero). Deve ser a primeira chamada na Serialize função e chamada apenas uma vez. Um valor de retorno de ( UINT)-1 indica que o número da versão é desconhecido.

Uma CObjectclasse derivada pode usar VERSIONABLE_SCHEMA combinada (usando bitwise "ou" (|)) com a IMPLEMENT_SERIAL própria versão do esquema (na macro) para criar um "objeto versionável", ou seja, um objeto cuja Serialize função de membro pode ler várias versões. A funcionalidade de estrutura padrão (sem VERSIONABLE_SCHEMA) é lançar uma exceção quando a versão é incompatível.

Exemplo

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

Chame essa função de membro para determinar se o buffer interno do objeto de arquivo morto está vazio.

BOOL IsBufferEmpty() const;

Valor de retorno

Diferente de zero se o buffer do arquivo estiver vazio; caso contrário, 0.

Observações

Esta função é fornecida para suportar a programação com a classe CSocketFileMFC Windows Sockets. Não é necessário usá-lo para um arquivo associado a um CFile objeto.

A razão para usar IsBufferEmpty com um arquivo associado a um CSocketFile objeto é que o buffer do arquivo pode conter mais de uma mensagem ou registro. Depois de receber uma mensagem, você deve usar IsBufferEmpty para controlar um loop que continua recebendo dados até que o buffer esteja vazio. Para obter mais informações, consulte a Receive função de membro da classe CAsyncSocket, que mostra como usar IsBufferEmptyo .

Para obter mais informações, consulte Windows Sockets: Usando soquetes com arquivos.

CArchive::IsLoading

Determina se o arquivo está carregando dados.

BOOL IsLoading() const;

Valor de retorno

Diferente de zero se o arquivo estiver sendo usado atualmente para carregamento; caso contrário, 0.

Observações

Esta função de membro é chamada pelas Serialize funções das classes arquivadas.

Exemplo

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

CArchive::IsStoring

Determina se o arquivo está armazenando dados.

BOOL IsStoring() const;

Valor de retorno

Diferente de zero se o arquivo estiver sendo usado atualmente para armazenamento; caso contrário, 0.

Observações

Esta função de membro é chamada pelas Serialize funções das classes arquivadas.

Se o IsStoring status de um arquivo for diferente de zero, seu IsLoading status será 0 e vice-versa.

Exemplo

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

CArchive::MapObject

Chame essa função de membro para colocar objetos no mapa que não são realmente serializados para o arquivo, mas que estão disponíveis para subobjetos para referência.

void MapObject(const CObject* pOb);

Parâmetros

pOb
Um ponteiro constante para o objeto que está sendo armazenado.

Observações

Por exemplo, você pode não serializar um documento, mas serializaria os itens que fazem parte do documento. Ao chamar MapObjecto , você permite que esses itens, ou subobjetos, façam referência ao documento. Além disso, os subitens serializados podem serializar seu m_pDocument ponteiro traseiro.

Você pode chamar MapObject quando armazenar e carregar a CArchive partir do objeto. MapObject Adiciona o objeto especificado às estruturas de dados internas mantidas pelo objeto durante a CArchive serialização e desserialização, mas, ao contrário ReadObject de e WriteObject, ele não chama serialize no objeto.

Exemplo

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

Definido como NULL por padrão, esse ponteiro para um CDocument pode ser definido para qualquer coisa que o CArchive usuário da instância deseje.

CDocument* m_pDocument;

Observações

Um uso comum desse ponteiro é transmitir informações adicionais sobre o processo de serialização para todos os objetos que estão sendo serializados. Isso é conseguido inicializando o ponteiro com o documento (uma CDocumentclasse derivada) que está sendo serializado, de tal forma que os objetos dentro do documento possam acessar o documento, se necessário. Esse ponteiro também é usado por COleClientItem objetos durante a serialização.

A estrutura define m_pDocument o documento que está sendo serializado quando um usuário emite um comando Abrir ou Salvar Arquivo. Se você serializar um documento de contêiner OLE (Object Linking and Embedding) por motivos diferentes de Arquivo Abrir ou Salvar, deverá definir m_pDocumentexplicitamente . Por exemplo, você faria isso ao serializar um documento contêiner para a área de transferência.

Exemplo

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

Armazena o objeto indicado ou o tipo primitivo no arquivo.

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

Valor de retorno

Uma CArchive referência que permite vários operadores de inserção em uma única linha.

Observações

As duas últimas versões acima são especificamente para armazenar inteiros de 64 bits.

Se você usou a IMPLEMENT_SERIAL macro em sua implementação de classe, o operador de inserção sobrecarregado para CObject chamadas de protegido WriteObject. Esta função, por sua vez, chama a Serialize função da classe.

O CStringT operador de inserção (<<) suporta despejo de diagnóstico e armazenamento em um arquivo.

Exemplos

Este exemplo demonstra o uso do operador de CArchive inserção com os << tipos e int .long

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

Este exemplo demonstra o uso do operador CArchive de << inserção com o CStringT tipo.

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

CArchive::operator >>

Carrega o objeto indicado ou o tipo primitivo do arquivo.

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

Valor de retorno

Uma CArchive referência que permite vários operadores de extração em uma única linha.

Observações

As duas últimas versões acima são especificamente para carregar inteiros de 64 bits.

Se você usou a IMPLEMENT_SERIAL macro em sua implementação de classe, os operadores de extração sobrecarregados para CObject chamar a função protegida ReadObject (com um ponteiro de classe de tempo de execução diferente de zero). Esta função, por sua vez, chama a Serialize função da classe.

O CStringT operador de extração (>>) suporta o carregamento de um arquivo.

Exemplos

Este exemplo demonstra o uso do operador CArchive de >> extração com o int tipo.

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

Este exemplo demonstra o uso dos operadores CArchive de << inserção e extração e >> com o CStringT tipo.

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

CArchive::Read

Lê um número especificado de bytes do arquivo.

UINT Read(void* lpBuf, UINT nMax);

Parâmetros

lpBuf
Um ponteiro para um buffer fornecido pelo usuário que deve receber os dados lidos do arquivo.

nMax
Um inteiro não assinado especificando o número de bytes a serem lidos do arquivo.

Valor de retorno

Um inteiro não assinado contendo o número de bytes realmente lidos. Se o valor de retorno for menor que o número solicitado, o fim do arquivo foi atingido. Nenhuma exceção é lançada na condição de fim de arquivo.

Observações

O arquivo não interpreta os bytes.

Você pode usar a função de membro dentro de Read sua Serialize função para ler estruturas comuns que estão contidas em seus objetos.

Exemplo

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

CArchive::ReadClass

Chame essa função de membro para ler uma referência a uma classe armazenada anteriormente com WriteClass.

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

Parâmetros

pClassRefRequested
Um ponteiro para a CRuntimeClass estrutura que corresponde à referência de classe solicitada. Pode ser NULL.

pSchema
Um ponteiro para um esquema da classe de tempo de execução armazenada anteriormente.

pObTag
Um número que se refere à tag exclusiva de um objeto. Utilizado internamente pela implementação do ReadObject. Exposto apenas para programação avançada; pObTag normalmente deve ser NULL.

Valor de retorno

Um ponteiro para a CRuntimeClass estrutura.

Observações

Se pClassRefRequested não NULLfor , ReadClass verifica se as informações de classe arquivadas são compatíveis com sua classe de tempo de execução. Se não for compatível, ReadClass lançará um CArchiveExceptionarquivo .

Sua classe de tempo de execução deve usar DECLARE_SERIAL e IMPLEMENT_SERIAL; caso contrário, ReadClass lançará um CNotSupportedExceptionarquivo .

Se pSchema for NULL, o esquema da classe armazenada pode ser recuperado chamando CArchive::GetObjectSchema; caso contrário, *pSchema conterá o esquema da classe de tempo de execução que foi armazenada anteriormente.

Você pode usar SerializeClass em vez de ReadClass, que lida com a leitura e a escrita da referência de classe.

Exemplo

Veja o exemplo para CArchive::WriteClass.

CArchive::ReadObject

Lê dados de objeto do arquivo morto e constrói um objeto do tipo apropriado.

CObject* ReadObject(const CRuntimeClass* pClass);

Parâmetros

pClass
Um ponteiro constante para a CRuntimeClass estrutura que corresponde ao objeto que você espera ler.

Valor de retorno

Um CObject ponteiro que deve ser convertido com segurança para a classe derivada correta usando CObject::IsKindOf.

Observações

Esta função é normalmente chamada pelo CArchive operador de extração (>>) sobrecarregado para um CObject ponteiro. ReadObject, por sua vez, chama a Serialize função da classe arquivada.

Se você fornecer um parâmetro diferente de pClass zeroRUNTIME_CLASS, que é obtido pela macro, a função verificará a classe de tempo de execução do objeto arquivado. Isso pressupõe que você tenha usado a IMPLEMENT_SERIAL macro na implementação da classe.

Exemplo

Veja o exemplo para CArchive::WriteObject.

CArchive::ReadString

Chame essa função de membro para ler dados de texto em um buffer do arquivo associado ao CArchive objeto.

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

Parâmetros

rString
Uma referência a um CString que conterá a cadeia de caracteres resultante depois que ela for lida do arquivo associado ao CArchive objeto.

lpsz
Especifica um ponteiro para um buffer fornecido pelo usuário que receberá uma cadeia de texto terminada em nulo.

nMax
Especifica o número máximo de caracteres a serem lidos. Deve ser um a menos do que o tamanho do lpsz buffer.

Valor de retorno

Na versão que retorna BOOL, se bem-sucedida, TRUEFALSE caso contrário.

Na versão que retorna um LPTSTR, um ponteiro para o buffer que contém os dados de texto, NULL se o fim do arquivo foi atingido.

Observações

Na versão da função de membro com o nMax parâmetro, o buffer irá manter até um limite de nMax - 1 caracteres. A leitura é interrompida por um par de alimentação da linha de retorno do carro. Os caracteres de nova linha à direita são sempre removidos. Um NULL caractere ('\0') é acrescentado em ambos os casos.

CArchive::Read também está disponível para entrada no modo texto, mas não termina em um par de alimentação de linha de retorno de carro.

Exemplo

Veja o exemplo para CArchive::WriteString.

CArchive::SerializeClass

Chame essa função de membro quando quiser armazenar e carregar as informações de versão de uma classe base.

void SerializeClass(const CRuntimeClass* pClassRef);

Parâmetros

pClassRef
Um ponteiro para um objeto de classe de tempo de execução para a classe base.

Observações

SerializeClass lê ou grava a referência a uma classe para o CArchive objeto, dependendo da direção do CArchive. Use SerializeClass no lugar e como uma maneira conveniente de serializar objetos de ReadClassWriteClass classe base, SerializeClass requer menos código e menos parâmetros.

Como ReadClass, SerializeClass verifica se as informações de classe arquivadas são compatíveis com sua classe de tempo de execução. Se não for compatível, SerializeClass lançará um CArchiveExceptionarquivo .

Sua classe de tempo de execução deve usar DECLARE_SERIAL e IMPLEMENT_SERIAL; caso contrário, SerializeClass lançará um CNotSupportedExceptionarquivo .

Use a RUNTIME_CLASS macro para recuperar o valor do pRuntimeClass parâmetro. A classe base deve ter usado a IMPLEMENT_SERIAL macro.

Exemplo

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

Ligue SetLoadParams quando você vai ler um grande número de objetos derivados de CObjectum arquivo.

void SetLoadParams(UINT nGrowBy = 1024);

Parâmetros

nGrowBy
O número mínimo de slots de elementos a alocar se for necessário um aumento de tamanho.

Observações

CArchive usa uma matriz de carga para resolver referências a objetos armazenados no arquivo. SetLoadParams Permite definir o tamanho para o qual a matriz de carga cresce.

Você não deve ligar SetLoadParams depois que qualquer objeto for carregado, ou depois MapObject ou ReadObject for chamado.

Exemplo

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

Chame essa função de membro para definir o esquema de objeto armazenado no objeto de arquivo morto como nSchema.

void SetObjectSchema(UINT nSchema);

Parâmetros

nSchema
Especifica o esquema do objeto.

Observações

A próxima chamada para GetObjectSchema retornará o valor armazenado em nSchema.

Use SetObjectSchema para versionamento avançado, por exemplo, quando você deseja forçar uma versão específica a ser lida em uma Serialize função de uma classe derivada.

Exemplo

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

CArchive::SetStoreParams

Use SetStoreParams ao armazenar um grande número de CObjectobjetos derivados em um arquivo.

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

Parâmetros

nHashSize
O tamanho da tabela de hash para mapas de ponteiro de interface. Deve ser um número primo.

nBlockSize
Especifica a granularidade de alocação de memória para estender os parâmetros. Deve ser uma potência de 2 para o melhor desempenho.

Observações

SetStoreParams Permite definir o tamanho da tabela de hash e o tamanho do bloco do mapa usado para identificar objetos exclusivos durante o processo de serialização.

Você não deve ligar SetStoreParams depois que nenhum objeto for armazenado, ou depois MapObject ou WriteObject for chamado.

Exemplo

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

Grava um número especificado de bytes no arquivo.

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

Parâmetros

lpBuf
Um ponteiro para um buffer fornecido pelo usuário que contém os dados a serem gravados no arquivo.

nMax
Um inteiro que especifica o número de bytes a serem gravados no arquivo.

Observações

O arquivo não formata os bytes.

Você pode usar a função de membro dentro de Write sua Serialize função para escrever estruturas comuns que estão contidas em seus objetos.

Exemplo

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

CArchive::WriteClass

Use WriteClass para armazenar as informações de versão e classe de uma classe base durante a serialização da classe derivada.

void WriteClass(const CRuntimeClass* pClassRef);

Parâmetros

pClassRef
Um ponteiro para a CRuntimeClass estrutura que corresponde à referência de classe solicitada.

Observações

WriteClass Grava uma referência ao CRuntimeClass para a classe base para o CArchive. Use CArchive::ReadClass para recuperar a referência.

WriteClass Verifica se as informações de classe arquivadas são compatíveis com sua classe de tempo de execução. Se não for compatível, WriteClass lançará um CArchiveExceptionarquivo .

Sua classe de tempo de execução deve usar DECLARE_SERIAL e IMPLEMENT_SERIAL; caso contrário, WriteClass lançará um CNotSupportedExceptionarquivo .

Você pode usar SerializeClass em vez de WriteClass, que lida com a leitura e a escrita da referência de classe.

Exemplo

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

Armazena o especificado CObject no arquivo.

void WriteObject(const CObject* pOb);

Parâmetros

pOb
Um ponteiro constante para o objeto que está sendo armazenado.

Observações

Esta função é normalmente chamada pelo operador de CArchive inserção (<<) sobrecarregado para CObject. WriteObject, por sua vez, chama a Serialize função da classe arquivada.

Você deve usar a macro para habilitar o IMPLEMENT_SERIAL arquivamento. WriteObject grava o nome da classe ASCII no arquivo. Esse nome de classe é validado posteriormente durante o processo de carregamento. Um esquema de codificação especial evita a duplicação desnecessária do nome da classe para vários objetos da classe. Esse esquema também impede o armazenamento redundante de objetos que são alvos de mais de um ponteiro.

O método exato de codificação de objeto (incluindo a presença do nome da classe ASCII) é um detalhe de implementação e pode mudar em versões futuras da biblioteca.

Exemplo

Para obter uma definição da classe CAge, consulte o exemplo de 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

Use essa função de membro para gravar dados de um buffer no arquivo associado ao CArchive objeto.

void WriteString(LPCTSTR lpsz);

Parâmetros

lpsz
Especifica um ponteiro para um buffer que contém uma cadeia de texto terminada em nulo.

Observações

O caractere nulo de terminação ('\0') não é gravado no arquivo; nem uma nova linha é escrita automaticamente.

WriteString lança uma exceção em resposta a várias condições, incluindo a condição de disco cheio.

Write também está disponível, mas em vez de terminar em um caractere nulo, ele grava o número solicitado de bytes no arquivo.

Exemplo

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

Ver também

Gráfico de Hierarquia
CFile Classe
CObject Classe
CSocket Classe
CSocketFile Classe