manpagez: man pages & more
html files: PolicyKit
Home | html | info | man

Caller Determination

Caller Determination — Obtaining seat, session and caller information via D-Bus and ConsoleKit.

Synopsis

PolKitSession *     polkit_session_new_from_objpath     (DBusConnection *con,
                                                         const char *objpath,
                                                         uid_t uid,
                                                         DBusError *error);
PolKitSession *     polkit_session_new_from_cookie      (DBusConnection *con,
                                                         const char *cookie,
                                                         DBusError *error);
PolKitCaller *      polkit_caller_new_from_dbus_name    (DBusConnection *con,
                                                         const char *dbus_name,
                                                         DBusError *error);
PolKitCaller *      polkit_caller_new_from_pid          (DBusConnection *con,
                                                         pid_t pid,
                                                         DBusError *error);
polkit_bool_t       polkit_is_authorization_relevant    (DBusConnection *con,
                                                         PolKitAuthorization *auth,
                                                         DBusError *error);
                    PolKitTracker;
PolKitTracker *     polkit_tracker_new                  (void);
PolKitTracker *     polkit_tracker_ref                  (PolKitTracker *pk_tracker);
void                polkit_tracker_unref                (PolKitTracker *pk_tracker);
void                polkit_tracker_set_system_bus_connection
                                                        (PolKitTracker *pk_tracker,
                                                         DBusConnection *con);
void                polkit_tracker_init                 (PolKitTracker *pk_tracker);
polkit_bool_t       polkit_tracker_dbus_func            (PolKitTracker *pk_tracker,
                                                         DBusMessage *message);
PolKitCaller *      polkit_tracker_get_caller_from_dbus_name
                                                        (PolKitTracker *pk_tracker,
                                                         const char *dbus_name,
                                                         DBusError *error);
PolKitCaller *      polkit_tracker_get_caller_from_pid  (PolKitTracker *pk_tracker,
                                                         pid_t pid,
                                                         DBusError *error);
polkit_bool_t       polkit_tracker_is_authorization_relevant
                                                        (PolKitTracker *pk_tracker,
                                                         PolKitAuthorization *auth,
                                                         DBusError *error);

Description

Helper library for obtaining seat, session and caller information via D-Bus and ConsoleKit. This library is only useful when writing a mechanism.

If the mechanism itself is a daemon exposing a remote services via the system message bus it's often a better idea, to reduce roundtrips, to use the high-level PolKitTracker class rather than the low-level functions polkit_caller_new_from_dbus_name() and polkit_caller_new_from_pid().

These functions are in libpolkit-dbus.

Details

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.

con :

D-Bus system bus connection

objpath :

object path of ConsoleKit session object

uid :

the user owning the session or -1 if unknown

error :

D-Bus error

Returns :

the new object or NULL if an error occured (in which case error will be set)

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.

con :

D-Bus system bus connection

cookie :

a ConsoleKit XDG_SESSION_COOKIE

error :

D-Bus error

Returns :

the new object or NULL if an error occured (in which case error will be set)

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.

con :

D-Bus system bus connection

dbus_name :

unique system bus connection name

error :

D-Bus error

Returns :

the new object or NULL if an error occured (in which case error will be set)

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.

con :

D-Bus system bus connection

pid :

process id

error :

D-Bus error

Returns :

the new object or NULL if an error occured (in which case error will be set)

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.

con :

D-Bus system bus connection

auth :

authorization to check for

error :

return location for error

Returns :

TRUE if the authorization still applies, FALSE if an error occurred (then error will be set) or if the entity the authorization refers to has gone out of scope. This function is in libpolkit-dbus.

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.

Returns :

the new object

Since 0.7


polkit_tracker_ref ()

PolKitTracker *     polkit_tracker_ref                  (PolKitTracker *pk_tracker);

Increase reference count.

This function is in libpolkit-dbus.

pk_tracker :

the tracker object

Returns :

the object

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.

pk_tracker :

the tracker object

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.

pk_tracker :

the tracker object

con :

the connection to the system message bus

Since 0.7


polkit_tracker_init ()

void                polkit_tracker_init                 (PolKitTracker *pk_tracker);

Initialize the tracker.

This function is in libpolkit-dbus.

pk_tracker :

the tracker object

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.

pk_tracker :

the tracker object

message :

message to pass

Returns :

TRUE only if there was a change in the ConsoleKit database.

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.

pk_tracker :

the tracker object

dbus_name :

unique name on the system message bus

error :

D-Bus error

Returns :

A PolKitCaller object; the caller must use polkit_caller_unref() on the object when done with it. Returns NULL if an error occured (in which case error will be set). This function is in libpolkit-dbus.

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.

pk_tracker :

the tracker object

pid :

UNIX process id to look at

error :

D-Bus error

Returns :

A PolKitCaller object; the caller must use polkit_caller_unref() on the object when done with it. Returns NULL if an error occured (in which case error will be set). This function is in libpolkit-dbus.

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.

pk_tracker :

the tracker

auth :

authorization to check for

error :

return location for error

Returns :

TRUE if the authorization still applies, FALSE if an error occurred (then error will be set) or if the entity the authorization refers to has gone out of scope. This function is in libpolkit-dbus.

Since 0.7

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.