AG_VERSION(3)

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