alchemist.h File Reference

#include <sys/types.h>

Classes
struct	adm_bb_cap_t
Defines
#define	ALCHEMIST_ABI_MAJOR_VER 0
#define	ALCHEMIST_ABI_MINOR_VER 0
#define	ADM_EDEADNODE 1
#define	ADM_EBADTYPE 2
#define	ADM_EBADNAME 3
#define	ADM_EBADDATA 4
#define	ADM_ECONSTRAINT 5
#define	ADM_ENOINDEX 51
#define	ADM_ENONAME 52
#define	ADM_ENOPATH 53
#define	ADM_EACCESSFAILED 101
#define	ADM_ENONAMESPACE 102
#define	ADM_ENOSUBSPACE 103
#define	ADM_ENOWRITE 201
#define	ADM_ENOREAD 202
#define	ADM_ENOLISTSERIAL 203
#define	ADM_ENOREADSERIAL 204
#define	ADM_ENOCACHE 205
#define	ADM_ENOBOXTYPE 251
#define	ADM_EPARSE 301
#define	AdmRefStr_str(REFSTR)
#define	AdmContext_getIdentityRoot_b(CONTEXT, ERROR)
#define	AdmIdentity_getParentA_b(ID, ERROR)
#define	AdmIdentity_getParentB_b(ID, ERROR)
#define	AdmIdentity_getContext_b(ID, ERROR)
#define	AdmContext_getDataRoot_b(CONTEXT, ERROR)
#define	AdmData_getContainer_b(DATA, ERROR)
#define	AdmData_getPrev_b(DATA, WRAP, ERROR)
#define	AdmData_getNext_b(DATA, WRAP, ERROR)
#define	AdmData_getContext_b(DATA, ERROR)
#define	AdmContext_getDataByPath_b(CONTEXT, PATH, ERROR)
#define	AdmList_getDataByIndex_b(LIST, INDEX, ERROR)
#define	AdmList_getDataByName_b(LIST, NAME, ERROR)
#define	AdmList_getDataByPath_b(LIST, PATH, ERROR)
#define	AdmList_addData_b(LIST, TYPE, NAME, ERROR)
#define	AdmList_copyData_b(LIST, DATA, ERROR)
#define	AdmList_renameCopyData_b(LIST, DATA, NAME, ERROR)
#define	ADM_BBCAP_SUP_WRITE(CAP) ((CAP).array[0] & (1 << 0))
#define	ADM_BBCAP_SUP_READ(CAP) ((CAP).array[0] & (1 << 1))
#define	ADM_BBCAP_SUP_LISTSERIAL(CAP) ((CAP).array[0] & (1 << 2))
#define	ADM_BBCAP_SUP_READSERIAL(CAP) ((CAP).array[0] & (1 << 3))
#define	ADM_BBCAP_CACHED(CAP) ((CAP).array[0] & (1 << 4))
#define	AdmSwitchboard_getNspCfg_b(CTX, NAMESPACE, ERROR)
#define	AdmSwitchboard_getSubspCfg_b(CTX, SUBSPACE, ERROR)
Typedefs
typedef struct AdmError	AdmError
typedef struct AdmRefStr	AdmRefStr
typedef struct AdmData	AdmData
typedef struct AdmList	AdmList
typedef struct AdmInt	AdmInt
typedef struct AdmBool	AdmBool
typedef struct AdmFloat	AdmFloat
typedef struct AdmString	AdmString
typedef struct AdmString	AdmBase64
typedef struct AdmString	AdmCopy
typedef struct AdmIdentity	AdmIdentity
typedef struct AdmContext	AdmContext
typedef struct AdmBlackBox	AdmBlackBox
Enumerations
enum	AdmDataType { ADM_TYPE_UNKNOWN = 0, ADM_TYPE_LIST = 1, ADM_TYPE_COPY = 2, ADM_TYPE_INT = 3, ADM_TYPE_FLOAT = 4, ADM_TYPE_BOOL = 5, ADM_TYPE_STRING = 6, ADM_TYPE_BASE64 = 7 }
Functions
void	AdmError_create (AdmError *error, int num, const char format,...)
	Allocate new AdmError structure.
void	AdmError_ref (AdmError *error)
	Increment the ref count of an AdmError structure.
void	AdmError_unref (AdmError *error)
	Decrement the ref count of an AdmError structure.
const char *	AdmError_strerr (AdmError *error)
	String description of error.
int	AdmError_errno (AdmError *error)
	Integer error code of error.
AdmRefStr *	AdmRefStr_ref (AdmRefStr *refstr)
void	AdmRefStr_unref (AdmRefStr *refstr)
size_t	AdmRefStr_len (AdmRefStr *refstr)
AdmRefStr *	AdmRefStr_get (const char *str, int force)
	Get an AdmRefStr.
AdmRefStr *	AdmRefStr_nget (const char *str, size_t len, int force)
	Get an AdmRefStr, by length.
AdmContext *	AdmContext_new (const char name, unsigned int serial, AdmError *error)
	AdmContext constructor.
AdmContext *	AdmContext_ref (AdmContext context, AdmError *error)
	AdmContext reference increment.
void	AdmContext_unref (AdmContext context, AdmError *error)
	AdmContext reference decrement.
AdmContext *	AdmContext_copy (AdmContext context, AdmError *error)
	AdmContext copy operator.
AdmContext *	AdmContext_merge (const char name, unsigned int serial, AdmContext contextA, AdmContext contextB, AdmError *error)
	AdmContext merge operator.
void	AdmContext_flatten (AdmContext context, AdmError *error)
	AdmContext flatten operator.
void	AdmContext_strip (AdmContext context, AdmError *error)
	AdmContext strip function.
char *	AdmContext_toXML (AdmContext context, AdmError *error)
AdmContext *	AdmContext_fromXML (const char xml, AdmError *error)
int	AdmContext_readFromFile (AdmContext *context, const char path, AdmError **error)
int	AdmContext_writeToFile (AdmContext context, const char path, int mode, uid_t uid, gid_t gid, AdmError **error)
AdmRefStr *	AdmContext_getMask (AdmContext context, unsigned int index, AdmError *error)
	AdmContext mask set accessor.
int	AdmContext_setMask (AdmContext context, const char path, AdmError **error)
	AdmContext mask set mutator.
int	AdmContext_clearMaskByIndex (AdmContext context, unsigned int index, AdmError *error)
	AdmContext mask set element index remove.
int	AdmContext_clearMaskByPath (AdmContext context, const char path, AdmError **error)
	AdmContext mask set element data path remove.
unsigned int	AdmContext_getNumMasks (AdmContext context, AdmError *error)
	AdmContext mask set length aggregator.
AdmIdentity *	AdmContext_getIdentityRoot (AdmContext context, AdmError *error)
	AdmContext identity root accessor.
AdmIdentity *	AdmIdentity_getParentA (AdmIdentity identity, AdmError *error)
	AdmIdentity parentA accessor.
AdmIdentity *	AdmIdentity_getParentB (AdmIdentity identity, AdmError *error)
	AdmIdentity parentB accessor.
AdmRefStr *	AdmIdentity_getName (AdmIdentity identity, AdmError *error)
	AdmIdentity name accessor.
int	AdmIdentity_setName (AdmIdentity identity, const char name, AdmError **error)
	AdmIdentity name mutator.
unsigned int	AdmIdentity_getSerial (AdmIdentity identity, AdmError *error)
	AdmIdentity serial number accessor.
int	AdmIdentity_setSerial (AdmIdentity identity, unsigned int serial, AdmError *error)
	AdmIdentity serial number mutator.
AdmIdentity *	AdmIdentity_ref (AdmIdentity identity, AdmError *error)
	AdmIdentity reference increment.
void	AdmIdentity_unref (AdmIdentity identity, AdmError *error)
	AdmIdentity reference decrement.
AdmContext *	AdmIdentity_getContext (AdmIdentity identity, AdmError *error)
	AdmIdentity context accessor.
int	AdmIdentity_isAlive (AdmIdentity identity, AdmError *error)
	AdmIdentity reference check.
AdmData *	AdmContext_getDataRoot (AdmContext context, AdmError *error)
	AdmContext data root accessor.
AdmData *	AdmData_getContainer (AdmData data, AdmError *error)
	AdmData container accessor.
AdmData *	AdmData_getPrev (AdmData data, int wrap, AdmError *error)
	get the previous sibling of an AdmData element
AdmData *	AdmData_getNext (AdmData data, int wrap, AdmError *error)
	get the next sibling of an AdmData element
AdmContext *	AdmData_getContext (AdmData data, AdmError *error)
	AdmData context accessor.
AdmData *	AdmContext_getDataByPath (AdmContext context, const char path, AdmError **error)
	AdmData path lookup.
AdmDataType	AdmData_getType (AdmData data, AdmError *error)
	AdmData type accessor.
AdmData *	AdmData_ref (AdmData data, AdmError *error)
	AdmData reference increment.
void	AdmData_unref (AdmData data, AdmError *error)
	AdmData reference decrement.
int	AdmData_isAlive (AdmData data, AdmError *error)
	AdmData reference check.
int	AdmData_unlink (AdmData data, AdmError *error)
	AdmData unlink operator.
int	AdmData_validName (const char *name)
	Checks a string for name validity.
AdmRefStr *	AdmData_getName (AdmData data, AdmError *error)
	AdmData name accessor.
int	AdmData_setName (AdmData data, const char name, AdmError **error)
	AdmData name mutator.
AdmRefStr *	AdmData_getSource (AdmData data, AdmError *error)
	AdmData source accessor.
int	AdmData_setSource (AdmData data, const char source, AdmError **error)
	AdmData source mutator.
int	AdmData_isProtected (AdmData data, AdmError *error)
	AdmData protected verification.
int	AdmData_setProtected (AdmData data, int state, AdmError *error)
	AdmData protected mutator.
int	AdmList_isAnonymous (AdmList list, AdmError *error)
	AdmList anonymous verification.
int	AdmList_setAnonymous (AdmList list, int state, AdmError *error)
	AdmList anonymous mutator.
int	AdmList_isAtomic (AdmList list, AdmError *error)
	AdmList atomic verification.
int	AdmList_setAtomic (AdmList list, int state, AdmError *error)
	AdmList atomic mutator.
int	AdmList_isPrepend (AdmList list, AdmError *error)
	AdmList prepend verification.
int	AdmList_setPrepend (AdmList list, int state, AdmError *error)
	AdmList prepend mutator.
unsigned int	AdmList_getNumData (AdmList list, AdmError *error)
	AdmList length aggregator.
AdmData *	AdmList_getDataByIndex (AdmList list, unsigned int index, AdmError *error)
	AdmList child index accessor.
AdmData *	AdmList_getDataByName (AdmList list, const char name, AdmError **error)
	AdmList child name accessor.
AdmData *	AdmList_getDataByPath (AdmList list, const char path, AdmError **error)
	AdmList child data path accessor.
AdmData *	AdmList_addData (AdmList list, AdmDataType type, const char name, AdmError **error)
	AdmList add child operator.
int	AdmList_moveData (AdmList list, AdmData data, unsigned int index, AdmError **error)
	AdmList child move operator.
AdmData *	AdmList_copyData (AdmList list, AdmData data, AdmError **error)
	AdmList copy data operator.
AdmData *	AdmList_renameCopyData (AdmList list, AdmData data, const char name, AdmError *error)
	AdmList copy data operator.
unsigned int	AdmData_getPos (AdmData data, AdmError *error)
	AdmList child position operator.
int	AdmInt_getValue (AdmInt int_scalar, AdmError *error)
	get an AdmInt's value
int	AdmInt_setValue (AdmInt int_scalar, int value, AdmError *error)
	set an AdmInt's value
double	AdmFloat_getValue (AdmFloat float_scalar, AdmError *error)
	get an AdmFloat's value
int	AdmFloat_setValue (AdmFloat float_scalar, double value, AdmError *error)
	set an AdmFloat's value
int	AdmBool_getValue (AdmBool bool_scalar, AdmError *error)
	get an AdmBool's value
int	AdmBool_setValue (AdmBool bool_scalar, int value, AdmError *error)
	set an AdmBool's value
AdmRefStr *	AdmString_getValue (AdmString string_scalar, AdmError *error)
	get an AdmString's value
int	AdmString_setValue (AdmString string_scalar, const char value, AdmError **error)
AdmRefStr *	AdmBase64_getValue (AdmBase64 base64_scalar, AdmError *error)
int	AdmBase64_setValue (AdmBase64 base64_scalar, const char value, AdmError **error)
	Set the value of an AdmBase64 element.
size_t	AdmBase64_getBinValue (AdmBase64 base64_scalar, void value, AdmError *error)
	Get the binary value of an AdmBase64 element.
int	AdmBase64_setBinValue (AdmBase64 base64_scalar, const void value, size_t size, AdmError **error)
	Set the value of an AdmBase64 element.
AdmRefStr *	AdmCopy_getValue (AdmCopy copy_scalar, AdmError *error)
	Get the value of an AdmCopy element.
int	AdmCopy_setValue (AdmCopy copy_scalar, const char value, AdmError **error)
	Set the value of an AdmCopy element.
AdmRefStr *	AdmBlackBox_getCacheDir (AdmError **error)
int	AdmBlackBox_setCacheDir (const char path, AdmError *error)
AdmBlackBox *	AdmBlackBox_getBox (AdmList box_cfg, AdmError *error)
adm_bb_cap_t	AdmBlackBox_caps (AdmBlackBox box, AdmError *error)
	AdmBlackBox capability querry.
void	AdmBlackBox_ref (AdmBlackBox box, AdmError *error)
	AdmBlackbox reference increment.
void	AdmBlackBox_unref (AdmBlackBox box, AdmError *error)
	AdmBlackbox reference decrement.
AdmContext *	AdmBlackBox_read (AdmBlackBox box, AdmError *error)
	AdmBlackbox read operator.
int	AdmBlackBox_listSerial (AdmBlackBox box, unsigned int array, unsigned int array_len, unsigned int top_serial, AdmError **error)
	AdmBlackbox serial list request.
AdmContext *	AdmBlackBox_readSerial (AdmBlackBox box, unsigned int serial, AdmError *error)
	AdmBlackbox serial list request.
int	AdmBlackBox_write (AdmBlackBox box, AdmContext context, AdmError **error)
	AdmBlackbox write operator.
unsigned int	AdmBlackBox_getMark (AdmBlackBox box, const char mark, AdmError **error)
	AdmBlackBox mark accessor.
int	AdmBlackBox_setMark (AdmBlackBox box, const char mark, AdmError **error)
	AdmBlackBox mark mutator.
int	AdmBlackBox_clearMark (AdmBlackBox box, const char mark, AdmError **error)
	AdmBlackbox mark destructor.
AdmRefStr *	AdmSwitchboard_getSwbDir (AdmError **error)
int	AdmSwitchboard_setSwbDir (const char path, AdmError *error)
int	AdmSwitchboard_markNsp (const char namespace, const char subspace, const char mark, AdmError *error)
int	AdmSwitchboard_markNspWithConfig (AdmList namespace_cfg, const char subspace, const char mark, AdmError *error)
int	AdmSwitchboard_checkNspMark (const char namespace, const char subspace, const char mark, AdmError *error)
int	AdmSwitchboard_checkNspMarkWithConfig (AdmList namespace_cfg, const char subspace, const char mark, AdmError *error)
AdmContext *	AdmSwitchboard_readNsp (const char namespace, const char subspace, unsigned int depth, AdmError **error)
AdmContext *	AdmSwitchboard_readNspWithConfig (AdmList namespace_cfg, const char subspace, unsigned int depth, AdmError **error)
int	AdmSwitchboard_writeNsp (const char namespace, const char subspace, AdmContext context, AdmError *error)
int	AdmSwitchboard_writeNspWithConfig (AdmList namespace_cfg, const char subspace, AdmContext context, AdmError *error)
AdmContext *	AdmSwitchboard_readNspCtx (const char namespace, AdmError *error)
	read a switchboard namespace configuration from the system
int	AdmSwitchboard_writeNspCtx (const char namespace, AdmContext namespace_ctx, int mode, uid_t uid, gid_t gid, AdmError **error)
	writes a switchboard namespace configuration to the system
AdmList *	AdmSwitchboard_getNspCfg (AdmContext namespace_ctx, const char namespace, AdmError **error)
AdmList *	AdmSwitchboard_getSubspCfg (AdmList namespace_cfg, const char subspace, AdmError **error)
AdmBlackBox *	AdmSwitchboard_getBox (AdmList subspace_cfg, const char box_name, AdmError **error)

Define Documentation

#define ALCHEMIST_ABI_MAJOR_VER 0

#define ALCHEMIST_ABI_MINOR_VER 0

#define ADM_EDEADNODE 1

#define ADM_EBADTYPE 2

#define ADM_EBADNAME 3

#define ADM_EBADDATA 4

#define ADM_ECONSTRAINT 5

#define ADM_ENOINDEX 51

#define ADM_ENONAME 52

#define ADM_ENOPATH 53

#define ADM_EACCESSFAILED 101

#define ADM_ENONAMESPACE 102

#define ADM_ENOSUBSPACE 103

#define ADM_ENOWRITE 201

#define ADM_ENOREAD 202

#define ADM_ENOLISTSERIAL 203

#define ADM_ENOREADSERIAL 204

#define ADM_ENOCACHE 205

#define ADM_ENOBOXTYPE 251

#define ADM_EPARSE 301

#define AdmRefStr_str ( REFSTR )

Value:

({ \
        AdmRefStr *__tok = (REFSTR); \
        (const char *) __tok; \
})

#define AdmContext_getIdentityRoot_b	(	CONTEXT,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmIdentity *__id; \
        __id = AdmContext_getIdentityRoot((CONTEXT), __err); \
        if (__id != NULL) \
                AdmIdentity_unref(__id, __err); \
        __id; \
})

#define AdmIdentity_getParentA_b	(	ID,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmIdentity *__id; \
        __id = AdmIdentity_getParentA((ID), __err); \
        if (__id != NULL) \
                AdmIdentity_unref(__id, __err); \
        __id; \
})

#define AdmIdentity_getParentB_b	(	ID,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmIdentity *__id; \
        __id = AdmIdentity_getParentB((ID), __err); \
        if (__id != NULL) \
                AdmIdentity_unref(__id, __err); \
        __id; \
})

#define AdmIdentity_getContext_b	(	ID,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmContext *__ctx; \
        __ctx = AdmIdentity_getContext((ID), __err); \
        if (__ctx != NULL) \
                AdmContext_unref(__ctx, __err); \
        __ctx; \
})

#define AdmContext_getDataRoot_b	(	CONTEXT,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmContext_getDataRoot((CONTEXT), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmData_getContainer_b	(	DATA,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmData_getContainer((DATA), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmData_getPrev_b	(	DATA,
		WRAP,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmData_getPrev((DATA), (WRAP), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmData_getNext_b	(	DATA,
		WRAP,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmData_getNext((DATA), (WRAP), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmData_getContext_b	(	DATA,
		ERROR		)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmContext *__ctx; \
        __ctx = AdmData_getContext((DATA), __err); \
        if (__ctx != NULL) \
                AdmContext_unref(__ctx, __err); \
        __ctx; \
})

#define AdmContext_getDataByPath_b	(	CONTEXT,
		PATH,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmContext_getDataByPath((CONTEXT), (PATH), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmList_getDataByIndex_b	(	LIST,
		INDEX,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmList_getDataByIndex((LIST), (INDEX), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmList_getDataByName_b	(	LIST,
		NAME,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmList_getDataByName((LIST), (NAME), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmList_getDataByPath_b	(	LIST,
		PATH,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmList_getDataByPath((LIST), (PATH), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmList_addData_b	(	LIST,
		TYPE,
		NAME,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmList_addData((LIST), (TYPE), (NAME), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmList_copyData_b	(	LIST,
		DATA,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmList_copyData((LIST), (DATA), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define AdmList_renameCopyData_b	(	LIST,
		DATA,
		NAME,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmData *__data; \
        __data = AdmList_renameCopyData((LIST), (DATA), (NAME), __err); \
        if (__data != NULL) \
                AdmData_unref(__data, __err); \
        __data; \
})

#define ADM_BBCAP_SUP_WRITE ( CAP ) ((CAP).array[0] & (1 << 0))

#define ADM_BBCAP_SUP_READ ( CAP ) ((CAP).array[0] & (1 << 1))

#define ADM_BBCAP_SUP_LISTSERIAL ( CAP ) ((CAP).array[0] & (1 << 2))

#define ADM_BBCAP_SUP_READSERIAL ( CAP ) ((CAP).array[0] & (1 << 3))

#define ADM_BBCAP_CACHED ( CAP ) ((CAP).array[0] & (1 << 4))

#define AdmSwitchboard_getNspCfg_b	(	CTX,
		NAMESPACE,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmList *__list; \
        __list = AdmSwitchboard_getNspCfg((CTX), (NAMESPACE), __err); \
        if (__list != NULL) \
                AdmData_unref((AdmData *) __list, __err); \
        __list; \
})

#define AdmSwitchboard_getSubspCfg_b	(	CTX,
		SUBSPACE,
		ERROR	)

Value:

({ \
        AdmError **__err = (ERROR); \
        AdmList *__list; \
        __list = AdmSwitchboard_getSubspCfg((CTX), (SUBSPACE), __err); \
        if (__list != NULL) \
                AdmData_unref((AdmData *) __list, __err); \
        __list; \
})

Typedef Documentation

typedef struct AdmError AdmError

typedef struct AdmRefStr AdmRefStr

typedef struct AdmData AdmData

typedef struct AdmList AdmList

typedef struct AdmInt AdmInt

typedef struct AdmBool AdmBool

typedef struct AdmFloat AdmFloat

typedef struct AdmString AdmString

typedef struct AdmString AdmBase64

typedef struct AdmString AdmCopy

typedef struct AdmIdentity AdmIdentity

typedef struct AdmContext AdmContext

typedef struct AdmBlackBox AdmBlackBox

Enumeration Type Documentation

enum AdmDataType

Enumerator:

ADM_TYPE_UNKNOWN
ADM_TYPE_LIST
ADM_TYPE_COPY
ADM_TYPE_INT
ADM_TYPE_FLOAT
ADM_TYPE_BOOL
ADM_TYPE_STRING
ADM_TYPE_BASE64

Function Documentation

void AdmError_create	(	AdmError **	error,
		int	num,
		const char *	format,
			...
	)

Constructor/allocator for our AdmError structure. Fails safely and silently if error is NULL.

Parameters:

	error	The pointer to the AdmError pointer in which the newly allocated AdmError structure will be returned.
	num	The integer error code of the new AdmError structure.
	format	The output format in printf(3) format.
	...	The variable arguments for the printf(3) format.

void AdmError_ref ( AdmError * error )

Parameters:

error

The pointer to the AdmError structure to be deallocated.

void AdmError_unref ( AdmError * error )

Decrements the reference count of the given AdmError function, and deallocates it when the count reaches 0. This function must only be called by reference holders.

Parameters:

error

The pointer to the AdmError structure to be deallocated.

const char* AdmError_strerr ( AdmError * error )

Returns the error string of the given AdmError structure. The error string returned is guaranteed for only as long as the AdmError is refed. Users that want a copy, should make one.

Parameters:

error

The pointer to the AdmError structure.

Returns:: The character string that contains the description of the error of the given AdmError structure.

Note:: Based on the strerror(3) *NIX C library.

int AdmError_errno ( AdmError * error )

Returns the error code of the given AdmError structure.

Parameters:

error

The pointer to the AdmError structure.

Returns:: The int error code of the given AdmError structure. See admerror.h for a list of valid error code.

Note:: Based on errno(3) *NIX C library.

See also:: AdmError

AdmRefStr* AdmRefStr_ref ( AdmRefStr * refstr )

void AdmRefStr_unref ( AdmRefStr * refstr )

size_t AdmRefStr_len ( AdmRefStr * refstr )

AdmRefStr* AdmRefStr_get	(	const char *	str,
		int	force
	)

Parameters:

	str	the string to match the AdmRefStr to
	force	if we should create a matching AdmRefStr if one does not already exist

Returns:: the unique matching AdmRefStr, or NULL if there is no match

AdmRefStr* AdmRefStr_nget	(	const char *	str,
		size_t	len,
		int	force
	)

Parameters:

	str	the string to match the AdmRefStr to
	len	the lenght of the string, as strlen would report it
	force	if we should create a matching AdmRefStr if one does not already exist

Returns:: the unique matching AdmRefStr, or NULL if there is no match

AdmContext* AdmContext_new	(	const char *	name,
		unsigned int	serial,
		AdmError **	error
	)

AdmContext_new: create a new AdmContext element.

This function creates a new AdmContext element. Its root id node will be initialized using the passed name and serial. The returned AdmContext will be given a ref for the caller.

Parameters:

	name	The name of the new AdmContext.
	serial	The serial number of the new AdmContext.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the new AdmContext element or NULL on failure.

AdmContext* AdmContext_ref	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_ref: ref an AdmContext element.

Increases the refcount of an AdmContext element

Parameters:

	context	The AdmContext to increase the reference to.
	error	Optional pointer to AdmError pointer.

Returns:: The AdmContext

void AdmContext_unref	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_unref: unref an AdmContext element.

Unrefs an AdmContext. This will free the context, and all its children, when the ref count reaches 0. It is an error for an entity which does not own a ref to a context to call AdmContext_unref. AdmContext refs can be acquired only by calls to AdmContext_new, AdmContext_copy, AdmContext_merge, AdmContext_fromXML, and AdmContext_ref.

Parameters:

	context	The AdmContext to decrease the reference to.
	error	Optional pointer to AdmError pointer.

AdmContext* AdmContext_copy	(	AdmContext *	context,
		AdmError **	error
	)

This function creates a full depth copy of an AdmContext element. It is one of the AdmContext refing functions.

Parameters:

	context	The pointer to the AdmContext element to be copied.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the copied AdmContext element.

AdmContext* AdmContext_merge	(	const char *	name,
		unsigned int	serial,
		AdmContext *	contextA,
		AdmContext *	contextB,
		AdmError **	error
	)

AdmContext_merge: merge two AdmContext elements into a third.

This is the heart function of the Alchemist. It performs the context merge algorithm upon two contexts, and returns the result. It is also one of the refing functions, as the returned child is refed for the caller.

Parameters:

	name	The name of the new AdmContext.
	serial	The serial number of the new AdmContext.
	contextA	The pointer to the first AdmContext element.
	contextB	The pointer to the second AdmContext element.
	error	Optional pointer to an AdmError pointer.

Returns:: The pointer to the new AdmContext element which contains the result of the merge operation of contextA and contextB or NULL on failure.

void AdmContext_flatten	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_flatten: flatten an AdmContext element.

This function strips all masks and AdmCopy elements from an AdmContext element.

Parameters:

	context	The pointer to the AdmContext element.
	error	Optional pointer to AdmError pointer.

void AdmContext_strip	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_strip: strip an AdmContext's id tree.

This function strips all ids except for the root id from an AdmContext's id tree.

Parameters:

	context	The pointer to the AdmContext element.
	error	Optional pointer to AdmError pointer.

char* AdmContext_toXML	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext* AdmContext_fromXML	(	const char *	xml,
		AdmError **	error
	)

int AdmContext_readFromFile	(	AdmContext **	context,
		const char *	path,
		AdmError **	error
	)

int AdmContext_writeToFile	(	AdmContext *	context,
		const char *	path,
		int	mode,
		uid_t	uid,
		gid_t	gid,
		AdmError **	error
	)

AdmRefStr* AdmContext_getMask	(	AdmContext *	context,
		unsigned int	index,
		AdmError **	error
	)

AdmContext_getMask: Gets a mask element from an AdmContext by index.

This function is used to request the index'th mask of an AdmContext element's mask set. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Specifically, it is guranteed for only so long as the AdmContext element is refed, and the mask is not cleared.

Parameters:

	context	The AdmContext to use.
	index	The index of the mask set element to get.
	error	Optional pointer to AdmError pointer.

Returns:: The mask set element AdmRefStr.

int AdmContext_setMask	(	AdmContext *	context,
		const char *	path,
		AdmError **	error
	)

AdmContext_setMask: set a mask in an AdmContext element's mask set.

This function adds a mask path to an AdmContext element's mask set. It will quietly handle duplicate paths. Blank paths will not be added.

Parameters:

	context	The AdmContext to use.
	path	The string of the mask set element to be added.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

Note:: This could be made much faster, if we searched the set only once.

int AdmContext_clearMaskByIndex	(	AdmContext *	context,
		unsigned int	index,
		AdmError **	error
	)

AdmContext_clearMaskByIndex: remove a mask entry from an AdmContext by index.

This function removes a mask entry from an AdmContext element by searching against the passed index. It is an error to index past the end of the mask set.

Parameters:

	context	The AdmContext to use.
	index	The index of the mask set element to remove.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

int AdmContext_clearMaskByPath	(	AdmContext *	context,
		const char *	path,
		AdmError **	error
	)

AdmContext_clearMaskByPath: remove a mask entry from an AdmContext by string.

This function removes a mask entry from an AdmContext element by searching against the passed string.

Parameters:

	context	The AdmContext to use.
	path	The data path of the mask set element to remove.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

unsigned int AdmContext_getNumMasks	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_getNumMasks: Gets the number of masks in an AdmContext's mask set.

This function returns the number of masks in an AdmContext's mask set.

Parameters:

	context	The AdmContext to use.
	error	Optional pointer to AdmError pointer.

Returns:: The number of mask set element of the given AdmContext.

AdmIdentity* AdmContext_getIdentityRoot	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_getIdentityRoot: Get the root AdmIdentity element of an AdmContext's id tree.

This function gets the root node AdmIdentity element of an AdmContext element's id tree.

Parameters:

	context	The AdmContext of which we want to get the root AdmIdentity.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the root AdmIdentity element.

AdmIdentity* AdmIdentity_getParentA	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_getParentA: Get the A parent of an AdmIdentity element.

This function returns the A parent of an AdmIdentity element, if it exists. Otherwise, it returns NULL.

Parameters:

	identity	The AdmIdentity of which to get the first parent.
	error	Optional pointer to AdmError pointer.

Returns:: The AdmIdentity pointer to the first parent.

AdmIdentity* AdmIdentity_getParentB	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_getParentB: Get the B parent of an AdmIdentity element.

This function returns the B parent of an AdmIdentity element, if it exists. Otherwise, it returns NULL.

Parameters:

	identity	The AdmIdentity of which to get the second parent.
	error	Optional pointer to AdmError pointer.

Returns:: The AdmIdentity pointer to the first parent.

AdmRefStr* AdmIdentity_getName	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_getName: Get the name of an AdmIdentity element.

This function is used to request the name of an AdmIdentity element. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Specifically, it is guranteed for only so long as the AdmCopy element is refed, and its value is not changed.

Parameters:

	identity	The AdmIdentity of which to get the name.
	error	Optional pointer to AdmError pointer.

Returns:: The name of the given AdmIdentity in an AdmRefStr.

int AdmIdentity_setName	(	AdmIdentity *	identity,
		const char *	name,
		AdmError **	error
	)

AdmIdentity_setName: Set the name of an AdmIdentity element.

This function sets the name of an AdmIdentity element.

Parameters:

	identity	The AdmIdentity of which to set the name.
	name	The new name of the AdmIdentity.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

unsigned int AdmIdentity_getSerial	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_getSerial: Get the serial number of an AdmIdentity element.

This function gets the serial number of an AdmIdentity element.

Parameters:

	identity	The AdmIdentity of which to get the serial number.
	error	Optional pointer to AdmError pointer.

Returns:: The serial number of the given AdmIdentity.

int AdmIdentity_setSerial	(	AdmIdentity *	identity,
		unsigned int	serial,
		AdmError **	error
	)

AdmIdentity_setSerial: Set the serial number of an AdmIdentity element.

This function sets the serial number of an AdmIdentity element.

Parameters:

	identity	The AdmIdentity of which to set the serial number.
	name	The new serial number of the AdmIdentity.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

AdmIdentity* AdmIdentity_ref	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_ref: ref an AdmIdentity element.

This function refs an AdmIdentity element. It is the only way to acquire a ref to an AdmIdentity element.

Parameters:

	identity	The AdmIdentity to increase the reference to.
	error	Optional pointer to AdmError pointer.

Returns:: The AdmIdentity (for convienience).

void AdmIdentity_unref	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_unref: unref an AdmIdentity element.

This function unrefs an AdmIdentity element, and frees it if the refcount reaches 0. It must only be called by entities which own a ref to the AdmIdentity element. AdmIdentity refs can only be aquired by calling AdmIdentity_ref.

Parameters:

	identity	The AdmIdentity to decrease the reference to.
	error	Optional pointer to AdmError pointer.

AdmContext* AdmIdentity_getContext	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_getContext: Get the context of an AdmIdentity element.

This function returns a pointer to the AdmContext in which this AdmIdentity element exists.

Parameters:

	id	The pointer to the AdmIdentity element.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the AdmContext of the given AdmIdentity.

int AdmIdentity_isAlive	(	AdmIdentity *	identity,
		AdmError **	error
	)

AdmIdentity_isAlive: check the lifecycle status of an AdmIdentity element.

This function checks the lifecycle status of an AdmIdentity element. It is used to tell if an element is still linked against an AdmContext, and is 'alive'; or if it is not, and is 'dead'.

A dead element must have a reference held against it that is not its container's reference.

Parameters:

	identity	The AdmIdentity to check.
	error	Optional pointer to AdmError pointer.

Returns:: TRUE if Identity is still referenced, FALSE otherwise.

AdmData* AdmContext_getDataRoot	(	AdmContext *	context,
		AdmError **	error
	)

AdmContext_getDataRoot: Get the root AdmData element of an AdmContext's data tree.

This function gets the root AdmData element of an AdmContext's data tree.

Parameters:

	context	The AdmContext of which we want to get the AdmData root.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the root AdmData element.

AdmData* AdmData_getContainer	(	AdmData *	data,
		AdmError **	error
	)

AdmData_getContainer: Get the container of an AdmData element.

This function returns a pointer to the AdmData element which contains this AdmData element. For the root node, it will return a pointer to the AdmData element it was passed.

Parameters:

	data	The AdmData of which we want to get the container (parent).
	error	Optional pointer to AdmError pointer.

Returns:: The container/parent of the given AdmData element.

AdmData* AdmData_getPrev	(	AdmData *	data,
		int	wrap,
		AdmError **	error
	)

Parameters:

	data	The AdmData element
	wrap	specify if we should wrap round the begining of the list
	error	Optional pointer to AdmError pointer.

Returns:: the previous AdmData element

AdmData* AdmData_getNext	(	AdmData *	data,
		int	wrap,
		AdmError **	error
	)

Parameters:

	data	The AdmData element
	wrap	specify if we should wrap round the end of the list
	error	Optional pointer to AdmError pointer.

Returns:: the next AdmData element

AdmContext* AdmData_getContext	(	AdmData *	data,
		AdmError **	error
	)

AdmData_getContext: Get the context of an AdmData element.

This function returns a pointer to the AdmContext in which this AdmData element exists.

Parameters:

	data	The AdmData of which we want to get the context.
	error	Optional pointer to AdmError pointer.

Returns:: The context of the given AdmData element.

AdmData* AdmContext_getDataByPath	(	AdmContext *	context,
		const char *	path,
		AdmError **	error
	)

AdmContext_getDataByPath: Gets an AdmData element from an AdmContext by path.

This function does path lookups against AdmContext element's data trees. It will give an error if no matching AdmData element is found.

Parameters:

	context	The AdmContext we want to search.
	path	The data path of the AdmData element to look up.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the found AdmData element or NULL on failure.

AdmDataType AdmData_getType	(	AdmData *	data,
		AdmError **	error
	)

AdmData_getType: Get the type of an AdmData element.

This function gets the type of an AdmData element

Parameters:

	data	The AdmData of which we want to get the data type.
	error	Optional pointer to AdmError pointer.

Returns:: The data type of the given AdmData element.

AdmData* AdmData_ref	(	AdmData *	data,
		AdmError **	error
	)

AdmData_ref: ref an AdmData element.

This function refs an AdmData element. It is the only way to aquire a ref to an AdmData element.

Parameters:

	data	The AdmData to increase the reference to.
	error	Optional pointer to AdmError pointer.

Returns:: The AdmData element

void AdmData_unref	(	AdmData *	data,
		AdmError **	error
	)

AdmData_unref: unref an AdmData element.

This function unrefs an AdmData element, and frees it if the refcount reaches 0. It must only be called by entities which own a ref to the AdmData element. AdmData refs can only be aquired by calling AdmData_ref.

Parameters:

	data	The AdmData to decrease the reference to.
	error	Optional pointer to AdmError pointer.

int AdmData_isAlive	(	AdmData *	data,
		AdmError **	error
	)

AdmData_isAlive: check the lifecycle status of an AdmData element.

This function checks the lifecycle status of an AdmData element. It is used to tell if an element is still linked against an AdmContext, and is 'alive'; or if it is not, and is 'dead'.

A dead element must have a reference held against it that is not its container's reference.

Parameters:

	data	The AdmData to check.
	error	Optional pointer to AdmError pointer.

Returns:: TRUE if Data is still referenced, FALSE otherwise.

int AdmData_unlink	(	AdmData *	data,
		AdmError **	error
	)

AdmData_unlink: Unlink an AdmData element from its container.

This function recursively unlinks an AdmData element from its containing AdmData element. It unrefs each element which it unlinks, as they loose their parents reference. It is an error to unlink the root node, and will fail.

Parameters:

	data	The AdmData to unlink.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

int AdmData_validName ( const char * name )

Checks a string to determine if it is a valid AdmData name. A valid name is of the form: Name = (Letter | '_') (Letter | Digit | '_' | '-' | '.'){0,254} Letter = ['a' - 'z'] | ['A' - 'Z'] Digit = ['0' - '9']

Parameters:

name

The string to check.

Returns:: 1 if the name is valid, 0 if the name is not.

AdmRefStr* AdmData_getName	(	AdmData *	data,
		AdmError **	error
	)

AdmData_getName: Get the name of an AdmData element.

This function is used to request the name of an AdmData element. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Specifically, it is guranteed for only so long as the AdmData element is refed, and its name is not changed.

Parameters:

	data	The AdmData of which we want to get the name.
	error	Optional pointer to AdmError pointer.

Returns:: The name of the given AdmData element.

int AdmData_setName	(	AdmData *	data,
		const char *	name,
		AdmError **	error
	)

AdmData_setName: Set the name of an AdmData element.

This function sets the name of an AdmData element to a copy of the passed string.

It will not alter the root node, and it is an error to attempt it.

Parameters:

	data	The AdmData of which we want to set the name.
	name	The new name of the AdmData element.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

AdmRefStr* AdmData_getSource	(	AdmData *	data,
		AdmError **	error
	)

AdmData_getSource: Get the source of an AdmData element.

This function is used to request the source of an AdmData element. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Specifically, it is guranteed for only so long as the AdmData element is refed, and its source is not changed. The source of the root data node changes every time the name of the root id node changes.

Parameters:

	data	The AdmData of which we want to get the source.
	error	Optional pointer to AdmError pointer.

Returns:: The source of the given AdmData element.

int AdmData_setSource	(	AdmData *	data,
		const char *	source,
		AdmError **	error
	)

AdmData_setSource: Set the source of an AdmData element.

This function sets the source of an AdmData element to a copy of the passed string.

It will not alter the root node, and it is an error to attempt it.

Parameters:

	data	The AdmData of which we want to set the source.
	name	The new source of the AdmData element.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

int AdmData_isProtected	(	AdmData *	data,
		AdmError **	error
	)

AdmData_isProtected: Get the state of an AdmData's protected flag.

This function gets the state of an AdmData's protected flag.

Parameters:

	data	The AdmData which we want to check for the protected flag.
	error	Optional pointer to AdmError pointer.

Returns:: TRUE if the given AdmData element is protected, FALSE otherwise.

int AdmData_setProtected	(	AdmData *	data,
		int	state,
		AdmError **	error
	)

AdmData_setProtected: Set an AdmData's protected flag.

This function sets the protected flag of an AdmData element to the value passed.

It will not set the flag of the root node, and is an error to attempt it.

Parameters:

	data	The AdmData of which we want to set the protected flag.
	state	The new protection state of the AdmData element.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

int AdmList_isAnonymous	(	AdmList *	list,
		AdmError **	error
	)

AdmList_isAnonymous: Get the state of an AdmList's anonymous flag.

This function gets the state of an AdmList's anonymous flag.

Parameters:

	list	The AdmList which we want to check for the anonymous flag.
	error	Optional pointer to AdmError pointer.

Returns:: TRUE if the given AdmList element is anonymous, FALSE otherwise.

int AdmList_setAnonymous	(	AdmList *	list,
		int	state,
		AdmError **	error
	)

AdmList_setAnonymous: Set an AdmList's anonymous flag.

This function sets the anonymous flag of an AdmList element to the value passed. It will not allow the flag to be cleared if it will cause a name collide, and will raise an error.

It will not set the flag of the root node, and is an error to attempt it.

Parameters:

	list	The AdmList of which we want to set the anonymous flag.
	state	The new anonymous state of the AdmList element.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

int AdmList_isAtomic	(	AdmList *	list,
		AdmError **	error
	)

AdmList_isAtomic: Get the state of an AdmList's atomic flag.

This function gets the state of an AdmList's atomic flag.

Parameters:

	list	The AdmList which we want to check for the atomic flag.
	error	Optional pointer to AdmError pointer.

Returns:: TRUE if the given AdmList element is atomic, FALSE otherwise.

int AdmList_setAtomic	(	AdmList *	list,
		int	state,
		AdmError **	error
	)

AdmList_setAtomic: Set an AdmList's atomic flag.

This function sets the atomic flag of an AdmList element to the value passed.

It will not set the flag of the root node, and is an error to attempt it.

Parameters:

	list	The AdmList of which we want to set the atomic flag.
	state	The new atomic state of the AdmList element.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

int AdmList_isPrepend	(	AdmList *	list,
		AdmError **	error
	)

AdmList_isPrepend: Get the state of an AdmList's prepend flag.

This function gets the state of an AdmList's prepend flag.

Parameters:

	list	The AdmList which we want to check for the prepend flag.
	error	Optional pointer to AdmError pointer.

Returns:: TRUE if the given AdmList element is prepend, FALSE otherwise.

int AdmList_setPrepend	(	AdmList *	list,
		int	state,
		AdmError **	error
	)

AdmList_setPrepend: Set an AdmList's prepend flag.

This function sets the prepend flag of an AdmList element to the value passed.

It will not set the flag of the root node, and is an error to attempt it.

Parameters:

	list	The AdmList of which we want to set the prepend flag.
	state	The new prepend state of the AdmList element.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

unsigned int AdmList_getNumData	(	AdmList *	list,
		AdmError **	error
	)

AdmList_getNumData: Get the size of an AdmList's child set.

This function gets the number of children held in an AdmList's child set.

Parameters:

	list	The AdmList which we want to count.
	error	Optional pointer to AdmError pointer.

Returns:: The number of children inside the given list.

AdmData* AdmList_getDataByIndex	(	AdmList *	list,
		unsigned int	index,
		AdmError **	error
	)

AdmList_getDataByIndex: Get a child of an AdmList element by its index.

This function seeks on an AdmList's child set, and returns its index'th child. It is an error to seek on an index greater >= the list length, since the first element is stored at index 0.

Parameters:

	list	The AdmList which we want to access.
	index	The index of the child we want to get.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to requested AdmData element of the list.

AdmData* AdmList_getDataByName	(	AdmList *	list,
		const char *	name,
		AdmError **	error
	)

AdmList_getDataByName: Get a child od an AdmList element by its name.

This function seeks againts an AdmList's child set, and returns the first child whose name matches the search name. It raises a AdmError if no name is found.

Parameters:

	list	The AdmList which we want to access.
	name	The name of the child we want to get.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to requested AdmData element of the list.

AdmData* AdmList_getDataByPath	(	AdmList *	list,
		const char *	path,
		AdmError **	error
	)

AdmList_getDataByPath: Get a child od an AdmList element by its path.

This function seeks againts an AdmList's child set, and returns the first child whose path matches the search path. It raises a AdmError if no path is found.

Parameters:

	list	The AdmList which we want to access.
	path	The data path of the child we want to get.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to requested AdmData element of the list.

AdmData* AdmList_addData	(	AdmList *	list,
		AdmDataType	type,
		const char *	name,
		AdmError **	error
	)

AdmList_addData: add a new child to an AdmList element.

This function appends a new child of the given type and name to the end of the AdmList. It returns a pointer to the new AdmData element. Name collides in non-anonymous lists are errors.

Note that new AdmCopy elements will have the invalid reference "" as their initial value, and must be changed.

The new child is refed, but the ref is owned by its AdmList element, and no ref is implied to the accessor.

Parameters:

	list	The AdmList to which we want to add a new child.
	type	The AdmData type of the new child to be added.
	name	The name of the new child to be added.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the newly added AdmData element.

int AdmList_moveData	(	AdmList *	list,
		AdmData *	data,
		unsigned int	index,
		AdmError **	error
	)

AdmList_moveData: reposition an AdmData element in its containing AdmList.

This function extracts an AdmData element from its containing list, and then reinserts it at the index value passed. It is an error to give it an illegal index value.

Parameters:

	list	The AdmList which we want to move in.
	data	The AdmData pointer of the child we want to move.
	index	The index to where we want to move the child.
	error	Optional pointer to AdmError pointer.

Returns:: -1 on error, 0 on success

AdmData* AdmList_copyData	(	AdmList *	list,
		AdmData *	data,
		AdmError **	error
	)

AdmList_copyData: copy a AdmData element into an AdmList element.

This function recursively copies an AdmData tree from the passed data node, and inserts the result onto the end of the passed AdmList. It checks for name collides in Non-anonymous lists, and will not copy a root node; both are errors.

Parameters:

	list	The AdmList to append the data to.
	data	The AdmData element to recursively copy and append to the list.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the newly copied and appended AdmData element.

AdmData* AdmList_renameCopyData	(	AdmList *	list,
		AdmData *	data,
		const char *	name,
		AdmError **	error
	)

AdmList_renameCopyData: copy and rename an AdmData element into an AdmList element.

This function recursively copies an AdmData tree from the passed data node, and inserts the result onto the end of the passed AdmList, using the specified name. It checks for name collides in Non-anonymous lists, and will not copy a root node; both are errors.

Parameters:

	list	The AdmList to append the data to.
	data	The AdmData element to recursively copy and append to the list.
	name	The new name to use.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the newly copied and appended AdmData element.

unsigned int AdmData_getPos	(	AdmData *	data,
		AdmError **	error
	)

AdmData_getPos: Get the position of an AdmData node in its containing list.

This function returns the position that an AdmData node holds in its containing list. The position of the root node is defined to be 0.

Parameters:

	data	The AdmData of which we want to know the index.
	error	Optional pointer to AdmError pointer.

Returns:: The index of the data element in it's parent list.

int AdmInt_getValue	(	AdmInt *	int_scalar,
		AdmError **	error
	)

Gets the integer value stored in an AdmInt node.

Parameters:

	int_scalar	a pointer to an AdmInt node
	error	an optional pointer to an AdmError pointer

Returns:: the value of the node

See also:: AdmInt; AdmError

int AdmInt_setValue	(	AdmInt *	int_scalar,
		int	value,
		AdmError **	error
	)

Sets the integer value stored in an AdmInt node.

Parameters:

	int_scalar	a pointer to an AdmInt node
	value	the integer value to set the node to
	error	an optional pointer to an AdmError pointer

Returns:: -1 on error, 0 on success

See also:: AdmInt; AdmError

double AdmFloat_getValue	(	AdmFloat *	float_scalar,
		AdmError **	error
	)

Gets the double value stored in an AdmFloat node.

Parameters:

	float_scalar	a pointer to an AdmFloat node
	error	an optional pointer to an AdmError pointer

Returns:: the double value of the node

See also:: AdmFloat; AdmError

int AdmFloat_setValue	(	AdmFloat *	float_scalar,
		double	value,
		AdmError **	error
	)

Sets the double value stored in an AdmFloat node.

Parameters:

	float_scalar	a pointer to an AdmFloat element
	value	the double value to set the node with
	error	an optional pointer to an AdmError pointer

Returns:: -1 on error, 0 on success

See also:: AdmFloat; AdmError

int AdmBool_getValue	(	AdmBool *	bool_scalar,
		AdmError **	error
	)

Gets the boolean value stored in an AdmBool node.

Parameters:

	bool_scalar	a pointer to an AdmBool node
	error	an optional pointer to an AdmError pointer

Returns:: the value of the node as an int

See also:: AdmBool; AdmError

int AdmBool_setValue	(	AdmBool *	bool_scalar,
		int	value,
		AdmError **	error
	)

Sets the boolean value stored in an AdmBool node.

Parameters:

	bool_scalar	a pointer to an AdmBool node
	value	the value to set the node to as an int
	error	an optional pointer to an AdmError pointer

Returns:: -1 on error, 0 on success

See also:: AdmBool; AdmError

AdmRefStr* AdmString_getValue	(	AdmString *	string_scalar,
		AdmError **	error
	)

Get the value of an AdmString element.

This function is used to request the string stored in an AdmString element. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Specifically, it is guaranteed for only so long as the AdmString element remains refed, and its value is not changed.

Parameters:

	string_scalar	The pointer to the AdmString element
	error	optional pointer to an AdmError pointer

Returns:: An AdmRefStr with the AdmString element's value string.

int AdmString_setValue	(	AdmString *	string_scalar,
		const char *	value,
		AdmError **	error
	)

Set the value of an AdmString element.

This function is used to set the value of an AdmString element. It stores a copy of the value string it is passed.

Parameters:

	string_scalar	The pointer to the AdmString element.
	value	The pointer to the string.
	error	optional pointer to an AdmError pointer

Returns:: -1 on error, 0 on success

AdmRefStr* AdmBase64_getValue	(	AdmBase64 *	base64_scalar,
		AdmError **	error
	)

AdmBase64_getValue: Get the value of an AdmBase64 element : a pointer to an AdmBase64 element : an optional AdmError

This function is used to request the string stored in an AdmBase64 string element. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Return value: a pointer to the AdmBase64 element's value string.

int AdmBase64_setValue	(	AdmBase64 *	base64_scalar,
		const char *	value,
		AdmError **	error
	)

This function is used to set the value of an AdmBase64 string element. It stores a copy of the value string it is passed.

Parameters:

	base64_scalar	a pointer to an AdmBase64 element
	value	a pointer to a base64 encoded binary string
	error	an optional AdmError

Returns:: -1 on error, 0 on success

size_t AdmBase64_getBinValue	(	AdmBase64 *	base64_scalar,
		void **	value,
		AdmError **	error
	)

Parameters:

	base64_scalar	a pointer to an AdmBase64 element
	value	a pointer to a void pointer to return the address of the new buffer.
	error	an optional AdmError

Returns:: the size of the new buffer.

This function will decode and return a copy of the binary string stored in a AdmBase64 element. You must free the returned buffer.

Return value: a pointer to the AdmBase64 element's value string.

int AdmBase64_setBinValue	(	AdmBase64 *	base64_scalar,
		const void *	value,
		size_t	size,
		AdmError **	error
	)

This function is used to set the binary value of an AdmBase64 string element. It stores an encoded copy of the value string it is passed.

Parameters:

	base64_scalar	a pointer to an AdmBase64 element
	value	a pointer to a binary string
	size	the size of the binary string
	error	an optional AdmError

Returns:: -1 on error, 0 on success

AdmRefStr* AdmCopy_getValue	(	AdmCopy *	copy_scalar,
		AdmError **	error
	)

This function is used to request the path of an AdmCopy element. The string returned must be considered const and volatile, and if it is needed for long periods of time, the programmer should copy it.

Specifically, it is guranteed for only so long as the AdmCopy element is refed, and its value is not changed.

Parameters:

	copy_scalar	a pointer to an AdmCopy element
	error	an optional GError

Returns:: An AdmRefStr containing the AdmCopy's path

int AdmCopy_setValue	(	AdmCopy *	copy_scalar,
		const char *	value,
		AdmError **	error
	)

This function is used to set the path of an AdmCopy element. It stores a copy of the string passed to it, after checking its path validity.

Parameters:

	copy_scalar	a pointer to an AdmCopy element
	value	a pointer to a valid path string
	error	an optional GError

Returns:: -1 on error, 0 on success

AdmRefStr* AdmBlackBox_getCacheDir ( AdmError ** error )

Gets the cache directory the alchemist is currently using.

Parameters:

error

an optional pointer to an AdmError pointer

Returns:: the cache dir

Note:: you do not own the return stritg, and must not free it

int AdmBlackBox_setCacheDir	(	const char *	path,
		AdmError **	error
	)

Sets the cache directory the alchemist is currently using.

Parameters:

	path	the cache directory you want to use
	error	an optional pointer to an AdmError pointer

Returns:: -1 on failure, 0 on succes

Note:: passing NULL as the path resets the path to the default

AdmBlackBox* AdmBlackBox_getBox	(	AdmList *	box_cfg,
		AdmError **	error
	)

adm_bb_cap_t AdmBlackBox_caps	(	AdmBlackBox *	box,
		AdmError **	error
	)

Returns a capability vector listing the capabilities of an AdmBlackBox.

Parameters:

	box	The AdmBlackBox to check
	error	Optional pointer to AdmError pointer.

Returns:: an adm_bb_cap_t structure

void AdmBlackBox_ref	(	AdmBlackBox *	box,
		AdmError **	error
	)

Increase reference to given AdmBlackBox element.

Parameters:

	box	The AdmBlackBox to increase the reference to.
	error	Optional pointer to AdmError pointer.

void AdmBlackBox_unref	(	AdmBlackBox *	box,
		AdmError **	error
	)

Decrease reference to given AdmBlackBox element.

Parameters:

	box	The AdmBlackBox to decrease the reference to.
	error	Optional pointer to AdmError pointer.

AdmContext* AdmBlackBox_read	(	AdmBlackBox *	box,
		AdmError **	error
	)

Tries to read the most current context from the given AdmBlackBox and return it. The BlackBox may not be able to be readable in which case NULL will be returned. Also it may allow caching and do so transparently.

Parameters:

	box	The AdmBlackBox to read from.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the AdmContext retrived through the given box.

int AdmBlackBox_listSerial	(	AdmBlackBox *	box,
		unsigned int *	array,
		unsigned int	array_len,
		unsigned int	top_serial,
		AdmError **	error
	)

Creates a list of serial numbers of the given AdmBlackBox subject to the constraints.

Parameters:

	box	The AdmBlackBox to get the list of serial numbers from.
	array	The pointer to the preallocated array of `int` values to be filled with the serial numbers.
	array_len	The size of the perallocated array.
	top_serial	The highest serial number that we request. Only serial numbers below that will be returned. Use `0` to request the newest (highest) serial numbers.
	error	Optional pointer to AdmError pointer.

Returns:: The amount of serial numbers filled in. Always less or equal to the array length.

Note:: The list of serial numbers can partially come from the local cached BlackBoxes as well.

AdmContext* AdmBlackBox_readSerial	(	AdmBlackBox *	box,
		unsigned int	serial,
		AdmError **	error
	)

Reads a context from the given AdmBlackBox with the specified serial number.

Parameters:

	box	The AdmBlackBox to read the context from.
	serial	The serial number of the context we request.
	error	Optional pointer to AdmError pointer.

Returns:: The pointer to the AdmContext retrived through the given box or NULL if no context with that serial number exists.

int AdmBlackBox_write	(	AdmBlackBox *	box,
		AdmContext *	context,
		AdmError **	error
	)

Write the given AdmContext to the given AdmBlackBox. Does automatic caching if the given AdmBlackBox supports it.

Parameters:

	box	The AdmBlackBox to write to.
	context	The AdmContext to be written to the box.
	error	Optional pointer to AdmError pointer.

Returns:: 0 on success, all other values indicate an error.

unsigned int AdmBlackBox_getMark	(	AdmBlackBox *	box,
		const char *	mark,
		AdmError **	error
	)

Get the serial number of the given AdmBlackBox for the given mark. The whole business with marks allows us to 'tag' cached boxes and to identify if they are dirty or not.

Parameters:

	box	The AdmBlackBox from which to get the marked serial.
	mark	The mark string.
	error	Optional pointer to AdmError pointer.

Returns:: The serial number of the marked cached box or 0 if no marked cached box exists.

int AdmBlackBox_setMark	(	AdmBlackBox *	box,
		const char *	mark,
		AdmError **	error
	)

Mark the given AdmBlackBox. The serial number is extracted from the given AdmBlackBox automatically. Any existing mark will be overwritten. If an AdmBlackBox is cached, then it is possible to mark it. This provides a mechanism for marking the top serial number in the cache down at a given mark, which is a string; allowing various applications to check to see if an interface has changed since the last time the accessed by doing something along the lines of:

 AdmBlackBox_setMark(box_p, "app1_mark_string", error);
 ...
 int i;
 if ((AdmBlackBok_listSerial(box_p, &i, 1, 0, NULL) &&
        (i != AdmBlackBox_getMark(box_p, "app1_mark_string", NULL)) {
        ...
 }

Parameters:

	box	The AdmBlackBox which we want to mark.
	mark	The mark string.
	error	Optional pointer to AdmError pointer.

Returns:: 0 on success, all other values indicate an error.

int AdmBlackBox_clearMark	(	AdmBlackBox *	box,
		const char *	mark,
		AdmError **	error
	)

Clear the mark for the given AdmBlackBox.

Parameters:

	box	The AdmBlackBox where we want to clear its mark.
	mark	The mark string.
	error	Optional pointer to AdmError pointer.

Returns:: 0 on success, all other values indicate an error.

AdmRefStr* AdmSwitchboard_getSwbDir ( AdmError ** error )

Gets the swb directory the alchemist is currently using.

Parameters:

error

an optional pointer to an AdmError pointer

Returns:: the swb dir

Note:: you do not own the return stritg, and must not free it

int AdmSwitchboard_setSwbDir	(	const char *	path,
		AdmError **	error
	)

Sets the swb directory the alchemist is currently using.

Parameters:

	path	the swb directory you want to use
	error	an optional pointer to an AdmError pointer

Returns:: -1 on failure, 0 on succes

Note:: passing NULL as the path resets the path to the default

int AdmSwitchboard_markNsp	(	const char *	namespace,
		const char *	subspace,
		const char *	mark,
		AdmError **	error
	)

int AdmSwitchboard_markNspWithConfig	(	AdmList *	namespace_cfg,
		const char *	subspace,
		const char *	mark,
		AdmError **	error
	)

int AdmSwitchboard_checkNspMark	(	const char *	namespace,
		const char *	subspace,
		const char *	mark,
		AdmError **	error
	)

int AdmSwitchboard_checkNspMarkWithConfig	(	AdmList *	namespace_cfg,
		const char *	subspace,
		const char *	mark,
		AdmError **	error
	)

AdmContext* AdmSwitchboard_readNsp	(	const char *	namespace,
		const char *	subspace,
		unsigned int	depth,
		AdmError **	error
	)

read the given subspace from the given namespace

Parameters:

	namespace	the namespace to read
	subspace	the box set to extract, NULL uses the default "config" set
	depth	the number of boxes in the namespace to read, 0 means all.
	error	an optional pointer to an AdmError pointer

AdmContext* AdmSwitchboard_readNspWithConfig	(	AdmList *	namespace_cfg,
		const char *	subspace,
		unsigned int	depth,
		AdmError **	error
	)

int AdmSwitchboard_writeNsp	(	const char *	namespace,
		const char *	subspace,
		AdmContext *	context,
		AdmError **	error
	)

writes the given subspace in the given namespace

Parameters:

	namespace	the namespace to write
	subspace	the box set to extract, NULL uses the default "config" set
	context	the context to write
	error	an optional pointer to an AdmError pointer

int AdmSwitchboard_writeNspWithConfig	(	AdmList *	namespace_cfg,
		const char *	subspace,
		AdmContext *	context,
		AdmError **	error
	)

AdmContext* AdmSwitchboard_readNspCtx	(	const char *	namespace,
		AdmError **	error
	)

Parameters:

	namespace	the name of the namespace to read
	error	an optional pointer to an AdmError pointer

Returns:: an AdmContext that is the namespace configuration

int AdmSwitchboard_writeNspCtx	(	const char *	namespace,
		AdmContext *	namespace_ctx,
		int	mode,
		uid_t	uid,
		gid_t	gid,
		AdmError **	error
	)

Parameters:

	namespace	the name of the namespace to read
	context	the configuration context to write
	mode	the file mode to write the context out with
	uid	the uid to write the file with, -1 for dont care
	gid	the gid to write the file with, -1 for dont care
	error	an optional pointer to an AdmError pointer

Returns:: -1 on failure, 0 on succes

AdmList* AdmSwitchboard_getNspCfg	(	AdmContext *	namespace_ctx,
		const char *	namespace,
		AdmError **	error
	)

extract a namespace config from a namespace context

Parameters:

	namespace	the namespace to extract
	config	the namespace config context

AdmList* AdmSwitchboard_getSubspCfg	(	AdmList *	namespace_cfg,
		const char *	subspace,
		AdmError **	error
	)

extract a box set from a namespace config

Parameters:

	subspace	the box set to extract, NULL uses the default "config" set
	namespace	the namespace used
	config	the namespace config context

AdmBlackBox* AdmSwitchboard_getBox	(	AdmList *	subspace_cfg,
		const char *	box_name,
		AdmError **	error
	)

extract a box_config set from a namespace config

Parameters:

	box_name	the box to extract
	subspace_cfg	the subspace config no use

alchemist.h File Reference

Classes

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation