|  |  |  | GP11 Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | Signals | ||||
                    GP11Module;
GP11Module*         gp11_module_new                     (CK_FUNCTION_LIST_PTR funcs);
GP11Module*         gp11_module_initialize              (const gchar *path,
                                                         gpointer reserved,
                                                         GError **err);
gboolean            gp11_module_equal                   (gconstpointer module1,
                                                         gconstpointer module2);
guint               gp11_module_hash                    (gconstpointer module);
const gchar*        gp11_module_get_path                (GP11Module *self);
CK_FUNCTION_LIST_PTR  gp11_module_get_functions         (GP11Module *self);
GP11ModuleInfo*     gp11_module_get_info                (GP11Module *self);
GList*              gp11_module_get_slots               (GP11Module *self,
                                                         gboolean token_present);
gboolean            gp11_module_get_pool_sessions       (GP11Module *self);
void                gp11_module_set_pool_sessions       (GP11Module *self,
                                                         gboolean pool_sessions);
gint                gp11_module_get_auto_authenticate   (GP11Module *self);
void                gp11_module_set_auto_authenticate   (GP11Module *self,
                                                         gint auto_authenticate);
gboolean            gp11_module_enumerate_objects       (GP11Module *self,
                                                         GP11ObjectForeachFunc func,
                                                         gpointer user_data);
gboolean            (*GP11ObjectForeachFunc)            (GP11Object *object,
                                                         gpointer user_data);
                    GP11ModuleInfo;
void                gp11_module_info_free               (GP11ModuleInfo *module_info);
"auto-authenticate" gint : Read / Write "functions" gpointer : Read / Write / Construct Only "path" gchar* : Read / Write / Construct Only "pool-sessions" gboolean : Read / Write
A GP11Module object holds a loaded PKCS11 module. A PKCS11 module is a shared library.
You can load and initialize a PKCS11 module with the gp11_module_initialize() call. If you already
have a loaded and initialized module that you'd like to use with the various GP11 functions, then 
you can use gp11_module_new().
GP11Module* gp11_module_new (CK_FUNCTION_LIST_PTR funcs);
Create a GP11Module representing a PKCS11 module. It is assumed that this the module is already initialized. In addition it will not be finalized when complete.
| 
 | Initialized PKCS11 function list pointer | 
| Returns : | The new PKCS11 module. | 
GP11Module* gp11_module_initialize (const gchar *path, gpointer reserved, GError **err);
Load and initialize a PKCS11 module represented by a GP11Module object.
| 
 | The file system path to the PKCS11 module to load. | 
| 
 | Extra arguments for the PKCS11 module, should usually be NULL. | 
| 
 | A location to store an error resulting from a failed load. | 
| Returns : | The loaded PKCS11 module or NULL if failed. | 
gboolean gp11_module_equal (gconstpointer module1, gconstpointer module2);
Checks equality of two modules. Two GP11Module objects can point to the same underlying PKCS11 module.
| 
 | A pointer to the first GP11Module | 
| 
 | A pointer to the second GP11Module | 
| Returns : | TRUE if module1 and module2 are equal. FALSE if either is not a GP11Module. | 
guint gp11_module_hash (gconstpointer module);
Create a hash value for the GP11Module.
This function is intended for easily hashing a GP11Module to add to a GHashTable or similar data structure.
| 
 | A pointer to a GP11Module | 
| Returns : | An integer that can be used as a hash value, or 0 if invalid. | 
const gchar* gp11_module_get_path (GP11Module *self);
Get the file path of this module. This may not be an absolute path, and 
usually reflects the path passed to gp11_module_initialize().
| 
 | The module for which to get the path. | 
| Returns : | The path, do not modify or free this value. | 
CK_FUNCTION_LIST_PTR gp11_module_get_functions (GP11Module *self);
Get the PKCS11 function list for the module.
| 
 | The module for which to get the function list. | 
| Returns : | The function list, do not modify this structure. | 
GP11ModuleInfo* gp11_module_get_info (GP11Module *self);
Get the info about a PKCS11 module.
| 
 | The module to get info for. | 
| Returns : | The module info. Release this with gp11_module_info_free(). | 
GList* gp11_module_get_slots (GP11Module *self, gboolean token_present);
Get the GP11Slot objects for a given module.
| 
 | The module for which to get the slots. | 
| 
 | Whether to limit only to slots with a token present. | 
| Returns : | The possibly empty list of slots. Release this with gp11_list_unref_free(). | 
gboolean gp11_module_get_pool_sessions (GP11Module *self);
Get the reuse sessions setting. When this is set, sessions
will be pooled and reused if their flags match when 
gp11_slot_open_session() is called.
| 
 | The module to get setting from. | 
| Returns : | Whether reusing sessions or not. | 
void gp11_module_set_pool_sessions (GP11Module *self, gboolean pool_sessions);
When this is set, sessions will be pooled and reused
if their flags match when gp11_slot_open_session() is called.
| 
 | The module to set the setting on. | 
| 
 | 
gint gp11_module_get_auto_authenticate (GP11Module *self);
Get the auto login setting. When this is set, this slot will emit the 'authenticate-slot' signal when a session requires authentication, and the 'authenticate-object' signal when an object requires authintication.
| 
 | The module to get setting from. | 
| Returns : | Whether auto login or not. | 
void gp11_module_set_auto_authenticate (GP11Module *self, gint auto_authenticate);
When this is set, this slot will emit the 'authenticate-slot' signal when a session requires authentication, and the 'authenticate-object' signal when an object requires authintication.
| 
 | The module to set the setting on. | 
| 
 | 
gboolean gp11_module_enumerate_objects (GP11Module *self, GP11ObjectForeachFunc func, gpointer user_data);
Call a function for every matching object on the module. This call may block for an indefinite period.
The arguments must be triples of: attribute type, data type, value
The variable argument list should contain:
| a) | The gulong attribute type (ie: CKA_LABEL). | 
| b) | The attribute data type (one of GP11_BOOLEAN, GP11_ULONG, GP11_STRING, GP11_DATE) orthe raw attribute value length. | 
| c) | The attribute value, either a gboolean, gulong, gchar*, GDate* or a pointer to a raw attribute value. | 
The variable argument list should be terminated with GP11_INVALID.
This function will open a session per slot. It's recommended that you set the 'reuse-sessions' property on each slot if you'll be calling it a lot.
You can access the session in which the object was found, by using the 
gp11_object_get_session() function on the resulting objects.
This function skips tokens that are not initialize, and makes a best effort to find objects on valid tokens.
The function can return FALSE to stop the enumeration.
| 
 | The module to enumerate objects. | 
| 
 | Function to call for each object. | 
| 
 | Data to pass to the function. | 
| Returns : | If FALSE then an error prevented all matching objects from being enumerated. | 
gboolean (*GP11ObjectForeachFunc) (GP11Object *object, gpointer user_data);
This function is passed to gp11_module_enumerate_objects() or a similar function.
It is called once for each object matched. 
The GP11Session through which the object is accessible can be retrieved by calling
gp11_object_get_session() on object.
| 
 | The enumerated object. | 
| 
 | Data passed to enumerate function. | 
| Returns : | TRUE to continue enumerating, FALSE to stop. | 
typedef struct {
	guint8 pkcs11_version_major;
	guint8 pkcs11_version_minor;
	
	gchar *manufacturer_id;
	gulong flags;
	
	gchar *library_description;
	guint8 library_version_major;
	guint8 library_version_minor;
} GP11ModuleInfo;
Holds information about the PKCS#11 module.
This structure corresponds to CK_MODULE_INFO in the PKCS11 standard. The strings are NULL terminated for easier use.
Use gp11_module_info_free() to release this structure when done with it.
| guint8  | The major version of the module. | 
| guint8  | The minor version of the module. | 
| gchar * | The module manufacturer. | 
| gulong  | The module PKCS#11 flags. | 
| gchar * | The module description. | 
| guint8  | The major version of the library. | 
| guint8  | The minor version of the library. | 
void gp11_module_info_free (GP11ModuleInfo *module_info);
Free a GP11ModuleInfo structure.
| 
 | The module info to free, or NULL. | 
"auto-authenticate" property"auto-authenticate" gint : Read / Write
Whether or not to automatically authenticate token objects that need a C_Login call before they can be used.
The "authenticate-object" signal will be fired when an object needs to be authenticated.
Allowed values: >= 0
Default value: 0
"functions" property"functions" gpointer : Read / Write / Construct Only
The raw PKCS#11 function list for the module.
This points to a CK_FUNCTION_LIST structure.
"path" property"path" gchar* : Read / Write / Construct Only
The PKCS#11 module file path.
This may be set to NULL if this object was created from an already
initialized module via the gp11_module_new() function.
Default value: NULL
"pool-sessions" property"pool-sessions" gboolean : Read / Write
Whether or not to pool PKCS#11 sessions. When this is set, sessions
will be pooled and reused if their flags match when gp11_slot_open_session() 
is called.
Default value: FALSE
"authenticate-object" signalgboolean user_function (GP11Module *module, GP11Object *object, gchar *label, gpointer password, gpointer user_data) : Run Last
This signal is emitted when a password is needed to authenticate a PKCS#11 object like a key. If the module prompts for passwords itself, then this signal will not be emitted.
| 
 | The module. | 
| 
 | The object to be authenticated. | 
| 
 | A displayable label which describes the object. | 
| 
 | A gchar** where a password should be returned. | 
| 
 | user data set when the signal handler was connected. | 
| Returns : | FALSE if the user cancelled, TRUE if we should proceed. | 
"authenticate-slot" signalgboolean user_function (GP11Module *module, GP11Slot *slot, gchar *string, gpointer password, gpointer user_data) : Run Last
This signal is emitted when a password is needed to authenticate a PKCS#11 slot. If the module prompts for passwords itself, then this signal will not be emitted.
| 
 | The module | 
| 
 | The slot to be authenticated. | 
| 
 | A displayable label which describes the object. | 
| 
 | A gchar** where a password should be returned. | 
| 
 | user data set when the signal handler was connected. | 
| Returns : | FALSE if the user cancelled, TRUE if we should proceed. |