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 14
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Subjects"/>
      <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>TODO: document required/optional key/value pairs in @subject_details.</para>"/>
15

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

20
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,Variant>:subject_details">
David Zeuthen's avatar
David Zeuthen committed
21
        <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."/>
22
      </annotation>
23

24 25
    </annotation>

26 27
    <!-- ---------------------------------------------------------------------------------------------------- -->

28 29
    <!-- Identity struct -->
    <annotation name="org.gtk.EggDBus.DeclareStruct" value="Identity">
David Zeuthen's avatar
David Zeuthen committed
30 31
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Subjects"/>
      <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>TODO: document required/optional key/value pairs in @identity_details.</para>"/>
32

33
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:identity_kind">
David Zeuthen's avatar
David Zeuthen committed
34
        <annotation name="org.gtk.EggDBus.DocString" value="Type of identity."/>
35
      </annotation>
36

37
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,Variant>:identity_details">
David Zeuthen's avatar
David Zeuthen committed
38
        <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."/>
39
      </annotation>
40

41
      <!-- TODO: document values in hash map for each identity type-->
42 43 44

    </annotation>

45 46
    <!-- ---------------------------------------------------------------------------------------------------- -->

47 48
    <!-- ActionDescription struct -->
    <annotation name="org.gtk.EggDBus.DeclareStruct" value="ActionDescription">
David Zeuthen's avatar
David Zeuthen committed
49 50
      <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."/>
51

52
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:action_id">
David Zeuthen's avatar
David Zeuthen committed
53
        <annotation name="org.gtk.EggDBus.DocString" value="Action Identifier."/>
54
      </annotation>
55

56
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:description">
David Zeuthen's avatar
David Zeuthen committed
57
        <annotation name="org.gtk.EggDBus.DocString" value="Localized description of the action."/>
58
      </annotation>
59

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

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

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

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

76 77
      <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
78
        <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply to any #Subject."/>
79
      </annotation>
80

81 82
      <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
83
        <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."/>
84
      </annotation>
85

86 87
      <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
88
        <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."/>
89
      </annotation>
90

91
      <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,String>:annotations">
David Zeuthen's avatar
David Zeuthen committed
92
        <annotation name="org.gtk.EggDBus.DocString" value="Annotations for the action."/>
93
      </annotation>
94

95
    </annotation>
96

97 98
    <!-- ---------------------------------------------------------------------------------------------------- -->

99 100
    <!-- Flags used for checking authorizations -->
    <annotation name="org.gtk.EggDBus.DeclareFlags" value="CheckAuthorizationFlags">
David Zeuthen's avatar
David Zeuthen committed
101 102 103
      <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."/>

104
      <annotation name="org.gtk.EggDBus.Flags.Member" value="AllowUserInteraction">
David Zeuthen's avatar
David Zeuthen committed
105
        <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."/>
106
      </annotation>
107
    </annotation>
108

109 110
    <!-- ---------------------------------------------------------------------------------------------------- -->

111 112
    <!-- An enumeration for results when checking for an authorization -->
    <annotation name="org.gtk.EggDBus.DeclareEnum" value="AuthorizationResult">
David Zeuthen's avatar
David Zeuthen committed
113 114 115
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Possible results for checking authorizations"/>
      <annotation name="org.gtk.EggDBus.DocString" value="Possible results that the org.freedesktop.PolicyKit1.Authority.CheckAuthorization() method can return."/>

116
      <annotation name="org.gtk.EggDBus.Enum.Member" value="NotAuthorized">
David Zeuthen's avatar
David Zeuthen committed
117
        <annotation name="org.gtk.EggDBus.DocString" value="The given #Subject is not authorized for the specified action."/>
118 119
      </annotation>
      <annotation name="org.gtk.EggDBus.Enum.Member" value="Authorized">
David Zeuthen's avatar
David Zeuthen committed
120
        <annotation name="org.gtk.EggDBus.DocString" value="The given #Subject is authorized for the specified action."/>
121 122
      </annotation>
      <annotation name="org.gtk.EggDBus.Enum.Member" value="Challenge">
David Zeuthen's avatar
David Zeuthen committed
123
        <annotation name="org.gtk.EggDBus.DocString" value="The given #Subject is authorized if more information is provided."/>
124
      </annotation>
125 126
    </annotation>

127 128
    <!-- ---------------------------------------------------------------------------------------------------- -->

129 130
    <!-- An enumeration for implicit authorizations -->
    <annotation name="org.gtk.EggDBus.DeclareEnum" value="ImplicitAuthorization">
David Zeuthen's avatar
David Zeuthen committed
131 132
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Implicit authorizations"/>
      <annotation name="org.gtk.EggDBus.DocString" value="An enumeration for granting implicit authorizations."/>
133

134
      <annotation name="org.gtk.EggDBus.Enum.Member" value="NotAuthorized">
David Zeuthen's avatar
David Zeuthen committed
135
        <annotation name="org.gtk.EggDBus.DocString" value="The #Subject is not authorized."/>
136
      </annotation>
137

138 139 140
      <annotation name="org.gtk.EggDBus.Enum.Member" value="AuthenticationRequired">
        <annotation name="org.gtk.EggDBus.DocString" value="Authentication is required."/>
      </annotation>
141

142 143 144
      <annotation name="org.gtk.EggDBus.Enum.Member" value="AdministratorAuthenticationRequired">
        <annotation name="org.gtk.EggDBus.DocString" value="Authentication as an administrator is required."/>
      </annotation>
145

146 147 148
      <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
149

150 151 152 153 154
      <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
155
        <annotation name="org.gtk.EggDBus.DocString" value="The subject is authorized."/>
156
      </annotation>
157

158 159
    </annotation>

160 161
    <!-- ---------------------------------------------------------------------------------------------------- -->

162 163
    <!-- The error domain used for reporting errors -->
    <annotation name="org.gtk.EggDBus.DeclareErrorDomain" value="Error">
David Zeuthen's avatar
David Zeuthen committed
164 165 166
      <annotation name="org.gtk.EggDBus.DocString.Summary" value="Errors"/>
      <annotation name="org.gtk.EggDBus.DocString" value="Errors that can be returned."/>

167
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.Failed">
David Zeuthen's avatar
David Zeuthen committed
168
        <annotation name="org.gtk.EggDBus.DocString" value="The operation failed."/>
169
      </annotation>
170 171 172
      <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>
173
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.NotSupported">
David Zeuthen's avatar
David Zeuthen committed
174
        <annotation name="org.gtk.EggDBus.DocString" value="Operation is not supported."/>
175 176
      </annotation>
      <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.NotAuthorized">
David Zeuthen's avatar
David Zeuthen committed
177
        <annotation name="org.gtk.EggDBus.DocString" value="Not authorized to perform operation."/>
178
      </annotation>
179 180 181 182 183 184

      <!-- 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>
185
    </annotation>
David Zeuthen's avatar
David Zeuthen committed
186

187 188
    <!-- ---------------------------------------------------------------------------------------------------- -->

189
    <method name="EnumerateActions">
190 191 192 193 194 195
      <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>

196 197
      <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
198
        <annotation name="org.gtk.EggDBus.DocString" value="An array of #ActionDescription structs."/>
199
      </arg>
200 201
    </method>

202 203
    <!-- ---------------------------------------------------------------------------------------------------- -->

204
    <method name="CheckAuthorization">
205
      <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>"/>
206

207
      <arg name="subject" direction="in" type="(sa{sv})">
David Zeuthen's avatar
David Zeuthen committed
208
        <annotation name="org.gtk.EggDBus.DocString" value="A #Subject struct."/>
209
        <annotation name="org.gtk.EggDBus.Type" value="Subject"/>
210
      </arg>
211 212 213 214 215

      <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>

216 217
      <arg name="flags" direction="in" type="u">
        <annotation name="org.gtk.EggDBus.Type" value="CheckAuthorizationFlags"/>
218
        <annotation name="org.gtk.EggDBus.DocString" value="A set of #CheckAuthorizationFlags."/>
219
      </arg>
220

221 222 223 224
      <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>

225 226 227
      <arg name="result" direction="out" type="u">
        <annotation name="org.gtk.EggDBus.Type" value="AuthorizationResult"/>
        <annotation name="org.gtk.EggDBus.DocString" value="A value from the #AuthorizationResult enumeration."/>
228 229 230
      </arg>
    </method>

231 232 233 234 235 236 237 238
    <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>

239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267
    <!-- ---------------------------------------------------------------------------------------------------- -->

    <method name="ObtainAuthorization">
      <annotation name="org.gtk.EggDBus.DocString" value="Obtains a temporary authorization for @subject to perform the action identified by @action_id. If @subject is already authorized, this method returns immediately without error. If the authorization could not be obtained or @action_id doesn't allow temporary authorizations, the %org.freedesktop.PolicyKit1.Error.Failed error is returned."/>

      <arg name="subject" direction="in" type="(sa{sv})">
        <annotation name="org.gtk.EggDBus.DocString" value="A #Subject struct."/>
        <annotation name="org.gtk.EggDBus.Type" value="Subject"/>
      </arg>

      <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>

      <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.CancelObtainAuthorization() or the empty string if cancellation is not needed."/>
      </arg>
    </method>

    <method name="CancelObtainAuthorization">
      <annotation name="org.gtk.EggDBus.DocString" value="Cancels an attempt to obtain an authorization."/>

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

    <!-- ---------------------------------------------------------------------------------------------------- -->

268
    <method name="RegisterAuthenticationAgent">
269 270 271 272 273
      <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>
274

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

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

283 284 285 286
      <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>

287
      <arg name="object_path" direction="in" type="s">
288
        <annotation name="org.gtk.EggDBus.DocString" value="The object path of authentication agent object on the unique name of the caller."/>
289 290 291
      </arg>
    </method>

292
    <method name="AuthenticationAgentResponse">
293 294
      <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."/>

295
      <arg name="cookie" direction="in" type="s">
296
        <annotation name="org.gtk.EggDBus.DocString" value="The cookie identifying the authentication request that was passed to the authentication agent."/>
297 298 299
      </arg>

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

305
    <signal name="Changed">
David Zeuthen's avatar
David Zeuthen committed
306
      <annotation name="org.gtk.EggDBus.DocString" value="This signal is emitted when actions and/or authorizations change"/>
307 308
    </signal>

David Zeuthen's avatar
David Zeuthen committed
309 310
  </interface>
</node>