MidgardConnection

MidgardConnection — Connection and environment variables handler.

Synopsis

#include <midgard/midgard.h>

#define             GETTEXT_PACKAGE
                    MidgardConnection;
typedef             MidgardConnectionClass;
MidgardConnection * midgard_connection_new              (void);
gboolean            midgard_connection_open             (MidgardConnection *self,
                                                         const gchar *name,
                                                         GError **error);
void                midgard_connection_close            (MidgardConnection *self);
gboolean            midgard_connection_open_config      (MidgardConnection *self,
                                                         MidgardConfig *config);
gboolean            midgard_connection_set_loglevel     (MidgardConnection *self,
                                                         const gchar *level,
                                                         GLogFunc log_func);
guint               midgard_connection_get_loglevel     (MidgardConnection *self);
void                midgard_connection_set_loghandler   (MidgardConnection *self,
                                                         guint loghandler);
guint               midgard_connection_get_loghandler   (MidgardConnection *self);
gint                midgard_connection_get_error        (MidgardConnection *self);
const gchar *       midgard_connection_get_error_string (MidgardConnection *self);
void                midgard_connection_set_error        (MidgardConnection *self,
                                                         gint errcode);
MidgardUser *       midgard_connection_get_user         (MidgardConnection *self);
MidgardConnection * midgard_connection_copy             (MidgardConnection *self);
gboolean            midgard_connection_reopen           (MidgardConnection *self);
gchar **            midgard_connection_list_auth_types  (MidgardConnection *self,
                                                         guint *n_types);
void                midgard_connection_enable_replication
                                                        (MidgardConnection *self,
                                                         gboolean toggle);
void                midgard_connection_enable_quota     (MidgardConnection *self,
                                                         gboolean toggle);
void                midgard_connection_enable_dbus      (MidgardConnection *self,
                                                         gboolean toggle);
void                midgard_connection_enable_workspace (MidgardConnection *self,
                                                         gboolean toggle);
gboolean            midgard_connection_is_enabled_replication
                                                        (MidgardConnection *self);
gboolean            midgard_connection_is_enabled_quota (MidgardConnection *self);
gboolean            midgard_connection_is_enabled_dbus  (MidgardConnection *self);
gboolean            midgard_connection_is_enabled_workspace
                                                        (MidgardConnection *self);
const MidgardWorkspaceStorage * midgard_connection_get_workspace
                                                        (MidgardConnection *self);
gboolean            midgard_connection_set_workspace    (MidgardConnection *self,
                                                         MidgardWorkspaceStorage *workspace);

Object Hierarchy

  GObject
   +----MidgardConnection

Properties

  "config"                   MidgardConfig*        : Read

Signals

  "auth-changed"                                   : No Hooks
  "connected"                                      : No Hooks
  "disconnected"                                   : No Hooks
  "error"                                          : No Hooks
  "lost-provider"                                  : No Hooks

Description

MidgardConnection represents database connection, and runtime Midgard related environment variables. Logged in MidgardUser or midgard_error for example.

Use midgard_connection_new() to initialize new MidgardConnection object, and midgard_connection_open() to open database connection. There is also midgard_connection_open_config() for cases, if configuration file is not in common path, and this file could be represented by MidgardConfig.

Details

GETTEXT_PACKAGE

#define GETTEXT_PACKAGE "midgard"


MidgardConnection

typedef struct {
	gint errnum;
	gchar *errstr;
	GError *err;
} MidgardConnection;


MidgardConnectionClass

typedef struct MidgardConnectionClass MidgardConnectionClass;


midgard_connection_new ()

MidgardConnection * midgard_connection_new              (void);

Initializes new instance of MidgardConnection object type.

MidgardConnectionClass has no properties registered as class members. Every internal data of MidgardConnection object is accessible with API functions, and is not settable or gettable as property's value. Particular methods should be implemented for language bindings.

MidgardConnection objects holds runtime ( or request ) non persistent data like authentication type, debug level, etc.

Persistent data like database name, blobs directory are associated with MidgardConfig object.

Returns :

pointer to MidgardConnection object or NULL on failure.

midgard_connection_open ()

gboolean            midgard_connection_open             (MidgardConnection *self,
                                                         const gchar *name,
                                                         GError **error);

Opens a connection to the database, which is defined in named configuration. The configuration file is read from the system configuration directory and is used as the configuration for the created connection. For example: `/etc` directory is taken into account if library is compiled with `/usr' prefix, `/usr/local/etc` if compiled with `/usr/local` prefix, etc.

Consider using midgard_connection_open_config(), if you need to open connection to database which is configured in user's home directory.

If the named database configuration can not be read or the connection fails, then FALSE is returned and an error message is written to the global midgard error state.

It also initializes MidgardSchema object (which is encapsulated by implementation ) and register all MgdSchema, MidgardObject derived classes defined by user. This happens only when basic Midgard classes are not registered in GType system. This is recommended way to initialize MgdSchema types.

self :

MidgardConnection instance

name :

configuration file name

error :

pointer to store error

Returns :

TRUE if the operation succeeded, FALSE otherwise.

midgard_connection_close ()

void                midgard_connection_close            (MidgardConnection *self);

Closes connection to underlying storage. All private and public data remains unchanged, so connection might be reopened at any time. After closing connection, 'disconnected' signal is emitted.

self :

MidgardConnection instance

Since 10.05.1


midgard_connection_open_config ()

gboolean            midgard_connection_open_config      (MidgardConnection *self,
                                                         MidgardConfig *config);

Opens a MidgardConnection with the given configuration.

Take a look at midgard_connection_open() wrt MidgardSchema.

If MidgardConnection is already associated with given config, method returns TRUE. If associated with another one, FALSE is returned and MGD_ERR_INTERNAL error is set.

self :

[in]newly initialized MidgardConnection object

config :

MidgardConfig object

Returns :

TRUE on success, FALSE otherwise

midgard_connection_set_loglevel ()

gboolean            midgard_connection_set_loglevel     (MidgardConnection *self,
                                                         const gchar *level,
                                                         GLogFunc log_func);

Sets log level of the given MidgardConnection. Overwrites internal MidgardConnection's log level defined in configuration file. By default MidgardConnection holds loglevel which is associated with ( and duplicated from ) MidgardConfig. MidgardConfig object's log level isn't changed by this function

This method is a shortcut which sets correctly loghandler,loglevel and GLib's log function. Default log function will be used if NULL is defined. Core's default function is midgard_error_default_log.

Available levels: error, warn, warning, info, message, debug. warn is default loglevel, SQL queries are logged with debug level. With info level, function names ( and classes' names ) are ( at least should be) logged in language bindings

self :

MidgardConnection instance

level :

Loglevel string

log_func :

log handler function. [scope call]

Returns :

TRUE if debug level is set, FALSE otherwise

midgard_connection_get_loglevel ()

guint               midgard_connection_get_loglevel     (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

unsigned integer flag specified by GLogLevelFlags.

midgard_connection_set_loghandler ()

void                midgard_connection_set_loghandler   (MidgardConnection *self,
                                                         guint loghandler);

Sets internal loghandler id associated with G_LOG_DOMAIN and loglevel. Caller is responsible to remove loghandler using g_log_remove_handler when new loglevel for G_LOG_DOMAIN is set.

See also: midgard_connection_set_loglevel

self :

MidgardConnection instance

loghandler :

loghandler id

midgard_connection_get_loghandler ()

guint               midgard_connection_get_loghandler   (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

unsigned integer value which is associated with G_LOG_DOMAIN and MidgardConnection's loglevel currently set.

midgard_connection_get_error ()

gint                midgard_connection_get_error        (MidgardConnection *self);

Error id may be one of set by midgard_error.

self :

MidgardConnection instance

Returns :

Last error id set

midgard_connection_get_error_string ()

const gchar *       midgard_connection_get_error_string (MidgardConnection *self);

Error string may be one set by midgard_error.

self :

MidgardConnection instance

Returns :

last error string

midgard_connection_set_error ()

void                midgard_connection_set_error        (MidgardConnection *self,
                                                         gint errcode);

Valid errcode is one defined in MidgardErrorGeneric.

self :

MidgardConnection instance

errcode :

error code

midgard_connection_get_user ()

MidgardUser *       midgard_connection_get_user         (MidgardConnection *self);

NULL is explicitly returned if there's no midgard_user logged in for the given MidgardConnection. See also MidgardUser methods if you need midgard_person associated with user.

self :

MidgardConnection instance

Returns :

A pointer to MidgardUser instance or NULL. [transfer none]

midgard_connection_copy ()

MidgardConnection * midgard_connection_copy             (MidgardConnection *self);

This function duplicates given MidgardConnection. It doesn't make deep copy. All persistant data are kept unchanged, but runtime related members are reset to default state. This function is helpful if application is forking and new processes might have different environment variables.

Call g_object_unref if returned object is no longer needed.

self :

MidgardConnection instance

Returns :

Newly allocated and duplicated MidgardConnection. [transfer full]

midgard_connection_reopen ()

gboolean            midgard_connection_reopen           (MidgardConnection *self);

This is MySQL optimized workaround for lost connection event.

self :

MidgardConnection instance

Returns :

TRUE on success, FALSE otherwise

midgard_connection_list_auth_types ()

gchar **            midgard_connection_list_auth_types  (MidgardConnection *self,
                                                         guint *n_types);

List available and registered authentication types. Use g_free() to free returned array.

self :

MidgardConnection instance

n_types :

a pointer to store number of returned types

Returns :

NULL terminated array with authentication types. [transfer container]

midgard_connection_enable_replication ()

void                midgard_connection_enable_replication
                                                        (MidgardConnection *self,
                                                         gboolean toggle);

Enable or disable repligard table usage. If enabled, every base operation (create, update, delete) will be recorded in repligard table.

self :

MidgardConnection instance

toggle :

replication enable, disable toggle

Since 10.05


midgard_connection_enable_quota ()

void                midgard_connection_enable_quota     (MidgardConnection *self,
                                                         gboolean toggle);

Enable or disable quota table usage. If enabled, every base operation (create, update, delete) will be recorded in quota table, limiting particular types usage.

self :

MidgardConnection instance

toggle :

quota enable, disable toggle

Since 10.05


midgard_connection_enable_dbus ()

void                midgard_connection_enable_dbus      (MidgardConnection *self,
                                                         gboolean toggle);

Enable or disable dbus messages send for basic operation

self :

MidgardConnection instance

toggle :

dbus enable, disable toggle

Since 10.05


midgard_connection_enable_workspace ()

void                midgard_connection_enable_workspace (MidgardConnection *self,
                                                         gboolean toggle);

Enable or disable workspace (and contexts) support

self :

MidgardConnection instance

toggle :

workspace enable, disable toggle

Since 10.05.5


midgard_connection_is_enabled_replication ()

gboolean            midgard_connection_is_enabled_replication
                                                        (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

TRUE, if replication is enabled, FALSE otherwise

Since 10.05


midgard_connection_is_enabled_quota ()

gboolean            midgard_connection_is_enabled_quota (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

TRUE, if quota is enabled, FALSE otherwise

Since 10.05


midgard_connection_is_enabled_dbus ()

gboolean            midgard_connection_is_enabled_dbus  (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

TRUE, if dbus is enabled, FALSE otherwise

Since 10.05


midgard_connection_is_enabled_workspace ()

gboolean            midgard_connection_is_enabled_workspace
                                                        (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

TRUE, if workspace support is enabled, FALSE otherwise

Since 10.05.5


midgard_connection_get_workspace ()

const MidgardWorkspaceStorage * midgard_connection_get_workspace
                                                        (MidgardConnection *self);

self :

MidgardConnection instance

Returns :

MidgardWorkspaceStorage associated with MidgardConnection or NULL. [transfer none]

Since 10.05.5


midgard_connection_set_workspace ()

gboolean            midgard_connection_set_workspace    (MidgardConnection *self,
                                                         MidgardWorkspaceStorage *workspace);

Actual workspace scope depends on MidgardWorkspaceStorage implementation. For example, if MidgardWorkspaceContext is passed as workspace argument, Midgard environmental workspace is a tree context, which is the opposite of MidgardWorkspace which limits workspace scope to given one only.

self :

MidgardConnection instance

workspace :

MidgardWorkspaceStorage to set for given MidgardConnection

Returns :

TRUE on success, FALSE otherwise

Since 10.05.5

Property Details

The "config" property

  "config"                   MidgardConfig*        : Read

A deep copy of config with empty database username and password values.

Signal Details

The "auth-changed" signal

void                user_function                      (MidgardConnection *midgardconnection,
                                                        gpointer           user_data)              : No Hooks

midgardconnection :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "connected" signal

void                user_function                      (MidgardConnection *midgardconnection,
                                                        gpointer           user_data)              : No Hooks

midgardconnection :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "disconnected" signal

void                user_function                      (MidgardConnection *midgardconnection,
                                                        gpointer           user_data)              : No Hooks

midgardconnection :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "error" signal

void                user_function                      (MidgardConnection *arg0,
                                                        gpointer           user_data)      : No Hooks

error signal is emitted every time when error set is different than MGD_ERR_OK

user_data :

user data set when the signal handler was connected.

The "lost-provider" signal

void                user_function                      (MidgardConnection *midgardconnection,
                                                        gpointer           user_data)              : No Hooks

midgardconnection :

the object which received the signal.

user_data :

user data set when the signal handler was connected.