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
       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 re-
       turns  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	signa-
       ture 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+14.3.quarterly>

home | help