summaryrefslogtreecommitdiff
path: root/dom/plugins/base/nsIPluginHost.idl
blob: d1124aa259599d32ccd5b5b40588a075bc45dac6 (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
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* 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/. */

#include "nspluginroot.idl"
#include "nsISupports.idl"
#include "nsIPluginTag.idl"

%{C++
#define MOZ_PLUGIN_HOST_CONTRACTID \
  "@mozilla.org/plugin/host;1"
%}

[scriptable, function, uuid(9c311778-7c2c-4ad8-b439-b8a2786a20dd)]
interface nsIClearSiteDataCallback : nsISupports
{
    /**
     * callback with the result from a call to clearSiteData
     */
    void callback(in nsresult rv);
};

[scriptable, uuid(f938f5ba-7093-42cd-a559-af8039d99204)]
interface nsIPluginHost : nsISupports
{
  /**
   * Causes the plugins directory to be searched again for new plugin
   * libraries.
   */
  void reloadPlugins();

  void getPluginTags([optional] out unsigned long aPluginCount,
    [retval, array, size_is(aPluginCount)] out nsIPluginTag aResults);

  /*
   * Flags for use with clearSiteData.
   *
   * FLAG_CLEAR_ALL: clear all data associated with a site.
   * FLAG_CLEAR_CACHE: clear cached data that can be retrieved again without
   *                   loss of functionality. To be used out of concern for
   *                   space and not necessarily privacy.
   */
  const uint32_t FLAG_CLEAR_ALL = 0;
  const uint32_t FLAG_CLEAR_CACHE = 1;

  /*
   * For use with Get*ForType functions
   */
  const uint32_t EXCLUDE_NONE     = 0;
  const uint32_t EXCLUDE_DISABLED = 1 << 0;
  const uint32_t EXCLUDE_FAKE     = 1 << 1;

  /*
   * Clear site data for a given plugin.
   *
   * @param plugin: the plugin to clear data for, such as one returned by
   *                nsIPluginHost.getPluginTags.
   * @param domain: the domain to clear data for. If this argument is null,
   *                clear data for all domains. Otherwise, it must be a domain
   *                only (not a complete URI or IRI). The base domain for the
   *                given site will be determined; any data for the base domain
   *                or its subdomains will be cleared.
   * @param flags: a flag value defined above.
   * @param maxAge: the maximum age in seconds of data to clear, inclusive. If
   *                maxAge is 0, no data is cleared; if it is -1, all data is
   *                cleared.
   *
   * @throws NS_ERROR_INVALID_ARG if the domain argument is malformed.
   * @throws NS_ERROR_PLUGIN_TIME_RANGE_NOT_SUPPORTED if maxAge is a value other
   *         than -1 and the plugin does not support clearing by timerange in
   *         general or for that particular site and/or flag combination.
   */
  void clearSiteData(in nsIPluginTag plugin, in AUTF8String domain,
                     in uint64_t flags, in int64_t maxAge,
                     in nsIClearSiteDataCallback callback);

  /*
   * Determine if a plugin has stored data for a given site.
   *
   * @param plugin: the plugin to query, such as one returned by
   *                nsIPluginHost.getPluginTags.
   * @param domain: the domain to test. If this argument is null, test if data
   *                is stored for any site. The base domain for the given domain
   *                will be determined; if any data for the base domain or its
   *                subdomains is found, return true.
   */
  boolean siteHasData(in nsIPluginTag plugin, in AUTF8String domain);

  /**
   * Get the "permission string" for the plugin.  This is a string that can be
   * passed to the permission manager to see whether the plugin is allowed to
   * run, for example.  This will typically be based on the plugin's "nice name"
   * and its blocklist state.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  ACString getPermissionStringForType(in AUTF8String mimeType,
                                      [optional] in uint32_t excludeFlags);

  /**
   * Get the "permission string" for the plugin.  This is a string that can be
   * passed to the permission manager to see whether the plugin is allowed to
   * run, for example.  This will typically be based on the plugin's "nice name"
   * and its blocklist state.
   *
   * @tag The tage we're interested in
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  ACString getPermissionStringForTag(in nsIPluginTag tag,
                                     [optional] in uint32_t excludeFlags);

  /**
   * Get the nsIPluginTag for this MIME type. This method works with both
   * enabled and disabled/blocklisted plugins, but an enabled plugin will
   * always be returned if available.
   *
   * A fake plugin tag, if one exists and is available, will be returned in
   * preference to NPAPI plugin tags unless excluded by the excludeFlags.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   *
   * @throws NS_ERROR_NOT_AVAILABLE if no plugin is available for this MIME
   *         type.
   */
  nsIPluginTag getPluginTagForType(in AUTF8String mimeType,
                                   [optional] in uint32_t excludeFlags);

  /**
   * Get the nsIPluginTag enabled state for this MIME type.  See
   * nsIPluginTag.enabledState.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  unsigned long getStateForType(in AUTF8String mimeType,
                                [optional] in uint32_t excludeFlags);

  /**
   * Get the blocklist state for a MIME type.  See nsIPluginTag.blocklistState.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  uint32_t getBlocklistStateForType(in AUTF8String aMimeType,
                                    [optional] in uint32_t excludeFlags);

  /**
   * Create a fake plugin tag, register it, and return it.  The argument is a
   * FakePluginTagInit dictionary.  See documentation in
   * FakePluginTagInit.webidl for what it should look like.  Will throw
   * NS_ERROR_UNEXPECTED if there is already a fake plugin registered with the
   * given handler URI.
   */
  [implicit_jscontext]
  nsIFakePluginTag registerFakePlugin(in jsval initDictionary);

  /**
   * Get a reference to an existing fake plugin tag for the given MIME type, if
   * any.  Can return null.
   */
  nsIFakePluginTag getFakePlugin(in AUTF8String mimeType);

  /**
   * Unregister a fake plugin.  The argument can be the .handlerURI.spec of an
   * existing nsIFakePluginTag, or just a known handler URI string that was
   * passed in the FakePluginTagInit when registering.
   */
  void unregisterFakePlugin(in AUTF8String handlerURI);
};