Debian Codegraph @

docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml

raw
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&lt;String,String&gt; details,
19 IN String cookie,
20 IN Array&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt; 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&lt;String,String&gt; details,
39 IN String cookie,
40 IN Array&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt; 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&lt;String,String&gt; <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&lt;<link linkend="eggdbus-struct-Identity">Identity</link>&gt; <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>