![]() |
![]() |
![]() |
PolicyKit Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
PolKitContext; void (*PolKitContextConfigChangedCB) (PolKitContext *pk_context, void *user_data); int (*PolKitContextAddIOWatch) (PolKitContext *pk_context, int fd); void (*PolKitContextRemoveIOWatch) (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_io_watch_functions (PolKitContext *pk_context, PolKitContextAddIOWatch io_add_watch_func, PolKitContextRemoveIOWatch io_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); void polkit_context_force_reload (PolKitContext *pk_context); void polkit_context_io_func (PolKitContext *pk_context, int fd); 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); PolKitConfig * polkit_context_get_config (PolKitContext *pk_context, PolKitError **error); PolKitResult polkit_context_is_caller_authorized (PolKitContext *pk_context, PolKitAction *action, PolKitCaller *caller, polkit_bool_t revoke_if_one_shot, PolKitError **error); PolKitResult polkit_context_is_session_authorized (PolKitContext *pk_context, PolKitAction *action, PolKitSession *session, PolKitError **error); PolKitAuthorizationDB * polkit_context_get_authorization_db (PolKitContext *pk_context);
This class is used to represent the interface to PolicyKit - it is used by Mechanisms that use PolicyKit for making decisions. Typically, it's used as a singleton:
.policy
file into /usr/share/PolicyKit/policy
. This is described in the PolicyKit specification.polkit_context_new()
to create a new contextpolkit_context_set_config_changed()
to register a callback when configuration changes. This is useful if, for example, the mechanism needs to revise decisions based on earlier answers from libpolkit. For example, a daemon that manages permissions on /dev
may want to add/remove ACL's when configuration changes; for example, the system administrator could have changed the PolicyKit configuration file /etc/PolicyKit/PolicyKit.conf
such that some user is now privileged to access a specific device.polkit_context_set_config_changed()
is used, the mechanism must also use polkit_context_set_io_watch_functions()
to integrate libpolkit into the mainloop.polkit_context_init()
such that libpolkit can load configuration files and properly initialize.polkit_context_can_caller_do_action()
(or polkit_context_can_session_do_action()
if applicable). The mechanism may use the libpolkit-dbus library (specifically the polkit_caller_new_from_dbus_name()
or polkit_caller_new_from_pid()
functions) but may opt, for performance reasons, to construct PolKitCaller (or PolKitSession if applicable) from it's own cache of information.polkit_result_to_string_representation()
. For example, if the mechanism is using D-Bus it could throw an com.some-mechanism.DeniedByPolicy exception with the PolKitResult textual representation in the detail field. Then the caller can interpret this exception and then act on it (for example it can attempt to gain that privilege).
For more information about using PolicyKit in mechanisms and callers, refer to the PolicyKit-gnome project which includes a sample application on how to use this in the GNOME desktop.
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.
The user must have set up watches using polkit_context_set_io_watch_functions for this to work.
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.
|
PolicyKit context |
|
user data |
int (*PolKitContextAddIOWatch) (PolKitContext *pk_context, int fd);
Type for function supplied by the application to integrate a watch
on a file descriptor into the applications main loop. The
application must call polkit_context_io_func()
when there is data
to read from the file descriptor.
For glib mainloop, the function will typically look like this:
static gboolean io_watch_have_data (GIOChannel *channel, GIOCondition condition, gpointer user_data) { int fd; PolKitContext *pk_context = user_data; fd = g_io_channel_unix_get_fd (channel); polkit_context_io_func (pk_context, fd); return TRUE; } static int io_add_watch (PolKitContext *pk_context, int fd) { guint id = 0; GIOChannel *channel; channel = g_io_channel_unix_new (fd); if (channel == NULL) goto out; id = g_io_add_watch (channel, G_IO_IN, io_watch_have_data, pk_context); if (id == 0) { g_io_channel_unref (channel); goto out; } g_io_channel_unref (channel); out: return id; }
|
the polkit context |
|
the file descriptor to watch |
Returns : |
0 if the watch couldn't be set up; otherwise an unique identifier for the watch. |
void (*PolKitContextRemoveIOWatch) (PolKitContext *pk_context, int watch_id);
Type for function supplied by the application to remove a watch set up via the supplied function of type PolKitContextAddIOWatch
For the glib mainloop, the function will typically look like this:
static void io_remove_watch (PolKitContext *pk_context, int watch_id) { g_source_remove (watch_id); }
|
the context object |
|
the id obtained from using the supplied function of type PolKitContextAddIOWatch |
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()
.
|
the context object |
|
the callback to invoke |
|
user data to pass to the callback |
void polkit_context_set_io_watch_functions (PolKitContext *pk_context, PolKitContextAddIOWatch io_add_watch_func, PolKitContextRemoveIOWatch io_remove_watch_func);
Register a functions that PolicyKit can use for watching IO descriptors.
This method must be called before polkit_context_init()
.
|
the context object |
|
the function that the PolicyKit library can invoke to start watching a file descriptor |
|
the function that the PolicyKit library can invoke to stop watching a file descriptor |
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. TODO: specify whether they are localized and how.
This method must be called before polkit_context_init()
.
|
the context |
polkit_bool_t polkit_context_init (PolKitContext *pk_context, PolKitError **error);
Initializes a new context; loads PolicyKit files from /usr/share/PolicyKit/policy.
|
the context object |
|
return location for error |
Returns : |
FALSE if error was set, otherwise TRUE
|
PolKitContext * polkit_context_ref (PolKitContext *pk_context);
Increase reference count.
|
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.
|
the context object |
void polkit_context_force_reload (PolKitContext *pk_context);
Force a reload.
Note that there is no reason to call this method in response to a config changed callback.
|
context |
Since 0.7
void polkit_context_io_func (PolKitContext *pk_context, int fd);
Method that the application must call when there is data to read from a file descriptor registered with the supplied function of type PolKitContextAddIOWatch.
|
the object |
|
the file descriptor passed to the supplied function of type PolKitContextAddIOWatch. |
PolKitPolicyCache * polkit_context_get_policy_cache (PolKitContext *pk_context);
Get the PolKitPolicyCache object that holds all the defined policies as well as their defaults.
|
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);
polkit_context_can_session_do_action
has been deprecated since version 0.7 and should not be used in newly-written code. use polkit_context_is_session_authorized()
instead.
Determine if a given session can do a given action.
This can fail with the following errors: POLKIT_ERROR_NOT_AUTHORIZED_TO_READ_AUTHORIZATIONS_FOR_OTHER_USERS
|
the PolicyKit context |
|
the type of access to check for |
|
the session in question |
Returns : |
A PolKitResult - can only be one of POLKIT_RESULT_YES, POLKIT_RESULT_NO. |
PolKitResult polkit_context_can_caller_do_action (PolKitContext *pk_context, PolKitAction *action, PolKitCaller *caller);
polkit_context_can_caller_do_action
has been deprecated since version 0.7 and should not be used in newly-written code. use polkit_context_is_caller_authorized()
instead.
Determine if a given caller can do a given action.
|
the PolicyKit context |
|
the type of access to check for |
|
the caller in question |
Returns : |
A PolKitResult specifying if, and how, the caller can do a specific action |
PolKitConfig * polkit_context_get_config (PolKitContext *pk_context, PolKitError **error);
Returns an object that provides access to the /etc/PolicyKit/PolicyKit.conf configuration files. Applications using PolicyKit should never use this method; it's only here for integration with other PolicyKit components.
|
the PolicyKit context |
|
Return location for error |
Returns : |
A PolKitConfig object or NULL if the configuration file is malformed. Caller should not unref this object. |
PolKitResult polkit_context_is_caller_authorized (PolKitContext *pk_context, PolKitAction *action, PolKitCaller *caller, polkit_bool_t revoke_if_one_shot, PolKitError **error);
Determine if a given caller is authorized to do a given action.
It is important to understand how one-shot authorizations work. The revoke_if_one_shot parameter, if TRUE, specifies whether one-shot authorizations should be revoked if they are used to make the decision to return POLKIT_RESULT_YES.
UI applications wanting to hint whether a caller is authorized must pass FALSE here. Mechanisms that wants to check authorizations before carrying out work on behalf of a caller must pass TRUE here.
As a side-effect, any process with the authorization org.freedesktop.policykit.read can revoke one-shot authorizations from other users. Even though the window for doing so is small (one-shot auths are typically used right away), be careful who you grant that authorization to.
This can fail with the following errors: POLKIT_ERROR_NOT_AUTHORIZED_TO_READ_AUTHORIZATIONS_FOR_OTHER_USERS
|
the PolicyKit context |
|
the type of access to check for |
|
the caller in question |
|
Whether to revoke one-shot authorizations. See below for discussion. |
|
return location for error |
Returns : |
A PolKitResult specifying if, and how, the caller can do a specific action. |
Since 0.7
PolKitResult polkit_context_is_session_authorized (PolKitContext *pk_context, PolKitAction *action, PolKitSession *session, PolKitError **error);
Determine if any caller from a giver session is authorized to do a given action.
|
the PolicyKit context |
|
the type of access to check for |
|
the session in question |
|
return location for error |
Returns : |
A PolKitResult specifying if, and how, the caller can do a specific action. |
Since 0.7
PolKitAuthorizationDB * polkit_context_get_authorization_db (PolKitContext *pk_context);
Returns an object that provides access to the authorization database. Applications using PolicyKit should never use this method; it's only here for integration with other PolicyKit components.
|
the PolicyKit context |
Returns : |
A PolKitAuthorizationDB object. Caller should not unref this object. |