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