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 VarTracker;
  27
  28 // Var -------------------------------------------------------------------------
  29
  30 // Represents a non-POD var.
  31 class 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 NPObjectVar* AsNPObjectVar();
  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());
 100 class 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);
 158 class 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_