1// Copyright (c) 2012 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 PPAPI_SHARED_IMPL_VAR_H_
6#define PPAPI_SHARED_IMPL_VAR_H_
7
8#include <string>
9
10#include "base/compiler_specific.h"
11#include "base/memory/ref_counted.h"
12#include "base/memory/shared_memory.h"
13#include "ppapi/c/pp_var.h"
14#include "ppapi/shared_impl/host_resource.h"
15#include "ppapi/shared_impl/ppapi_shared_export.h"
16
17namespace ppapi {
18
19class ArrayBufferVar;
20class ArrayVar;
21class DictionaryVar;
22class ProxyObjectVar;
23class ResourceVar;
24class StringVar;
25class V8ObjectVar;
26class VarTracker;
27
28// Var -------------------------------------------------------------------------
29
30// Represents a non-POD var.
31class PPAPI_SHARED_EXPORT Var : public base::RefCounted<Var> {
32 public:
33  // Returns a string representing the given var for logging purposes.
34  static std::string PPVarToLogString(PP_Var var);
35
36  virtual StringVar* AsStringVar();
37  virtual ArrayBufferVar* AsArrayBufferVar();
38  virtual V8ObjectVar* AsV8ObjectVar();
39  virtual ProxyObjectVar* AsProxyObjectVar();
40  virtual ArrayVar* AsArrayVar();
41  virtual DictionaryVar* AsDictionaryVar();
42  virtual ResourceVar* AsResourceVar();
43
44  // Creates a PP_Var corresponding to this object. The return value will have
45  // one reference addrefed on behalf of the caller.
46  PP_Var GetPPVar();
47
48  // Returns the type of this var.
49  virtual PP_VarType GetType() const = 0;
50
51  // Returns the ID corresponing to the string or object if it exists already,
52  // or 0 if an ID hasn't been generated for this object (the plugin is holding
53  // no refs).
54  //
55  // Contrast to GetOrCreateVarID which creates the ID and a ref on behalf of
56  // the plugin.
57  int32 GetExistingVarID() const;
58
59 protected:
60  friend class base::RefCounted<Var>;
61  friend class VarTracker;
62
63  Var();
64  virtual ~Var();
65
66  // Returns the unique ID associated with this string or object, creating it
67  // if necessary. The return value will be 0 if the string or object is
68  // invalid.
69  //
70  // This function will take a reference to the var that will be passed to the
71  // caller.
72  int32 GetOrCreateVarID();
73
74  // Sets the internal object ID. This assumes that the ID hasn't been set
75  // before. This is used in cases where the ID is generated externally.
76  void AssignVarID(int32 id);
77
78  // Reset the assigned object ID.
79  void ResetVarID() { var_id_ = 0; }
80
81 private:
82  // This will be 0 if no ID has been assigned (this happens lazily).
83  int32 var_id_;
84
85  DISALLOW_COPY_AND_ASSIGN(Var);
86};
87
88// StringVar -------------------------------------------------------------------
89
90// Represents a string-based Var.
91//
92// Returning a given string as a PP_Var:
93//   return StringVar::StringToPPVar(my_string);
94//
95// Converting a PP_Var to a string:
96//   StringVar* string = StringVar::FromPPVar(var);
97//   if (!string)
98//     return false;  // Not a string or an invalid var.
99//   DoSomethingWithTheString(string->value());
100class PPAPI_SHARED_EXPORT StringVar : public Var {
101 public:
102  explicit StringVar(const std::string& str);
103  StringVar(const char* str, uint32 len);
104  virtual ~StringVar();
105
106  const std::string& value() const { return value_; }
107  // Return a pointer to the internal string. This allows other objects to
108  // temporarily store a weak pointer to our internal string. Use with care; the
109  // pointer *will* become invalid if this StringVar is removed from the
110  // tracker. (All of this applies to value(), but this one's even easier to use
111  // dangerously).
112  const std::string* ptr() const { return &value_; }
113
114  // Var override.
115  virtual StringVar* AsStringVar() OVERRIDE;
116  virtual PP_VarType GetType() const OVERRIDE;
117
118  // Helper function to create a PP_Var of type string that contains a copy of
119  // the given string. The input data must be valid UTF-8 encoded text, if it
120  // is not valid UTF-8, a NULL var will be returned.
121  //
122  // The return value will have a reference count of 1. Internally, this will
123  // create a StringVar and return the reference to it in the var.
124  static PP_Var StringToPPVar(const std::string& str);
125  static PP_Var StringToPPVar(const char* str, uint32 len);
126
127  // Same as StringToPPVar but avoids a copy by destructively swapping the
128  // given string into the newly created StringVar. The string must already be
129  // valid UTF-8. After the call, *src will be empty.
130  static PP_Var SwapValidatedUTF8StringIntoPPVar(std::string* src);
131
132  // Helper function that converts a PP_Var to a string. This will return NULL
133  // if the PP_Var is not of string type or the string is invalid.
134  static StringVar* FromPPVar(PP_Var var);
135
136 private:
137  StringVar();  // Makes an empty string.
138
139  std::string value_;
140
141  DISALLOW_COPY_AND_ASSIGN(StringVar);
142};
143
144// ArrayBufferVar --------------------------------------------------------------
145
146// Represents an array buffer Var.
147//
148// Note this is an abstract class. To create an appropriate concrete one, you
149// need to use the VarTracker:
150//   VarArrayBuffer* buf =
151//       PpapiGlobals::Get()->GetVarTracker()->CreateArrayBuffer(size);
152//
153// Converting a PP_Var to an ArrayBufferVar:
154//   ArrayBufferVar* array = ArrayBufferVar::FromPPVar(var);
155//   if (!array)
156//     return false;  // Not an ArrayBuffer or an invalid var.
157//   DoSomethingWithTheBuffer(array);
158class PPAPI_SHARED_EXPORT ArrayBufferVar : public Var {
159 public:
160  ArrayBufferVar();
161  virtual ~ArrayBufferVar();
162
163  virtual void* Map() = 0;
164  virtual void Unmap() = 0;
165  virtual uint32 ByteLength() = 0;
166
167  // Creates a new shared memory region, and copies the data in the
168  // ArrayBufferVar into it. On the plugin side, host_shm_handle_id will be set
169  // to some value that is not -1. On the host side, plugin_shm_handle will be
170  // set to a valid SharedMemoryHandle.
171  //
172  // Returns true if creating the shared memory (and copying) is successful,
173  // false otherwise.
174  virtual bool CopyToNewShmem(PP_Instance instance,
175                              int* host_shm_handle_id,
176                              base::SharedMemoryHandle* plugin_shm_handle) = 0;
177
178  // Var override.
179  virtual ArrayBufferVar* AsArrayBufferVar() OVERRIDE;
180  virtual PP_VarType GetType() const OVERRIDE;
181
182  // Helper function that converts a PP_Var to an ArrayBufferVar. This will
183  // return NULL if the PP_Var is not of ArrayBuffer type.
184  static ArrayBufferVar* FromPPVar(PP_Var var);
185
186 private:
187  DISALLOW_COPY_AND_ASSIGN(ArrayBufferVar);
188};
189
190}  // namespace ppapi
191
192#endif  // PPAPI_SHARED_IMPL_VAR_H_
193