Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_VERSION(3)		     Library Functions Manual		   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 deserial-
     ization  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 repre-
     sented 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

Agar 1.7			December 21, 2022		   AG_VERSION(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Version&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help