ppapi/shared_impl/var.h

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