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