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