home / products / comet / documentation
Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

comet::com_ptr< Itf > Class Template Reference
[Com type wrappers.]

Interface smart pointer. More...

#include <ptr.h>

Inheritance diagram for comet::com_ptr< Itf >:

Inheritance graph
[legend]
List of all members.

Public Types

typedef Itf * interface_pointer
 Type of pointer to wrapped interface.
typedef wrap_t< Itf > * safe_interface_pointer
 Safe interface pointer.

Public Member Functions

 com_ptr () throw ()
 Default constructor.
 ~com_ptr () throw ()
 Destructor.
template<typename Itf2>  com_ptr (const com_ptr< Itf2 > &x) throw ()
 Upcasting constructor.
template<typename Itf2>  com_ptr (const impl::com_cast_t< Itf2 > &x) throw ()
 QueryInterface construction.
template<typename Itf2>  com_ptr (const impl::try_cast_t< Itf2 > &x) throw (com_error)
 QueryInterface construction.
 com_ptr (const com_ptr &x) throw ()
 Copy constructor.
 com_ptr (const identity_ptr &x) throw ()
 Copy from identity_unknown class.
 com_ptr (const impl::com_cast_t< variant_t > &v) throw ()
 Construction from variant_t.
 com_ptr (const impl::try_cast_t< variant_t > &v) throw (com_error)
 Construction from variant_t.
 com_ptr (interface_pointer p) throw ()
 Construction from a raw interface pointer.
 com_ptr (const impl::auto_attach_t< interface_pointer > &p) throw ()
 Attach construction of raw interface pointer.
 com_ptr (const uuid_t &clsid, DWORD dwClsContext=CLSCTX_ALL) throw (com_error)
 Construction from CLSID.
 com_ptr (const uuid_t &clsid, const com_ptr<::IUnknown > &outer, DWORD dwClsContext=CLSCTX_ALL) throw (com_error)
 Construction of aggregated object from CLSID.
 com_ptr (int null) throw (com_error)
 Constructions of null pointer.
 com_ptr (const wchar_t *progid, DWORD dwClsContext=CLSCTX_ALL) throw (com_error)
 Construction from ProgID.
 com_ptr (const wchar_t *progid, const com_ptr<::IUnknown > &outer, DWORD dwClsContext=CLSCTX_ALL) throw (com_error)
 Construction from ProgID.
 com_ptr (const wchar_t *name, BIND_OPTS &bind_opts)
 Construction using CoGetObject.
safe_interface_pointer operator-> () const throw (com_error)
 Arrow operator.
com_ptr & operator= (interface_pointer x) throw ()
 Assignment of raw interface pointer.
template<typename Itfx> com_ptr & operator= (const impl::com_cast_t< Itfx > &x) throw ()
 QueryInterface assignment.
template<typename Itf2> com_ptr & operator= (const impl::try_cast_t< Itf2 > &x) throw (com_error)
 QueryInterface assignment.
template<typename Itf2> com_ptr & operator= (const com_ptr< Itf2 > &x) throw ()
com_ptr & operator= (const com_ptr &x) throw ()
 Default assigment operator.
com_ptr & operator= (int null) throw (com_error)
 Null assignment.
com_ptr & operator= (const impl::auto_attach_t< interface_pointer > &p) throw ()
 Attaching assignment.
bool is_null () const throw ()
 Returns true if the wrapped pointer is null.
bool operator! () const throw ()
 Returns true if the wrapped pointer is null.
bool operator== (int null) const
 Null comparison.
bool operator!= (int null) const
 Null comparison.
template<typename Itf2> bool same_pointer (const com_ptr< Itf2 > &x) const throw (com_error)
 Pointer comparison.
void swap (com_ptr &x) throw ()
 Swap operation.
interface_pointer detach () throw ()
 Detaches ownership.
 operator bool_tester * () const throw ()
Pointer Comparison
!

template<typename T> bool operator< (const T &x) const throw (com_error)
template<typename T> bool operator> (const T &x) const throw (com_error)
template<typename T> bool operator<= (const T &x) const throw (com_error)
template<typename T> bool operator>= (const T &x) const throw (com_error)
template<typename Itf2> bool operator== (const com_ptr< Itf2 > &x) const throw (com_error)
template<typename Itf2> bool operator!= (const com_ptr< Itf2 > &x) const throw (com_error)
Adapter methods.
interface_pointer in () const throw ()
 [in] adapter
interface_pointer raw () const throw ()
interface_pointer get () const throw ()
interface_pointer * out () throw ()
 [out] adapter.
interface_pointer * inout () throw ()
 [in, out] adapter.

Static Public Member Functions

interface_pointer detach (com_ptr &x) throw ()
 Detaches ownership.
const com_ptr & create_const_reference (const interface_pointer &x)
com_ptr & create_reference (interface_pointer &x)

Related Functions

(Note that these are not member functions.)

impl::com_cast_t< Itf > com_cast (const com_ptr< Itf > &t)
 Cast com_ptr.
bool operator== (int null, const com_ptr< Itf2 > &x) throw(com_error)
 Comparison with null.
bool operator!= (int null, const com_ptr< Itf > &x) throw(com_error)
 Comparison with null.
bool operator!= (int null, const identity_ptr &x) throw(com_error)
 Comparison with null.
com_ptr< Itf > try_cast_ptr (const impl::try_caster_t< Itf > &caster)

Detailed Description

template<typename Itf>
class comet::com_ptr< Itf >

Interface smart pointer.

Note:
All members are exception safe.
See also:
cometcomptr

Member Typedef Documentation

template<typename Itf>
typedef wrap_t<Itf>* comet::com_ptr< Itf >::safe_interface_pointer
 

Safe interface pointer.

Interface pointer where the methods from IUnknown have been hidden.

Constructor & Destructor Documentation

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (   )  throw () [inline]
 

Default constructor.

Initialises the wrapped pointer to null.

template<typename Itf>
comet::com_ptr< Itf >::~com_ptr (   )  throw () [inline]
 

Destructor.

Calls Release() on pointer if necessary.

template<typename Itf>
template<typename Itf2>
comet::com_ptr< Itf >::com_ptr (  const com_ptr< Itf2 > &  x  )  throw () [inline]
 

Upcasting constructor.

Used for upcasting interface pointer without invocation of QueryInterface.

This contructor only allows com_ptr upcasts.

Parameters:
x com_ptr to cast.

template<typename Itf>
template<typename Itf2>
comet::com_ptr< Itf >::com_ptr (  const impl::com_cast_t< Itf2 > &  x  )  throw () [inline]
 

QueryInterface construction.

Uses QueryInterface to query for interface of type Itf. If the pointer is incompatible, the pointer will be initialised to null.

                        com_ptr<IFoo> foo;
                        com_ptr<IBar> bar( com_cast(foo) );

Parameters:
x com_ptr to cast

template<typename Itf>
template<typename Itf2>
comet::com_ptr< Itf >::com_ptr (  const impl::try_cast_t< Itf2 > &  x  )  throw (com_error) [inline]
 

QueryInterface construction.

Uses QueryInterface to query for interface of type Itf. Should the pointer be incompatible, com_error will be thrown.

                        com_ptr<IFoo> foo = Foo::create();
                        com_ptr<IBar> bar( try_cast(foo) );

Parameters:
x com_ptr to cast
Exceptions:
com_error Throws E_NOINTERFACE if cast fails. Throws E_POINTER if pointer is zero.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const com_ptr< Itf > &  x  )  throw () [inline]
 

Copy constructor.

Parameters:
x com_ptr to copy.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const identity_ptr &  x  )  throw () [inline]
 

Copy from identity_unknown class.

Itf must be IUnknown for this to work. Otherwise use try_cast or com_cast.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const impl::com_cast_t< variant_t > &  v  )  throw () [inline]
 

Construction from variant_t.

This constructor does not throw. The wrapped pointer is initialised to null if the variant is incompatible.

Parameters:
v Wrapped com_variant to construct com_ptr from

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const impl::try_cast_t< variant_t > &  v  )  throw (com_error) [inline]
 

Construction from variant_t.

Throws com_error should the variant be incompatible.

Parameters:
v Wrapped com_variant to construct com_ptr from
Exceptions:
com_error Throws E_NOINTERFACE if cast fails.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  interface_pointer  p  )  throw () [inline]
 

Construction from a raw interface pointer.

Calls AddRef, and thus does not take ownership of the pointer.

Parameters:
p Interface pointer to construct com_ptr from.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const impl::auto_attach_t< interface_pointer > &  p  )  throw () [inline]
 

Attach construction of raw interface pointer.

An attachment construction does not AddRef on the interface, and is said to take ownership of the interface pointer.

Parameters:
p auto_attach wrapped pointer to construct com_ptr from.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const uuid_t &  clsid,
DWORD  dwClsContext = CLSCTX_ALL
)  throw (com_error) [inline, explicit]
 

Construction from CLSID.

Parameters:
clsid Class ID of coclass.
dwClsContext Class context to create object in.
Exceptions:
com_error 

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const uuid_t &  clsid,
const com_ptr<::IUnknown > &  outer,
DWORD  dwClsContext = CLSCTX_ALL
)  throw (com_error) [inline]
 

Construction of aggregated object from CLSID.

Parameters:
clsid Class ID of coclass.
outer Pointer to outer object.
dwClsContext Class context to create object in.
Exceptions:
com_error 

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  int  null  )  throw (com_error) [inline, explicit]
 

Constructions of null pointer.

Parameters:
null Only 0 is valid. Any other value will cause E_POINTER to be thrown.
Exceptions:
com_error Throws E_POINTER if a non-zero value is specified.

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const wchar_t *  progid,
DWORD  dwClsContext = CLSCTX_ALL
)  throw (com_error) [inline, explicit]
 

Construction from ProgID.

Parameters:
progid ProgID of class.
dwClsContext Class context to create object in.
Exceptions:
com_error 

template<typename Itf>
comet::com_ptr< Itf >::com_ptr (  const wchar_t *  progid,
const com_ptr<::IUnknown > &  outer,
DWORD  dwClsContext = CLSCTX_ALL
)  throw (com_error) [inline]
 

Construction from ProgID.

Parameters:
progid ProgID of class.
outer Pointer to outer object.
dwClsContext Class context to create object in.
Exceptions:
com_error 

Member Function Documentation

template<typename Itf>
const com_ptr& comet::com_ptr< Itf >::create_const_reference (  const interface_pointer &  x  )  [inline, static]
 

! Create a const reference to a pointer without invoking reference-counting. Since neither constructor or destructor get called.

template<typename Itf>
com_ptr& comet::com_ptr< Itf >::create_reference (  interface_pointer &  x  )  [inline, static]
 

! Create a reference to a pointer without invoking reference-counting. Since neither constructor or destructor get called.

template<typename Itf>
interface_pointer comet::com_ptr< Itf >::detach (  com_ptr< Itf > &  x  )  throw () [inline, static]
 

Detaches ownership.

template<typename Itf>
interface_pointer comet::com_ptr< Itf >::detach (   )  throw () [inline]
 

Detaches ownership.

Detaches the pointer from the wrapper and returns it as raw pointer.

This method is primarily for use by the interface wrapper code. You should very seldomly find use for it.

template<typename Itf>
interface_pointer comet::com_ptr< Itf >::in (   )  const throw () [inline]
 

[in] adapter

Used when calling raw interfaces that require an [in] IXXX * argument.

                                com_ptr<IFoo> foo;
                                HRESULT hr = pRawInterface->raw_Method(foo.in());

Only use this wrapper when forced to deal with raw interface.

template<typename Itf>
interface_pointer* comet::com_ptr< Itf >::inout (   )  throw () [inline]
 

[in, out] adapter.

Used when calling raw interfaces that require an [in, out] IXXX ** argument.

                                com_ptr<IFoo> foo;
                                HRESULT hr = pRawInterface->raw_MethodThatChangesPtr(foo.inout());

Only use this wrapper when forced to deal with raw interface.

template<typename Itf>
bool comet::com_ptr< Itf >::operator!= (  int  null  )  const [inline]
 

Null comparison.

Only comparison with a value of zero is allowed. Non-zero values will result in E_POINTER (wrapped in com_error) being thrown.

Exceptions:
com_error 

template<typename Itf>
safe_interface_pointer comet::com_ptr< Itf >::operator-> (   )  const throw (com_error) [inline]
 

Arrow operator.

Used to access methods and properties of the wrapped interface.

Note:
The methods of IUnknown are deliberately hidden.

template<typename Itf>
com_ptr& comet::com_ptr< Itf >::operator= (  const impl::auto_attach_t< interface_pointer > &  p  )  throw () [inline]
 

Attaching assignment.

Attaches a raw interface pointer to the com_ptr.

                                com_ptr<IFoo> foo;
                                foo = auto_attach( raw_foo_pointer );

template<typename Itf>
com_ptr& comet::com_ptr< Itf >::operator= (  int  null  )  throw (com_error) [inline]
 

Null assignment.

Only null is allowed as argument. Attempting to assign a non-zero value will result in E_POINTER (wrapped in com_error) being thrown.

Exceptions:
com_error Throw E_POINTER if a non-zero value is specified.

template<typename Itf>
template<typename Itf2>
com_ptr& comet::com_ptr< Itf >::operator= (  const impl::try_cast_t< Itf2 > &  x  )  throw (com_error) [inline]
 

QueryInterface assignment.

In order to cast unrelated interfaces you must use either com_cast or try_cast.

A try_cast that fails will throw E_NOINTERFACE wrapped in com_error.

                                com_ptr<IFoo> foo;
                                com_ptr<IBar> bar;
                                try {
                                        bar = try_cast(foo);
                                        bar->DoTheThing();
                                } catch (com_error&) {
                                        // Cast didn't work.
                                }

Exceptions:
com_error Throws E_NOINTERFACE if cast fails.

template<typename Itf>
template<typename Itfx>
com_ptr& comet::com_ptr< Itf >::operator= (  const impl::com_cast_t< Itfx > &  x  )  throw () [inline]
 

QueryInterface assignment.

In order to cast unrelated interfaces you must use either com_cast or try_cast.

A com_cast that fails results in a null pointer assignment.

                                com_ptr<IFoo> foo;
                                com_ptr<IBar> bar;
                                bar = com_cast(foo);
                                if (!bar.is_null()) {
                                        // Cast is ok.
                                        bar->DoTheThing();
                                }

template<typename Itf>
bool comet::com_ptr< Itf >::operator== (  int  null  )  const [inline]
 

Null comparison.

Only comparison with a value of zero is allowed. Non-zero values will result in E_POINTER (wrapped in com_error) being thrown.

Exceptions:
com_error 

template<typename Itf>
template<typename Itf2>
bool comet::com_ptr< Itf >::operator== (  const com_ptr< Itf2 > &  x  )  const throw (com_error) [inline]
 

Object equality.

template<typename Itf>
interface_pointer* comet::com_ptr< Itf >::out (   )  throw () [inline]
 

[out] adapter.

Used when calling raw interfaces that require an [out] IXXX ** argument.

                                com_ptr<IFoo> foo;
                                HRESULT hr = pRawInterface->raw_MethodThatReturnsPtr(foo.out());

Only use this wrapper when forced to deal with raw interface.

template<typename Itf>
template<typename Itf2>
bool comet::com_ptr< Itf >::same_pointer (  const com_ptr< Itf2 > &  x  )  const throw (com_error) [inline]
 

Pointer comparison.

Returns true if the two pointers are the same.

template<typename Itf>
void comet::com_ptr< Itf >::swap (  com_ptr< Itf > &  x  )  throw () [inline]
 

Swap operation.

This method is very fast, since it does not call AddRef or Release.

The documentation for this class was generated from the following file:
Copyright 2002 Sofus Mortensen. All rights reserved.