polkit-module

polkit-module — PolicyKit loadable module interface

Synopsis




struct              PolKitModuleInterface;
polkit_bool_t       (*PolKitModuleInitialize)           (PolKitModuleInterface *module_interface,
                                                         int argc,
                                                         char *argv[]);
void                (*PolKitModuleShutdown)             (PolKitModuleInterface *module_interface);
PolKitResult        (*PolKitModuleCanSessionDoAction)   (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitSession *session);
PolKitResult        (*PolKitModuleCanCallerDoAction)    (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);
PolKitModuleInterface* polkit_module_interface_new      (void);
PolKitModuleInterface* polkit_module_interface_ref      (PolKitModuleInterface *module_interface);
void                polkit_module_interface_unref       (PolKitModuleInterface *module_interface);
const char*         polkit_module_get_name              (PolKitModuleInterface *module_interface);
void                polkit_module_set_user_data         (PolKitModuleInterface *module_interface,
                                                         void *user_data);
void*               polkit_module_get_user_data         (PolKitModuleInterface *module_interface);
void                polkit_module_set_func_initialize   (PolKitModuleInterface *module_interface,
                                                         PolKitModuleInitialize func);
void                polkit_module_set_func_shutdown     (PolKitModuleInterface *module_interface,
                                                         PolKitModuleShutdown func);
void                polkit_module_set_func_can_session_do_action
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitModuleCanSessionDoAction func);
void                polkit_module_set_func_can_caller_do_action
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitModuleCanCallerDoAction func);
PolKitModuleInitialize polkit_module_get_func_initialize
                                                        (PolKitModuleInterface *module_interface);
PolKitModuleShutdown polkit_module_get_func_shutdown    (PolKitModuleInterface *module_interface);
PolKitModuleCanSessionDoAction polkit_module_get_func_can_session_do_action
                                                        (PolKitModuleInterface *module_interface);
PolKitModuleCanCallerDoAction polkit_module_get_func_can_caller_do_action
                                                        (PolKitModuleInterface *module_interface);
enum                PolKitModuleControl;
const char*         polkit_module_control_to_string_representation
                                                        (PolKitModuleControl module_control);
polkit_bool_t       polkit_module_control_from_string_representation
                                                        (const char *string,
                                                         PolKitModuleControl *out_module_control);
PolKitModuleInterface* polkit_module_interface_load_module
                                                        (const char *name,
                                                         PolKitModuleControl module_control,
                                                         int argc,
                                                         char *argv[]);
PolKitModuleControl polkit_module_interface_get_control (PolKitModuleInterface *module_interface);
polkit_bool_t       polkit_module_interface_check_builtin_confinement_for_session
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitSession *session);
polkit_bool_t       polkit_module_interface_check_builtin_confinement_for_caller
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);

Description

These functions are used by loadable PolicyKit modules.

Details

struct PolKitModuleInterface

struct PolKitModuleInterface;

Objects of this class are used to interface with PolicyKit modules

PolKitModuleInitialize ()

polkit_bool_t       (*PolKitModuleInitialize)           (PolKitModuleInterface *module_interface,
                                                         int argc,
                                                         char *argv[]);

Type of PolicyKit module function to initialize the module.

module_interface : the module interface
argc : number of arguments to pass to module
argv : arguments passed to module; the first argument is the filename/path to the module
Returns : Whether the module was initialized.

PolKitModuleShutdown ()

void                (*PolKitModuleShutdown)             (PolKitModuleInterface *module_interface);

Type of PolicyKit module function to shutdown the module.

module_interface : the module interface

PolKitModuleCanSessionDoAction ()

PolKitResult        (*PolKitModuleCanSessionDoAction)   (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitSession *session);

module_interface :
pk_context :
action :
session :
Returns :

PolKitModuleCanCallerDoAction ()

PolKitResult        (*PolKitModuleCanCallerDoAction)    (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);

module_interface :
pk_context :
action :
caller :
Returns :

polkit_module_interface_new ()

PolKitModuleInterface* polkit_module_interface_new      (void);

Create a new PolKitModuleInterface object.

Returns : the new object

polkit_module_interface_ref ()

PolKitModuleInterface* polkit_module_interface_ref      (PolKitModuleInterface *module_interface);

Increase reference count.

module_interface : the module_interface object
Returns : the object

polkit_module_interface_unref ()

void                polkit_module_interface_unref       (PolKitModuleInterface *module_interface);

Decreases the reference count of the object. If it becomes zero, the object is freed. Before freeing, reference counts on embedded objects are decresed by one.

module_interface : the module_interface object

polkit_module_get_name ()

const char*         polkit_module_get_name              (PolKitModuleInterface *module_interface);

Get the name of the module

module_interface : the module interface
Returns : name or NULL if an error occured

polkit_module_set_user_data ()

void                polkit_module_set_user_data         (PolKitModuleInterface *module_interface,
                                                         void *user_data);

Set user data. A PolicyKit module should use these instead of global variables as multiple instances of the module may be instantiated at the same time.

module_interface : module interface
user_data : user data to set

polkit_module_get_user_data ()

void*               polkit_module_get_user_data         (PolKitModuleInterface *module_interface);

Get user data.

module_interface : module interface
Returns : The user data set with polkit_module_set_user_data()

polkit_module_set_func_initialize ()

void                polkit_module_set_func_initialize   (PolKitModuleInterface *module_interface,
                                                         PolKitModuleInitialize func);

Set the function pointer.

module_interface : the module interface
func : the function pointer

polkit_module_set_func_shutdown ()

void                polkit_module_set_func_shutdown     (PolKitModuleInterface *module_interface,
                                                         PolKitModuleShutdown func);

Set the function pointer.

module_interface : the module interface
func : the function pointer

polkit_module_set_func_can_session_do_action ()

void                polkit_module_set_func_can_session_do_action
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitModuleCanSessionDoAction func);

Set the function pointer.

module_interface : the module interface
func : the function pointer

polkit_module_set_func_can_caller_do_action ()

void                polkit_module_set_func_can_caller_do_action
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitModuleCanCallerDoAction func);

Set the function pointer.

module_interface : the module interface
func : the function pointer

polkit_module_get_func_initialize ()

PolKitModuleInitialize polkit_module_get_func_initialize
                                                        (PolKitModuleInterface *module_interface);

Get the function pointer.

module_interface : the module interface
Returns : Function pointer or NULL if it's unavailable or an error occured

polkit_module_get_func_shutdown ()

PolKitModuleShutdown polkit_module_get_func_shutdown    (PolKitModuleInterface *module_interface);

Get the function pointer.

module_interface : the module interface
Returns : Function pointer or NULL if it's unavailable or an error occured

polkit_module_get_func_can_session_do_action ()

PolKitModuleCanSessionDoAction polkit_module_get_func_can_session_do_action
                                                        (PolKitModuleInterface *module_interface);

Get the function pointer.

module_interface : the module interface
Returns : Function pointer or NULL if it's unavailable or an error occured

polkit_module_get_func_can_caller_do_action ()

PolKitModuleCanCallerDoAction polkit_module_get_func_can_caller_do_action
                                                        (PolKitModuleInterface *module_interface);

Get the function pointer.

module_interface : the module interface
Returns : Function pointer or NULL if it's unavailable or an error occured

enum PolKitModuleControl

typedef enum
{
        POLKIT_MODULE_CONTROL_ADVISE,
        POLKIT_MODULE_CONTROL_MANDATORY,
        POLKIT_MODULE_CONTROL_N_CONTROLS
} PolKitModuleControl;

The control stanza for a PolicyKit module. This is read from the PolicyKit configuration file (/etc/PolicyKit/PolicyKit.conf) that defines the stacked order of the modules and is chosen by the system administrator. See the definition of PolKitResult for the definition of "strict" with respect to result values.

POLKIT_MODULE_CONTROL_ADVISE Allow modules, marked with POLKIT_MODULE_CONTROL_MANDATORY, down the stack to override results from this module. Modules down the stack that are also marked with the POLKIT_MODULE_CONTROL_ADVISE control will only take effect it they change the result to be "less strict".
POLKIT_MODULE_CONTROL_MANDATORY Always use results (unless it returns POLKIT_RESULT_UNKNOWN_ACTION for a given request) from this module, even if it changes whether the result to be "more strict". . If a later module also uses this control, results from that module will override it.
POLKIT_MODULE_CONTROL_N_CONTROLS Number of control stanzas

polkit_module_control_to_string_representation ()

const char*         polkit_module_control_to_string_representation
                                                        (PolKitModuleControl module_control);

Gives a textual representation of a PolKitModuleControl object.

module_control : the given value
Returns : The textual representation or NULL if the value passed is invalid

polkit_module_control_from_string_representation ()

polkit_bool_t       polkit_module_control_from_string_representation
                                                        (const char *string,
                                                         PolKitModuleControl *out_module_control);

Given a textual representation of a PolKitModuleControl object, find the PolKitModuleControl value.

string : the textual representation
out_module_control : return location for the value
Returns : TRUE if the textual representation was valid, otherwise FALSE

polkit_module_interface_load_module ()

PolKitModuleInterface* polkit_module_interface_load_module
                                                        (const char *name,
                                                         PolKitModuleControl module_control,
                                                         int argc,
                                                         char *argv[]);

Load and initialize a PolicyKit module

name : name of module, e.g. "polkit-module-default.so"
module_control : the module control; from the configuration file
argc : number arguments to pass
argv : argument vector, the first argument must be the filename/path to the module
Returns : A PolKitModuleInterface object on success; NULL on failure.

polkit_module_interface_get_control ()

PolKitModuleControl polkit_module_interface_get_control (PolKitModuleInterface *module_interface);

Get the control for this module.

module_interface : the module interface
Returns : A PolKitModuleControl value.

polkit_module_interface_check_builtin_confinement_for_session ()

polkit_bool_t       polkit_module_interface_check_builtin_confinement_for_session
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitSession *session);

Check whether some of the built-in module options (e.g. action="hal-storage-*", user=davidz) confines the given module, e.g. whether it should be skipped.

module_interface : the given module
pk_context : the PolicyKit context
action : the type of access to check for
session : the session in question
Returns : TRUE if, and only if, the module is confined from handling the request

polkit_module_interface_check_builtin_confinement_for_caller ()

polkit_bool_t       polkit_module_interface_check_builtin_confinement_for_caller
                                                        (PolKitModuleInterface *module_interface,
                                                         PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);

Check whether some of the built-in module options (e.g. action="hal-storage-*", user=davidz) confines the given module, e.g. whether it should be skipped.

module_interface : the given module
pk_context : the PolicyKit context
action : the type of access to check for
caller : the caller in question
Returns : TRUE if, and only if, the module is confined from handling the request