mozilla

Compare Revisions

Getting Started Guide

Change Revisions

Revision 311249:

Revision 311249 by gsvelto on

Revision 320723:

Revision 320723 by gsvelto on

Title:
Getting Started Guide
Getting Started Guide
Slug:
Using_nsCOMPtr/Getting_Started_Guide
Using_nsCOMPtr/Getting_Started_Guide
Tags:
"XPCOM"
"XPCOM"
Content:

Revision 311249
Revision 320723
n8      If you have never used <code>nsCOMPtr</code>s before, this n8      If you have never used <code>nsCOMPtr</code>s before, this 
>section is for you. If you're already familiar with <code>nsCOMPt>section is for you. If you're already familiar with <code>nsCOMPt
>r</code>s, then you might want to skip ahead to the <a href="/en/>r</code>s, then you might want to skip ahead to the <a href="/en-
>docs/Using_nsCOMPtr/Reference_Manual">Reference Manual</a> or the>US/docs/Using_nsCOMPtr/Reference_Manual">Reference Manual</a> or 
> <a href="/en/docs/Using_nsCOMPtr/Frequently_Asked_Questions">FAQ>the <a href="/en-US/docs/Using_nsCOMPtr/Frequently_Asked_Question
></a>. Don't worry; the Getting Started Guide is short.>s">FAQ</a>. Don't worry; the Getting Started Guide is short.
n50      A reference through which you will call <code>AddRef</code>n50      A reference through which you will call <code>AddRef</code>
> and <code>Release</code> is called an <strong>owning reference</> and <code>Release</code> is called an <strong>owning reference</
>strong>. It holds a stake in the underlying object. That object c>strong>. It holds a stake in the underlying object. That object c
>annot go away until the owning reference has relinquished its cla>annot go away until the owning reference has relinquished its cla
>im. Not all references need to be owning references. In fact, if >im. Not all references need to be owning references. In fact, if 
>two objects somehow end up owning each other (even transitively) >two objects somehow end up owning each other (even transitively) 
>it becomes difficult for either of those object to be reclaimed w>it becomes difficult for either of those object to be reclaimed w
>ithout adding some `out-of-band' mechanism for breaking the owner>ithout adding some `out-of-band' mechanism for breaking the owner
>ship cycle. The document <a href="/en/docs/XPCOM_ownership_guidel>ship cycle. The document <a href="/en-US/docs/XPCOM_ownership_gui
>ines">Some COM Ownership Guidelines</a> provides some hints on wh>delines">Some COM Ownership Guidelines</a> provides some hints on
>en ownership is needed. The following lists are good starting poi> when ownership is needed. The following lists are good starting 
>nt, but by no means complete.>point, but by no means complete.
n252      Second: you can't just pass the address of an <code>nsCOMPtn252      Second: you can't just pass the address of an <code>nsCOMPt
>r</code> to a getter expecting to return a result through a raw X>r</code> to a getter expecting to return a result through a raw X
>PCOM interface pointer parameter. You have to `annotate' the <cod>PCOM interface pointer parameter. You have to `annotate' the <cod
>e>nsCOMPtr</code> with the <a href="/en/docs/Using_nsCOMPtr/Refer>e>nsCOMPtr</code> with the <a href="/en-US/docs/Using_nsCOMPtr/Re
>ence_Manual#.60Out.27_Parameters:_getter_AddRefs"><code>getter_Ad>ference_Manual#.60Out.27_Parameters:_getter_AddRefs"><code>getter
>dRefs</code></a> directive.>_AddRefs</code></a> directive.
n316      <code>QueryInterface</code> is used so frequently, though, n316      <code>QueryInterface</code> is used so frequently, though, 
>that <code>nsCOMPtr</code> has a special facility to call it. Thi>that <code>nsCOMPtr</code> has a special facility to call it. Thi
>s facility is type-safe, and it enables an <code>nsCOMPtr</code> >s facility is type-safe, and it enables an <code>nsCOMPtr</code> 
>to be directly constructed from the result of <code>QueryInterfac>to be directly constructed from the result of <code>QueryInterfac
>e</code>. Construction from the correct value is more efficient t>e</code>. Construction from the correct value is more efficient t
>hat construction followed by assignment. This facility is the <a >hat construction followed by assignment. This facility is the <a 
>href="/en/docs/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3>href="/en-US/docs/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E
>D_do_QueryInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_d>_.3D_do_QueryInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3
>o_QueryInterface.28_nsISupports.2A.2C_nsresult.2A_.29"><code>do_Q>D_do_QueryInterface.28_nsISupports.2A.2C_nsresult.2A_.29"><code>d
>ueryInterface</code></a> directive. Using <code>do_QueryInterface>o_QueryInterface</code></a> directive. Using <code>do_QueryInterf
></code>, the sample above would look like this>ace</code>, the sample above would look like this
n339      <code>nsCOMPtr</code> happily calls <code>AddRef</code> andn339      <code>nsCOMPtr</code> happily calls <code>AddRef</code> and
> <code>Release</code> implicitly. This same favor is <em>not</em>> <code>Release</code> implicitly. This same favor is <em>not</em>
> extended to <code>QueryInterface</code>. <code>nsCOMPtr</code> d> extended to <code>QueryInterface</code>. <code>nsCOMPtr</code> d
>oes not <code>QueryInterface</code> on assignment without your ex>oes not <code>QueryInterface</code> on assignment without your ex
>plicit permission in the form of the <code>do_QueryInterface</cod>plicit permission in the form of the <code>do_QueryInterface</cod
>e> directive. You need never worry about hidden queries. However,>e> directive. You need never worry about hidden queries. However,
> be aware that if you <em>should</em> have queried but didn't, e.> be aware that if you <em>should</em> have queried but didn't, e.
>g., when assigning in a raw pointer where C++ allows the assignme>g., when assigning in a raw pointer where C++ allows the assignme
>nt, but XPCOM wouldn't, <code>nsCOMPtr</code> will <a href="/en/d>nt, but XPCOM wouldn't, <code>nsCOMPtr</code> will <a href="/en-U
>ocs/Using_nsCOMPtr/Reference_Manual#Type_Safeguards">assert at ru>S/docs/Using_nsCOMPtr/Reference_Manual#Type_Safeguards">assert at
>ntime</a>. Use <code>do_QueryInterface</code> whenever you assign> runtime</a>. Use <code>do_QueryInterface</code> whenever you ass
> in a pointer to a XPCOM interface of a different type, even if t>ign in a pointer to a XPCOM interface of a different type, even i
>hat type happens to derive from the base type of the <code>nsCOMP>f that type happens to derive from the base type of the <code>nsC
>tr</code>>OMPtr</code>
n386      <a href="/en/docs/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.n386      <a href="/en-US/docs/Using_nsCOMPtr/Reference_Manual#nsCOMP
>3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_getter_A>tr.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_gette
>ddRefs.28_T.2A_.29"><code>dont_AddRef</code></a> is a similar dir>r_AddRefs.28_T.2A_.29"><code>dont_AddRef</code></a> is a similar 
>ective that helps you when you assign in a pointer that has alrea>directive that helps you when you assign in a pointer that has al
>dy been <code>AddRef</code>ed, e.g., because you called a getter >ready been <code>AddRef</code>ed, e.g., because you called a gett
>that returned the pointer as its function result.>er that returned the pointer as its function result.
n482      Don't use <code>nsCOMPtr</code>s where you don't need an own482      Don't use <code>nsCOMPtr</code>s where you don't need an ow
>ning reference. See <a href="/en/docs/XPCOM_ownership_guidelines">ning reference. See <a href="/en-US/docs/XPCOM_ownership_guidelin
>>Some COM Ownership Guidelines</a>. <code>nsCOMPtr</code> is desi>es">Some COM Ownership Guidelines</a>. <code>nsCOMPtr</code> is d
>gned to be used with XPCOM interfaces, so don't use it with non-i>esigned to be used with XPCOM interfaces, so don't use it with no
>nterfaces with specific exceptions described <a href="/en/docs/Us>n-interfaces with specific exceptions described <a href="/en-US/d
>ing_nsCOMPtr/Getting_Started_Guide#nsCOMPtrs_for_non-interface_cl>ocs/Using_nsCOMPtr/Getting_Started_Guide#nsCOMPtrs_for_non-interf
>asses">below</a>. Don't use <code>nsCOMPtr</code>s in XPCOM inter>ace_classes">below</a>. Don't use <code>nsCOMPtr</code>s in XPCOM
>faces. Don't use them in plain old C code; <code>nsCOMPtr</code>s> interfaces. Don't use them in plain old C code; <code>nsCOMPtr</
> are, of course, a C++ only construct. <a href="/en/docs/Using_ns>code>s are, of course, a C++ only construct. <a href="/en-US/docs
>COMPtr/Reference_Manual#Casting">Never cast</a> an <code>nsCOMPtr>/Using_nsCOMPtr/Reference_Manual#Casting">Never cast</a> an <code
></code>, it's almost guaranteed to leak.>>nsCOMPtr</code>, it's almost guaranteed to leak.
n580      This practice requires callers to have an <code>nsCOMPtr</cn580      This practice requires callers to have an <code>nsCOMPtr</c
>ode>, and requires them to do a little extra work, as <code>opera>ode>, and requires them to do a little extra work, as <code>opera
>tor&amp;</code> for <code>nsCOMPtr</code>s is <code>private</code>tor&amp;</code> for <code>nsCOMPtr</code>s is <code>private</code
>> (to help prevent <a href="/en/docs/Using_nsCOMPtr/Reference_Man>> (to help prevent <a href="/en-US/docs/Using_nsCOMPtr/Reference_
>ual#Casting">leaks caused by casting</a>; also see {{ Bug(59414) >Manual#Casting">leaks caused by casting</a>; also see {{ Bug(5941
>}}). This is an acceptable way to declare `in/out' parameters, bu>4) }}). This is an acceptable way to declare `in/out' parameters,
>t prefer passing <code>nsCOMPtr</code>s by reference, as below.> but prefer passing <code>nsCOMPtr</code>s by reference, as below
 >.
n612      You use an <code>nsCOMPtr</code> exactly as you would a rawn612      You use an <code>nsCOMPtr</code> exactly as you would a raw
> XPCOM interface pointer in almost all cases. You won't have to e> XPCOM interface pointer in almost all cases. You won't have to e
>xplictly call <code>AddRef</code> or <code>Release</code> through>xplictly call <code>AddRef</code> or <code>Release</code> through
> it, nor will the compiler allow it. The only place you can't use> it, nor will the compiler allow it. The only place you can't use
> an <code>nsCOMPtr</code> without change is where a raw XPCOM int> an <code>nsCOMPtr</code> without change is where a raw XPCOM int
>erface pointer is an `out' parameter. In this case, you wrap the >erface pointer is an `out' parameter. In this case, you wrap the 
><code>nsCOMPtr</code> with <a href="/en/docs/Using_nsCOMPtr/Refer><code>nsCOMPtr</code> with <a href="/en-US/docs/Using_nsCOMPtr/Re
>ence_Manual#.60Out.27_Parameters:_getter_AddRefs"><code>getter_Ad>ference_Manual#.60Out.27_Parameters:_getter_AddRefs"><code>getter
>dRefs</code></a> (see {{ web.link("#Comparison_4", "Comparison 4">_AddRefs</code></a> (see {{ web.link("#Comparison_4", "Comparison
>) }}).> 4") }}).
t618      You can tell <code>nsCOMPtr</code> it doesn't need to <codet618      You can tell <code>nsCOMPtr</code> it doesn't need to <code
>>AddRef</code> the new value on assignment by wrapping the new va>>AddRef</code> the new value on assignment by wrapping the new va
>lue in <a href="/en/docs/Using_nsCOMPtr/Reference_Manual#nsCOMPtr>lue in <a href="/en-US/docs/Using_nsCOMPtr/Reference_Manual#nsCOM
>.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_getter_>Ptr.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_gett
>AddRefs.28_T.2A_.29"><code>dont_AddRef</code></a>. Do this, for e>er_AddRefs.28_T.2A_.29"><code>dont_AddRef</code></a>. Do this, fo
>xample, when you got the new value from a function which, like al>r example, when you got the new value from a function which, like
>l good XPCOM getters, already called <code>AddRef</code> on your > all good XPCOM getters, already called <code>AddRef</code> on yo
>behalf.>ur behalf.
619    </p>
620    <p>619    </p>
620    <p>
621      You may not assign in a pointer to a different interface ty621      You may not assign in a pointer to a different interface ty
>pe; you must first query it to the right type (see, e.g., {{ web.>pe; you must first query it to the right type (see, e.g., {{ web.
>link("#Comparison_6", "Comparison 6") }} and the surrounding disc>link("#Comparison_6", "Comparison 6") }} and the surrounding disc
>ussion). <code>nsCOMPtr</code> <em>never</em> calls <code>QueryIn>ussion). <code>nsCOMPtr</code> <em>never</em> calls <code>QueryIn
>terface</code> implicitly, i.e., you must call it yourself, or ex>terface</code> implicitly, i.e., you must call it yourself, or ex
>plictly ask <code>nsCOMPtr</code> to call it with <a href="/en/do>plictly ask <code>nsCOMPtr</code> to call it with <a href="/en-US
>cs/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_do_QueryIn>/docs/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_do_Quer
>terface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_do_QueryInter>yInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_do_QueryIn
>face.28_nsISupports.2A.2C_nsresult.2A_.29"><code>do_QueryInterfac>terface.28_nsISupports.2A.2C_nsresult.2A_.29"><code>do_QueryInter
>e</code></a>. The <code>do_QueryInterface</code> directive allows>face</code></a>. The <code>do_QueryInterface</code> directive all
> you to do the query as part of the assignment. This better facil>ows you to do the query as part of the assignment. This better fa
>itates constructing an <code>nsCOMPtr</code> directly from the ri>cilitates constructing an <code>nsCOMPtr</code> directly from the
>ght value, rather than constructing it and assigning in the corre> right value, rather than constructing it and assigning in the co
>ct value later. Construction alone is more efficient than constru>rrect value later. Construction alone is more efficient than cons
>ction followed by assignment. Prefer construction over assignment>truction followed by assignment. Prefer construction over assignm
> whereever reasonable. Be careful not to apply <code>do_QueryInte>ent whereever reasonable. Be careful not to apply <code>do_QueryI
>rface</code> to a function returning an <code>AddRef</code>ed poi>nterface</code> to a function returning an <code>AddRef</code>ed 
>nter (see <a href="/en/docs/Using_nsCOMPtr/Reference_Manual#nsCOM>pointer (see <a href="/en-US/docs/Using_nsCOMPtr/Reference_Manual
>Ptr.3CT.3E_.3D_.2F.2A_call_QueryInterface_but_don.27t_AddRef_.2A.>#nsCOMPtr.3CT.3E_.3D_.2F.2A_call_QueryInterface_but_don.27t_AddRe
>2F">this short section</a> for an explanation)>f_.2A.2F">this short section</a> for an explanation)
622    </p>
623    <p>622    </p>
624      For more details, continue on to the <a href="/en/docs/Usin
>g_nsCOMPtr/Reference_Manual">Reference Manual</a>. 
625    </p>623    <p>
626    <p>624      For more details, continue on to the <a a="" href="/en-US/d
 >ocs/Using_nsCOMPtr/Reference_Manual" reference="">{{ languages( {
 > "ja": "ja/Using_nsCOMPtr/Getting_Started_Guide" } ) }}</a>
627      {{ languages( { "ja": "ja/Using_nsCOMPtr/Getting_Started_Gu
>ide" } ) }} 

Back to History