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