Classe CArchive

Permite que você salve 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

Nome	Descrição
CArchive::CArchive	Cria um objeto CArchive.

Métodos públicos

Nome	Descrição
CArchive::Abort	Fecha um arquivo morto sem gerar uma exceção.
CArchive::Close	Libera dados não escritos e desconecta-se de CFile.
CArchive::Flush	Libera dados não escritos do buffer de arquivos.
CArchive::GetFile	Obtém o ponteiro do objeto CFile para este arquivo morto.
CArchive::GetObjectSchema	Chamado da função Serialize para determinar a versão do objeto que está sendo desserializado.
CArchive::IsBufferEmpty	Determina se o buffer foi esvaziado durante um processo de recebimento do Windows Sockets.
CArchive::IsLoading	Determina se o arquivo morto está sendo carregado.
CArchive::IsStoring	Determina se o arquivo morto está armazenando.
CArchive::MapObject	Coloca objetos no mapa que não são serializados para o arquivo, mas que estão disponíveis para referência de sub-objetos.
CArchive::Read	Lê bytes brutos.
CArchive::ReadClass	Lê uma referência de classe armazenada anteriormente com WriteClass.
CArchive::ReadObject	Chama a função Serialize de um objeto para carregamento.
CArchive::ReadString	Lê apenas uma linha de texto.
CArchive::SerializeClass	Lê ou grava a referência de classe no objeto CArchive dependendo da direção do CArchive.
CArchive::SetLoadParams	Define o tamanho para o qual a matriz de carga cresce. Deve ser chamado antes de qualquer objeto ser carregado ou antes de MapObject ou ReadObject ser chamado.
CArchive::SetObjectSchema	Define o esquema de objeto armazenado no objeto de arquivo morto.
CArchive::SetStoreParams	Define o tamanho da tabela de hash e o tamanho do bloco do mapa usado para identificar objetos exclusivos durante o processo de serialização.
CArchive::Write	Grava bytes brutos.
CArchive::WriteClass	Grava uma referência ao CRuntimeClass para CArchive.
CArchive::WriteObject	Chama a função Serialize de um objeto para armazenar.
CArchive::WriteString	Grava uma só linha de texto.

Operadores públicos

Nome	Descrição
CArchive::operator <<	Armazena objetos e tipos primitivos no arquivo morto.
CArchive::operator >>	Carrega objetos e tipos primitivos do arquivo morto.

Membros de Dados Públicos

Nome	Descrição
CArchive::m_pDocument

Comentários

CArchive não tem uma classe base.

Posteriormente, 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 morto como uma espécie de fluxo binário. Como um fluxo de entrada/saída, um arquivo morto é associado a um arquivo e permite a gravação e a leitura de dados em buffer de e para o armazenamento. Um fluxo de entrada/saída processa sequências de caracteres ASCII, mas um arquivo morto processa dados de objeto binário em um formato eficiente e não variável.

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

Ao construir um objeto CArchive, anexe-o a um objeto de classe CFile (ou uma classe derivada) que representa um arquivo aberto. Você também especifica se o arquivo morto será usado para carregamento ou armazenamento. Um objeto CArchive pode processar não apenas tipos primitivos, mas também objetos de classes derivadas de CObject projetadas para serialização. Uma classe serializável geralmente tem uma função Serialize de membro e costuma usar as macros DECLARE_SERIAL e IMPLEMENT_SERIAL, conforme descrito na classe CObject.

Os operadores de extração (>>) e inserção (<<) sobrecarregados são interfaces de programação de arquivos convenientes que dão suporte a tipos primitivos e classes derivadas de CObject.

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

Para mais informações sobre CArchive, confira os artigos Serialização e Windows Sockets: como usar soquetes com arquivos.

Hierarquia de herança

CArchive

Requisitos

Cabeçalho: afx.h

CArchive::Abort

Chame essa função para fechar o arquivo morto sem gerar uma exceção.

void Abort ();

Comentários

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

Ao capturar essas exceções, é uma boa ideia usar Abort para que a destruição do objeto CArchive não cause mais exceções. Ao tratar exceções, CArchive::Abort não gerará uma exceção em falhas porque, ao contrário de CArchive::Close, Abort ignora falhas.

Se você usou new para alocar o objeto CArchive no heap, deverá excluí-lo depois de fechar o arquivo.

Exemplo

Confira o exemplo de CArchive::WriteClass.

CArchive::CArchive

Constrói um objeto CArchive 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 objeto CFile que é a origem ou destino final dos dados persistentes.

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

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

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

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

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

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

Comentários

Você não pode alterar essa especificação depois de criar o arquivo morto.

Talvez você não use operações CFile para alterar o estado do arquivo até que tenha fechado o arquivo morto. Qualquer operação desse tipo danificará a integridade do arquivo morto. Você pode acessar a posição do ponteiro de arquivo a qualquer momento durante a serialização, obtendo o objeto de arquivo do arquivo morto da função de membro GetFile e então usando a função CFile::GetPosition. Você deve chamar 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 morto e desconecta o arquivo morto.

void Close();

Comentários

Nenhuma operação adicional no arquivo morto é permitida. Depois de fechar um arquivo morto, você pode criar outro arquivo morto para o mesmo arquivo ou pode fechar o arquivo.

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

Exemplo

Confira o exemplo de CArchive::WriteString.

CArchive::Flush

Força que todos os dados restantes no buffer de arquivos sejam gravados no arquivo.

void Flush();

Comentários

A função de membro Flush garante que todos os dados sejam transferidos do arquivo morto para o arquivo. Você deve chamar CFile::Close para concluir a transferência do arquivo para o meio 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 do objeto CFile para este arquivo morto.

CFile* GetFile() const;

Valor de retorno

Um ponteiro constante para o objeto CFile em uso.

Comentários

Você deve liberar o arquivo morto antes de usar GetFile.

Exemplo

const CFile *fp = ar.GetFile();

CArchive::GetObjectSchema

Chame essa função da função Serialize 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 lido.

Comentários

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

Uma classe derivada de CObject pode usar VERSIONABLE_SCHEMA combinado (usando "or" bit a bit (|)) com a própria versão do esquema (na macro IMPLEMENT_SERIAL) para criar um "objeto apto a controle de versão", ou seja, um objeto cuja função Serialize de membro pode ler várias versões. A funcionalidade padrão da estrutura (sem VERSIONABLE_SCHEMA) é gerar uma exceção quando a versão for 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

Não zero se o buffer do arquivo morto estiver vazio; caso contrário, 0.

Comentários

Essa função é fornecida para dar suporte à programação com a classe CSocketFile Windows Sockets do MFC. Você não precisa usá-lo para um arquivo morto associado a um objeto CFile.

O motivo para usar IsBufferEmpty com um arquivo morto associado a um objeto CSocketFile é que o buffer do arquivo morto 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 mais informações, confira a função de membro Receive da classe CAsyncSocket, que mostra como usar IsBufferEmpty.

Para obter mais informações, consulte Soquetes do Windows: usando soquetes com arquivos.

CArchive::IsLoading

Determina se o arquivo morto está carregando dados.

BOOL IsLoading() const;

Valor de retorno

Diferente de zero se o arquivo morto está sendo usado no momento para carregamento; caso contrário, 0.

Comentários

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

Exemplo

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

CArchive::IsStoring

Determina se o arquivo morto está armazenando dados.

BOOL IsStoring() const;

Valor de retorno

Não zero se o arquivo morto está sendo usado no momento para armazenamento; caso contrário, 0.

Comentários

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

Se o status IsStoring de um arquivo morto não diferente de zero, seu status IsLoading 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 sub-objetos a serem referenciados.

void MapObject(const CObject* pOb);

Parâmetros

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

Comentários

Por exemplo, você pode não serializar um documento, mas serializar os itens que fazem parte do documento. Ao chamar MapObject, você permite que esses itens, ou sub-objetos, façam referência ao documento. Além disso, subitens serializados podem serializar o ponteiro para trás m_pDocument.

Você pode chamar MapObject quando armazenar e carregar do objeto CArchive. MapObject adiciona o objeto especificado às estruturas de dados internas mantidas pelo objeto CArchive durante a serialização e desserialização, mas, ao contrário de ReadObject e WriteObject, não chama serializar 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 como qualquer coisa que o usuário da instância CArchive quiser.

CDocument* m_pDocument;

Comentários

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 é obtido inicializando o ponteiro com o documento (uma classe derivada de CDocument) que está sendo serializado, de modo que objetos dentro do documento possam acessar o documento, se necessário. Esse ponteiro também é usado por objetos COleClientItem durante a serialização.

A estrutura define m_pDocument como 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 (vinculação e incorporação de objeto) por motivos que não Abrir ou Salvar Arquivo, deverá definir m_pDocument explicitamente. Por exemplo, você faria isso ao serializar um documento de 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 morto.

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 referência CArchive que habilita vários operadores de inserção em uma só linha.

Comentários

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

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

O operador de inserção CStringT (<<) dá suporte ao despejo de diagnóstico e ao armazenamento em um arquivo morto.

Exemplos

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

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

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

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

CArchive::operator >>

Carrega o objeto indicado ou o tipo primitivo do arquivo morto.

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 referência CArchive que permite vários operadores de extração em uma só linha.

Comentários

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

Se você usou a macro IMPLEMENT_SERIAL 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). Essa função, por sua vez, chama a função Serialize da classe.

O operador de extração CStringT (>>) dá suporte ao carregamento de um arquivo morto.

Exemplos

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

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

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

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

CArchive::Read

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

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

nMax
Um inteiro sem sinal que especifica o número de bytes a serem lidos do arquivo morto.

Valor de retorno

Um inteiro sem sinal que contém o número de bytes realmente lidos. Se o valor retornado for menor que o número solicitado, o final do arquivo será atingido. Nenhuma exceção é gerada na condição de fim do arquivo.

Comentários

O arquivo morto não interpreta os bytes.

Você pode usar a função de membro Read dentro de sua função Serialize para ler estruturas comuns 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 estrutura CRuntimeClass 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 à marca exclusiva de um objeto. Usado internamente pela implementação de ReadObject. Exposto somente para programação avançada; pObTag normalmente deve ser NULL.

Valor de retorno

Um ponteiro para a estrutura CRuntimeClass.

Comentários

Se pClassRefRequested não for NULL, ReadClass verifica se as informações de classe arquivadas são compatíveis com sua classe de runtime. Se não forem compatíveis, ReadClass gerará um CArchiveException.

Sua classe de runtime deve usar DECLARE_SERIAL e IMPLEMENT_SERIAL; caso contrário, ReadClass gerará um CNotSupportedException.

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

Você pode usar SerializeClass, em vez de ReadClass, o que manipula a leitura e a gravação da referência de classe.

Exemplo

Confira o exemplo de 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 estrutura CRuntimeClass que corresponde ao objeto que você espera ler.

Valor de retorno

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

Comentários

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

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

Exemplo

Confira o exemplo de CArchive::WriteObject.

CArchive::ReadString

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

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 após a leitura do arquivo associado ao objeto CArchive.

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

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

Valor de retorno

Na versão que retorna BOOL, TRUE se tiver êxito; caso contrário, FALSE.

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 tiver sido atingido.

Comentários

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

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

Exemplo

Confira o exemplo de 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 em tempo de execução para a classe base.

Comentários

SerializeClass lê ou grava a referência a uma classe no objeto CArchive, dependendo da direção do CArchive. Use SerializeClass no lugar de ReadClass e WriteClass como um modo conveniente de serializar objetos de 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 runtime. Se não forem compatíveis, SerializeClass gerará um CArchiveException.

Sua classe de runtime deve usar DECLARE_SERIAL e IMPLEMENT_SERIAL; caso contrário, SerializeClass gerará um CNotSupportedException.

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

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

Chame SetLoadParams quando você vai ler um grande número de objetos derivados de CObject um arquivo morto.

void SetLoadParams(UINT nGrowBy = 1024);

Parâmetros

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

Comentários

CArchive usa uma matriz de carga para resolver referências a objetos armazenados no arquivo morto. SetLoadParams permite que você defina o tamanho para o qual a matriz de carga cresce.

Você não deve chamar SetLoadParams depois que qualquer objeto for carregado ou depois que 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.

Comentários

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

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

Exemplo

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

CArchive::SetStoreParams

Use SetStoreParams ao armazenar um grande número de objetos derivados de CObject em um arquivo morto.

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.

Comentários

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 deverá chamar SetStoreParams depois de qualquer objeto ser armazenado ou depois que 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 morto.

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

Parâmetros

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

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

Comentários

O arquivo morto não formata os bytes.

Você pode usar a função de membro Write dentro de sua função Serialize para gravar estruturas comuns 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 estrutura CRuntimeClass que corresponde à referência de classe solicitada.

Comentários

WriteClass grava uma referência a CRuntimeClass para a classe base no 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 runtime. Se não forem compatíveis, WriteClass gerará um CArchiveException.

Sua classe de runtime deve usar DECLARE_SERIAL e IMPLEMENT_SERIAL; caso contrário, WriteClass gerará um CNotSupportedException.

Você pode usar SerializeClass, em vez de WriteClass, o que manipula a leitura e a gravação 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 CObject especificado no arquivo morto.

void WriteObject(const CObject* pOb);

Parâmetros

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

Comentários

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

Você deve usar a macro IMPLEMENT_SERIAL para habilitar o arquivamento. WriteObject grava o nome de classe ASCII no arquivo morto. Esse nome de classe é validado posteriormente durante o processo de carregamento. Um esquema de codificação especial impede a duplicação desnecessária do nome de 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 de classe ASCII) é um detalhe de implementação e pode mudar em versões futuras da biblioteca.

Observação

Conclua a criação, a exclusão e a atualização de todos os objetos antes de começar a arquivá-los. Seu arquivo morto será corrompido se você misturar arquivamento com modificação de objeto.

Exemplo

Para uma definição da classe CAge, confira 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 membro para gravar dados de um buffer no arquivo associado ao objeto CArchive.

void WriteString(LPCTSTR lpsz);

Parâmetros

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

Comentários

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

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

Confira também

Gráfico da hierarquia
Classe CFile
Classe CObject
Classe CSocket
Classe CSocketFile