SYNOPSIS
#include <agar/core.h>
DESCRIPTION
The
AG_Version structure represents a version number for an
AG_Object(3) (or any other type of data).
It is defined as follows:
The major version number is incremented whenever a change introduces any type of binary incompatibility with previous versions of the data file.
The minor number is incremented when a new feature is introduced which does not break binary compatibility with previous versions. A typical deserialization routine may test the minor number to determine the presence of new features (which do not break binary compatibility).
The cid field is a 32-bit numerical class ID (or 0).
The unicode field is an optional Unicode character value (or 0).
typedef struct ag_version {
Uint32 major; /* Major version number */
Uint32 minor; /* Minor version number */
Uint32 cid; /* Class ID */
Uint32 unicode; /* Icon (Unicode value) */
} AG_Version;
The major version number is incremented whenever a change introduces any type of binary incompatibility with previous versions of the data file.
The minor number is incremented when a new feature is introduced which does not break binary compatibility with previous versions. A typical deserialization routine may test the minor number to determine the presence of new features (which do not break binary compatibility).
The cid field is a 32-bit numerical class ID (or 0).
The unicode field is an optional Unicode character value (or 0).
VERSIONING
int AG_ReadVersion (AG_DataSource *ds, const char *magic, const AG_Version *verRequired, AG_Version *verRead)
void AG_WriteVersion (AG_DataSource *ds, const char *magic, const AG_Version *ver)
int AG_ReadObjectVersion (AG_DataSource *ds, AG_Object *obj)
void AG_WriteObjectVersion (AG_DataSource *ds, const AG_Object *obj)
The AG_ReadVersion() function reads version information from ds and returns 0 if the following data is binary compatible against the version represented by verRequired, or -1 if the data is not compatible. If verRead is not NULL, it is set to the version information read from ds.
AG_WriteVersion() writes version information from ver to ds.
The AG_ReadObjectVersion() and AG_WriteObjectVersion() variants use the version number from the class description structure and sets the signature to the name of the class (see AG_ObjectClass(3)).
EXAMPLES
The following code writes version information to a data stream:
The following code reads version information from a data stream:
AG_DataSource *ds; AG_Version ver; ver.major = 1; ver.minor = 1; AG_WriteVersion(ds, "My-Magic", &ver);
The following code reads version information from a data stream:
AG_DataSource *ds;
AG_Version verRequired, ver;
verRequired.major = 1;
verRequired.minor = 0;
if (AG_ReadVersion(ds, "My-Magic", &verRequired,
&ver) == 0) {
AG_Verbose("Version OK! (%u.%u)\n",
ver.major, ver.minor);
} else {
AG_Verbose("Version not OK!\n");
}
SEE ALSO
HISTORY
The
AG_Version interface first appeared in
Agar 1.0
