Clase `CArchive`

Artículo
06/16/2023

Te permite guardar una red compleja de objetos en un formato binario permanente (normalmente almacenamiento en disco) que se conserva después de que se eliminen esos objetos.

Sintaxis

class CArchive

Miembros

Constructores públicos

Nombre	Descripción
`CArchive::CArchive`	Crea un objeto `CArchive`.

Métodos públicos

Nombre	Descripción
`CArchive::Abort`	Cierra un archivo sin iniciar una excepción.
`CArchive::Close`	Vacía los datos no escritos y se desconecta de `CFile`.
`CArchive::Flush`	Vacía los datos no escritos del búfer de archivo.
`CArchive::GetFile`	Obtiene el puntero de objeto `CFile` para este archivo.
`CArchive::GetObjectSchema`	Se llama desde la función `Serialize` para determinar la versión del objeto que se está deserializando.
`CArchive::IsBufferEmpty`	Determina si el búfer se ha vaciado durante un proceso de recepción de Windows Sockets.
`CArchive::IsLoading`	Determina si el archivo se está cargando.
`CArchive::IsStoring`	Determina si el archivo está almacenando.
`CArchive::MapObject`	Coloca objetos en el mapa que no se serializan en el fichero, pero que están disponibles para que se haga referencia a los subobjetos.
`CArchive::Read`	Lee bytes sin procesar.
`CArchive::ReadClass`	Lee una referencia de clase almacenada previamente con `WriteClass`.
`CArchive::ReadObject`	Llama a la función de `Serialize` un objeto para cargar.
`CArchive::ReadString`	Lee una sola línea de texto.
`CArchive::SerializeClass`	Lee o escribe la referencia de clase al objeto `CArchive` en función de la dirección de `CArchive`.
`CArchive::SetLoadParams`	Establece el tamaño en el que crece la matriz de carga. Se debe llamar a antes de que se cargue cualquier objeto o antes de llamar a `MapObject` o `ReadObject`.
`CArchive::SetObjectSchema`	Establece el esquema de objeto almacenado en el objeto de archivo.
`CArchive::SetStoreParams`	Establece el tamaño de la tabla hash y el tamaño de bloque del mapa usado para identificar objetos únicos durante el proceso de serialización.
`CArchive::Write`	Escribe bytes sin procesar.
`CArchive::WriteClass`	[in] Escribe una referencia al `CRuntimeClass` para el `CArchive`.
`CArchive::WriteObject`	Llama a la función de `Serialize` un objeto para almacenarla.
`CArchive::WriteString`	Escribe una sola línea de texto.

Operadores públicos

Nombre	Descripción
`CArchive::operator <<`	Almacena objetos y tipos primitivos en el archivo.
`CArchive::operator >>`	Carga objetos y tipos primitivos del archivo.

Miembros de datos públicos

Nombre	Descripción
`CArchive::m_pDocument`

Comentarios

CArchive no tiene una clase base.

Más adelante puedes cargar los objetos desde el almacenamiento persistente, reconstituyéndolas en la memoria. Este proceso de creación de datos persistente se denomina «serialización».

Puedes considerar un objeto de archivo como un tipo de secuencia binaria. Al igual que un flujo de entrada y salida, un archivo está asociado a un fichero y permite la escritura almacenada en búfer y la lectura de datos hacia y desde el almacenamiento. Un flujo de entrada y salida procesa secuencias de caracteres ASCII, pero un archivo procesa los datos de objetos binarios en un formato eficaz y no redundante.

Debes crear un objeto CFile para poder crear un objeto CArchive. Además, debes asegurarte de que el estado de carga o almacén del archivo sea compatible con el modo abierto del fichero. Estás limitado a un archivo activo por fichero.

Al construir un CArchive objeto, lo adjuntas a un objeto de clase CFile (o una clase derivada) que representa un fichero abierto. También especificas si el archivo se usará para cargar o almacenar. Un objeto CArchive no solo puede procesar tipos primitivos, sino también objetos de clases CObject derivadas diseñadas para la serialización. Una clase serializable normalmente tiene una función Serialize miembro y normalmente usa las macros DECLARE_SERIAL y IMPLEMENT_SERIAL, como se describe en la clase CObject.

Los operadores de extracción sobrecargada ( >>) e inserción ( <<) son interfaces de programación de archivo convenientes que admiten tipos primitivos y CObjectclases derivadas.

CArchive también admite la programación con las clases CSocket de Windows Sockets de MFC y CSocketFile. La IsBufferEmpty función miembro admite ese uso.

Para obtener más información sobre CArchive, vea los artículos Serialización y Windows Sockets: Uso de sockets con archivos.

Jerarquía de herencia

CArchive

Requisitos

Encabezadoafx.h:

`CArchive::Abort`

Llame a esta función para cerrar el archivo sin iniciar una excepción.

void Abort ();

Comentarios

Normalmente, el destructor CArchive llamará a Close, que vaciará los datos que no se hayan guardado en el objeto asociado CFile. Esto puede provocar excepciones.

Al detectar estas excepciones, es recomendable usar Abort, de modo que la destrucción del objeto CArchive no provoque más excepciones. Al controlar excepciones, CArchive::Abort no producirá una excepción en los errores porque, a diferencia de CArchive::Close, Abort omite los errores.

Si has usado new para asignar el objeto CArchive en el montón, debes eliminarlo después de cerrar el fichero.

Ejemplo

Vea el ejemplo de CArchive::WriteClass.

`CArchive::CArchive`

Construye un objeto CArchive y especifica si se usará para cargar o almacenar objetos.

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

Parámetros

pFile
Un puntero al objeto CFile que es el origen o destino finales de los datos persistentes.

nMode
Una marca que especifica si los objetos se cargarán desde o se almacenarán en el archivo. Este parámetro nMode debe tener uno de los valores siguientes:

CArchive::load Carga datos del archivo. Requiere solo CFile permiso de lectura.
CArchive::store Guarda los datos en el archivo. Requiere CFile permiso de escritura.
CArchive::bNoFlushOnDelete Impide que el archivo llame Flush automáticamente cuando se llama al destructor de archivo. Si estableces esta marca, eres responsable de llamar explícitamente a Close antes de llamar al destructor. Si no lo haces, los datos se dañarán.

nBufSize
Número entero que especifica el tamaño del búfer del fichero interno, en bytes. El tamaño de búfer predeterminado es 4.096 bytes. Si archivas rutinariamente objetos grandes, mejorarás el rendimiento si usas un tamaño de búfer mayor que sea un múltiplo del tamaño del búfer de ficheros.

lpBuf
Un puntero opcional a un búfer proporcionado por el usuario de tamaño nBufSize. Si no especificas este parámetro, el archivo asigna un búfer del montón local y lo libera cuando se destruye el objeto. El archivo no libera un búfer proporcionado por el usuario.

Comentarios

No puedes cambiar esta especificación después de haber creado el archivo.

Es posible que no uses CFile operaciones para modificar el estado del archivo hasta que hayas cerrado el fichero. Cualquier operación de este tipo dañará la integridad del archivo. Puedes acceder a la posición del puntero de fichero en cualquier momento durante la serialización obteniendo el objeto de archivo del fichero de la función miembro GetFile y, a continuación, usando la función CFile::GetPosition. Debes llamar CArchive::Flush a antes de obtener la posición del puntero de fichero.

Ejemplo

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`

Vacía los datos restantes en el búfer, cierra el archivo y desconecta el archivo del fichero.

void Close();

Comentarios

No se permiten más operaciones en el archivo. Después de cerrar un archivo, puedes crear otro archivo para el mismo fichero o puedes cerrarlo.

La función Close miembro garantiza que todos los datos se transfieren del archivo al fichero y hace que el archivo no esté disponible. Para completar la transferencia del fichero al medio de almacenamiento, primero debes usar CFile::Close y, a continuación, destruir el CFile objeto.

Ejemplo

Consulta el ejemplo de CArchive::WriteString.

`CArchive::Flush`

Obliga a que los datos que quedan en el búfer de archivos se escriban en el fichero.

void Flush();

Comentarios

La función Flush miembro garantiza que todos los datos se transfieren del archivo al fichero. Debes llamar CFile::Close a para completar la transferencia del archivo al medio de almacenamiento.

Ejemplo

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`

Obtiene el puntero de objeto CFile para este archivo.

CFile* GetFile() const;

Valor devuelto

Un puntero constante al objeto en uso CFile.

Comentarios

Debes vaciar el archivo antes de usar GetFile.

Ejemplo

const CFile *fp = ar.GetFile();

`CArchive::GetObjectSchema`

Llama a esta función desde la función Serialize para determinar la versión del objeto que se está deserializando actualmente.

UINT GetObjectSchema();

Valor devuelto

Durante la deserialización, la versión del objeto que se lee.

Comentarios

Llamar a esta función solo es válida cuando se carga el CArchive objeto ( CArchive::IsLoading devuelve un valor distinto de cero). Debe ser la primera llamada a la función Serialize y se llama solo una vez. Un valor devuelto de ( UINT)-1 indica que el número de versión es desconocido.

Una clase derivada de CObject se puede usar VERSIONABLE_SCHEMA combinada (mediante «o» bit a bit (|)) con la propia versión del esquema (en la IMPLEMENT_SERIAL macro) para crear un «objeto versionable», es decir, un objeto cuya función Serialize miembro puede leer varias versiones. La funcionalidad de marco predeterminada (sin VERSIONABLE_SCHEMA) es producir una excepción cuando la versión no coincide.

Ejemplo

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`

Llama a esta función miembro para determinar si el búfer interno del objeto de archivo está vacío.

BOOL IsBufferEmpty() const;

Valor devuelto

Distinto de cero si el búfer del archivo está vacío; de lo contrario, 0.

Comentarios

Esta función se proporciona para admitir la programación con la clase CSocketFileMFC Windows Sockets. No es necesario usarlo para un archivo asociado a un objeto CFile.

El motivo del uso de IsBufferEmpty con un archivo asociado a un objeto CSocketFile es que el búfer del archivo puede contener más de un mensaje o registro. Después de recibir un mensaje, debes usar IsBufferEmpty para controlar un bucle que continúa recibiendo datos hasta que el búfer esté vacío. Para obtener más información, consulta la función Receive miembro de la clase CAsyncSocket, que muestra cómo usar IsBufferEmpty.

Para más información, consulte Windows Sockets: Uso de sockets con archivos.

`CArchive::IsLoading`

Determina si el archivo se está cargando datos.

BOOL IsLoading() const;

Valor devuelto

Distinto de cero si el archivo se está usando actualmente para la carga; de lo contrario, 0.

Comentarios

Las funciones de las clases archivadas llaman a esta función miembro Serialize.

Ejemplo

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

`CArchive::IsStoring`

Determina si el archivo está almacenando.

BOOL IsStoring() const;

Valor devuelto

Distinto de cero si el archivo se está usando actualmente para almacenar; de lo contrario, 0.

Comentarios

Las funciones de las clases archivadas llaman a esta función miembro Serialize.

Si el estado IsStoring de un archivo es distinto de cero, su estado IsLoading es 0 y viceversa.

Ejemplo

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

`CArchive::MapObject`

Llame a esta función miembro para colocar objetos en el mapa que no se serializan realmente en el fichero, pero que están disponibles para que hagan referencia a los subobjetos.

void MapObject(const CObject* pOb);

Parámetros

pOb
Un puntero constante al objeto que se almacena.

Comentarios

Por ejemplo, es posible que no serialices un documento, pero serializarías los elementos que forman parte del documento. Al llamar a MapObject, permites que esos elementos, o subobjetos, hagan referencia al documento. Además, los subelementos serializados pueden serializar su puntero m_pDocument de nuevo.

Puedes llamar a MapObject cuando almacenes y cargues desde el objeto CArchive. MapObject agrega el objeto especificado a las estructuras de datos internas mantenidas por el objeto durante la serialización y deserialización CArchive, pero a diferencia de ReadObject y WriteObject, no llama a serializar en el objeto.

Ejemplo

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

Se establece NULL en de forma predeterminada, este puntero a CDocument se puede establecer en cualquier elemento que desee el usuario de la instancia CArchive.

CDocument* m_pDocument;

Comentarios

Un uso común de este puntero es transmitir información adicional sobre el proceso de serialización a todos los objetos que se serializan. Esto se logra inicializando el puntero con el documento (una clase derivada CDocument) que se está serializando, de forma que los objetos del documento puedan acceder al documento si es necesario. Este puntero también lo usan los objetos COleClientItem durante la serialización.

El marco establece m_pDocument en el documento que se serializa cuando un usuario emite un comando Abrir o Guardar fichero. Si serializas un documento de contenedor de vinculación e inserción de objetos (OLE) por motivos distintos de Abrir o Guardar fichero, debe establecer explícitamente m_pDocument. Por ejemplo, lo harías al serializar un documento de contenedor en el Portapapeles.

Ejemplo

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

Almacena el objeto indicado o el tipo primitivo en el archivo.

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 devuelto

Referencia CArchive que habilita varios operadores de inserción en una sola línea.

Comentarios

Las dos últimas versiones anteriores son específicamente para almacenar enteros de 64 bits.

Si usaste la macro en la IMPLEMENT_SERIAL implementación de clase, el operador de inserción sobrecargado para CObject llama a la clase protegida WriteObject. Esta función, a su vez, llama a la función de la clase Serialize.

El operador de inserción CStringT (<<) admite el volcado de diagnóstico y el almacenamiento de un objeto en un archivo.

Ejemplos

En este ejemplo se muestra el uso del operador de CArchive inserción con los << tipos int y long.

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

En este ejemplo se muestra el uso del operador CArchive de << inserción con el tipo CStringT.

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

`CArchive::operator >>`

Carga el objeto indicado o el tipo primitivo desde archivo.

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 devuelto

Una referencia CArchive que habilita varios operadores de extracción en una sola línea.

Comentarios

Las dos últimas versiones anteriores son específicamente para cargar enteros de 64 bits.

Si has usado la macro en la IMPLEMENT_SERIAL implementación de clase, los operadores de extracción sobrecargados para CObject llamar a la función protegida ReadObject (con un puntero de clase en tiempo de ejecución distinto de cero). Esta función, a su vez, llama a la función de la clase Serialize.

El CStringToperador de extracción (>>) admite la carga desde un archivo.

Ejemplos

En este ejemplo se muestra el uso del operador CArchive de extracción >> con el tipo int.

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

En este ejemplo se muestra el uso de los CArchive operadores << de inserción y extracción y >> con el tipo CStringT.

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

`CArchive::Read`

Lee un número especificado de bytes del archivo.

UINT Read(void* lpBuf, UINT nMax);

Parámetros

lpBuf
Un puntero al búfer proporcionado por el usuario que va a recibir los datos leídos del archivo.

nMax
Entero sin signo que especifica el número de bytes que se van a leer del archivo.

Valor devuelto

Un entero sin signo que contiene el número de bytes leídos realmente. Si el valor devuelto es menor que el número solicitado, se ha alcanzado el final del fichero. No se produce ninguna excepción en la condición de fin de fichero.

Comentarios

El archivo no interpreta los bytes.

Puedes usar la función Read miembro dentro de la función Serialize para leer estructuras normales que están contenidas en los objetos.

Ejemplo

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

`CArchive::ReadClass`

Llama a esta función miembro para leer una referencia a una clase almacenada previamente con WriteClass.

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

Parámetros

pClassRefRequested
Un puntero a la estructura CRuntimeClass que corresponde a la referencia de clase solicitada. Puede ser NULL.

pSchema
Un puntero a un esquema de la clase en tiempo de ejecución previamente almacenada.

pObTag
Un número que hace referencia a la etiqueta única de un objeto. Lo usa internamente la implementación de ReadObject. Expuesto solo para programación avanzada; pObTag normalmente debe ser NULL.

Valor devuelto

Un puntero a la estructura CRuntimeClass.

Comentarios

Si pClassRefRequested no es NULL, ReadClass comprueba que la información de clase archivada sea compatible con la clase en tiempo de ejecución. Si no es compatible, ReadClass producirá una excepción CArchiveException.

La clase en tiempo de ejecución debe usar DECLARE_SERIAL y IMPLEMENT_SERIAL; de lo contrario, ReadClass producirá un CNotSupportedException.

Si pSchema es NULL, el esquema de la clase almacenada se puede recuperar llamando a CArchive::GetObjectSchema; de lo contrario, *pSchema contendrá el esquema de la clase en tiempo de ejecución que se almacenó anteriormente.

Puedes usar SerializeClass en lugar de ReadClass, que controla tanto la lectura como la escritura de la referencia de clase.

Ejemplo

Vea el ejemplo de CArchive::WriteClass.

`CArchive::ReadObject`

Lee los datos de objeto del archivo y construye un objeto del tipo adecuado.

CObject* ReadObject(const CRuntimeClass* pClass);

Parámetros

pClass
Un puntero constante a la estructura CRuntimeClass que corresponde al objeto que espera leer.

Valor devuelto

Un puntero CObject que se debe convertir de forma segura en la clase derivada correcta mediante CObject::IsKindOf.

Comentarios

Normalmente, se llama a esta función mediante el operador CArchive de extracción ( >>) sobrecargado para un puntero CObject. ReadObject, a su vez, llama a la función Serialize de la clase archivada.

Si proporcionas un parámetro pClass distinto de cero, que se obtiene mediante la macro RUNTIME_CLASS, la función comprueba la clase en tiempo de ejecución del objeto archivado. Se supone que ha usados la macro IMPLEMENT_SERIAL en la implementación de la clase.

Ejemplo

Vea el ejemplo de CArchive::WriteObject.

`CArchive::ReadString`

Llame a esta función miembro para leer datos de texto en un búfer del fichero asociado al objeto CArchive.

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

Parámetros

rString
Referencia a un CString objeto que contendrá la cadena resultante después de que se lea del fichero asociado al objeto CArchive.

lpsz
Especifica un puntero a un búfer proporcionado por el usuario que recibirá una cadena de texto terminada en NULL.

nMax
Especifica el número máximo de caracteres que se van a leer. Debe ser uno menor que el tamaño del búfer de lpsz.

Valor devuelto

En la versión que devuelve BOOL, TRUE si se ejecuta correctamente; FALSE en caso contrario.

En la versión que devuelve un LPTSTR, un puntero al búfer que contiene los datos de texto; NULL si se alcanzó el final del fichero.

Comentarios

En la versión de la función miembro con el parámetro nMax, el búfer contendrá hasta un límite de nMax - 1 caracteres. La lectura se detiene con un par de retorno de carro-alimentación de línea. Siempre se quitan los caracteres de nueva línea finales. Un carácter nulo NULL ('\0') se anexa en cualquier caso.

CArchive::Read también está disponible para la entrada en modo de texto, pero no termina en un par de avance de retorno de carro.

Ejemplo

Vea el ejemplo de CArchive::WriteString.

`CArchive::SerializeClass`

Llama a esta función miembro cuando quieras almacenar y cargar la información de versión de una clase base.

void SerializeClass(const CRuntimeClass* pClassRef);

Parámetros

pClassRef
Un puntero a un objeto de clase en tiempo de ejecución para la clase base.

Comentarios

SerializeClass Lee o escribe la referencia de clase al objeto CArchive en función de la dirección de CArchive. Usa SerializeClass en lugar de ReadClass y WriteClass como una manera cómoda de serializar objetos de clase base; SerializeClass requiere menos código y menos parámetros.

Igual que ReadClass, SerializeClass comprueba que la información de clase archivada sea compatible con la clase en tiempo de ejecución. Si no es compatible, SerializeClass producirá una excepción CArchiveException.

La clase en tiempo de ejecución debe usar DECLARE_SERIAL y IMPLEMENT_SERIAL; de lo contrario, SerializeClass producirá un CNotSupportedException.

Usa la RUNTIME_CLASS macro para recuperar el valor del parámetro pRuntimeClass. La clase base debe haber usado la macro IMPLEMENT_SERIAL.

Ejemplo

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`

Llama a SetLoadParams cuando vayas a leer un gran número de objetos derivados de CObject de un archivo.

void SetLoadParams(UINT nGrowBy = 1024);

Parámetros

nGrowBy
Número mínimo de ranuras de elemento que se van a asignar si es necesario un aumento de tamaño.

Comentarios

CArchive usa una matriz de carga para resolver referencias a objetos almacenados en el archivo. SetLoadParams te permite establecer el tamaño en el que crece la matriz de carga.

No debes llamar a SetLoadParams después de cargar ningún objeto o después de llamar a MapObject o ReadObject.

Ejemplo

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`

Llama a esta función miembro para establecer el esquema de objeto almacenado en el objeto de archivo en nSchema.

void SetObjectSchema(UINT nSchema);

Parámetros

nSchema
Especifica el esquema del objeto.

Comentarios

La siguiente llamada a GetObjectSchema devolverá el valor almacenado en nSchema.

Usa SetObjectSchema para el control de versiones avanzadas; por ejemplo, si deseas forzar que una versión determinada se lea en una función Serialize de una clase derivada.

Ejemplo

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

`CArchive::SetStoreParams`

Usa SetStoreParams al almacenar un gran número de objetos derivados CObject en un archivo.

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

Parámetros

nHashSize
Tamaño de la tabla hash para los mapas de puntero de interfaz. Debe ser un número primo.

nBlockSize
Especifica la granularidad de la asignación de memoria para extender los parámetros. Debe ser una potencia de 2 para obtener el mejor rendimiento.

Comentarios

SetStoreParams te permite establecer el tamaño de la tabla hash y el tamaño de bloque del mapa usado para identificar objetos únicos durante el proceso de serialización.

No debes llamar a SetStoreParams después de cargar ningún objeto o después de llamar a MapObject o WriteObject.

Ejemplo

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`

Escribe un número especificado de bytes del archivo.

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

Parámetros

lpBuf
Un puntero al búfer proporcionado por el usuario que contiene los datos que se van a escribir en el archivo.

nMax
Un entero que especifica el número de bytes que se van a escribir en el archivo.

Comentarios

El archivo no da formato a los bytes.

Puedes usar la función Write miembro dentro de la función Serialize para escribir estructuras normales que están contenidas en los objetos.

Ejemplo

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

`CArchive::WriteClass`

Usa WriteClass para almacenar la información de versión y clase de una clase base durante la serialización de la clase derivada.

void WriteClass(const CRuntimeClass* pClassRef);

Parámetros

pClassRef
Un puntero a la estructura CRuntimeClass que corresponde a la referencia de clase solicitada.

Comentarios

WriteClassescribe una referencia al CRuntimeClass para la clase base en CArchive. Usa CArchive::ReadClass para recuperar la referencia.

WriteClasscomprueba que la información de clase archivada sea compatible con la clase en tiempo de ejecución. Si no es compatible, WriteClass producirá una excepción CArchiveException.

La clase en tiempo de ejecución debe usar DECLARE_SERIAL y IMPLEMENT_SERIAL; de lo contrario, WriteClass producirá un CNotSupportedException.

Puedes usar SerializeClass en lugar de WriteClass, que controla tanto la lectura como la escritura de la referencia de clase.

Ejemplo

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`

Almacena el objeto especificado CObject en el archivo.

void WriteObject(const CObject* pOb);

Parámetros

pOb
Un puntero constante al objeto que se almacena.

Comentarios

Normalmente, se llama a esta función mediante el operador CArchive de inserción ( <<) sobrecargado para CObject. WriteObject, a su vez, llama a la función Serialize de la clase archivada.

Debes usar la macro para habilitar el archivado IMPLEMENT_SERIAL. WriteObject escribe el nombre de clase ASCII en el archivo. Este nombre de clase se valida más adelante durante el proceso de carga. Un esquema de codificación especial evita la duplicación innecesaria del nombre de clase para varios objetos de la clase. Este esquema también impide el almacenamiento redundante de objetos que son destinos de más de un puntero.

El método exacto de codificación de objetos (incluida la presencia del nombre de clase ASCII) es un detalle de implementación y podría cambiar en versiones futuras de la biblioteca.

Nota:

Termina de crear, eliminar y actualizar todos los objetos antes de empezar a archivarlos. Tu archivo se dañará si mezclas el archivado con modificación de objetos.

Ejemplo

Para obtener una definición de la clase CAge, consulta el ejemplo 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`

Usa esta función miembro para escribir datos de un búfer en el fichero asociado al objeto CArchive.

void WriteString(LPCTSTR lpsz);

Parámetros

lpsz
Especifica un puntero a un búfer que contiene una cadena de texto terminada en NULL.

Comentarios

El carácter nulo de terminación ('\0') no se escribe en el fichero; ni es una nueva línea escrita automáticamente.

WriteString inicia una excepción en respuesta a varias condiciones, incluida la condición de disco lleno.

Write también está disponible, pero en lugar de terminar en un carácter nulo, escribe el número solicitado de bytes en el fichero.

Ejemplo

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

Consulte también

Gráfico de jerarquías
CFile (clase)
CObject (clase)
CSocket (clase)
CSocketFile (clase)

Compartir a través de

Clase CArchive

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Operadores públicos

Miembros de datos públicos

Comentarios

Jerarquía de herencia

Requisitos

CArchive::Abort

Comentarios

Ejemplo

CArchive::CArchive

Parámetros

Comentarios

Ejemplo

CArchive::Close

Comentarios

Ejemplo

CArchive::Flush

Comentarios

Ejemplo

CArchive::GetFile

Valor devuelto

Comentarios

Ejemplo

CArchive::GetObjectSchema

Valor devuelto

Comentarios

Ejemplo

CArchive::IsBufferEmpty

Valor devuelto

Comentarios

CArchive::IsLoading

Valor devuelto

Comentarios

Ejemplo

CArchive::IsStoring

Valor devuelto

Comentarios

Ejemplo

CArchive::MapObject

Parámetros

Comentarios

Ejemplo

CArchive::m_pDocument

Comentarios

Ejemplo

CArchive::operator <<

Valor devuelto

Comentarios

Ejemplos

CArchive::operator >>

Valor devuelto

Comentarios

Ejemplos

CArchive::Read

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArchive::ReadClass

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArchive::ReadObject

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArchive::ReadString

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArchive::SerializeClass

Parámetros

Clase `CArchive`

`CArchive::Abort`

`CArchive::CArchive`

`CArchive::Close`

`CArchive::Flush`

`CArchive::GetFile`

`CArchive::GetObjectSchema`

`CArchive::IsBufferEmpty`

`CArchive::IsLoading`

`CArchive::IsStoring`

`CArchive::MapObject`

`CArchive::m_pDocument`

`CArchive::operator <<`

`CArchive::operator >>`

`CArchive::Read`

`CArchive::ReadClass`

`CArchive::ReadObject`

`CArchive::ReadString`

`CArchive::SerializeClass`

`CArchive::SetLoadParams`

`CArchive::SetObjectSchema`

`CArchive::SetStoreParams`

`CArchive::Write`

`CArchive::WriteClass`

`CArchive::WriteObject`

`CArchive::WriteString`