NAME

AG_Version — agar data file versioning

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:

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:

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

AG_DataSource(3), AG_Intro(3)

HISTORY

The AG_Version interface first appeared in Agar 1.0