Core API Reference - Context

PolKitContext

typedef struct _PolKitContext 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.

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.

PolKitContextAddIOWatch ()

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;
}

PolKitContextRemoveIOWatch ()

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);
}

polkit_context_new ()

PolKitContext*      polkit_context_new                  (void);

Create a new context

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().

polkit_context_set_io_watch_functions ()

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().

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. TODO: specify whether they are localized and how.

This method must be called before polkit_context_init().

polkit_context_init ()

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

Initializes a new context; loads PolicyKit files from /usr/share/PolicyKit/policy.

polkit_context_ref ()

PolKitContext*      polkit_context_ref                  (PolKitContext *pk_context);

Increase reference count.

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.

polkit_context_force_reload ()

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.

Since 0.7

polkit_context_io_func ()

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.

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.

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.

This can fail with the following errors: POLKIT_ERROR_NOT_AUTHORIZED_TO_READ_AUTHORIZATIONS_FOR_OTHER_USERS

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.

polkit_context_get_config ()

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.

polkit_context_is_caller_authorized ()

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

Since 0.7

polkit_context_is_session_authorized ()

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.

Since 0.7

polkit_context_get_authorization_db ()

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.