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
|
Reference Counting Helpers
==========================
RefPtr versus nsCOMPtr
----------------------
The general rule of thumb is to use ``nsCOMPtr<T>`` when ``T`` is an
interface type which inherits from ``nsISupports``, and ``RefPtr<T>`` when
``T`` is a concrete type.
This basic rule derives from some ``nsCOMPtr<T>`` code being factored into
the ``nsCOMPtr_base`` base class, which stores the pointer as a
``nsISupports*``. This design was intended to save some space in the binary
(though it is unclear if it still does). Since ``nsCOMPtr`` stores the
pointer as ``nsISupports*``, it must be possible to unambiguously cast from
``T*`` to ``nsISupports**``. Many concrete classes inherit from more than
one XPCOM interface, meaning that they cannot be used with ``nsCOMPtr``,
which leads to the suggestion to use ``RefPtr`` for these classes.
``nsCOMPtr<T>`` also requires that the target type ``T`` be a valid target
for ``QueryInterface`` so that it can assert that the stored pointer is a
canonical ``T`` pointer (i.e. that ``mRawPtr->QueryInterface(T_IID) ==
mRawPtr``).
do_XXX() nsCOMPtr helpers
-------------------------
There are a number of ``do_XXX`` helper methods across the codebase which can
be assigned into ``nsCOMPtr`` (and sometimes ``RefPtr``) to perform explicit
operations based on the target pointer type.
In general, when these operations succeed, they will initialize the smart
pointer with a valid value, and otherwise they will silently initialize the
smart pointer to ``nullptr``.
``do_QueryInterface`` and ``do_QueryObject``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Attempts to cast the provided object to the target class using the XPCOM
``QueryInterface`` mechanism. In general, use ``do_QueryInterface`` may only
be used to cast between interface types in a ``nsCOMPtr<T>``, and
``do_QueryObject`` in situations when downcasting to concrete types.
``do_GetInterface``
~~~~~~~~~~~~~~~~~~~
Looks up an object implementing the requested interface using the
``nsIInterfaceRequestor`` interface. If the target object doesn't implement
``nsIInterfaceRequestor`` or doesn't provide the given interface, initializes
the smart pointer with ``nullptr``.
``do_GetService``
~~~~~~~~~~~~~~~~~
Looks up the component defined by the passed-in CID or ContractID string in
the component manager, and returns a pointer to the service instance. This
may start the service if it hasn't been started already. The resulting
service will be cast to the target interface type using ``QueryInterface``.
``do_CreateInstance``
~~~~~~~~~~~~~~~~~~~~~
Looks up the component defined by the passed-in CID or ContractID string in
the component manager, creates and returns a new instance. The resulting
object will be cast to the target interface type using ``QueryInterface``.
``do_QueryReferent`` and ``do_GetWeakReference``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When passed a ``nsIWeakReference*`` (e.g. from a ``nsWeakPtr``),
``do_QueryReferent`` attempts to re-acquire a strong reference to the held
type, and cast it to the target type with ``QueryInterface``. Initializes the
smart pointer with ``nullptr`` if either of these steps fail.
In contrast ``do_GetWeakReference`` does the opposite, using
``QueryInterface`` to cast the type to ``nsISupportsWeakReference*``, and
acquire a ``nsIWeakReference*`` to the passed-in object.
|
