1// Copyright (c) 2011 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef BASE_WIN_SCOPED_COMPTR_H_
6#define BASE_WIN_SCOPED_COMPTR_H_
7
8#include <unknwn.h>
9
10#include "base/logging.h"
11#include "base/memory/ref_counted.h"
12
13namespace base {
14namespace win {
15
16// A fairly minimalistic smart class for COM interface pointers.
17// Uses scoped_refptr for the basic smart pointer functionality
18// and adds a few IUnknown specific services.
19template <class Interface, const IID* interface_id = &__uuidof(Interface)>
20class ScopedComPtr : public scoped_refptr<Interface> {
21 public:
22  // Utility template to prevent users of ScopedComPtr from calling AddRef
23  // and/or Release() without going through the ScopedComPtr class.
24  class BlockIUnknownMethods : public Interface {
25   private:
26    STDMETHOD(QueryInterface)(REFIID iid, void** object) = 0;
27    STDMETHOD_(ULONG, AddRef)() = 0;
28    STDMETHOD_(ULONG, Release)() = 0;
29  };
30
31  typedef scoped_refptr<Interface> ParentClass;
32
33  ScopedComPtr() {
34  }
35
36  explicit ScopedComPtr(Interface* p) : ParentClass(p) {
37  }
38
39  ScopedComPtr(const ScopedComPtr<Interface, interface_id>& p)
40      : ParentClass(p) {
41  }
42
43  ~ScopedComPtr() {
44    // We don't want the smart pointer class to be bigger than the pointer
45    // it wraps.
46    static_assert(
47        sizeof(ScopedComPtr<Interface, interface_id>) == sizeof(Interface*),
48        "ScopedComPtrSize");
49  }
50
51  // Explicit Release() of the held object.  Useful for reuse of the
52  // ScopedComPtr instance.
53  // Note that this function equates to IUnknown::Release and should not
54  // be confused with e.g. scoped_ptr::release().
55  void Release() {
56    if (this->ptr_ != NULL) {
57      this->ptr_->Release();
58      this->ptr_ = NULL;
59    }
60  }
61
62  // Sets the internal pointer to NULL and returns the held object without
63  // releasing the reference.
64  Interface* Detach() {
65    Interface* p = this->ptr_;
66    this->ptr_ = NULL;
67    return p;
68  }
69
70  // Accepts an interface pointer that has already been addref-ed.
71  void Attach(Interface* p) {
72    DCHECK(!this->ptr_);
73    this->ptr_ = p;
74  }
75
76  // Retrieves the pointer address.
77  // Used to receive object pointers as out arguments (and take ownership).
78  // The function DCHECKs on the current value being NULL.
79  // Usage: Foo(p.Receive());
80  Interface** Receive() {
81    DCHECK(!this->ptr_) << "Object leak. Pointer must be NULL";
82    return &this->ptr_;
83  }
84
85  // A convenience for whenever a void pointer is needed as an out argument.
86  void** ReceiveVoid() {
87    return reinterpret_cast<void**>(Receive());
88  }
89
90  template <class Query>
91  HRESULT QueryInterface(Query** p) {
92    DCHECK(p != NULL);
93    DCHECK(this->ptr_ != NULL);
94    // IUnknown already has a template version of QueryInterface
95    // so the iid parameter is implicit here. The only thing this
96    // function adds are the DCHECKs.
97    return this->ptr_->QueryInterface(p);
98  }
99
100  // QI for times when the IID is not associated with the type.
101  HRESULT QueryInterface(const IID& iid, void** obj) {
102    DCHECK(obj != NULL);
103    DCHECK(this->ptr_ != NULL);
104    return this->ptr_->QueryInterface(iid, obj);
105  }
106
107  // Queries |other| for the interface this object wraps and returns the
108  // error code from the other->QueryInterface operation.
109  HRESULT QueryFrom(IUnknown* object) {
110    DCHECK(object != NULL);
111    return object->QueryInterface(Receive());
112  }
113
114  // Convenience wrapper around CoCreateInstance
115  HRESULT CreateInstance(const CLSID& clsid, IUnknown* outer = NULL,
116                         DWORD context = CLSCTX_ALL) {
117    DCHECK(!this->ptr_);
118    HRESULT hr = ::CoCreateInstance(clsid, outer, context, *interface_id,
119                                    reinterpret_cast<void**>(&this->ptr_));
120    return hr;
121  }
122
123  // Checks if the identity of |other| and this object is the same.
124  bool IsSameObject(IUnknown* other) {
125    if (!other && !this->ptr_)
126      return true;
127
128    if (!other || !this->ptr_)
129      return false;
130
131    ScopedComPtr<IUnknown> my_identity;
132    QueryInterface(my_identity.Receive());
133
134    ScopedComPtr<IUnknown> other_identity;
135    other->QueryInterface(other_identity.Receive());
136
137    return my_identity == other_identity;
138  }
139
140  // Provides direct access to the interface.
141  // Here we use a well known trick to make sure we block access to
142  // IUnknown methods so that something bad like this doesn't happen:
143  //    ScopedComPtr<IUnknown> p(Foo());
144  //    p->Release();
145  //    ... later the destructor runs, which will Release() again.
146  // and to get the benefit of the DCHECKs we add to QueryInterface.
147  // There's still a way to call these methods if you absolutely must
148  // by statically casting the ScopedComPtr instance to the wrapped interface
149  // and then making the call... but generally that shouldn't be necessary.
150  BlockIUnknownMethods* operator->() const {
151    DCHECK(this->ptr_ != NULL);
152    return reinterpret_cast<BlockIUnknownMethods*>(this->ptr_);
153  }
154
155  // Pull in operator=() from the parent class.
156  using scoped_refptr<Interface>::operator=;
157
158  // static methods
159
160  static const IID& iid() {
161    return *interface_id;
162  }
163};
164
165}  // namespace win
166}  // namespace base
167
168#endif  // BASE_WIN_SCOPED_COMPTR_H_
169