polkit_session_new_from_objpath ()

PolKitSession *     polkit_session_new_from_objpath     (DBusConnection *con,
                                                         const char *objpath,
                                                         uid_t uid,
                                                         DBusError *error);

This function will construct a PolKitSession object by querying the ConsoleKit daemon for information. Note that this will do a lot of blocking IO so it is best avoided if your process already tracks/caches all the information. If you pass in uid as a non-negative number, a round trip can be saved.

This function is in libpolkit-dbus.

polkit_session_new_from_cookie ()

PolKitSession *     polkit_session_new_from_cookie      (DBusConnection *con,
                                                         const char *cookie,
                                                         DBusError *error);

This function will construct a PolKitSession object by querying the ConsoleKit daemon for information. Note that this will do a lot of blocking IO so it is best avoided if your process already tracks/caches all the information.

This function is in libpolkit-dbus.

polkit_caller_new_from_dbus_name ()

PolKitCaller *      polkit_caller_new_from_dbus_name    (DBusConnection *con,
                                                         const char *dbus_name,
                                                         DBusError *error);

This function will construct a PolKitCaller object by querying both the system bus daemon and the ConsoleKit daemon for information. Note that this will do a lot of blocking IO so it is best avoided if your process already tracks/caches all the information. You can use the PolKitTracker class for this.

This function is in libpolkit-dbus.

polkit_caller_new_from_pid ()

PolKitCaller *      polkit_caller_new_from_pid          (DBusConnection *con,
                                                         pid_t pid,
                                                         DBusError *error);

This function will construct a PolKitCaller object by querying both information in /proc (on Linux) and the ConsoleKit daemon for information about a given process. Note that this will do a lot of blocking IO so it is best avoided if your process already tracks/caches all the information. You can use the PolKitTracker class for this.

This function is in libpolkit-dbus.

polkit_is_authorization_relevant ()

polkit_bool_t       polkit_is_authorization_relevant    (DBusConnection *con,
                                                         PolKitAuthorization *auth,
                                                         DBusError *error);

As explicit authorizations are scoped (process single shot, process, session or everything), they become irrelevant once the entity (process or session) ceases to exist. This function determines whether the authorization is still relevant; it's useful for reporting and graphical tools displaying authorizations.

Note that this may do blocking IO to check for session authorizations so it is best avoided if your process already tracks/caches all the information. You can use the polkit_tracker_is_authorization_relevant() method on the PolKitTracker class for this.

Since 0.7

PolKitTracker

typedef struct _PolKitTracker PolKitTracker;

Instances of this class are used to cache information about callers; typically this is used in scenarios where the same caller is calling into a mechanism multiple times.

Thus, an application can use this class to get the PolKitCaller object; the class will listen to both NameOwnerChanged and ActivityChanged signals from the message bus and update / retire the PolKitCaller objects.

An example of how to use PolKitTracker is provided here. First, build the following program

FIXME: MISSING XINCLUDE CONTENT

with

gcc -o tracker-example `pkg-config --cflags --libs dbus-glib-1 polkit-dbus` tracker-example.c

Then put the following content

FIXME: MISSING XINCLUDE CONTENT

in the file /etc/dbus-1/system.d/dk.fubar.PolKitTestService.conf. Finally, create a small Python client like this

FIXME: MISSING XINCLUDE CONTENT

as tracker-example-client.py. Now, run tracker-example in one window and tracker-example-client in another. The output of the former should look like this

18:20:00.414: PolKitCaller: refcount=1 dbus_name=:1.473 uid=500 pid=8636 selinux_context=system_u:system_r:unconfined_t
18:20:00.414: PolKitSession: refcount=1 uid=0 objpath=/org/freedesktop/ConsoleKit/Session1 is_active=1 is_local=1 remote_host=(null)
18:20:00.414: PolKitSeat: refcount=1 objpath=/org/freedesktop/ConsoleKit/Seat1

18:20:01.424: PolKitCaller: refcount=1 dbus_name=:1.473 uid=500 pid=8636 selinux_context=system_u:system_r:unconfined_t
18:20:01.424: PolKitSession: refcount=1 uid=0 objpath=/org/freedesktop/ConsoleKit/Session1 is_active=1 is_local=1 remote_host=(null)
18:20:01.424: PolKitSeat: refcount=1 objpath=/org/freedesktop/ConsoleKit/Seat1

18:20:02.434: PolKitCaller: refcount=1 dbus_name=:1.473 uid=500 pid=8636 selinux_context=system_u:system_r:unconfined_t
18:20:02.434: PolKitSession: refcount=1 uid=0 objpath=/org/freedesktop/ConsoleKit/Session1 is_active=0 is_local=1 remote_host=(null)
18:20:02.434: PolKitSeat: refcount=1 objpath=/org/freedesktop/ConsoleKit/Seat1

18:20:03.445: PolKitCaller: refcount=1 dbus_name=:1.473 uid=500 pid=8636 selinux_context=system_u:system_r:unconfined_t
18:20:03.445: PolKitSession: refcount=1 uid=0 objpath=/org/freedesktop/ConsoleKit/Session1 is_active=1 is_local=1 remote_host=(null)
18:20:03.445: PolKitSeat: refcount=1 objpath=/org/freedesktop/ConsoleKit/Seat1

The point of the test program is simply to gather caller information about clients (the small Python program, you may launch multiple instances of it) that repeatedly calls into the D-Bus service; if one runs strace(1) in front of the test program one will notice that there is only syscall / IPC overhead (except for printing to stdout) on the first call from the client.

The careful reader will notice that, during the testing session, we did a quick VT switch away from the session (and back) which is reflected in the output.

These functions are in libpolkit-dbus.

polkit_tracker_new ()

PolKitTracker *     polkit_tracker_new                  (void);

Creates a new PolKitTracker object.

This function is in libpolkit-dbus.

Since 0.7

polkit_tracker_ref ()

PolKitTracker *     polkit_tracker_ref                  (PolKitTracker *pk_tracker);

Increase reference count.

This function is in libpolkit-dbus.

Since 0.7

polkit_tracker_unref ()

void                polkit_tracker_unref                (PolKitTracker *pk_tracker);

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.

This function is in libpolkit-dbus.

Since 0.7

polkit_tracker_set_system_bus_connection ()

void                polkit_tracker_set_system_bus_connection
                                                        (PolKitTracker *pk_tracker,
                                                         DBusConnection *con);

Tell the PolKitTracker object to use the given D-Bus connection when it needs to fetch information from the system message bus and ConsoleKit services. This is used for priming the cache.

This function is in libpolkit-dbus.

Since 0.7

polkit_tracker_init ()

void                polkit_tracker_init                 (PolKitTracker *pk_tracker);

Initialize the tracker.

This function is in libpolkit-dbus.

Since 0.7

polkit_tracker_dbus_func ()

polkit_bool_t       polkit_tracker_dbus_func            (PolKitTracker *pk_tracker,
                                                         DBusMessage *message);

The owner of the PolKitTracker object must pass signals from the system message bus (just NameOwnerChanged will do) and all signals from the ConsoleKit service into this function.

This function is in libpolkit-dbus.

Since 0.7

polkit_tracker_get_caller_from_dbus_name ()

PolKitCaller *      polkit_tracker_get_caller_from_dbus_name
                                                        (PolKitTracker *pk_tracker,
                                                         const char *dbus_name,
                                                         DBusError *error);

This function is similar to polkit_caller_new_from_dbus_name() except that it uses the cache in PolKitTracker. So on the second and subsequent calls, for the same D-Bus name, there will be no syscall or IPC overhead in calling this function.

Since 0.7

polkit_tracker_get_caller_from_pid ()

PolKitCaller *      polkit_tracker_get_caller_from_pid  (PolKitTracker *pk_tracker,
                                                         pid_t pid,
                                                         DBusError *error);

This function is similar to polkit_caller_new_from_pid() except that it uses the cache in PolKitTracker. So on the second and subsequent calls, for the same D-Bus name, there will be no IPC overhead in calling this function.

There will be some syscall overhead to lookup the time when the given process is started (on Linux, looking up /proc/$pid/stat); this is needed because pid's can be recycled and the cache thus needs to record this in addition to the pid.

Since 0.7

polkit_tracker_is_authorization_relevant ()

polkit_bool_t       polkit_tracker_is_authorization_relevant
                                                        (PolKitTracker *pk_tracker,
                                                         PolKitAuthorization *auth,
                                                         DBusError *error);

As explicit authorizations are scoped (process single shot, process, session or everything), they become irrelevant once the entity (process or session) ceases to exist. This function determines whether the authorization is still relevant; it's useful for reporting and graphical tools displaying authorizations.

This function is similar to polkit_is_authorization_relevant() only that it avoids IPC overhead on the 2nd and subsequent calls when checking authorizations scoped for a session.

Since 0.7