output_traits.h revision c2e0dbddbe15c98d52c4786dac06cb8952a8ae6d
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 90// Output traits for all resource types. It is implemented to pass a 91// PP_Resource* as an output parameter to the browser, and convert to the 92// given resource object type T when passing to the plugin. 93// 94// Note that this class is parameterized by the resource object, for example 95// ResourceCallbackOutputTraits<pp::FileRef>. This is used as a base class for 96// CallbackOutputTraits below for the case where T is a derived class of 97// pp::Resource. 98template<typename T> 99struct ResourceCallbackOutputTraits { 100 // To call the browser, we just pass a PP_Resource pointer as the out param. 101 typedef PP_Resource* APIArgType; 102 typedef PP_Resource StorageType; 103 104 static inline APIArgType StorageToAPIArg(StorageType& t) { 105 return &t; 106 } 107 108 // Converts the PP_Resource to a pp::* object, passing any reference counted 109 // object along with it. This must only be called once since there will only 110 // be one reference that the browser has assigned to us for the out param! 111 // When calling into the plugin, convert the PP_Resource into the requested 112 // resource object type. 113 static inline T StorageToPluginArg(StorageType& t) { 114 return T(PASS_REF, t); 115 } 116}; 117 118// The general templatized base class for all CallbackOutputTraits. This class 119// covers both resources and POD (ints, structs, etc.) by inheriting from the 120// appropriate base class depending on whether the given type derives from 121// pp::Resource. This trick allows us to do this once rather than writing 122// specializations for every resource object type. 123template<typename T> 124struct CallbackOutputTraits 125 : public InheritIf<GenericCallbackOutputTraits<T>, 126 !IsBaseOf<Resource, T>::value>, 127 public InheritIf<ResourceCallbackOutputTraits<T>, 128 IsBaseOf<Resource, T>::value> { 129}; 130 131// A specialization of CallbackOutputTraits for pp::Var output parameters. 132// It passes a PP_Var* to the browser and converts to a pp::Var when passing 133// to the plugin. 134template<> 135struct CallbackOutputTraits<Var> { 136 // To call the browser, we just pass a PP_Var* as an output param. 137 typedef PP_Var* APIArgType; 138 typedef PP_Var StorageType; 139 140 static inline APIArgType StorageToAPIArg(StorageType& t) { 141 return &t; 142 } 143 144 // Converts the PP_Var to a pp::Var object, passing any reference counted 145 // object along with it. This must only be called once since there will only 146 // be one reference that the browser has assigned to us for the out param! 147 static inline pp::Var StorageToPluginArg(StorageType& t) { 148 return Var(PASS_REF, t); 149 } 150}; 151 152// Array output parameters ----------------------------------------------------- 153 154// Output traits for vectors of all "plain old data" (POD) types. It is 155// implemented to pass a pointer to the browser as an output parameter. 156// 157// This is used as a base class for the general vector CallbackOutputTraits 158// below in the case where T is not a resource. 159template<typename T> 160struct GenericVectorCallbackOutputTraits { 161 // All arrays are output via a PP_ArrayOutput type. 162 typedef PP_ArrayOutput APIArgType; 163 164 // We store the array as this adapter which combines the PP_ArrayOutput 165 // structure with the underlying std::vector that it will write into. 166 typedef ArrayOutputAdapterWithStorage<T> StorageType; 167 168 // Retrieves the PP_ArrayOutput interface for our vector object that the 169 // browser will use to write into our code. 170 static inline APIArgType StorageToAPIArg(StorageType& t) { 171 return t.pp_array_output(); 172 } 173 174 // Retrieves the underlying vector that can be passed to the plugin. 175 static inline std::vector<T>& StorageToPluginArg(StorageType& t) { 176 return t.output(); 177 } 178}; 179 180// Output traits for all vectors of resource types. It is implemented to pass 181// a PP_ArrayOutput parameter to the browser, and convert the returned resources 182// to a vector of the given resource object type T when passing to the plugin. 183// 184// Note that this class is parameterized by the resource object, for example 185// ResourceVectorCallbackOutputTraits<pp::FileRef>. This is used as a base 186// class for CallbackOutputTraits below for the case where T is a derived 187// class of pp::Resource. 188template<typename T> 189struct ResourceVectorCallbackOutputTraits { 190 typedef PP_ArrayOutput APIArgType; 191 typedef ResourceArrayOutputAdapterWithStorage<T> StorageType; 192 193 static inline APIArgType StorageToAPIArg(StorageType& t) { 194 return t.pp_array_output(); 195 } 196 static inline std::vector<T>& StorageToPluginArg(StorageType& t) { 197 return t.output(); 198 } 199}; 200 201// Specialization of CallbackOutputTraits for vectors. This struct covers both 202// arrays of resources and arrays of POD (ints, structs, etc.) by inheriting 203// from the appropriate base class depending on whether the given type derives 204// from pp::Resource. This trick allows us to do this once rather than writing 205// specializations for every resource object type. 206template<typename T> 207struct CallbackOutputTraits< std::vector<T> > 208 : public InheritIf<GenericVectorCallbackOutputTraits<T>, 209 !IsBaseOf<Resource, T>::value>, 210 public InheritIf<ResourceVectorCallbackOutputTraits<T>, 211 IsBaseOf<Resource, T>::value> { 212}; 213 214// A specialization of CallbackOutputTraits to provide the callback system 215// the information on how to handle vectors of pp::Var. Vectors of resources 216// and plain data are handled separately. See the above definition for more. 217template<> 218struct CallbackOutputTraits< std::vector<pp::Var> > { 219 // All arrays are output via a PP_ArrayOutput type. 220 typedef PP_ArrayOutput APIArgType; 221 222 // We store the array as this adapter which combines the PP_ArrayOutput 223 // structure with the underlying std::vector that it will write into. 224 typedef VarArrayOutputAdapterWithStorage StorageType; 225 226 // Retrieves the PP_ArrayOutput interface for our vector object that the 227 // browser will use to write into our code. 228 static inline APIArgType StorageToAPIArg(StorageType& t) { 229 return t.pp_array_output(); 230 } 231 232 // Retrieves the underlying vector that can be passed to the plugin. 233 static inline std::vector<pp::Var>& StorageToPluginArg(StorageType& t) { 234 return t.output(); 235 } 236}; 237 238} // namespace internal 239} // namespace pp 240 241#endif // PPAPI_CPP_OUTPUT_TRAITS_H_ 242