| 1 |
<?xml version="1.0"?> |
| 2 |
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2 //EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> |
| 4 |
<refentry id="eggdbus-interface-org.freedesktop.PolicyKit1.AuthenticationAgent"> |
| 5 |
<refmeta> |
| 6 |
<refentrytitle role="top_of_page">org.freedesktop.PolicyKit1.AuthenticationAgent Interface</refentrytitle> |
| 7 |
</refmeta> |
| 8 |
<refnamediv> |
| 9 |
<refname>org.freedesktop.PolicyKit1.AuthenticationAgent Interface</refname> |
| 10 |
<refpurpose>Authentication Agent Interface</refpurpose> |
| 11 |
</refnamediv> |
| 12 |
<refsynopsisdiv role="synopsis"> |
| 13 |
<title role="synopsis.title">Methods</title> |
| 14 |
<synopsis> |
| 15 |
<link linkend="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.BeginAuthentication">BeginAuthentication</link> (IN String action_id, |
| 16 |
IN String message, |
| 17 |
IN String icon_name, |
| 18 |
IN Dict<String,String> details, |
| 19 |
IN String cookie, |
| 20 |
IN Array<<link linkend="eggdbus-struct-Identity">Identity</link>> identities) |
| 21 |
<link linkend="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.CancelAuthentication">CancelAuthentication</link> (IN String cookie) |
| 22 |
</synopsis> |
| 23 |
</refsynopsisdiv> |
| 24 |
<refsect1 role="desc" id="eggdbus-if-description-org.freedesktop.PolicyKit1.AuthenticationAgent"> |
| 25 |
<title role="desc.title">Description</title> |
| 26 |
<para> |
| 27 |
<para>This D-Bus interface is used for communication between the system-wide PolicyKit daemon and one or more authentication agents each running in a user session.</para><para>An authentication agent must implement this interface and register (passing the object path of the object implementing the interface) using the <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link> and <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.UnregisterAuthenticationAgent">UnregisterAuthenticationAgent()</link> methods on the <link linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link> interface of the PolicyKit daemon.</para> |
| 28 |
</para> |
| 29 |
</refsect1> |
| 30 |
<refsect1 role="details" id="eggdbus-if-method-details-org.freedesktop.PolicyKit1.AuthenticationAgent"> |
| 31 |
<title role="details.title">Method Details</title> |
| 32 |
<refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.BeginAuthentication"> |
| 33 |
<title>BeginAuthentication ()</title> |
| 34 |
<programlisting> |
| 35 |
BeginAuthentication (IN String action_id, |
| 36 |
IN String message, |
| 37 |
IN String icon_name, |
| 38 |
IN Dict<String,String> details, |
| 39 |
IN String cookie, |
| 40 |
IN Array<<link linkend="eggdbus-struct-Identity">Identity</link>> identities) |
| 41 |
</programlisting> |
| 42 |
<para> |
| 43 |
<para> |
| 44 |
Called by the PolicyKit daemon when the authentication agent |
| 45 |
needs the user to authenticate as one of the identities in |
| 46 |
<parameter>identities</parameter> for the action with the |
| 47 |
identifier <parameter>action_id</parameter>.</para><para>Upon |
| 48 |
succesful authentication, the authentication agent must invoke |
| 49 |
the <link |
| 50 |
linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.AuthenticationAgentResponse2">AuthenticationAgentResponse2()</link> |
| 51 |
method on the <link |
| 52 |
linkend="eggdbus-interface-org.freedesktop.PolicyKit1.Authority">org.freedesktop.PolicyKit1.Authority</link> |
| 53 |
interface of the PolicyKit daemon before returning. This is normally |
| 54 |
achieved via the <link linkend="PolkitAgentSession">PolkitAgentSession</link> |
| 55 |
API, which invokes a private setuid helper process to verify the |
| 56 |
authentication. |
| 57 |
</para> |
| 58 |
<para> |
| 59 |
The authentication agent should not return until after authentication is complete. |
| 60 |
If the user dismisses the authentication dialog, the authentication agent should return the <link linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.Cancelled">org.freedesktop.PolicyKit1.Error.Cancelled</link> error. |
| 61 |
</para> |
| 62 |
</para> |
| 63 |
|
| 64 |
<variablelist role="params"> |
| 65 |
<varlistentry> |
| 66 |
<term><literal>IN String <parameter>action_id</parameter></literal>:</term> |
| 67 |
<listitem> |
| 68 |
<para> |
| 69 |
The identifier for the action that the user is authentication for. |
| 70 |
</para> |
| 71 |
</listitem> |
| 72 |
</varlistentry> |
| 73 |
<varlistentry> |
| 74 |
<term><literal>IN String <parameter>message</parameter></literal>:</term> |
| 75 |
<listitem> |
| 76 |
<para> |
| 77 |
The message to display to the user. This is translated into the locale passed when registering the authentication agent using <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>. |
| 78 |
</para> |
| 79 |
</listitem> |
| 80 |
</varlistentry> |
| 81 |
<varlistentry> |
| 82 |
<term><literal>IN String <parameter>icon_name</parameter></literal>:</term> |
| 83 |
<listitem> |
| 84 |
<para> |
| 85 |
The themed icon describing the action or the empty string if no icon is set. |
| 86 |
</para> |
| 87 |
</listitem> |
| 88 |
</varlistentry> |
| 89 |
<varlistentry> |
| 90 |
<term><literal>IN Dict<String,String> <parameter>details</parameter></literal>:</term> |
| 91 |
<listitem> |
| 92 |
<para> |
| 93 |
Details about the authentication request. This is a dictionary |
| 94 |
of key/value pairs where both key and value are strings. |
| 95 |
Known key/value-pairs include |
| 96 |
<literal>polkit.caller-pid</literal> (the process id of the |
| 97 |
mechanism making the authorization check) and |
| 98 |
<literal>polkit.subject-pid</literal> (the process id of the |
| 99 |
subject the check is for). |
| 100 |
</para> |
| 101 |
</listitem> |
| 102 |
</varlistentry> |
| 103 |
<varlistentry> |
| 104 |
<term><literal>IN String <parameter>cookie</parameter></literal>:</term> |
| 105 |
<listitem> |
| 106 |
<para> |
| 107 |
A cookie identifying the authentication request. |
| 108 |
</para> |
| 109 |
</listitem> |
| 110 |
</varlistentry> |
| 111 |
<varlistentry> |
| 112 |
<term><literal>IN Array<<link linkend="eggdbus-struct-Identity">Identity</link>> <parameter>identities</parameter></literal>:</term> |
| 113 |
<listitem> |
| 114 |
<para> |
| 115 |
An array of <link linkend="eggdbus-struct-Identity">Identity</link> structs that the user can use for authentication. |
| 116 |
</para> |
| 117 |
</listitem> |
| 118 |
</varlistentry> |
| 119 |
</variablelist> |
| 120 |
</refsect2> |
| 121 |
<refsect2 role="function" id="eggdbus-method-org.freedesktop.PolicyKit1.AuthenticationAgent.CancelAuthentication"> |
| 122 |
<title>CancelAuthentication ()</title> |
| 123 |
<programlisting> |
| 124 |
CancelAuthentication (IN String cookie) |
| 125 |
</programlisting> |
| 126 |
<para> |
| 127 |
Called by the PolicyKit daemon if the authentication agent needs to cancel an authentication dialog. |
| 128 |
</para> |
| 129 |
<variablelist role="params"> |
| 130 |
<varlistentry> |
| 131 |
<term><literal>IN String <parameter>cookie</parameter></literal>:</term> |
| 132 |
<listitem> |
| 133 |
<para> |
| 134 |
The cookie identifying the authentication request. |
| 135 |
</para> |
| 136 |
</listitem> |
| 137 |
</varlistentry> |
| 138 |
</variablelist> |
| 139 |
</refsect2> |
| 140 |
</refsect1> |
| 141 |
</refentry> |