ppapi/cpp/output_traits.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_CPP_OUTPUT_TRAITS_H_
   6 #define PPAPI_CPP_OUTPUT_TRAITS_H_
   7
   8 #include <vector>
   9
  10 #include "ppapi/c/pp_resource.h"
  11 #include "ppapi/cpp/array_output.h"
  12 #include "ppapi/cpp/resource.h"
  13
  14 /// @file
  15 /// This file defines internal templates for defining how data is passed to the
  16 /// browser via output parameters and how to convert that data to the
  17 /// corresponding C++ object types.
  18 ///
  19 /// It is used by the callback system, it should not be necessary for end-users
  20 /// to use these templates directly.
  21
  22 struct PP_Var;
  23
  24 namespace pp {
  25
  26 class Var;
  27
  28 namespace internal {
  29
  30 // This goop is a trick used to implement a template that can be used to
  31 // determine if a given class is the base class of another given class. It is
  32 // used in the resource object partial specialization below.
  33 template<typename, typename> struct IsSame {
  34   static bool const value = false;
  35 };
  36 template<typename A> struct IsSame<A, A> {
  37   static bool const value = true;
  38 };
  39 template<typename Base, typename Derived> struct IsBaseOf {
  40  private:
  41   // This class doesn't work correctly with forward declarations.
  42   // Because sizeof cannot be applied to incomplete types, this line prevents us
  43   // from passing in forward declarations.
  44   typedef char (*EnsureTypesAreComplete)[sizeof(Base) + sizeof(Derived)];
  45
  46   static Derived* CreateDerived();
  47   static char (&Check(Base*))[1];
  48   static char (&Check(...))[2];
  49
  50  public:
  51   static bool const value = sizeof Check(CreateDerived()) == 1 &&
  52                             !IsSame<Base const, void const>::value;
  53 };
  54
  55 // Template to optionally derive from a given base class T if the given
  56 // predicate P is true.
  57 template <class T, bool P> struct InheritIf {};
  58 template <class T> struct InheritIf<T, true> : public T {};
  59
  60 // Single output parameters ----------------------------------------------------
  61
  62 // Output traits for all "plain old data" (POD) types. It is implemented to
  63 // pass a pointer to the browser as an output parameter.
  64 //
  65 // This is used as a base class for the general CallbackOutputTraits below in
  66 // the case where T is not a resource.
  67 template<typename T>
  68 struct GenericCallbackOutputTraits {
  69   // The type passed to the PPAPI C API for this parameter. For normal out
  70   // params, we pass a pointer to the object so the browser can write into it.
  71   typedef T* APIArgType;
  72
  73   // The type used to store the value. This is used internally in asynchronous
  74   // callbacks by the CompletionCallbackFactory to have the browser write into
  75   // a temporary value associated with the callback, which is passed to the
  76   // plugin code when the callback is issued.
  77   typedef T StorageType;
  78
  79   // Converts a "storage type" to a value that can be passed to the browser as
  80   // an output parameter. This just takes the address to convert the value to
  81   // a pointer.
  82   static inline APIArgType StorageToAPIArg(StorageType& t) { return &t; }
  83
  84   // Converts the "storage type" to the value we pass to the plugin for
  85   // callbacks. This doesn't actually need to do anything in this case,
  86   // it's needed for some of more complex template specializations below.
  87   static inline T& StorageToPluginArg(StorageType& t) { return t; }
  88
  89   // Initializes the "storage type" to a default value, if necessary. Here,
  90   // we do nothing, assuming that the default constructor for T suffices.
  91   static inline void Initialize(StorageType* /* t */) {}
  92 };
  93
  94 // Output traits for all resource types. It is implemented to pass a
  95 // PP_Resource* as an output parameter to the browser, and convert to the
  96 // given resource object type T when passing to the plugin.
  97 //
  98 // Note that this class is parameterized by the resource object, for example
  99 // ResourceCallbackOutputTraits<pp::FileRef>. This is used as a base class for
 100 // CallbackOutputTraits below for the case where T is a derived class of
 101 // pp::Resource.
 102 template<typename T>
 103 struct ResourceCallbackOutputTraits {
 104   // To call the browser, we just pass a PP_Resource pointer as the out param.
 105   typedef PP_Resource* APIArgType;
 106   typedef PP_Resource StorageType;
 107
 108   static inline APIArgType StorageToAPIArg(StorageType& t) {
 109     return &t;
 110   }
 111
 112   // Converts the PP_Resource to a pp::* object, passing any reference counted
 113   // object along with it. This must only be called once since there will only
 114   // be one reference that the browser has assigned to us for the out param!
 115   // When calling into the plugin, convert the PP_Resource into the requested
 116   // resource object type.
 117   static inline T StorageToPluginArg(StorageType& t) {
 118     return T(PASS_REF, t);
 119   }
 120
 121   static inline void Initialize(StorageType* t) {
 122     *t = 0;
 123   }
 124 };
 125
 126 // The general templatized base class for all CallbackOutputTraits. This class
 127 // covers both resources and POD (ints, structs, etc.) by inheriting from the
 128 // appropriate base class depending on whether the given type derives from
 129 // pp::Resource. This trick allows us to do this once rather than writing
 130 // specializations for every resource object type.
 131 template<typename T>
 132 struct CallbackOutputTraits
 133     : public InheritIf<GenericCallbackOutputTraits<T>,
 134                        !IsBaseOf<Resource, T>::value>,
 135       public InheritIf<ResourceCallbackOutputTraits<T>,
 136                        IsBaseOf<Resource, T>::value> {
 137 };
 138
 139 // A specialization of CallbackOutputTraits for pp::Var output parameters.
 140 // It passes a PP_Var* to the browser and converts to a pp::Var when passing
 141 // to the plugin.
 142 template<>
 143 struct CallbackOutputTraits<Var> {
 144   // To call the browser, we just pass a PP_Var* as an output param.
 145   typedef PP_Var* APIArgType;
 146   typedef PP_Var StorageType;
 147
 148   static inline APIArgType StorageToAPIArg(StorageType& t) {
 149     return &t;
 150   }
 151
 152   // Converts the PP_Var to a pp::Var object, passing any reference counted
 153   // object along with it. This must only be called once since there will only
 154   // be one reference that the browser has assigned to us for the out param!
 155   static inline pp::Var StorageToPluginArg(StorageType& t) {
 156     return Var(PASS_REF, t);
 157   }
 158
 159   static inline void Initialize(StorageType* t) {
 160     *t = PP_MakeUndefined();
 161   }
 162 };
 163
 164 // A specialization of CallbackOutputTraits for bool output parameters.
 165 // It passes a PP_Bool* to the browser and converts to a bool when passing
 166 // to the plugin.
 167 template<>
 168 struct CallbackOutputTraits<bool> {
 169   // To call the browser, we just pass a PP_Bool* as an output param.
 170   typedef PP_Bool* APIArgType;
 171   typedef PP_Bool StorageType;
 172
 173   static inline APIArgType StorageToAPIArg(StorageType& t) {
 174     return &t;
 175   }
 176
 177   // Converts the PP_Bool to a bool object.
 178   static inline bool StorageToPluginArg(StorageType& t) {
 179     return PP_ToBool(t);
 180   }
 181
 182   static inline void Initialize(StorageType* t) {
 183     *t = PP_FALSE;
 184   }
 185 };
 186
 187 // Array output parameters -----------------------------------------------------
 188
 189 // Output traits for vectors of all "plain old data" (POD) types. It is
 190 // implemented to pass a pointer to the browser as an output parameter.
 191 //
 192 // This is used as a base class for the general vector CallbackOutputTraits
 193 // below in the case where T is not a resource.
 194 template<typename T>
 195 struct GenericVectorCallbackOutputTraits {
 196   // All arrays are output via a PP_ArrayOutput type.
 197   typedef PP_ArrayOutput APIArgType;
 198
 199   // We store the array as this adapter which combines the PP_ArrayOutput
 200   // structure with the underlying std::vector that it will write into.
 201   typedef ArrayOutputAdapterWithStorage<T> StorageType;
 202
 203   // Retrieves the PP_ArrayOutput interface for our vector object that the
 204   // browser will use to write into our code.
 205   static inline APIArgType StorageToAPIArg(StorageType& t) {
 206     return t.pp_array_output();
 207   }
 208
 209   // Retrieves the underlying vector that can be passed to the plugin.
 210   static inline std::vector<T>& StorageToPluginArg(StorageType& t) {
 211     return t.output();
 212   }
 213
 214   static inline void Initialize(StorageType* /* t */) {}
 215 };
 216
 217 // Output traits for all vectors of resource types. It is implemented to pass
 218 // a PP_ArrayOutput parameter to the browser, and convert the returned resources
 219 // to a vector of the given resource object type T when passing to the plugin.
 220 //
 221 // Note that this class is parameterized by the resource object, for example
 222 // ResourceVectorCallbackOutputTraits<pp::FileRef>. This is used as a base
 223 // class for CallbackOutputTraits below for the case where T is a derived
 224 // class of pp::Resource.
 225 template<typename T>
 226 struct ResourceVectorCallbackOutputTraits {
 227   typedef PP_ArrayOutput APIArgType;
 228   typedef ResourceArrayOutputAdapterWithStorage<T> StorageType;
 229
 230   static inline APIArgType StorageToAPIArg(StorageType& t) {
 231     return t.pp_array_output();
 232   }
 233   static inline std::vector<T>& StorageToPluginArg(StorageType& t) {
 234     return t.output();
 235   }
 236
 237   static inline void Initialize(StorageType* /* t */) {}
 238 };
 239
 240 // Specialization of CallbackOutputTraits for vectors. This struct covers both
 241 // arrays of resources and arrays of POD (ints, structs, etc.) by inheriting
 242 // from the appropriate base class depending on whether the given type derives
 243 // from pp::Resource. This trick allows us to do this once rather than writing
 244 // specializations for every resource object type.
 245 template<typename T>
 246 struct CallbackOutputTraits< std::vector<T> >
 247     : public InheritIf<GenericVectorCallbackOutputTraits<T>,
 248                        !IsBaseOf<Resource, T>::value>,
 249       public InheritIf<ResourceVectorCallbackOutputTraits<T>,
 250                        IsBaseOf<Resource, T>::value> {
 251 };
 252
 253 // A specialization of CallbackOutputTraits to provide the callback system
 254 // the information on how to handle vectors of pp::Var. Vectors of resources
 255 // and plain data are handled separately. See the above definition for more.
 256 template<>
 257 struct CallbackOutputTraits< std::vector<pp::Var> > {
 258   // All arrays are output via a PP_ArrayOutput type.
 259   typedef PP_ArrayOutput APIArgType;
 260
 261   // We store the array as this adapter which combines the PP_ArrayOutput
 262   // structure with the underlying std::vector that it will write into.
 263   typedef VarArrayOutputAdapterWithStorage StorageType;
 264
 265   // Retrieves the PP_ArrayOutput interface for our vector object that the
 266   // browser will use to write into our code.
 267   static inline APIArgType StorageToAPIArg(StorageType& t) {
 268     return t.pp_array_output();
 269   }
 270
 271   // Retrieves the underlying vector that can be passed to the plugin.
 272   static inline std::vector<pp::Var>& StorageToPluginArg(StorageType& t) {
 273     return t.output();
 274   }
 275
 276   static inline void Initialize(StorageType* /* t */) {}
 277 };
 278
 279 }  // namespace internal
 280 }  // namespace pp
 281
 282 #endif  // PPAPI_CPP_OUTPUT_TRAITS_H_