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 22struct PP_Var; 23 24namespace pp { 25 26class Var; 27 28namespace 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. 33template<typename, typename> struct IsSame { 34 static bool const value = false; 35}; 36template<typename A> struct IsSame<A, A> { 37 static bool const value = true; 38}; 39template<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. 57template <class T, bool P> struct InheritIf {}; 58template <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. 67template<typename T> 68struct 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. 102template<typename T> 103struct 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. 131template<typename T> 132struct 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. 142template<> 143struct 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. 167template<> 168struct 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. 194template<typename T> 195struct 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. 225template<typename T> 226struct 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. 245template<typename T> 246struct 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. 256template<> 257struct 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_ 283