org.freedesktop.PolicyKit1.Authority.xml 18.5 KB
Newer Older
David Zeuthen's avatar
David Zeuthen committed
1 2 3 4
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>

5 6 7
  <interface name="org.freedesktop.PolicyKit1.Authority">
    <annotation name="org.gtk.EggDBus.DocString.Summary" value="Authority Interface"/>
    <annotation name="org.gtk.EggDBus.DocString" value="This D-Bus interface is implemented by the <literal>/org/freedesktop/PoliycKit1/Authority</literal> object on the well-known name <literal>org.freedesktop.PolicyKit1</literal> on the system message bus."/>
8

9 10
    <!-- ---------------------------------------------------------------------------------------------------- -->

11 12
    <!-- Subject struct -->
    <annotation name="org.gtk.EggDBus.DeclareStruct" value="Subject">
David Zeuthen's avatar
David Zeuthen committed
13
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Subjects"/>
David Zeuthen's avatar
David Zeuthen committed
14 15 16 17
      <annotation name="org.gtk.EggDBus.DocString" value="<para>This struct describes subjects such as UNIX processes. It is typically used to check if a given process is authorized for an action.</para><para>The following kinds of subjects are known:</para>
                  <formalpara><title>Unix Process</title><para><literal>subject_kind</literal> should be set to <literal>unix-process</literal> with keys <literal>pid</literal> (of type <literal>uint32</literal>) and <literal>start-time</literal> (of type <literal>uint64</literal>).</para></formalpara>
                  <formalpara><title>Unix Session</title><para><literal>subject_kind</literal> should be set to <literal>unix-session</literal> with the key <literal>session-id</literal> (of type <literal>string</literal>).</para></formalpara>
                  <formalpara><title>System Bus Name</title><para><literal>subject_kind</literal> should be set to <literal>system-bus-name</literal> with the key <literal>name</literal> (of type <literal>string</literal>).</para></formalpara>"/>
18

19
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:subject_kind">
David Zeuthen's avatar
David Zeuthen committed
20
        <annotation name="org.gtk.EggDBus.DocString" value="The type of the subject."/>
21
      </annotation>
22

23
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,Variant>:subject_details">
David Zeuthen's avatar
David Zeuthen committed
24
        <annotation name="org.gtk.EggDBus.DocString" value="Details about the subject. Depending of the value of @subject_kind, a set of well-defined key/value pairs are guaranteed to be available."/>
25
      </annotation>
26

27 28
    </annotation>

29 30
    <!-- ---------------------------------------------------------------------------------------------------- -->

31 32
    <!-- Identity struct -->
    <annotation name="org.gtk.EggDBus.DeclareStruct" value="Identity">
David Zeuthen's avatar
David Zeuthen committed
33
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Subjects"/>
David Zeuthen's avatar
David Zeuthen committed
34 35 36 37 38
      <annotation name="org.gtk.EggDBus.DocString" value="<para>This struct describes identities such as UNIX users and UNIX groups. It is typically used to check if a given process is authorized for an action.</para><para>The following kinds of identities are known:</para>
                  <formalpara><title>Unix User</title><para><literal>identity_kind</literal> should be set to <literal>unix-user</literal> with key <literal>uid</literal> (of type <literal>uint32</literal>).</para></formalpara>
                  <formalpara><title>Unix Group</title><para><literal>identity_kind</literal> should be set to <literal>unix-group</literal> with key <literal>gid</literal> (of type <literal>uint32</literal>).</para></formalpara>

"/>
39

40
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:identity_kind">
David Zeuthen's avatar
David Zeuthen committed
41
        <annotation name="org.gtk.EggDBus.DocString" value="Type of identity."/>
42
      </annotation>
43

44
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,Variant>:identity_details">
David Zeuthen's avatar
David Zeuthen committed
45
        <annotation name="org.gtk.EggDBus.DocString" value="Details about the identity. Depending of the value of @identity_kind, a set of well-defined key/value pairs are guaranteed to be available."/>
46
      </annotation>
47

48
      <!-- TODO: document values in hash map for each identity type-->
49 50 51

    </annotation>

52 53
    <!-- ---------------------------------------------------------------------------------------------------- -->

54 55
    <!-- ActionDescription struct -->
    <annotation name="org.gtk.EggDBus.DeclareStruct" value="ActionDescription">
David Zeuthen's avatar
David Zeuthen committed
56 57
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Actions"/>
      <annotation name="org.gtk.EggDBus.DocString" value="This struct describes actions registered with the PolicyKit daemon."/>
58

59
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:action_id">
David Zeuthen's avatar
David Zeuthen committed
60
        <annotation name="org.gtk.EggDBus.DocString" value="Action Identifier."/>
61
      </annotation>
62

63
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:description">
David Zeuthen's avatar
David Zeuthen committed
64
        <annotation name="org.gtk.EggDBus.DocString" value="Localized description of the action."/>
65
      </annotation>
66

67
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:message">
David Zeuthen's avatar
David Zeuthen committed
68
        <annotation name="org.gtk.EggDBus.DocString" value="Localized message to be displayed when making the user authenticate for an action."/>
69
      </annotation>
70

71
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:vendor_name">
David Zeuthen's avatar
David Zeuthen committed
72
        <annotation name="org.gtk.EggDBus.DocString" value="Name of the provider of the action or the empty string."/>
73
      </annotation>
74

75
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:vendor_url">
David Zeuthen's avatar
David Zeuthen committed
76
        <annotation name="org.gtk.EggDBus.DocString" value="A URL pointing to a place with more information about the action or the empty string."/>
77
      </annotation>
78

79
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:icon_name">
David Zeuthen's avatar
David Zeuthen committed
80
        <annotation name="org.gtk.EggDBus.DocString" value="The themed icon describing the action or the empty string if no icon is set."/>
81
      </annotation>
82

83 84
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="ImplicitAuthorization:implicit_any">
        <annotation name="org.gtk.EggDBus.Type" value="ImplicitAuthorization"/>
David Zeuthen's avatar
David Zeuthen committed
85
        <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply to any #Subject."/>
86
      </annotation>
87

88 89
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="ImplicitAuthorization:implicit_inactive">
        <annotation name="org.gtk.EggDBus.Type" value="ImplicitAuthorization"/>
David Zeuthen's avatar
David Zeuthen committed
90
        <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply any #Subject in an inactive user session on the local console."/>
91
      </annotation>
92

93 94
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="ImplicitAuthorization:implicit_active">
        <annotation name="org.gtk.EggDBus.Type" value="ImplicitAuthorization"/>
David Zeuthen's avatar
David Zeuthen committed
95
        <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply any #Subject in an active user session on the local console."/>
96
      </annotation>
97

98
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,String>:annotations">
David Zeuthen's avatar
David Zeuthen committed
99
        <annotation name="org.gtk.EggDBus.DocString" value="Annotations for the action."/>
100
      </annotation>
101

102
    </annotation>
103

104 105
    <!-- ---------------------------------------------------------------------------------------------------- -->

106 107
    <!-- Flags used for checking authorizations -->
    <annotation name="org.gtk.EggDBus.DeclareFlags" value="CheckAuthorizationFlags">
David Zeuthen's avatar
David Zeuthen committed
108 109 110
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Flags used when checking authorizations"/>
      <annotation name="org.gtk.EggDBus.DocString" value="Flags used in the org.freedesktop.PolicyKit1.Authority.CheckAuthorization() method."/>

111
      <annotation name="org.gtk.EggDBus.Flags.Member" value="AllowUserInteraction">
David Zeuthen's avatar
David Zeuthen committed
112
        <annotation name="org.gtk.EggDBus.DocString" value="If the #Subject can obtain the authorization through authentication, and an authentication agent is available, then attempt to do so. Note, this means that the org.freedesktop.PolicyKit1.Authority.CheckAuthorization() method will block while the user is being asked to authenticate."/>
113
      </annotation>
114
    </annotation>
115

116 117
    <!-- ---------------------------------------------------------------------------------------------------- -->

David Zeuthen's avatar
David Zeuthen committed
118
    <!-- An structure containing the results of an authorization check -->
119 120 121
    <annotation name="org.gtk.EggDBus.DeclareStruct" value="AuthorizationResult">
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Authorization Results"/>
      <annotation name="org.gtk.EggDBus.DocString" value="Describes the result of calling org.freedesktop.PolicyKit1.Authority.CheckAuthorization()."/>
David Zeuthen's avatar
David Zeuthen committed
122

123
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Boolean:is_authorized">
David Zeuthen's avatar
David Zeuthen committed
124
        <annotation name="org.gtk.EggDBus.DocString" value="TRUE if the given #Subject is authorized for the given action."/>
125
      </annotation>
126 127

      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Boolean:is_challenge">
David Zeuthen's avatar
David Zeuthen committed
128
        <annotation name="org.gtk.EggDBus.DocString" value="TRUE if the given #Subject could be authorized if more information was provided, and %CheckAuthorizationFlags.AllowUserInteraction wasn't passed or no suitable authentication agent was available."/>
129
      </annotation>
130 131 132

      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,String>:details">
        <annotation name="org.gtk.EggDBus.DocString" value="Details for the result or empty if not authorized."/>
133
      </annotation>
134 135
    </annotation>

136 137
    <!-- ---------------------------------------------------------------------------------------------------- -->

138 139
    <!-- An enumeration for implicit authorizations -->
    <annotation name="org.gtk.EggDBus.DeclareEnum" value="ImplicitAuthorization">
David Zeuthen's avatar
David Zeuthen committed
140 141
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Implicit authorizations"/>
      <annotation name="org.gtk.EggDBus.DocString" value="An enumeration for granting implicit authorizations."/>
142

143
      <annotation name="org.gtk.EggDBus.Enum.Member" value="NotAuthorized">
David Zeuthen's avatar
David Zeuthen committed
144
        <annotation name="org.gtk.EggDBus.DocString" value="The #Subject is not authorized."/>
145
      </annotation>
146

147 148 149
      <annotation name="org.gtk.EggDBus.Enum.Member" value="AuthenticationRequired">
        <annotation name="org.gtk.EggDBus.DocString" value="Authentication is required."/>
      </annotation>
150

151 152 153
      <annotation name="org.gtk.EggDBus.Enum.Member" value="AdministratorAuthenticationRequired">
        <annotation name="org.gtk.EggDBus.DocString" value="Authentication as an administrator is required."/>
      </annotation>
154

155 156 157
      <annotation name="org.gtk.EggDBus.Enum.Member" value="AuthenticationRequiredRetained">
        <annotation name="org.gtk.EggDBus.DocString" value="Authentication is required. If the authorization is obtained, it is retained."/>
      </annotation>
David Zeuthen's avatar
David Zeuthen committed
158

159 160 161 162 163
      <annotation name="org.gtk.EggDBus.Enum.Member" value="AdministratorAuthenticationRequiredRetained">
        <annotation name="org.gtk.EggDBus.DocString" value="Authentication as an administrator is required. If the authorization is obtained, it is retained."/>
      </annotation>

      <annotation name="org.gtk.EggDBus.Enum.Member" value="Authorized">
David Zeuthen's avatar
David Zeuthen committed
164
        <annotation name="org.gtk.EggDBus.DocString" value="The subject is authorized."/>
165
      </annotation>
166

167 168
    </annotation>

169 170
    <!-- ---------------------------------------------------------------------------------------------------- -->

171 172
    <!-- The error domain used for reporting errors -->
    <annotation name="org.gtk.EggDBus.DeclareErrorDomain" value="Error">
David Zeuthen's avatar
David Zeuthen committed
173
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Errors"/>
David Zeuthen's avatar
David Zeuthen committed
174
      <annotation name="org.gtk.EggDBus.DocString" value="Errors that can be returned by various method calls."/>
David Zeuthen's avatar
David Zeuthen committed
175

176
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.Failed">
David Zeuthen's avatar
David Zeuthen committed
177
        <annotation name="org.gtk.EggDBus.DocString" value="The operation failed."/>
178
      </annotation>
179 180 181
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.Cancelled">
        <annotation name="org.gtk.EggDBus.DocString" value="The operation was cancelled."/>
      </annotation>
182
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.NotSupported">
David Zeuthen's avatar
David Zeuthen committed
183
        <annotation name="org.gtk.EggDBus.DocString" value="The operation is not supported."/>
184 185
      </annotation>
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.NotAuthorized">
David Zeuthen's avatar
David Zeuthen committed
186
        <annotation name="org.gtk.EggDBus.DocString" value="You are not authorized to perform the requested operation."/>
187
      </annotation>
188 189 190 191 192 193

      <!-- errors not exposed in GObject library follows here -->
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique">
        <annotation name="org.gtk.EggDBus.ErrorDomain.Member.Value" value="1000"/>
        <annotation name="org.gtk.EggDBus.DocString" value="The passed @cancellation_id is already in use."/>
      </annotation>
194
    </annotation>
David Zeuthen's avatar
David Zeuthen committed
195

196 197
    <!-- ---------------------------------------------------------------------------------------------------- -->

198
    <method name="EnumerateActions">
199 200 201 202 203 204
      <annotation name="org.gtk.EggDBus.DocString" value="Enumerates all registered PolicyKit actions."/>

      <arg name="locale" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="The locale to get descriptions in or the blank string to use the system locale."/>
      </arg>

205 206
      <arg name="action_descriptions" direction="out" type="a(ssssssuuua{ss})">
        <annotation name="org.gtk.EggDBus.Type" value="Array<ActionDescription>"/>
David Zeuthen's avatar
David Zeuthen committed
207
        <annotation name="org.gtk.EggDBus.DocString" value="An array of #ActionDescription structs."/>
208
      </arg>
209 210
    </method>

211 212
    <!-- ---------------------------------------------------------------------------------------------------- -->

213
    <method name="CheckAuthorization">
214
      <annotation name="org.gtk.EggDBus.DocString" value="<para>Checks if @subject is authorized to perform the action with identifier @action_id.</para><para>If @cancellation_id is non-empty and already in use for the caller, the %org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique error is returned.</para>"/>
215

216
      <arg name="subject" direction="in" type="(sa{sv})">
David Zeuthen's avatar
David Zeuthen committed
217
        <annotation name="org.gtk.EggDBus.DocString" value="A #Subject struct."/>
218
        <annotation name="org.gtk.EggDBus.Type" value="Subject"/>
219
      </arg>
220 221 222 223 224

      <arg name="action_id" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="Identifier for the action that @subject is attempting to do."/>
      </arg>

225 226 227 228
      <arg name="details" direction="in" type="a{ss}">
        <annotation name="org.gtk.EggDBus.DocString" value="Details describing the action."/>
      </arg>

229 230
      <arg name="flags" direction="in" type="u">
        <annotation name="org.gtk.EggDBus.Type" value="CheckAuthorizationFlags"/>
231
        <annotation name="org.gtk.EggDBus.DocString" value="A set of #CheckAuthorizationFlags."/>
232
      </arg>
233

234 235 236 237
      <arg name="cancellation_id" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="A unique id used to cancel the the authentication check via org.freedesktop.PolicyKit1.Authority.CancelCheckAuthorization() or the empty string if cancellation is not needed."/>
      </arg>

238
      <arg name="result" direction="out" type="(bba{ss})">
239
        <annotation name="org.gtk.EggDBus.Type" value="AuthorizationResult"/>
240
        <annotation name="org.gtk.EggDBus.DocString" value="An #AuthorizationResult structure."/>
241 242 243
      </arg>
    </method>

244 245 246 247 248 249 250 251
    <method name="CancelCheckAuthorization">
      <annotation name="org.gtk.EggDBus.DocString" value="Cancels an authorization check."/>

      <arg name="cancellation_id" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="The @cancellation_id passed to org.freedesktop.PolicyKit1.Authority.CheckAuthorization()."/>
      </arg>
    </method>

252 253
    <!-- ---------------------------------------------------------------------------------------------------- -->

254
    <method name="RegisterAuthenticationAgent">
255 256 257 258 259
      <annotation name="org.gtk.EggDBus.DocString" value="<para>Register an authentication agent.</para><para>Note that current versions of PolicyKit will only work if @session_id is set to the empty string. In the future it might work for non-empty strings if the caller is sufficiently privileged.</para>"/>

      <arg name="session_id" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="The session to register the authentication for or blank for the session the caller of the method is in."/>
      </arg>
260

261 262 263 264
      <arg name="locale" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="The locale of the authentication agent."/>
      </arg>

265
      <arg name="object_path" direction="in" type="s">
266
        <annotation name="org.gtk.EggDBus.DocString" value="The object path of authentication agent object on the unique name of the caller."/>
267 268 269 270
      </arg>
    </method>

    <method name="UnregisterAuthenticationAgent">
271 272
      <annotation name="org.gtk.EggDBus.DocString" value="Unregister an authentication agent."/>

273 274 275 276
      <arg name="session_id" direction="in" type="s">
        <annotation name="org.gtk.EggDBus.DocString" value="The session identifier passed to org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent()."/>
      </arg>

277
      <arg name="object_path" direction="in" type="s">
278
        <annotation name="org.gtk.EggDBus.DocString" value="The object path of authentication agent object on the unique name of the caller."/>
279 280 281
      </arg>
    </method>

282
    <method name="AuthenticationAgentResponse">
283 284
      <annotation name="org.gtk.EggDBus.DocString" value="Method for authentication agents to invoke on successful authentication. This method will fail unless a sufficiently privileged caller invokes it."/>

285
      <arg name="cookie" direction="in" type="s">
286
        <annotation name="org.gtk.EggDBus.DocString" value="The cookie identifying the authentication request that was passed to the authentication agent."/>
287 288 289
      </arg>

      <arg name="identity" direction="in" type="(sa{sv})">
290
        <annotation name="org.gtk.EggDBus.Type" value="Identity"/>
David Zeuthen's avatar
David Zeuthen committed
291
        <annotation name="org.gtk.EggDBus.DocString" value="A #Identity struct describing what identity was authenticated."/>
292 293 294
      </arg>
    </method>

295
    <signal name="Changed">
David Zeuthen's avatar
David Zeuthen committed
296
      <annotation name="org.gtk.EggDBus.DocString" value="This signal is emitted when actions and/or authorizations change"/>
297 298
    </signal>

David Zeuthen's avatar
David Zeuthen committed
299 300
  </interface>
</node>