![]() |
![]() |
![]() |
PolicyKit Library Reference Manual | ![]() |
---|---|---|---|---|
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);
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 |
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.
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 |
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. |
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 |
PolKitContext* polkit_context_new (void);
Create a new context
Returns : | the object |
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 |
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 |
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_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.
PolKitContext* polkit_context_ref (PolKitContext *pk_context);
Increase reference count.
pk_context : |
the context object |
Returns : | the object |
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 |
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. |
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. |
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 |