This section will help you if you're fixing a broken build, or have what you think is a quick obvious question, and you don't have time to read the Reference Manual. This FAQ usually just refers back directly to the appropriate answer, there. If you're looking here just to learn about
nsCOMPtrs, you'll get a better introduction in the Getting Started Guide.
The FAQ is divided into sections to help you find what you're looking for faster. In most cases, the answer will just refer back into the reference manual, above. No need to explain things twice
The build just broke. It's not in your code, or it's not on your platform, but there's an
nsCOMPtr on the line where the error is and you're suspicious. You're looking in the right place.
nsCOMPtr to a raw XPCOM interface pointer
nsCOMPtr to a forward-declared class
not linking to XPCOM
not including nsCOMPtr.h
different settings of
NS_ASSERTION "QueryInterface needed"
May be caused by a class that derives from a given interface, when you forgetting to also specify the interface name in the
For example, the assertion occurs when you convert the pointer to the object to a raw pointer to that interface, then assign the raw pointer to another
nsCOMPtr for that interface.
NS_PRECONDITION "You can't dereference a NULL nsCOMPtr with operator->()"
NS_PRECONDITION "You can't dereference a NULL nsCOMPtr with operator*()"
printf("%x\n", mynsCOMPtr);can cause the program to crash on
SIGILL(illegal instruction), and not on the line with the
printf, which can make it tricky to figure out. For debugging purposes you can write
nsCOMPtr before it goes out of scope?
0 into it. Whenever an
nsCOMPtr takes on a new value, it always
Releases its old value, if any. Assigning in the value
0 is just like assigning in a raw pointer that happens to be
NULL. The old referent will be
Released. [See Initialization and Assignment for more details]
You should note, though, that there is a small performance penalty for this. The
nsCOMPtr will still exercize logic in its destructor to attempt to
Release the value it has at that time. The optimal solution is to arrange the lifetime of your
nsCOMPtr to correspond to exactly how long you want to hold the reference. E.g., using blocks as in this sample
Editors Note: Move this discussion to the efficiency section, and link to it from here.
nsCOMPtr leak (for a debug test)?
call a getter that uses a raw XPCOM interface pointer as an `in/out' parameter?
call a getter that fills in an
call a getter that doesn't
AddRef its result?
Any XPCOM function that returns an interface pointer, i.e., a `getter', must have already
AddRefed that pointer. If it didn't, you should probably report it as a bug. No matter which code pattern you use to solve this problem, you should comment it, e.g.,
// Warning: this getter doesn't AddRef() its result. If the getter returns the new pointer as its function result, no worries,
nsCOMPtr bloat the code?
nsCOMPtrs fast? Can I use them in tight loops?
- nsCOMPtr.h, and nsCOMPtr.cpp are the source to
nsCOMPtr. You can examine the source to
nsCOMPtronline using (the wonderful) LXR. Exploring this code is not an adventure for the faint of heart.
- Some COM Ownership Guidelines.
- Interface Pointers Considered Harmful by Don Box originally appeared in the September 1995 issue of "The C++ Report".
- COM Smart Pointers Even More Harmful by Don Box is a follow-up article that originally appeared in the February 1996 issue of "The C++ Report".
- Essential COM by Don Box.
- Effective COM by Don Box, et al.
- The C++ Programming Language (3rd Edition) by Bjarne Stroustrup.
- Effective C++ (2nd Edition): 50 Specific Ways to Improve Your Programs and Designs by Scott Meyers.
- More Effective C++ : 35 New Ways to Improve Your Programs and Designs by Scott Meyers.
- Effective C++ CD: 85 Specific Ways to Improve Your Programs and Designs by Scott Meyers.
- Don Box is a smart guy who has been writing about COM programming for a long time.