summaryrefslogtreecommitdiff
path: root/netwerk/base/nsIPermissionManager.idl
blob: b61817d4cfa6e63f721c1065de212bc0191176fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
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
268
269
270
271
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * This file contains an interface to the Permission Manager,
 * used to persistenly store permissions for different object types (cookies, 
 * images etc) on a site-by-site basis.
 *
 * This service broadcasts the following notification when the permission list
 * is changed:
 *
 * topic  : "perm-changed" (PERM_CHANGE_NOTIFICATION)
 *          broadcast whenever the permission list changes in some way. there
 *          are four possible data strings for this notification; one
 *          notification will be broadcast for each change, and will involve
 *          a single permission.
 * subject: an nsIPermission interface pointer representing the permission object
 *          that changed.
 * data   : "deleted"
 *          a permission was deleted. the subject is the deleted permission.
 *          "added"
 *          a permission was added. the subject is the added permission.
 *          "changed"
 *          a permission was changed. the subject is the new permission.
 *          "cleared"
 *          the entire permission list was cleared. the subject is null.
 */

#include "nsISupports.idl"

interface nsIURI;
interface nsIObserver;
interface nsIPrincipal;
interface mozIDOMWindow;
interface nsIPermission;
interface nsISimpleEnumerator;

[scriptable, uuid(4dcb3851-eba2-4e42-b236-82d2596fca22)]
interface nsIPermissionManager : nsISupports
{
  /**
   * Predefined return values for the testPermission method and for
   * the permission param of the add method
   * NOTE: UNKNOWN_ACTION (0) is reserved to represent the
   * default permission when no entry is found for a host, and
   * should not be used by consumers to indicate otherwise.
   */
  const uint32_t UNKNOWN_ACTION = 0;
  const uint32_t ALLOW_ACTION = 1;
  const uint32_t DENY_ACTION = 2;
  const uint32_t PROMPT_ACTION = 3;

  /**
   * Predefined expiration types for permissions.  Permissions can be permanent
   * (never expire), expire at the end of the session, or expire at a specified
   * time. Permissions that expire at the end of a session may also have a
   * specified expiration time.
   */
  const uint32_t EXPIRE_NEVER = 0;
  const uint32_t EXPIRE_SESSION = 1;
  const uint32_t EXPIRE_TIME = 2;

  /**
   * Add permission information for a given URI and permission type. This
   * operation will cause the type string to be registered if it does not
   * currently exist. If a permission already exists for a given type, it
   * will be modified.
   *
   * @param uri         the uri to add the permission for
   * @param type        a case-sensitive ASCII string, identifying the consumer.
   *                    Consumers should choose this string to be unique, with
   *                    respect to other consumers.
   * @param permission  an integer representing the desired action (e.g. allow
   *                    or deny). The interpretation of this number is up to the
   *                    consumer, and may represent different actions for different
   *                    types. Consumers may use one of the enumerated permission
   *                    actions defined above, for convenience.
   *                    NOTE: UNKNOWN_ACTION (0) is reserved to represent the
   *                    default permission when no entry is found for a host, and
   *                    should not be used by consumers to indicate otherwise.
   * @param expiretype  a constant defining whether this permission should
   *                    never expire (EXPIRE_NEVER), expire at the end of the
   *                    session (EXPIRE_SESSION), or expire at a specified time
   *                    (EXPIRE_TIME).
   * @param expiretime  an integer representation of when this permission
   *                    should be forgotten (milliseconds since Jan 1 1970 0:00:00). 
   */
  void add(in nsIURI uri,
           in string type,
           in uint32_t permission,
           [optional] in uint32_t expireType,
           [optional] in int64_t expireTime);

  /**
   * Get all custom permissions for a given URI. This will return
   * an enumerator of all permissions which are not set to default
   * and which belong to the matching prinicpal of the given URI.
   *
   * @param uri  the URI to get all permissions for
   */
  nsISimpleEnumerator getAllForURI(in nsIURI uri);

  /**
   * Add permission information for a given principal.
   * It is internally calling the other add() method using the nsIURI from the
   * principal.
   * Passing a system principal will be a no-op because they will always be
   * granted permissions.
   */
  void addFromPrincipal(in nsIPrincipal principal, in string typed,
                        in uint32_t permission,
                        [optional] in uint32_t expireType,
                        [optional] in int64_t expireTime);

  /**
   * Remove permission information for a given URI and permission type. This will
   * remove the permission for the entire host described by the uri, acting as the
   * opposite operation to the add() method.
   *
   * @param uri    the uri to remove the permission for
   * @param type   a case-sensitive ASCII string, identifying the consumer. 
   *               The type must have been previously registered using the
   *               add() method.
   */
  void remove(in nsIURI uri,
              in string type);

  /**
   * Remove permission information for a given principal.
   * This is internally calling remove() with the host from the principal's URI.
   * Passing system principal will be a no-op because we never add them to the
   * database.
   */
  void removeFromPrincipal(in nsIPrincipal principal, in string type);

  /**
   * Remove the given permission from the permission manager.
   *
   * @param perm   a permission obtained from the permission manager.
   */
  void removePermission(in nsIPermission perm);

  /**
   * Clear permission information for all websites.
   */
  void removeAll();

  /**
   * Clear all permission information added since the specified time.
   */
  void removeAllSince(in int64_t since);

  /**
   * Test whether a website has permission to perform the given action.
   * @param uri     the uri to be tested
   * @param type    a case-sensitive ASCII string, identifying the consumer
   * @param return  see add(), param permission. returns UNKNOWN_ACTION when
   *                there is no stored permission for this uri and / or type.
   */
  uint32_t testPermission(in nsIURI uri,
                          in string type);

  /**
   * Test whether the principal has the permission to perform a given action.
   * System principals will always have permissions granted.
   */
  uint32_t testPermissionFromPrincipal(in nsIPrincipal principal,
                                       in string type);

  /**
   * Test whether the principal associated with the window's document has the
   * permission to perform a given action.  System principals will always
   * have permissions granted.
   */
  uint32_t testPermissionFromWindow(in mozIDOMWindow window,
                                    in string type);

  /**
   * Test whether a website has permission to perform the given action.
   * This requires an exact hostname match, subdomains are not a match.
   * @param uri     the uri to be tested
   * @param type    a case-sensitive ASCII string, identifying the consumer
   * @param return  see add(), param permission. returns UNKNOWN_ACTION when
   *                there is no stored permission for this uri and / or type.
   */
  uint32_t testExactPermission(in nsIURI uri,
                               in string type);

  /**
   * See testExactPermission() above.
   * System principals will always have permissions granted.
   */
  uint32_t testExactPermissionFromPrincipal(in nsIPrincipal principal,
                                            in string type);

  /**
   * Test whether a website has permission to perform the given action
   * ignoring active sessions.
   * System principals will always have permissions granted.
   *
   * @param principal the principal
   * @param type      a case-sensitive ASCII string, identifying the consumer
   * @param return    see add(), param permission. returns UNKNOWN_ACTION when
   *                  there is no stored permission for this uri and / or type.
   */
  uint32_t testExactPermanentPermission(in nsIPrincipal principal,
                                        in string type);

  /**
   * Get the permission object associated with the given principal and action.
   * @param principal The principal
   * @param type      A case-sensitive ASCII string identifying the consumer
   * @param exactHost If true, only the specific host will be matched,
   *                  @see testExactPermission. If false, subdomains will
   *                  also be searched, @see testPermission.
   * @returns The matching permission object, or null if no matching object
   *          was found. No matching object is equivalent to UNKNOWN_ACTION.
   * @note Clients in general should prefer the test* methods unless they
   *       need to know the specific stored details.
   * @note This method will always return null for the system principal.
   */
  nsIPermission getPermissionObject(in nsIPrincipal principal,
                                    in string type,
                                    in boolean exactHost);

  /**
   * Allows enumeration of all stored permissions
   * @return an nsISimpleEnumerator interface that allows access to
   *         nsIPermission objects
   */
  readonly attribute nsISimpleEnumerator enumerator;

  /**
   * Remove all permissions that will match the origin pattern.
   */
  void removePermissionsWithAttributes(in DOMString patternAsJSON);

  /**
   * If the current permission is set to expire, reset the expiration time. If
   * there is no permission or the current permission does not expire, this
   * method will silently return.
   *
   * @param sessionExpiretime  an integer representation of when this permission
   *                           should be forgotten (milliseconds since
   *                           Jan 1 1970 0:00:00), if it is currently
   *                           EXPIRE_SESSION.
   * @param sessionExpiretime  an integer representation of when this permission
   *                           should be forgotten (milliseconds since
   *                           Jan 1 1970 0:00:00), if it is currently
   *                           EXPIRE_TIME.
   */
  void updateExpireTime(in nsIPrincipal principal,
                        in string type,
                        in boolean exactHost,
                        in uint64_t sessionExpireTime,
                        in uint64_t persistentExpireTime);

  /**
   * Remove all current permission settings and get permission settings from
   * chrome process.
   */
  void refreshPermission();
};

%{ C++
#define NS_PERMISSIONMANAGER_CONTRACTID "@mozilla.org/permissionmanager;1"

#define PERM_CHANGE_NOTIFICATION "perm-changed"
%}