MidgardUser

MidgardUser — User account and authentication

Synopsis

#include <midgard/midgard.h>

struct              MidgardUserClass;
                    MidgardUserPrivate;
                    MidgardUser;
MidgardUser *       midgard_user_new                    (MidgardConnection *mgd,
                                                         guint n_params,
                                                         const GParameter *parameters);
MidgardUser *       midgard_user_get                    (MidgardConnection *mgd,
                                                         guint n_params,
                                                         const GParameter *parameters);
MidgardUser **      midgard_user_query                  (MidgardConnection *mgd,
                                                         guint n_params,
                                                         const GParameter *parameters);
gboolean            midgard_user_create                 (MidgardUser *self);
gboolean            midgard_user_update                 (MidgardUser *self);
gboolean            midgard_user_delete                 (MidgardUser *self);
gboolean            midgard_user_log_in                 (MidgardUser *self);
gboolean            midgard_user_log_out                (MidgardUser *self);
gboolean            midgard_user_is_user                (MidgardUser *self);
gboolean            midgard_user_is_admin               (MidgardUser *self);
MidgardObject *     midgard_user_get_person             (MidgardUser *self);
gboolean            midgard_user_set_person             (MidgardUser *self,
                                                         MidgardObject *person);

Object Hierarchy

  GObject
   +----MidgardDBObject
         +----MidgardUser

Properties

  "active"                   gboolean              : Read / Write
  "authtype"                 gchar*                : Read / Write
  "authtypeid"               guint                 : Read
  "guid"                     gchar*                : Read
  "login"                    gchar*                : Read / Write
  "password"                 gchar*                : Read / Write
  "person"                   gchar*                : Read
  "usertype"                 guint                 : Read / Write

Description

MidgardUser (midgard_user) class is a special class which let's you authenticate any user into Midgard system. Class itself (and its implementation) doesn't provide any special security routines. Instead, it provides easy to use interfaces to implement many derived ones.

Valid user (from Midgard core point of view) is an object which can be stored in underlying storage, and can be identified by unique guid, unique login name and authentication type. It's very important to notice that user's guid is unique per storage, while login name is unique with particular authentication type. Which means, the same login name can be used with different authentication types.

Valid authentication types are read from shared data directory (e.g. /usr/local/share/midgard2) and initialized when application is initialized. New authentication types are always defined in shared, midgard_auth_types.xml file.

MidgardUser class doesn't do any password validation or doesn't support password encryption or decryption. For such, proper implementation should be made for derived class. An exception is legacy and backward compatible authentication which is supported by unix encrypt utils in the background.

MidgardUser provides very basic and low level access control system.

Details

struct MidgardUserClass

struct MidgardUserClass {
	MidgardDBObjectClass parent;
	
	/* methods */
	const MidgardConnection *(*get_connection) (MidgardDBObject *);
	
	/* API methods */
	MidgardObject *(*get_person)		(MidgardUser *self);
	gboolean        (*log_in)              	(MidgardUser *self);
	gboolean        (*log_out)             	(MidgardUser *self);
	MidgardUser     *(*get)               	(MidgardConnection *mgd, guint n_params, const GParameter *parameters);
	MidgardUser     **(*query) 		(MidgardConnection *mgd, guint n_params, const GParameter *parameters);
	gboolean        (*create)           	(MidgardUser *self);
	gboolean        (*update)             	(MidgardUser *self);
	gboolean 	(*delete_record) (MidgardUser *self);
	gboolean 	(*is_user)		(MidgardUser *self);
	gboolean 	(*is_admin)		(MidgardUser *self);
};

MidgardUserPrivate

typedef struct _MidgardUserPrivate MidgardUserPrivate;

MidgardUser

typedef struct _MidgardUser MidgardUser;

midgard_user_new ()

MidgardUser *       midgard_user_new                    (MidgardConnection *mgd,
                                                         guint n_params,
                                                         const GParameter *parameters);

parameters and n_params arguments are optional. midgard_user_get() will be invoked in constructor if parameters argument will be set to not NULL value.

mgd :

 MidgardConnection instance

n_params :

 number of parameters

parameters :

 GParameter with MidgardUser properties

Returns :

 MidgardUser object or NULL on failure

midgard_user_get ()

MidgardUser *       midgard_user_get                    (MidgardConnection *mgd,
                                                         guint n_params,
                                                         const GParameter *parameters);

Fetch MidgardUser object from storage. At least 'login' and 'authtype' property are required to be set in parameters.

Cases to return NULL:

  • 'login' or 'authtype' properties do not exist in given parameters (MGD_ERR_INVALID_PROPERTY_VALUE)

  • There's no user object which match given parameters (MGD_ERR_NOT_EXISTS)

  • More than one record found in database (MGD_ERR_INTERNAL)

mgd :

 MidgardConnection instance

n_params :

 number of parameters

parameters :

 GParameter with MidgardUser properties

Returns :

 new MidgardUser instance or NULL in case of failure Since 9.09. [transfer full]

midgard_user_query ()

MidgardUser **      midgard_user_query                  (MidgardConnection *mgd,
                                                         guint n_params,
                                                         const GParameter *parameters);

Fetch MidgardUser objects from storage. At least 'login' and 'authtype' property are required to be set in parameters.

Cases to return NULL:

  • There are no user objects which match given parameters (MGD_ERR_NOT_EXISTS)

Returned array should be freed (g_free()) when no longer needed.

mgd :

 MidgardConnection instance

n_params :

 number of parameters

parameters :

 GParameter with MidgardUser properties

Returns :

 newly allocated and NULL terminated array of MidgardUser objects or NULL Since 9.09. [transfer full]

midgard_user_create ()

gboolean            midgard_user_create                 (MidgardUser *self);

Creates database record for given user.

Cases to return FALSE:

  • User with such login and authentication type already exists ( MGD_ERR_DUPLICATE )

  • User's guid is already set ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • 'authtype' property is empty or NULL ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • 'authtype' property value is invalid ( MGD_ERR_INTERNAL )

self :

 MidgardUser instance

Returns :

 TRUE on success, FALSE otherwise

Since 9.09

midgard_user_update ()

gboolean            midgard_user_update                 (MidgardUser *self);

Updates user storage record

Cases to return FALSE:

  • User with such login and authentication type already exists ( MGD_ERR_DUPLICATE )

  • User's guid is not set ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • 'authtype' property is empty or NULL ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • User record hasn't been found ( MGD_ERR_INTERNAL )

  • Failed to update storage record ( MGD_ERR_INTERNAL )

  • 'authtype' property value is invalid ( MGD_ERR_INTERNAL )

self :

 MidgardUser instance

Returns :

 TRUE on success, FALSE otherwise

Since 9.09

midgard_user_delete ()

gboolean            midgard_user_delete                 (MidgardUser *self);

Delete user's storage record.

Cases to return FALSE:

  • User's guid is not set ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • Failed to delete storage record ( MGD_ERR_INTERNAL )

self :

 MidgardUser instance

Returns :

 TRUE on success, FALSE otherwise

Since 9.09.2

midgard_user_log_in ()

gboolean            midgard_user_log_in                 (MidgardUser *self);

Logs in user instance, if given one is valid. A valid user object must have (at least) guid set. Which means, MidgardObject must be fetched from database. Either with midgard_user_get() or with midgard_user_query().

This method silently returns with success when given user is already logged in.

Cases to return FALSE:

  • User's guid is not set ( MGD_ERR_INVALID_PROPERTY_VALUE )

self :

 MidgardUser instance

Returns :

 TRUE if user has been logged in, FALSE otherwise

Since 9.09

midgard_user_log_out ()

gboolean            midgard_user_log_out                (MidgardUser *self);

Cases to return FALSE:

  • There's no user logged in (MGD_ERR_INTERNAL)

  • User is not recently logged in (MGD_ERR_INTERNAL)

self :

 MidgardUser instance

Returns :

 TRUE if user successfully logs out, FALSE otherwise

Since 9.09

midgard_user_is_user ()

gboolean            midgard_user_is_user                (MidgardUser *self);

Checks if given user is a user. For example, function will return FALSE for user who is logged in as admin or root.

self :

 MidgardUser instance

Returns :

 TRUE if user is a user, FALSE otherwise

midgard_user_is_admin ()

gboolean            midgard_user_is_admin               (MidgardUser *self);

Checks if given user is an admin.

self :

 MidgardUser instance

Returns :

 TRUE if user is an admin, FALSE otherwise

midgard_user_get_person ()

MidgardObject *     midgard_user_get_person             (MidgardUser *self);

Returned object should not be unref.

self :

 MidgardUser instance

Returns :

 MidgardObject of "midgard_person" type, or NULL if none associated. [transfer none]

midgard_user_set_person ()

gboolean            midgard_user_set_person             (MidgardUser *self,
                                                         MidgardObject *person);

Associates given MidgardObject person with self MidgardUser. Sets person property and updates user storage record.

MidgardUser self takes ownership of the given MidgardObject ('midgard_person' type) reference, and increases person's object reference count.

See midgard_user_update() for returned error details.

self :

 MidgardUser instance

person :

 MidgardObject instance

Returns :

 TRUE on success, FALSE otherwise

Property Details

The "active" property

  "active"                   gboolean              : Read / Write

Default value: FALSE

The "authtype" property

  "authtype"                 gchar*                : Read / Write

Default value: ""

The "authtypeid" property

  "authtypeid"               guint                 : Read

Default value: 0

The "guid" property

  "guid"                     gchar*                : Read

Default value: ""

The "login" property

  "login"                    gchar*                : Read / Write

Default value: ""

The "password" property

  "password"                 gchar*                : Read / Write

Default value: ""

The "person" property

  "person"                   gchar*                : Read

Default value: ""

The "usertype" property

  "usertype"                 guint                 : Read / Write

Default value: 0

Generated by GTK-Doc V1.18