polkit-context

polkit-context — Context.

Synopsis




struct              PolKitContext;
void                (*PolKitContextConfigChangedCB)     (PolKitContext *pk_context,
                                                         void *user_data);
enum                PolKitContextFileMonitorEvent;
void                (*PolKitContextFileMonitorNotifyFunc)
                                                        (PolKitContext *pk_context,
                                                         PolKitContextFileMonitorEvent event_mask,
                                                         const char *path,
                                                         void *user_data);
int                 (*PolKitContextFileMonitorAddWatch) (PolKitContext *pk_context,
                                                         const char *path,
                                                         PolKitContextFileMonitorEvent event_mask,
                                                         PolKitContextFileMonitorNotifyFunc notify_cb,
                                                         void *user_data);
void                (*PolKitContextFileMonitorRemoveWatch)
                                                        (PolKitContext *pk_context,
                                                         int watch_id);
PolKitContext*      polkit_context_new                  (void);
void                polkit_context_set_config_changed   (PolKitContext *pk_context,
                                                         PolKitContextConfigChangedCB cb,
                                                         void *user_data);
void                polkit_context_set_file_monitor     (PolKitContext *pk_context,
                                                         PolKitContextFileMonitorAddWatch add_watch_func,
                                                         PolKitContextFileMonitorRemoveWatch remove_watch_func);
void                polkit_context_set_load_descriptions
                                                        (PolKitContext *pk_context);
polkit_bool_t       polkit_context_init                 (PolKitContext *pk_context,
                                                         PolKitError **error);
PolKitContext*      polkit_context_ref                  (PolKitContext *pk_context);
void                polkit_context_unref                (PolKitContext *pk_context);
PolKitPolicyCache*  polkit_context_get_policy_cache     (PolKitContext *pk_context);
PolKitResult        polkit_context_can_session_do_action
                                                        (PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitSession *session);
PolKitResult        polkit_context_can_caller_do_action (PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);

Description

This class is used to represent the interface to PolicyKit.

Details

struct PolKitContext

struct PolKitContext;

Context object for users of PolicyKit.


PolKitContextConfigChangedCB ()

void                (*PolKitContextConfigChangedCB)     (PolKitContext *pk_context,
                                                         void *user_data);

The type of the callback function for when configuration changes. Mechanisms should use this callback to e.g. reconfigure all permissions / acl's they have set in response to policy decisions made from information provided by PolicyKit.

Note that this function may be called many times within a short interval due to how file monitoring works if e.g. the user is editing a configuration file (editors typically create back-up files). Mechanisms should use a "cool-off" timer (of, say, one second) to avoid doing many expensive operations (such as reconfiguring all ACL's for all devices) within a very short timeframe.

pk_context : PolicyKit context
user_data : user data

enum PolKitContextFileMonitorEvent

typedef enum
{
        POLKIT_CONTEXT_FILE_MONITOR_EVENT_NONE    = 1 << 0,
        POLKIT_CONTEXT_FILE_MONITOR_EVENT_ACCESS  = 1 << 1,
        POLKIT_CONTEXT_FILE_MONITOR_EVENT_CREATE  = 1 << 2,
        POLKIT_CONTEXT_FILE_MONITOR_EVENT_DELETE  = 1 << 3,
        POLKIT_CONTEXT_FILE_MONITOR_EVENT_CHANGE  = 1 << 4,
} PolKitContextFileMonitorEvent;

File monitoring events.

POLKIT_CONTEXT_FILE_MONITOR_EVENT_NONE TODO
POLKIT_CONTEXT_FILE_MONITOR_EVENT_ACCESS watch when a file is accessed
POLKIT_CONTEXT_FILE_MONITOR_EVENT_CREATE watch when a file is created
POLKIT_CONTEXT_FILE_MONITOR_EVENT_DELETE watch when a file is deleted
POLKIT_CONTEXT_FILE_MONITOR_EVENT_CHANGE watch when a file changes

PolKitContextFileMonitorNotifyFunc ()

void                (*PolKitContextFileMonitorNotifyFunc)
                                                        (PolKitContext *pk_context,
                                                         PolKitContextFileMonitorEvent event_mask,
                                                         const char *path,
                                                         void *user_data);

Callback when an event happens on a file that is monitored.

pk_context : PolicyKit context
event_mask : event that happened
path : the path to the monitored file
user_data : the user data supplied to the function of type PolKitContextFileMonitorAddWatch

PolKitContextFileMonitorAddWatch ()

int                 (*PolKitContextFileMonitorAddWatch) (PolKitContext *pk_context,
                                                         const char *path,
                                                         PolKitContextFileMonitorEvent event_mask,
                                                         PolKitContextFileMonitorNotifyFunc notify_cb,
                                                         void *user_data);

The type of a function that PolicyKit can use to watch file events. This function must call the supplied notify_cb function (and pass path and user_data) on events

pk_context : PolicyKit context
path : path to file/directory to monitor for events
event_mask : events to look for
notify_cb : function to call on events
user_data : user data
Returns : A handle for the watch. If zero it means the file cannot be watched. Caller can remove the watch using the supplied function of type PolKitContextFileMonitorRemoveWatch and the handle.

PolKitContextFileMonitorRemoveWatch ()

void                (*PolKitContextFileMonitorRemoveWatch)
                                                        (PolKitContext *pk_context,
                                                         int watch_id);

The type of a function that PolicyKit can use to stop monitoring file events. Pass the handle obtained from the supplied function of type PolKitContextFileMonitorAddWatch.

pk_context : PolicyKit context
watch_id : the watch id

polkit_context_new ()

PolKitContext*      polkit_context_new                  (void);

Create a new context

Returns : the object

polkit_context_set_config_changed ()

void                polkit_context_set_config_changed   (PolKitContext *pk_context,
                                                         PolKitContextConfigChangedCB cb,
                                                         void *user_data);

Register the callback function for when configuration changes. Mechanisms should use this callback to e.g. reconfigure all permissions / acl's they have set in response to policy decisions made from information provided by PolicyKit.

Note that this function may be called many times within a short interval due to how file monitoring works if e.g. the user is editing a configuration file (editors typically create back-up files). Mechanisms should use a "cool-off" timer (of, say, one second) to avoid doing many expensive operations (such as reconfiguring all ACL's for all devices) within a very short timeframe.

This method must be called before polkit_context_init().

pk_context : the context object
cb : the callback to invoke
user_data : user data to pass to the callback

polkit_context_set_file_monitor ()

void                polkit_context_set_file_monitor     (PolKitContext *pk_context,
                                                         PolKitContextFileMonitorAddWatch add_watch_func,
                                                         PolKitContextFileMonitorRemoveWatch remove_watch_func);

Register a functions that PolicyKit can use for watching files.

This method must be called before polkit_context_init().

pk_context : the context object
add_watch_func : the function that the PolicyKit library can invoke to start watching a file
remove_watch_func : the function that the PolicyKit library can invoke to stop watching a file

polkit_context_set_load_descriptions ()

void                polkit_context_set_load_descriptions
                                                        (PolKitContext *pk_context);

Set whether policy descriptions should be loaded. By default these are not loaded to keep memory use down.

This method must be called before polkit_context_init().

pk_context : the context

polkit_context_init ()

polkit_bool_t       polkit_context_init                 (PolKitContext *pk_context,
                                                         PolKitError **error);

Initializes a new context; loads PolicyKit files from /etc/PolicyKit/policy unless the environment variable $POLKIT_POLICY_DIR points to a location.

pk_context : the context object
error : return location for error
Returns : FALSE if error was set, otherwise TRUE

polkit_context_ref ()

PolKitContext*      polkit_context_ref                  (PolKitContext *pk_context);

Increase reference count.

pk_context : the context object
Returns : the object

polkit_context_unref ()

void                polkit_context_unref                (PolKitContext *pk_context);

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.

pk_context : the context object

polkit_context_get_policy_cache ()

PolKitPolicyCache*  polkit_context_get_policy_cache     (PolKitContext *pk_context);

Get the PolKitPolicyCache object that holds all the defined policies as well as their defaults.

pk_context : the context
Returns : the PolKitPolicyCache object. Caller shall not unref it.

polkit_context_can_session_do_action ()

PolKitResult        polkit_context_can_session_do_action
                                                        (PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitSession *session);

Determine if a given session can do a given action.

pk_context : the PolicyKit context
action : the type of access to check for
session : the session in question
Returns : A PolKitResult - can only be one of POLKIT_RESULT_NOT_AUTHORIZED_TO_KNOW, POLKIT_RESULT_YES, POLKIT_RESULT_NO.

polkit_context_can_caller_do_action ()

PolKitResult        polkit_context_can_caller_do_action (PolKitContext *pk_context,
                                                         PolKitAction *action,
                                                         PolKitCaller *caller);

Determine if a given caller can do a given action.

pk_context : the PolicyKit context
action : the type of access to check for
caller : the caller in question
Returns : A PolKitResult specifying if, and how, the caller can do a specific action