Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 8 | #include <vector> |
| 9 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 10 | #include "ppapi/c/pp_resource.h" |
| 11 | #include "ppapi/cpp/array_output.h" |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 12 | #include "ppapi/cpp/resource.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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; } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 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 */) {} |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 120 | |
| 121 | static inline void Initialize(StorageType* t) { |
| 122 | *t = 0; |
| 123 | } |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 124 | }; |
| 125 | |
| 126 | // The general templatized base class for all CallbackOutputTraits. This class |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 131 | template<typename T> |
| 132 | struct CallbackOutputTraits |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 133 | : public InheritIf<GenericCallbackOutputTraits<T>, |
| 134 | !IsBaseOf<Resource, T>::value>, |
| 135 | public InheritIf<ResourceCallbackOutputTraits<T>, |
| 136 | IsBaseOf<Resource, T>::value> { |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 158 | |
| 159 | static inline void Initialize(StorageType* t) { |
| 160 | *t = PP_MakeUndefined(); |
| 161 | } |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 162 | }; |
| 163 | |
Torne (Richard Coles) | d0247b1 | 2013-09-19 22:36:51 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 213 | |
| 214 | static inline void Initialize(StorageType* /* t */) {} |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 236 | |
| 237 | static inline void Initialize(StorageType* /* t */) {} |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 238 | }; |
| 239 | |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 245 | template<typename T> |
| 246 | struct CallbackOutputTraits< std::vector<T> > |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 247 | : public InheritIf<GenericVectorCallbackOutputTraits<T>, |
| 248 | !IsBaseOf<Resource, T>::value>, |
| 249 | public InheritIf<ResourceVectorCallbackOutputTraits<T>, |
| 250 | IsBaseOf<Resource, T>::value> { |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | } |
Ben Murdoch | 7dbb3d5 | 2013-07-17 14:55:54 +0100 | [diff] [blame] | 275 | |
| 276 | static inline void Initialize(StorageType* /* t */) {} |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 277 | }; |
| 278 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 279 | } // namespace internal |
| 280 | } // namespace pp |
| 281 | |
| 282 | #endif // PPAPI_CPP_OUTPUT_TRAITS_H_ |