ACC SHELL
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Caller Determination</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="PolicyKit Library Reference Manual">
<link rel="up" href="ref-core.html" title="Core API Reference">
<link rel="prev" href="polkit-Caller.html" title="Caller">
<link rel="next" href="polkit-Context.html" title="Context">
<meta name="generator" content="GTK-Doc V1.14 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="polkit-Caller.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="ref-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">PolicyKit Library Reference Manual</th>
<td><a accesskey="n" href="polkit-Context.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#polkit-Caller-Determination.synopsis" class="shortcut">Top</a>
|
<a href="#polkit-Caller-Determination.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry" title="Caller Determination">
<a name="polkit-Caller-Determination"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="polkit-Caller-Determination.top_of_page"></a>Caller Determination</span></h2>
<p>Caller Determination — Obtaining seat, session and caller information
via D-Bus and ConsoleKit.</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv" title="Synopsis">
<a name="polkit-Caller-Determination.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis"><a class="link" href="polkit-Session.html#PolKitSession" title="PolKitSession"><span class="returnvalue">PolKitSession</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-session-new-from-objpath" title="polkit_session_new_from_objpath ()">polkit_session_new_from_objpath</a> (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *objpath</code></em>,
<em class="parameter"><code><span class="type">uid_t</span> uid</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Session.html#PolKitSession" title="PolKitSession"><span class="returnvalue">PolKitSession</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-session-new-from-cookie" title="polkit_session_new_from_cookie ()">polkit_session_new_from_cookie</a> (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *cookie</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-caller-new-from-dbus-name" title="polkit_caller_new_from_dbus_name ()">polkit_caller_new_from_dbus_name</a> (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *dbus_name</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-caller-new-from-pid" title="polkit_caller_new_from_pid ()">polkit_caller_new_from_pid</a> (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code><span class="type">pid_t</span> pid</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Basic-types.html#polkit-bool-t" title="polkit_bool_t"><span class="returnvalue">polkit_bool_t</span></a> <a class="link" href="polkit-Caller-Determination.html#polkit-is-authorization-relevant" title="polkit_is_authorization_relevant ()">polkit_is_authorization_relevant</a> (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code><a class="link" href="polkit-Authorization-Entry.html#PolKitAuthorization" title="PolKitAuthorization"><span class="type">PolKitAuthorization</span></a> *auth</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker">PolKitTracker</a>;
<a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="returnvalue">PolKitTracker</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-new" title="polkit_tracker_new ()">polkit_tracker_new</a> (<em class="parameter"><code><span class="type">void</span></code></em>);
<a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="returnvalue">PolKitTracker</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-ref" title="polkit_tracker_ref ()">polkit_tracker_ref</a> (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>);
<span class="returnvalue">void</span> <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-unref" title="polkit_tracker_unref ()">polkit_tracker_unref</a> (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>);
<span class="returnvalue">void</span> <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-set-system-bus-connection" title="polkit_tracker_set_system_bus_connection ()">polkit_tracker_set_system_bus_connection</a>
(<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>);
<span class="returnvalue">void</span> <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-init" title="polkit_tracker_init ()">polkit_tracker_init</a> (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>);
<a class="link" href="polkit-Basic-types.html#polkit-bool-t" title="polkit_bool_t"><span class="returnvalue">polkit_bool_t</span></a> <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-dbus-func" title="polkit_tracker_dbus_func ()">polkit_tracker_dbus_func</a> (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><span class="type">DBusMessage</span> *message</code></em>);
<a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-get-caller-from-dbus-name" title="polkit_tracker_get_caller_from_dbus_name ()">polkit_tracker_get_caller_from_dbus_name</a>
(<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *dbus_name</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-get-caller-from-pid" title="polkit_tracker_get_caller_from_pid ()">polkit_tracker_get_caller_from_pid</a> (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><span class="type">pid_t</span> pid</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
<a class="link" href="polkit-Basic-types.html#polkit-bool-t" title="polkit_bool_t"><span class="returnvalue">polkit_bool_t</span></a> <a class="link" href="polkit-Caller-Determination.html#polkit-tracker-is-authorization-relevant" title="polkit_tracker_is_authorization_relevant ()">polkit_tracker_is_authorization_relevant</a>
(<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><a class="link" href="polkit-Authorization-Entry.html#PolKitAuthorization" title="PolKitAuthorization"><span class="type">PolKitAuthorization</span></a> *auth</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);
</pre>
</div>
<div class="refsect1" title="Description">
<a name="polkit-Caller-Determination.description"></a><h2>Description</h2>
<p>
Helper library for obtaining seat, session and caller information
via D-Bus and ConsoleKit. This library is only useful when writing
a mechanism.
</p>
<p>
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 <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> class rather than
the low-level functions <a class="link" href="polkit-Caller-Determination.html#polkit-caller-new-from-dbus-name" title="polkit_caller_new_from_dbus_name ()"><code class="function">polkit_caller_new_from_dbus_name()</code></a> and
<a class="link" href="polkit-Caller-Determination.html#polkit-caller-new-from-pid" title="polkit_caller_new_from_pid ()"><code class="function">polkit_caller_new_from_pid()</code></a>.
</p>
<p>
These functions are in <code class="literal">libpolkit-dbus</code>.
</p>
</div>
<div class="refsect1" title="Details">
<a name="polkit-Caller-Determination.details"></a><h2>Details</h2>
<div class="refsect2" title="polkit_session_new_from_objpath ()">
<a name="polkit-session-new-from-objpath"></a><h3>polkit_session_new_from_objpath ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Session.html#PolKitSession" title="PolKitSession"><span class="returnvalue">PolKitSession</span></a> * polkit_session_new_from_objpath (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *objpath</code></em>,
<em class="parameter"><code><span class="type">uid_t</span> uid</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
This function will construct a <a class="link" href="polkit-Session.html#PolKitSession" title="PolKitSession"><span class="type">PolKitSession</span></a> 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 <em class="parameter"><code>uid</code></em> as a
non-negative number, a round trip can be saved.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>con</code></em> :</span></p></td>
<td>D-Bus system bus connection
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>objpath</code></em> :</span></p></td>
<td>object path of ConsoleKit session object
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>uid</code></em> :</span></p></td>
<td>the user owning the session or -1 if unknown
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>D-Bus error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the new object or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><span class="type">NULL</span></a> if an error occured (in which case
<em class="parameter"><code>error</code></em> will be set)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="polkit_session_new_from_cookie ()">
<a name="polkit-session-new-from-cookie"></a><h3>polkit_session_new_from_cookie ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Session.html#PolKitSession" title="PolKitSession"><span class="returnvalue">PolKitSession</span></a> * polkit_session_new_from_cookie (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *cookie</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
This function will construct a <a class="link" href="polkit-Session.html#PolKitSession" title="PolKitSession"><span class="type">PolKitSession</span></a> 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.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>con</code></em> :</span></p></td>
<td>D-Bus system bus connection
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>cookie</code></em> :</span></p></td>
<td>a ConsoleKit XDG_SESSION_COOKIE
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>D-Bus error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the new object or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><span class="type">NULL</span></a> if an error occured (in which case
<em class="parameter"><code>error</code></em> will be set)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="polkit_caller_new_from_dbus_name ()">
<a name="polkit-caller-new-from-dbus-name"></a><h3>polkit_caller_new_from_dbus_name ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * polkit_caller_new_from_dbus_name (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *dbus_name</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
This function will construct a <a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="type">PolKitCaller</span></a> 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 <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> class for this.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>con</code></em> :</span></p></td>
<td>D-Bus system bus connection
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dbus_name</code></em> :</span></p></td>
<td>unique system bus connection name
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>D-Bus error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the new object or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><span class="type">NULL</span></a> if an error occured (in which case
<em class="parameter"><code>error</code></em> will be set)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="polkit_caller_new_from_pid ()">
<a name="polkit-caller-new-from-pid"></a><h3>polkit_caller_new_from_pid ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * polkit_caller_new_from_pid (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code><span class="type">pid_t</span> pid</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
This function will construct a <a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="type">PolKitCaller</span></a> 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 <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a>
class for this.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>con</code></em> :</span></p></td>
<td>D-Bus system bus connection
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pid</code></em> :</span></p></td>
<td>process id
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>D-Bus error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the new object or <a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><span class="type">NULL</span></a> if an error occured (in which case
<em class="parameter"><code>error</code></em> will be set)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="polkit_is_authorization_relevant ()">
<a name="polkit-is-authorization-relevant"></a><h3>polkit_is_authorization_relevant ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Basic-types.html#polkit-bool-t" title="polkit_bool_t"><span class="returnvalue">polkit_bool_t</span></a> polkit_is_authorization_relevant (<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>,
<em class="parameter"><code><a class="link" href="polkit-Authorization-Entry.html#PolKitAuthorization" title="PolKitAuthorization"><span class="type">PolKitAuthorization</span></a> *auth</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
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.
</p>
<p>
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
<a class="link" href="polkit-Caller-Determination.html#polkit-tracker-is-authorization-relevant" title="polkit_tracker_is_authorization_relevant ()"><code class="function">polkit_tracker_is_authorization_relevant()</code></a> method on the
<a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> class for this.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>con</code></em> :</span></p></td>
<td>D-Bus system bus connection
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>auth</code></em> :</span></p></td>
<td>authorization to check for
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>return location for error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><span class="type">TRUE</span></a> if the authorization still applies, <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><span class="type">FALSE</span></a> 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 <code class="literal">libpolkit-dbus</code>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="PolKitTracker">
<a name="PolKitTracker"></a><h3>PolKitTracker</h3>
<pre class="programlisting">typedef struct _PolKitTracker PolKitTracker;</pre>
<p>
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.
</p>
<p>
Thus, an application can use this class to get the <a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="type">PolKitCaller</span></a>
object; the class will listen to both NameOwnerChanged and
ActivityChanged signals from the message bus and update / retire
the <a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="type">PolKitCaller</span></a> objects.
</p>
<p>
An example of how to use <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> is provided here. First, build the following program
</p>
<p>
</p>
<pre class="programlisting">FIXME: MISSING XINCLUDE CONTENT</pre>
<p>
</p>
<p>
with
</p>
<p>
</p>
<pre class="programlisting">gcc -o tracker-example `pkg-config --cflags --libs dbus-glib-1 polkit-dbus` tracker-example.c</pre>
<p>
</p>
<p>
Then put the following content
</p>
<p>
</p>
<pre class="programlisting">FIXME: MISSING XINCLUDE CONTENT</pre>
<p>
</p>
<p>
in the file <code class="literal">/etc/dbus-1/system.d/dk.fubar.PolKitTestService.conf</code>. Finally,
create a small Python client like this
</p>
<p>
</p>
<pre class="programlisting">FIXME: MISSING XINCLUDE CONTENT</pre>
<p>
</p>
<p>
as <code class="literal">tracker-example-client.py</code>. Now, run <code class="literal">tracker-example</code>
in one window and <code class="literal">tracker-example-client</code> in another. The output of
the former should look like this
</p>
<p>
</p>
<pre class="programlisting">
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
</pre>
<p>
</p>
<p>
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 <code class="literal">strace(1)</code> 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.
</p>
<p>
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.
</p>
<p>
These functions are in <code class="literal">libpolkit-dbus</code>.
</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_new ()">
<a name="polkit-tracker-new"></a><h3>polkit_tracker_new ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="returnvalue">PolKitTracker</span></a> * polkit_tracker_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>
Creates a new <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> object.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the new object
</td>
</tr></tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_ref ()">
<a name="polkit-tracker-ref"></a><h3>polkit_tracker_ref ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="returnvalue">PolKitTracker</span></a> * polkit_tracker_ref (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>);</pre>
<p>
Increase reference count.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the object
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_unref ()">
<a name="polkit-tracker-unref"></a><h3>polkit_tracker_unref ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> polkit_tracker_unref (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>);</pre>
<p>
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.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr></tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_set_system_bus_connection ()">
<a name="polkit-tracker-set-system-bus-connection"></a><h3>polkit_tracker_set_system_bus_connection ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> polkit_tracker_set_system_bus_connection
(<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><span class="type">DBusConnection</span> *con</code></em>);</pre>
<p>
Tell the <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> 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.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>con</code></em> :</span></p></td>
<td>the connection to the system message bus
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_init ()">
<a name="polkit-tracker-init"></a><h3>polkit_tracker_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> polkit_tracker_init (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>);</pre>
<p>
Initialize the tracker.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr></tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_dbus_func ()">
<a name="polkit-tracker-dbus-func"></a><h3>polkit_tracker_dbus_func ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Basic-types.html#polkit-bool-t" title="polkit_bool_t"><span class="returnvalue">polkit_bool_t</span></a> polkit_tracker_dbus_func (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><span class="type">DBusMessage</span> *message</code></em>);</pre>
<p>
The owner of the <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> object must pass signals from the
system message bus (just NameOwnerChanged will do) and all signals
from the ConsoleKit service into this function.
</p>
<p>
This function is in <code class="literal">libpolkit-dbus</code>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>message</code></em> :</span></p></td>
<td>message to pass
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><span class="type">TRUE</span></a> only if there was a change in the ConsoleKit database.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_get_caller_from_dbus_name ()">
<a name="polkit-tracker-get-caller-from-dbus-name"></a><h3>polkit_tracker_get_caller_from_dbus_name ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * polkit_tracker_get_caller_from_dbus_name
(<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *dbus_name</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
This function is similar to <a class="link" href="polkit-Caller-Determination.html#polkit-caller-new-from-dbus-name" title="polkit_caller_new_from_dbus_name ()"><code class="function">polkit_caller_new_from_dbus_name()</code></a>
except that it uses the cache in <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a>. 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.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dbus_name</code></em> :</span></p></td>
<td>unique name on the system message bus
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>D-Bus error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> A <a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="type">PolKitCaller</span></a> object; the caller must use
<a class="link" href="polkit-Caller.html#polkit-caller-unref" title="polkit_caller_unref ()"><code class="function">polkit_caller_unref()</code></a> on the object when done with it. Returns
<a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><span class="type">NULL</span></a> if an error occured (in which case error will be set).
This function is in <code class="literal">libpolkit-dbus</code>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_get_caller_from_pid ()">
<a name="polkit-tracker-get-caller-from-pid"></a><h3>polkit_tracker_get_caller_from_pid ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="returnvalue">PolKitCaller</span></a> * polkit_tracker_get_caller_from_pid (<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><span class="type">pid_t</span> pid</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
This function is similar to <a class="link" href="polkit-Caller-Determination.html#polkit-caller-new-from-pid" title="polkit_caller_new_from_pid ()"><code class="function">polkit_caller_new_from_pid()</code></a>
except that it uses the cache in <a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a>. So on the second
and subsequent calls, for the same D-Bus name, there will be no
IPC overhead in calling this function.
</p>
<p>
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.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker object
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pid</code></em> :</span></p></td>
<td>UNIX process id to look at
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>D-Bus error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> A <a class="link" href="polkit-Caller.html#PolKitCaller" title="PolKitCaller"><span class="type">PolKitCaller</span></a> object; the caller must use
<a class="link" href="polkit-Caller.html#polkit-caller-unref" title="polkit_caller_unref ()"><code class="function">polkit_caller_unref()</code></a> on the object when done with it. Returns
<a href="../glib/glib-Standard-Macros.html#NULL:CAPS"><span class="type">NULL</span></a> if an error occured (in which case error will be set).
This function is in <code class="literal">libpolkit-dbus</code>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
<hr>
<div class="refsect2" title="polkit_tracker_is_authorization_relevant ()">
<a name="polkit-tracker-is-authorization-relevant"></a><h3>polkit_tracker_is_authorization_relevant ()</h3>
<pre class="programlisting"><a class="link" href="polkit-Basic-types.html#polkit-bool-t" title="polkit_bool_t"><span class="returnvalue">polkit_bool_t</span></a> polkit_tracker_is_authorization_relevant
(<em class="parameter"><code><a class="link" href="polkit-Caller-Determination.html#PolKitTracker" title="PolKitTracker"><span class="type">PolKitTracker</span></a> *pk_tracker</code></em>,
<em class="parameter"><code><a class="link" href="polkit-Authorization-Entry.html#PolKitAuthorization" title="PolKitAuthorization"><span class="type">PolKitAuthorization</span></a> *auth</code></em>,
<em class="parameter"><code><span class="type">DBusError</span> *error</code></em>);</pre>
<p>
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.
</p>
<p>
This function is similar to <a class="link" href="polkit-Caller-Determination.html#polkit-is-authorization-relevant" title="polkit_is_authorization_relevant ()"><code class="function">polkit_is_authorization_relevant()</code></a> only
that it avoids IPC overhead on the 2nd and subsequent calls when
checking authorizations scoped for a session.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>pk_tracker</code></em> :</span></p></td>
<td>the tracker
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>auth</code></em> :</span></p></td>
<td>authorization to check for
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>return location for error
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><span class="type">TRUE</span></a> if the authorization still applies, <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><span class="type">FALSE</span></a> 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 <code class="literal">libpolkit-dbus</code>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 0.7</p>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.14</div>
</body>
</html>
ACC SHELL 2018