/*------------------------------------------------------------------------*
  Filename....: fzrt_uuid_type.h
  Scope.......: Data types for UUIDs
  Last Change.:

  Version      Date                Description      Author
	 1.0        09/25/02            New				Tim Hanes

  COPYRIGHT (C) 2000.  All Rights Reserved.
  auto*des*sys, Inc., Columbus, Ohio, USA.
 *------------------------------------------------------------------------*/

#ifndef FZPL_UUID_TYPE_H
#define FZPL_UUID_TYPE_H


#ifdef  __cplusplus
extern "C" {
#endif /* __cplusplus */

#include <stdio.h>
#include "fzrt_api_type.h"

#include "fzrt_extern.h"

/* @doc EXTERNAL FZPL_UUID */

/*********************************************************
 *
 *	Universally Unique Identifiers
 *	Used to uniquely identify plugins, plugin types,
 *	function sets and other stuff.
 *
 *********************************************************/

/********************************************************************************************************

	@def	formZ UUID type size

	@desc	UUIDs are 128 bit numbers; 128 / 8 = 16 bytes
			
	@avail	5.0.0.0

	@toc	fzrt_base

*********************************************************************************************************/
#define FZRT_UUID_NUM_BYTES		16

/********************************************************************************************************

	@type	formZ UUID type

 	@desc	Universally Unique Identifiers
 			Used to uniquely identify plugins, plugin types,
			function sets and other stuff.
			
	@avail	5.0.0.0

	@toc	fzrt_base

*********************************************************************************************************/
typedef char fzrt_UUID_td[FZRT_UUID_NUM_BYTES];

/********************************************************************************************************

	@def	formZ UUID string max size
			
	@avail	5.0.0.0

	@toc	fzrt_base

*********************************************************************************************************/
#define FZPL_UUID_STR_SIZE		68

/********************************************************************************************************

	@def	formZ UUID string max string length
			
	@avail	5.0.0.0

	@toc	fzrt_base

*********************************************************************************************************/
#define FZRT_UUID_MAX_STR_LEN	FZPL_UUID_STR_SIZE-1

/********************************************************************************************************

	@def FZRT_UUID_NULL | NULL UUID - 0 filled
			
	@avail	5.0.0.0

	@toc	fzrt_base

*********************************************************************************************************/
#define FZRT_UUID_NULL	"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"

/********************************************************************************************************

	@fsfunc_t
		
	@desc		Copies one UUID to another.
				Copies uuid_src to uuid_dst.
  
	@return		The address of uuid_dst on success.<nl>
				NULL		- on failure.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_set_NULL, fzrt_UUID_compare, fzrt_UUID_td

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_UUID_td *(FZRT_SPEC *fzrt_UUID_copy_func)(
				const fzrt_UUID_td uuid_src,		/* @parm <in> | The UUID to copy. */
				fzrt_UUID_td uuid_dst				/* @parm <out> | The UUID to copy to. */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Checks if a uuid is NULL or FZRT_UUID_NULL.
					
	@return		TRUE  - uuid is NULL or equal to FZRT_UUID_NULL.<nl>
				FALSE - otherwise.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_set_NULL, fzrt_UUID_is_notNULL, fzrt_UUID_td

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_NULL_func)(
					const fzrt_UUID_td uuid			/* @parm <in> | The UUID to check. */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Checks if a UUID is not NULL.
				Checks if a uuid is not NULL and not FZRT_UUID_NULL.
					
	@return		TRUE  - uuid is NULL or equal to FZRT_UUID_NULL.<nl>
				FALSE - otherwise.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_set_NULL, fzrt_UUID_is_NULL, fzrt_UUID_td

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_notNULL_func)(
					const fzrt_UUID_td uuid			/* @parm <in> | The UUID to check. */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Sets a UUID to FZRT_UUID_NULL.
				Sets uuid to FZRT_UUID_NULL.
	
	@return		The address of uuid on success.<nl>
				NULL		- on failure.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_is_NULL, fzrt_UUID_is_notNULL, fzrt_UUID_td,
				fzrt_UUID_copy

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_UUID_td * (FZRT_SPEC *fzrt_UUID_set_NULL_func)(
					fzrt_UUID_td uuid				/* @parm <out> | The UUID to set */
);

/********************************************************************************************************

	@fsfunc_t
		
	@desc		Checks if two UUIDs are equal.
				Checks if uuid1 is equal to uuid2.
  
	@return		TRUE  - uuid1 is equal to uuid2.<nl>
				FALSE - otherwise.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_is_notequal, fzrt_UUID_compare, fzrt_UUID_td

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_equal_func)(
					const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
					const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t
		
	@desc		Checks if two UUIDs are not equal.
				Checks if uuid1 is not equal to uuid2.
		
	@return		TRUE  - uuid1 is not equal to uuid2.<nl>
				FALSE - otherwise.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_is_equal, fzrt_UUID_compare, fzrt_UUID_td

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_notequal_func)(
					const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
					const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Compares 2 UUIDs.
				Compares uuid1 with uuid2.  Returns a negative number if
				uuid1 is less than uuid2, zero if uuid1 equals uuid2,
				or a positive number if uuid1 is greater than uuid2.
			
	@return 	<lt> 0 - uuid1 <lt>  uuid2.<nl>
				0 - uuid1 == uuid2.<nl>
				<gt> 0 - uuid1 <gt>  uuid2.<nl>
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_is_equal, fzrt_UUID_is_notequal, fzrt_UUID_td

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_int (FZRT_SPEC *fzrt_UUID_compare_func)(
					const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
					const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Checks if one UUID is less than an other.
				Compares uuid1 with uuid2.  Returns TRUE if
				uuid1 is less than uuid2.
			
	@return		TRUE - uuid1 <lt>  uuid2.<nl>
				FALSE - otherwise.
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_compare, fzrt_UUID_is_greater, fzrt_UUID_td,
				fzrt_UUID_is_less_equal

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_less_func)(
									const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
									const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Checks if one UUID is greater than an other.
				Compares uuid1 with uuid2.  Returns TRUE if
				uuid1 is greater than uuid2.
			
	@return		TRUE - uuid1 <gt>  uuid2.<nl>
				FALSE - otherwise.
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_compare, fzrt_UUID_is_less, fzrt_UUID_td,
				fzrt_UUID_is_greater_equal

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_greater_func)(
									const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
									const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Checks if one UUID is less than or equal to an other.
				Compares uuid1 with uuid2.  Returns TRUE if
				uuid1 is less than or equal to uuid2.
			
	@return		TRUE - uuid1 <lt>=  uuid2.<nl>
				FALSE - otherwise.
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_compare, fzrt_UUID_is_less, fzrt_UUID_td,
				fzrt_UUID_is_greater_equal

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_less_equal_func)(
									const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
									const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Checks if one UUID is greater than or equal to an other.
				Compares uuid1 with uuid2.  Returns TRUE if
				uuid1 is greater than or equal to uuid2.
			
	@return		TRUE - uuid1 <gt>=  uuid2.<nl>
				FALSE - otherwise.
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_compare, fzrt_UUID_is_greater, fzrt_UUID_td,
				fzrt_UUID_is_less_equal

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_boolean (FZRT_SPEC *fzrt_UUID_is_greater_equal_func)(
									const fzrt_UUID_td uuid1,		/* @parm <in> | The first UUID to compare */
									const fzrt_UUID_td uuid2		/* @parm <in> | The second UUID to compare */
);

/********************************************************************************************************

	@fsfunc_t

	@desc		Creates an ascii string for a UUID.  Two string format options are available:
				Traditional : "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
				formZ		: "\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX"
					where X is a hexadecimal digit.
				A traditional string will be created if traditional is set to TRUE.

				Traditional strings are the most common way to present a UUID in
				a human readable form.  formZ strings are used to set UUIDs
				to variables in formZ plugins and scripts.
			
	@return		FZRT_NOERR on success.<nl>
				FZ_BAD_PARAMETER_ERROR		- str or uuid is NULL.
			
	@avail		5.0.0.0

  	@see		fzrt_string_to_UUID, fzrt_UUID_td,

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_error_td (FZRT_SPEC *fzrt_UUID_to_string_func)(
									const fzrt_UUID_td uuid,	/* @parm <in> | The UUID to convert */
									fzrt_boolean traditional,	/* @parm <in> | String format indicator */
									char *str,					/* @parm <out> | The created UUID string */
									fzrt_int max_len					/* @parm <in> | The maximum length (in bytes) of the UUID string */
);


/********************************************************************************************************

	@fsfunc_t

	@desc		Creates a uuid from an ascii string.  Two string format options are available:
				Traditional : "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
				formZ		: "\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX\xXX"
					where X is a hexadecimal digit.
				A traditional string will be created if traditional is set to TRUE.

				Traditional strings are the most common way to present a UUID in
				a human readable form.  formZ strings are used to set UUIDs
				to variables in formZ plugins and scripts.
			
	@return		FZRT_NOERR on success.<nl>
				FZ_BAD_PARAMETER_ERROR		- str or uuid is NULL.
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_to_string, fzrt_UUID_td,

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_error_td (FZRT_SPEC *fzrt_string_to_UUID_func)(
									char *str,					/* @parm <in> | The string to convert */
									fzrt_boolean traditional,	/* @parm <in> | String format indicator */
									fzrt_UUID_td uuid			/* @parm <out> | The UUID generated from the string */
);


/********************************************************************************************************

	@fsfunc_t

	@desc		Creates a uuid.
			
	@return		FZRT_NOERR on success.<nl>
				FZ_BAD_PARAMETER_ERROR		- str or uuid is NULL.
			
	@avail		5.0.0.0

  	@see		fzrt_UUID_to_string, fzrt_UUID_td,

	@toc		fzrt_base

*********************************************************************************************************/
typedef fzrt_error_td (FZRT_SPEC *fzrt_UUID_create_func)(
									fzrt_UUID_td uuid			/* @parm <out> | The UUID created. */
									);


#ifdef  __cplusplus
}
#endif /* __cplusplus */

#endif /* FZPL_UUID_TYPE_H */
