|
|
|
|
@ -1,5 +1,24 @@
|
|
|
|
|
MOSTLY OUT-OF-DATE (Feb. 2021)
|
|
|
|
|
|
|
|
|
|
## The `window` object
|
|
|
|
|
# Guide to the code
|
|
|
|
|
|
|
|
|
|
The control flow starts from `chrome/bootstrap.js` where we specify
|
|
|
|
|
window scripts like `pepmessengercompose.js` and
|
|
|
|
|
`pepmsghdrview.js`. These scripts are executed when Thunderbird opens
|
|
|
|
|
a window with the matching type.
|
|
|
|
|
|
|
|
|
|
These "window scripts" are in in `chrome/content` like most of the
|
|
|
|
|
code. When executed they import other modules with
|
|
|
|
|
`ChromeUtils.import`, passing the window and other global objects if
|
|
|
|
|
needed. Outside of this context we cannot assume that `window` is
|
|
|
|
|
accessible.
|
|
|
|
|
|
|
|
|
|
The three-pane window is always running when Thunderbird is running,
|
|
|
|
|
so its `pepmsghdrview.js` script performs most of the application
|
|
|
|
|
initialisation. One of the main objects to be initialised is the
|
|
|
|
|
controller within `chrome/content/p4tb.js`.
|
|
|
|
|
|
|
|
|
|
# The `window` object
|
|
|
|
|
|
|
|
|
|
In `bootstrap.js` we subscribe to notifications from a `ww` service
|
|
|
|
|
that calls a `paint` method when the `window` object is globally
|
|
|
|
|
@ -10,14 +29,99 @@ it. Outside of this context we cannot assume that `window` is
|
|
|
|
|
accessible. An `unpaint` notification will be sent when the window is
|
|
|
|
|
closed.
|
|
|
|
|
|
|
|
|
|
## pEpController and `p4tb.js`
|
|
|
|
|
|
|
|
|
|
The `pEpController` is a module defined in
|
|
|
|
|
`chrome/content/modules/pEp.js` and is meant to be independent from
|
|
|
|
|
Thunderbird. Within `p4tb.js`, the controller gets augmented with
|
|
|
|
|
Thunderbird-specific logic.
|
|
|
|
|
|
|
|
|
|
`p4tb.js` also contains most of the initialisation logic. There the
|
|
|
|
|
server gets a `detectJsonAdapter` which populates the
|
|
|
|
|
`server.connectionInfo` on initialisation.
|
|
|
|
|
|
|
|
|
|
Note that this initialisation sequence is confined to the window where
|
|
|
|
|
the script has run, so it's executed again for every message
|
|
|
|
|
composition window when the matching `pepmessengercompose.js` script
|
|
|
|
|
is executed.
|
|
|
|
|
|
|
|
|
|
## Types of modules
|
|
|
|
|
|
|
|
|
|
Above we mentioned the `pEpController` module. Here we have mainly two
|
|
|
|
|
types of modules:
|
|
|
|
|
|
|
|
|
|
- `ChromeUtils` modules
|
|
|
|
|
- `ChromeUtils` & Node modules
|
|
|
|
|
|
|
|
|
|
Most files in `chrome/content` define a module of the first type. The
|
|
|
|
|
files in `chrome/content/modules` are `ChromeUtils` _and_ Node
|
|
|
|
|
modules, so they can be tested with our unit tests.
|
|
|
|
|
|
|
|
|
|
Our Node modules cannot import other Node modules because then they
|
|
|
|
|
wouldn't work as `ChromeUtils` modules. These modules can be imported
|
|
|
|
|
once and that's it. They can be combined with each other using
|
|
|
|
|
dependency injection.
|
|
|
|
|
|
|
|
|
|
## Encryption & Decryption
|
|
|
|
|
|
|
|
|
|
Encryption and decryption are performed via components and factories
|
|
|
|
|
defined in `pEpMimeEncrypt.js` and `pEpMimeDecrypt.js` (branch
|
|
|
|
|
`P4TB-43-2` to be merged).
|
|
|
|
|
|
|
|
|
|
We define component objects and wrap them with factories that get
|
|
|
|
|
registered on startup and deregistered on teardown. You might want to
|
|
|
|
|
deregister factories for testing purposes, since only one factory can
|
|
|
|
|
be registered for every component id.
|
|
|
|
|
|
|
|
|
|
Component objects are created in isolation when some events happen,
|
|
|
|
|
for example the encryption component is created when there is an
|
|
|
|
|
outgoing message. Since they have this ad-hoc, isolated lifecycle,
|
|
|
|
|
communication between our components and our views is not
|
|
|
|
|
straightforward.
|
|
|
|
|
|
|
|
|
|
# Other notes
|
|
|
|
|
|
|
|
|
|
## Environment setup
|
|
|
|
|
|
|
|
|
|
We suggest to use [different
|
|
|
|
|
profiles](https://support.mozilla.org/en-US/kb/using-multiple-profiles),
|
|
|
|
|
one for your regular mail use and one for extension development.
|
|
|
|
|
|
|
|
|
|
Testing can be done using one of the [test accounts (need VPN
|
|
|
|
|
access)](intern.pep.security/service/QA/testaccounts).
|
|
|
|
|
|
|
|
|
|
## Relevant entry points to the engine code
|
|
|
|
|
|
|
|
|
|
Most of the extension code is written under the assumption that the
|
|
|
|
|
extension developer can read the engine code as a form of
|
|
|
|
|
documentation and keep the extension synchronised with the engine's
|
|
|
|
|
(and adapter's) interfaces.
|
|
|
|
|
|
|
|
|
|
Many interfaces are defined in the following engine's files:
|
|
|
|
|
|
|
|
|
|
- `pEpEngine.h`
|
|
|
|
|
- `message_api.h`
|
|
|
|
|
- `message.h`
|
|
|
|
|
- `pEp_internal.h`
|
|
|
|
|
|
|
|
|
|
After that, grep is your friend/enemy (`darthmama`'s quote)
|
|
|
|
|
|
|
|
|
|
## Adapter
|
|
|
|
|
|
|
|
|
|
The extension connects to the JSON adapter server using a token which
|
|
|
|
|
is found in `~/.pEp/json-token`. The whole purpose of the token is to
|
|
|
|
|
be sure that the client runs with the same user rights than the server
|
|
|
|
|
(`Roker`'s quote).
|
|
|
|
|
|
|
|
|
|
## Updating the options
|
|
|
|
|
|
|
|
|
|
When we want to change the plugin preferences we can do so by
|
|
|
|
|
modifying three areas in the code:
|
|
|
|
|
modifying different areas in the code:
|
|
|
|
|
|
|
|
|
|
- `options.xul` the markup, here you define the identifier for the option that will be used also elsewhere
|
|
|
|
|
- `prefsFactory.js` update getter and setter functions corresponding to the option and the default value
|
|
|
|
|
- `options.js` update `addAll`, the window load handler, the dialogAccept handler
|
|
|
|
|
- `bootstrap.js` update the defaults
|
|
|
|
|
|
|
|
|
|
## Compat and Prefs
|
|
|
|
|
|
|
|
|
|
|
