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_BSTR_H_
6#define BASE_WIN_SCOPED_BSTR_H_
7
8#include <windows.h>
9#include <oleauto.h>
10
11#include "base/base_export.h"
12#include "base/logging.h"
13#include "base/strings/string16.h"
14
15namespace base {
16namespace win {
17
18// Manages a BSTR string pointer.
19// The class interface is based on scoped_ptr.
20class BASE_EXPORT ScopedBstr {
21 public:
22  ScopedBstr() : bstr_(NULL) {
23  }
24
25  // Constructor to create a new BSTR.
26  //
27  // NOTE: Do not pass a BSTR to this constructor expecting ownership to
28  // be transferred - even though it compiles! ;-)
29  explicit ScopedBstr(const char16* non_bstr);
30  ~ScopedBstr();
31
32  // Give ScopedBstr ownership over an already allocated BSTR or NULL.
33  // If you need to allocate a new BSTR instance, use |allocate| instead.
34  void Reset(BSTR bstr = NULL);
35
36  // Releases ownership of the BSTR to the caller.
37  BSTR Release();
38
39  // Creates a new BSTR from a 16-bit C-style string.
40  //
41  // If you already have a BSTR and want to transfer ownership to the
42  // ScopedBstr instance, call |reset| instead.
43  //
44  // Returns a pointer to the new BSTR, or NULL if allocation failed.
45  BSTR Allocate(const char16* str);
46
47  // Allocates a new BSTR with the specified number of bytes.
48  // Returns a pointer to the new BSTR, or NULL if allocation failed.
49  BSTR AllocateBytes(size_t bytes);
50
51  // Sets the allocated length field of the already-allocated BSTR to be
52  // |bytes|.  This is useful when the BSTR was preallocated with e.g.
53  // SysAllocStringLen or SysAllocStringByteLen (call |AllocateBytes|) and then
54  // not all the bytes are being used.
55  //
56  // Note that if you want to set the length to a specific number of
57  // characters, you need to multiply by sizeof(wchar_t).  Oddly, there's no
58  // public API to set the length, so we do this ourselves by hand.
59  //
60  // NOTE: The actual allocated size of the BSTR MUST be >= bytes.  That
61  // responsibility is with the caller.
62  void SetByteLen(size_t bytes);
63
64  // Swap values of two ScopedBstr's.
65  void Swap(ScopedBstr& bstr2);
66
67  // Retrieves the pointer address.
68  // Used to receive BSTRs as out arguments (and take ownership).
69  // The function DCHECKs on the current value being NULL.
70  // Usage: GetBstr(bstr.Receive());
71  BSTR* Receive();
72
73  // Returns number of chars in the BSTR.
74  size_t Length() const;
75
76  // Returns the number of bytes allocated for the BSTR.
77  size_t ByteLength() const;
78
79  operator BSTR() const {
80    return bstr_;
81  }
82
83 protected:
84  BSTR bstr_;
85
86 private:
87  // Forbid comparison of ScopedBstr types.  You should never have the same
88  // BSTR owned by two different scoped_ptrs.
89  bool operator==(const ScopedBstr& bstr2) const;
90  bool operator!=(const ScopedBstr& bstr2) const;
91  DISALLOW_COPY_AND_ASSIGN(ScopedBstr);
92};
93
94}  // namespace win
95}  // namespace base
96
97#endif  // BASE_SCOPED_BSTR_H_
98