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
|
Wiring up new WebExtensions WebIDL files into mozilla-central
=============================================================
Add a new entry in ``dom/bindings/Bindings.conf``
-------------------------------------------------
New WebIDL bindings should be added as new entries in ``dom/bindings/Bindings.conf``. The new entry should be
added in alphabetic order and nearby the other WebExtensions API bindings already listed in this config file
(look for the ``ExtensionBrowser`` webidl definition and the other existing WebIDL bindings related to the
WebExtensions APIs):
.. code-block::
# WebExtension API
...
'ExtensionRuntime': {
'headerFile': 'mozilla/extensions/ExtensionRuntime.h',
'nativeType': 'mozilla::extensions::ExtensionRuntime',
},
.. warning::
`mach build` will fail if the entries in `dom/bindings/Bindings.conf` are not in alphabetic order,
or if the `headerFile` referenced does not exist yet.
Add a new entry in ``dom/webidl/moz.build``
-------------------------------------------
The new ``.webidl`` file has to be also listed in "dom/webidl/moz.build", it should be added in
- the existing group of ``WEBIDL_FILES`` entries meant specifically for the WebExtensions API bindings
- or in the group of ``PREPROCESSED_WEBIDL_FILES`` entries meant specifically for the WebExtensions
API bindings, **if the generated `.webidl` includes preprocessing macros** (e.g. when part of an API
is not available in all builds, e.g. subset of APIs that are only available in Desktop builds).
.. code-block::
# WebExtensions API.
WEBIDL_FILES += [
...
"ExtensionRuntime.webidl"
...
]
PREPROCESSED_WEBIDL_FILES += [
...
]
.. warning::
The group of PREPROCESSED_WERBIDL_FILES meant to list WebExtensions APIs ``.webidl`` files
may not exist yet (one will be added right after the existing `WEBIDL_FILES` when the first
preprocessed `.webidl` will be added).
Add new entries in ``toolkit/components/extensions/webidl-api/moz.build``
-------------------------------------------------------------------------
The new C++ files for the WebExtensions API binding needs to be added to ``toolkit/components/extensions/webidl-api/moz.build``
to make them part of the build, The new ``.cpp`` file has to be added into the ``UNIFIED_SOURCES`` group
where the other WebIDL bindings are being listed. Similarly, the new ``.h`` counterpart has to be added to
``EXPORTS.mozilla.extensions`` (which ensures that the header file will be placed into the path set earlier
in ``dom/bindings/Bindings.conf``):
.. code-block::
# WebExtensions API namespaces.
UNIFIED_SOURCES += [
...
"ExtensionRuntime.cpp",
...
]
EXPORTS.mozilla.extensions += [
...
"ExtensionRuntime.h",
...
]
Wiring up the new API into ``dom/webidl/ExtensionBrowser.webidl``
-----------------------------------------------------------------
To make the new WebIDL bindings part of the ``browser`` global, a new attribute has to be added to
``dom/webidl/ExtensionBrowser.webidl``:
.. code-block::
// `browser.runtime` API namespace.
[Replaceable, SameObject, BinaryName="GetExtensionRuntime",
Func="mozilla::extensions::ExtensionRuntime::IsAllowed"]
readonly attribute ExtensionRuntime runtime;
.. note::
``chrome`` is defined as an alias of the ``browser`` global, and so by adding the new attribute
into ``ExtensionBrowser` the same attribute will also be available in the ``chrome`` global.
Unlike the "Privileged JS"-based WebExtensions API, the ``chrome`` and ``browser`` APIs are
exactly the same and a the async methods return a Promise if no callback has been passed
(similarly to Safari versions where the WebExtensions APIs are supported).
The additional attribute added into ``ExtensionBrowser.webidl`` will require some addition to the ``ExtensionBrowser``
C++ class as defined in ``toolkit/components/extensions/webidl-api/ExtensionBrowser.h``:
- the definition of a new corresponding **public method** (by convention named ``GetExtensionMyNamespace``)
- a ``RefPtr`` as a new **private data member named** (by convention named ``mExtensionMyNamespace``)
.. code-block::
...
namespace extensions {
...
class ExtensionRuntime;
...
class ExtensionBrowser final : ... {
...
RefPtr<ExtensionRuntime> mExtensionRuntime;
...
public:
...
ExtensionRuntime* GetExtensionRuntime();
}
...
And then in its ``toolkit/components/extensions/webidl-api/ExtensionBrowser.cpp`` counterpart:
- the implementation of the new public method
- the addition of the new private member data ``RefPtr`` in the ``NS_IMPL_CYCLE_COLLECTION_UNLINK``
and ``NS_IMPL_CYCLE_COLLECTION_TRAVERSE`` macros
.. code-block::
...
#include "mozilla/extensions/ExtensionRuntime.h"
...
NS_IMPL_CYCLE_COLLECTION_UNLINK_BEGIN(ExtensionBrowser)
...
NS_IMPL_CYCLE_COLLECTION_UNLINK(mExtensionRuntime)
...
NS_IMPL_CYCLE_COLLECTION_UNLINK_END
NS_IMPL_CYCLE_COLLECTION_TRAVERSE_BEGIN(ExtensionBrowser)
...
NS_IMPL_CYCLE_COLLECTION_TRAVERSE(mExtensionRuntime)
...
NS_IMPL_CYCLE_COLLECTION_TRAVERSE_END
...
ExtensionRuntime* ExtensionBrowser::GetExtensionRuntime() {
if (!mExtensionRuntime) {
mExtensionRuntime = new ExtensionRuntime(mGlobal, this);
}
return mExtensionRuntime
}
.. warning::
Forgetting to add the new ``RefPtr`` into the cycle collection traverse and unlink macros
will not result in a build error, but it will result into a leak.
Make sure to don't forget to double-check these macros, especially if some tests are failing
because of detected shutdown leaks.
|
