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