libmcs  0.6.0
Classes | Macros | Typedefs | Enumerations | Functions
mcs.h File Reference
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <dirent.h>
#include <stdio.h>
#include <limits.h>
#include <stdarg.h>
#include <errno.h>
#include <dlfcn.h>
#include <mowgli.h>

Go to the source code of this file.

Classes

struct  mcs_backend_t
 Contains the vtable and some references for an mcs storage backend. More...
struct  mcs_handle_
 Represents an MCS object handle. More...

Macros

#define PATH_MAX   4096

Typedefs

typedef struct mcs_handle_ mcs_handle_t

Enumerations

enum  mcs_response_t { MCS_FAIL, MCS_OK }

Functions

void mcs_init (void)
 Initialises the mcs library classes and loads the backend plugins.
void mcs_fini (void)
 Releases resources used by the mcs backend plugins.
char * mcs_version (void)
 Retrieves the version of the mcs implementation.
void mcs_handle_class_init (void)
 Initialises the mowgli.object.class for the mcs.handle object.
mcs_response_t mcs_backend_register (mcs_backend_t *backend)
 Registers a custom mcs.backend.
mcs_response_t mcs_backend_unregister (mcs_backend_t *backend)
 Unregisters a custom mcs.backend.
mowgli_queue_t * mcs_backend_get_list (void)
 Returns a mowgli.queue representing the backends list.
const char * mcs_backend_select (void)
 Determines the backend that should be used.
mcs_handle_tmcs_new (char *domain)
void mcs_destroy (mcs_handle_t *handle)
 Destroys an mcs.handle object.
mcs_response_t mcs_get_string (mcs_handle_t *handle, const char *section, const char *key, char **value)
 Public function to retrieve a string value from a configuration database.
mcs_response_t mcs_get_int (mcs_handle_t *handle, const char *section, const char *key, int *value)
 Public function to retrieve an integer value from a configuration database.
mcs_response_t mcs_get_bool (mcs_handle_t *handle, const char *section, const char *key, int *value)
 Public function to retrieve a boolean value from a configuration database.
mcs_response_t mcs_get_float (mcs_handle_t *handle, const char *section, const char *key, float *value)
 Public function to retrieve a floating point value from a configuration database.
mcs_response_t mcs_get_double (mcs_handle_t *handle, const char *section, const char *key, double *value)
 Public function to retrieve a double-precision floating point value from a configuration database.
mcs_response_t mcs_set_string (mcs_handle_t *handle, const char *section, const char *key, const char *value)
 Public function to set a string value in a configuration database.
mcs_response_t mcs_set_int (mcs_handle_t *handle, const char *section, const char *key, int value)
 Public function to set an integer value in a configuration database.
mcs_response_t mcs_set_bool (mcs_handle_t *handle, const char *section, const char *key, int value)
 Public function to set a boolean value in a configuration database.
mcs_response_t mcs_set_float (mcs_handle_t *handle, const char *section, const char *key, float value)
 Public function to set a floating point value in a configuration database.
mcs_response_t mcs_set_double (mcs_handle_t *handle, const char *section, const char *key, double value)
 Public function to set a double-precision floating point value in a configuration database.
mcs_response_t mcs_unset_key (mcs_handle_t *handle, const char *section, const char *key)
 Public function to remove a value from a configuration database.
mowgli_queue_t * mcs_get_keys (mcs_handle_t *handle, const char *section)
 Public function to retrieve a mowgli.queue of keys from a configuration database.
mowgli_queue_t * mcs_get_sections (mcs_handle_t *handle)
 Public function to retrieve a mowgli.queue of sections from a configuration database.
void mcs_load_plugins (void)
 Loads all of the plugins in -DPLUGIN_DIR.
void mcs_unload_plugins (mowgli_queue_t *l)
 Unloads a given list of plugins.
size_t mcs_strnlen (const char *str, size_t len)
 Determines the length of a string, limited by an arbitrary length.
char * mcs_strndup (const char *str, size_t len)
 Duplicates a string, limited to a specific length.
int mcs_create_directory (const char *path, mode_t mode)
 A utility function which creates a directory.
size_t mcs_strlcat (char *dest, const char *src, size_t count)
 Concatenates a string, limited to a maximum buffer size.
size_t mcs_strlcpy (char *dest, const char *src, size_t count)
 Copies a string, limited to a maximum buffer size.

Macro Definition Documentation

#define PATH_MAX   4096

Referenced by mcs_load_plugins().

Typedef Documentation

typedef struct mcs_handle_ mcs_handle_t

Friendly name for struct mcs_handle_

Enumeration Type Documentation

mcs_response_t denotes the status of a transaction.

Enumerator:
MCS_FAIL 

designates transaction failure

MCS_OK 

designates transaction success

Function Documentation

mowgli_queue_t* mcs_backend_get_list ( void  )

Returns a mowgli.queue representing the backends list.

This is the portable version of using the mcs_backends_lst symbol.

Returns
A mowgli.queue representing the backend list.

References mcs_backends_lst.

Referenced by mcs_backend_select().

mcs_response_t mcs_backend_register ( mcs_backend_t b)

Registers a custom mcs.backend.

This is used to register a named mcs.backend vtable with mcs. This should be unregistered with mcs_backend_unregister() when it is no longer needed, such as during an application unload.

Parameters
bAn mcs.backend vtable to register.
Returns
A mcs_response_t code depending on success or failure of the registration.

References mcs_backends_lst, and MCS_OK.

Referenced by mcs_load_plugins().

const char* mcs_backend_select ( void  )

Determines the backend that should be used.

This function checks the environment variable, MCS_BACKEND first. If that is empty, it checks $HOME/.mcs-backend, followed by /etc/mcs-backend. If no preference is found, it returns "default".

Returns
The name of the backend that should be used.

References mcs_backend_get_list(), and mcs_backend_t::name.

Referenced by mcs_new().

mcs_response_t mcs_backend_unregister ( mcs_backend_t b)

Unregisters a custom mcs.backend.

This is used to unregister a named mcs.backend vtable with mcs. This should be called when you are no longer interested in using the backend implementation with mcs.

Parameters
bAn mcs.backend vtable to register.
Returns
A mcs_response_t code depending on success or failure of the deregistration.

References mcs_backends_lst, and MCS_OK.

int mcs_create_directory ( const char *  path,
mode_t  mode 
)

A utility function which creates a directory.

This function creates a directory. It recurses to handle any parents which also need to be created.

Parameters
pathThe path to create.
modeThe mode of the directory that should be created.
Returns
0 on success, -1 on failure.

References mcs_strndup().

void mcs_destroy ( mcs_handle_t self)

Destroys an mcs.handle object.

This function is considered deprecated since version 0.6. It should not be used in any newly written code.

void mcs_fini ( void  )

Releases resources used by the mcs backend plugins.

This function unloads and releases resources used by the mcs backend plugins.

References mcs_backends_lst, and mcs_unload_plugins().

mcs_response_t mcs_get_bool ( mcs_handle_t self,
const char *  section,
const char *  key,
int *  value 
)

Public function to retrieve a boolean value from a configuration database.

This function is the public interface for retrieving a boolean value from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to look in.
keyThe key to look up.
valueA memory location to put the value in.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_get_double ( mcs_handle_t self,
const char *  section,
const char *  key,
double *  value 
)

Public function to retrieve a double-precision floating point value from a configuration database.

This function is the public interface for retrieving a double value from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to look in.
keyThe key to look up.
valueA memory location to put the value in.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_get_float ( mcs_handle_t self,
const char *  section,
const char *  key,
float *  value 
)

Public function to retrieve a floating point value from a configuration database.

This function is the public interface for retrieving a float value from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to look in.
keyThe key to look up.
valueA memory location to put the value in.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_get_int ( mcs_handle_t self,
const char *  section,
const char *  key,
int *  value 
)

Public function to retrieve an integer value from a configuration database.

This function is the public interface for retrieving an integer value from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to look in.
keyThe key to look up.
valueA memory location to put the value in.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mowgli_queue_t* mcs_get_keys ( mcs_handle_t self,
const char *  section 
)

Public function to retrieve a mowgli.queue of keys from a configuration database.

This function is the public interface for retrieving a mowgli.queue of keys from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to search.
Returns
A mowgli.queue of key names in the requested section.
mowgli_queue_t* mcs_get_sections ( mcs_handle_t self)

Public function to retrieve a mowgli.queue of sections from a configuration database.

This function is the public interface for retrieving a mowgli.queue of sections from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
Returns
A mowgli.queue of section names in the requested section.
mcs_response_t mcs_get_string ( mcs_handle_t self,
const char *  section,
const char *  key,
char **  value 
)

Public function to retrieve a string value from a configuration database.

This function is the public interface for retrieving a string value from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to look in.
keyThe key to look up.
valueA memory location to put the value in.
Returns
A mcs_response_t value representing the success or failure of the transaction.
void mcs_handle_class_init ( void  )

Initialises the mowgli.object.class for the mcs.handle object.

Referenced by mcs_init().

void mcs_init ( void  )

Initialises the mcs library classes and loads the backend plugins.

mcs_init() initialises mowgli.object, followed by all of the mcs library classes which extend mowgli.object to provide an extensible configuration management system.

Once the library mowgli.object classes have been initialised, the mcs plugin directory is iterated and various backend plugins are loaded.

References mcs_handle_class_init(), and mcs_load_plugins().

void mcs_load_plugins ( void  )

Loads all of the plugins in -DPLUGIN_DIR.

References mcs_backend_t::handle, mcs_backend_register(), and PATH_MAX.

Referenced by mcs_init().

mcs_handle_t* mcs_new ( char *  domain)
mcs_response_t mcs_set_bool ( mcs_handle_t self,
const char *  section,
const char *  key,
int  value 
)

Public function to set a boolean value in a configuration database.

This function is the public interface for boolean a string value in a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to set the value in.
keyThe key to set.
valueThe value to set.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_set_double ( mcs_handle_t self,
const char *  section,
const char *  key,
double  value 
)

Public function to set a double-precision floating point value in a configuration database.

This function is the public interface for setting a double value in a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to set the value in.
keyThe key to set.
valueThe value to set.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_set_float ( mcs_handle_t self,
const char *  section,
const char *  key,
float  value 
)

Public function to set a floating point value in a configuration database.

This function is the public interface for setting a float value in a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to set the value in.
keyThe key to set.
valueThe value to set.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_set_int ( mcs_handle_t self,
const char *  section,
const char *  key,
int  value 
)

Public function to set an integer value in a configuration database.

This function is the public interface for setting an integer value in a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to set the value in.
keyThe key to set.
valueThe value to set.
Returns
A mcs_response_t value representing the success or failure of the transaction.
mcs_response_t mcs_set_string ( mcs_handle_t self,
const char *  section,
const char *  key,
const char *  value 
)

Public function to set a string value in a configuration database.

This function is the public interface for setting a string value in a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to set the value in.
keyThe key to set.
valueThe value to set.
Returns
A mcs_response_t value representing the success or failure of the transaction.
size_t mcs_strlcat ( char *  dest,
const char *  src,
size_t  count 
)

Concatenates a string, limited to a maximum buffer size.

This is a function which is useful for safely copying a string.

Parameters
destThe string to copy to.
srcThe string to copy from.
countThe maximum allowed length of the string.
Returns
The length of the new string.
size_t mcs_strlcpy ( char *  dest,
const char *  src,
size_t  size 
)

Copies a string, limited to a maximum buffer size.

This is a function which is useful for safely copying a string.

Parameters
destThe string to copy to.
srcThe string to copy from.
sizeThe maximum allowed length of the string.
Returns
The length of the new string.
char* mcs_strndup ( const char *  str,
size_t  len 
)

Duplicates a string, limited to a specific length.

This is a function which duplicates a string limited to a maximum length.

Parameters
strThe string to duplicate.
lenThe maximum allowed length of the string.
Returns
The pointer to a copy of the string. Free this with free().

References mcs_strnlen().

Referenced by mcs_create_directory().

size_t mcs_strnlen ( const char *  str,
size_t  len 
)

Determines the length of a string, limited by an arbitrary length.

This is a function which is useful for limiting the length of a string.

Parameters
strThe string to test.
lenThe maximum allowed length of the string.
Returns
The length of the string or len, whichever is smaller.

Referenced by mcs_strndup().

void mcs_unload_plugins ( mowgli_queue_t *  pl)

Unloads a given list of plugins.

Parameters
plA mowgli.queue representing a list of plugins to unload.

References mcs_backend_t::handle.

Referenced by mcs_fini().

mcs_response_t mcs_unset_key ( mcs_handle_t self,
const char *  section,
const char *  key 
)

Public function to remove a value from a configuration database.

This function is the public interface for removing a value from a configuration database via a configuration backend class.

Parameters
selfThe mcs.handle object that represents the configuration database.
sectionThe section to unset the value in.
keyThe key to unset.
Returns
A mcs_response_t value representing the success or failure of the transaction.
char* mcs_version ( void  )

Retrieves the version of the mcs implementation.

This function is useful for displaying the version of the system implementation.

Returns
A dynamically allocated string containing the mcs implementation. This should be used with free().

References PACKAGE_NAME, and PACKAGE_VERSION.