ppapi/cpp/output_traits.h - chromium/src.git - Git at Google

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef PPAPI_CPP_OUTPUT_TRAITS_H_
 #define PPAPI_CPP_OUTPUT_TRAITS_H_

 #include <vector>

 #include "ppapi/c/pp_resource.h"
 #include "ppapi/cpp/array_output.h"
 #include "ppapi/cpp/resource.h"

 /// @file
 /// This file defines internal templates for defining how data is passed to the
 /// browser via output parameters and how to convert that data to the
 /// corresponding C++ object types.
 ///
 /// It is used by the callback system, it should not be necessary for end-users
 /// to use these templates directly.

 struct PP_Var;

 namespace pp {

 class Var;

 namespace internal {

 // This goop is a trick used to implement a template that can be used to
 // determine if a given class is the base class of another given class. It is
 // used in the resource object partial specialization below.
 template<typename, typename> struct IsSame {
   static bool const value = false;
 };
 template<typename A> struct IsSame<A, A> {
   static bool const value = true;
 };
 template<typename Base, typename Derived> struct IsBaseOf {
  private:
   // This class doesn't work correctly with forward declarations.
   // Because sizeof cannot be applied to incomplete types, this line prevents us
   // from passing in forward declarations.
   typedef char (*EnsureTypesAreComplete)[sizeof(Base) + sizeof(Derived)];

   static Derived* CreateDerived();
   static char (&Check(Base*))[1];
   static char (&Check(...))[2];

  public:
   static bool const value = sizeof Check(CreateDerived()) == 1 &&
                             !IsSame<Base const, void const>::value;
 };

 // Template to optionally derive from a given base class T if the given
 // predicate P is true.
 template <class T, bool P> struct InheritIf {};
 template <class T> struct InheritIf<T, true> : public T {};

 // Single output parameters ----------------------------------------------------

 // Output traits for all "plain old data" (POD) types. It is implemented to
 // pass a pointer to the browser as an output parameter.
 //
 // This is used as a base class for the general CallbackOutputTraits below in
 // the case where T is not a resource.
 template<typename T>
 struct GenericCallbackOutputTraits {
   // The type passed to the PPAPI C API for this parameter. For normal out
   // params, we pass a pointer to the object so the browser can write into it.
   typedef T* APIArgType;

   // The type used to store the value. This is used internally in asynchronous
   // callbacks by the CompletionCallbackFactory to have the browser write into
   // a temporary value associated with the callback, which is passed to the
   // plugin code when the callback is issued.
   typedef T StorageType;

   // Converts a "storage type" to a value that can be passed to the browser as
   // an output parameter. This just takes the address to convert the value to
   // a pointer.
   static inline APIArgType StorageToAPIArg(StorageType& t) { return &t; }

   // Converts the "storage type" to the value we pass to the plugin for
   // callbacks. This doesn't actually need to do anything in this case,
   // it's needed for some of more complex template specializations below.
   static inline T& StorageToPluginArg(StorageType& t) { return t; }

   // Initializes the "storage type" to a default value, if necessary. Here,
   // we do nothing, assuming that the default constructor for T suffices.
   static inline void Initialize(StorageType* /* t */) {}
 };

 // Output traits for all resource types. It is implemented to pass a
 // PP_Resource* as an output parameter to the browser, and convert to the
 // given resource object type T when passing to the plugin.
 //
 // Note that this class is parameterized by the resource object, for example
 // ResourceCallbackOutputTraits<pp::FileRef>. This is used as a base class for
 // CallbackOutputTraits below for the case where T is a derived class of
 // pp::Resource.
 template<typename T>
 struct ResourceCallbackOutputTraits {
   // To call the browser, we just pass a PP_Resource pointer as the out param.
   typedef PP_Resource* APIArgType;
   typedef PP_Resource StorageType;

   static inline APIArgType StorageToAPIArg(StorageType& t) {
     return &t;
   }

   // Converts the PP_Resource to a pp::* object, passing any reference counted
   // object along with it. This must only be called once since there will only
   // be one reference that the browser has assigned to us for the out param!
   // When calling into the plugin, convert the PP_Resource into the requested
   // resource object type.
   static inline T StorageToPluginArg(StorageType& t) {
     return T(PASS_REF, t);
   }

   static inline void Initialize(StorageType* t) {
     *t = 0;
   }
 };

 // The general templatized base class for all CallbackOutputTraits. This class
 // covers both resources and POD (ints, structs, etc.) by inheriting from the
 // appropriate base class depending on whether the given type derives from
 // pp::Resource. This trick allows us to do this once rather than writing
 // specializations for every resource object type.
 template<typename T>
 struct CallbackOutputTraits
     : public InheritIf<GenericCallbackOutputTraits<T>,
                        !IsBaseOf<Resource, T>::value>,
       public InheritIf<ResourceCallbackOutputTraits<T>,
                        IsBaseOf<Resource, T>::value> {
 };

 // A specialization of CallbackOutputTraits for pp::Var output parameters.
 // It passes a PP_Var* to the browser and converts to a pp::Var when passing
 // to the plugin.
 template<>
 struct CallbackOutputTraits<Var> {
   // To call the browser, we just pass a PP_Var* as an output param.
   typedef PP_Var* APIArgType;
   typedef PP_Var StorageType;

   static inline APIArgType StorageToAPIArg(StorageType& t) {
     return &t;
   }

   // Converts the PP_Var to a pp::Var object, passing any reference counted
   // object along with it. This must only be called once since there will only
   // be one reference that the browser has assigned to us for the out param!
   static inline pp::Var StorageToPluginArg(StorageType& t) {
     return Var(PASS_REF, t);
   }

   static inline void Initialize(StorageType* t) {
     *t = PP_MakeUndefined();
   }
 };

 // A specialization of CallbackOutputTraits for bool output parameters.
 // It passes a PP_Bool* to the browser and converts to a bool when passing
 // to the plugin.
 template<>
 struct CallbackOutputTraits<bool> {
   // To call the browser, we just pass a PP_Bool* as an output param.
   typedef PP_Bool* APIArgType;
   typedef PP_Bool StorageType;

   static inline APIArgType StorageToAPIArg(StorageType& t) {
     return &t;
   }

   // Converts the PP_Bool to a bool object.
   static inline bool StorageToPluginArg(StorageType& t) {
     return PP_ToBool(t);
   }

   static inline void Initialize(StorageType* t) {
     *t = PP_FALSE;
   }
 };

 // Array output parameters -----------------------------------------------------

 // Output traits for vectors of all "plain old data" (POD) types. It is
 // implemented to pass a pointer to the browser as an output parameter.
 //
 // This is used as a base class for the general vector CallbackOutputTraits
 // below in the case where T is not a resource.
 template<typename T>
 struct GenericVectorCallbackOutputTraits {
   // All arrays are output via a PP_ArrayOutput type.
   typedef PP_ArrayOutput APIArgType;

   // We store the array as this adapter which combines the PP_ArrayOutput
   // structure with the underlying std::vector that it will write into.
   typedef ArrayOutputAdapterWithStorage<T> StorageType;

   // Retrieves the PP_ArrayOutput interface for our vector object that the
   // browser will use to write into our code.
   static inline APIArgType StorageToAPIArg(StorageType& t) {
     return t.pp_array_output();
   }

   // Retrieves the underlying vector that can be passed to the plugin.
   static inline std::vector<T>& StorageToPluginArg(StorageType& t) {
     return t.output();
   }

   static inline void Initialize(StorageType* /* t */) {}
 };

 // Output traits for all vectors of resource types. It is implemented to pass
 // a PP_ArrayOutput parameter to the browser, and convert the returned resources
 // to a vector of the given resource object type T when passing to the plugin.
 //
 // Note that this class is parameterized by the resource object, for example
 // ResourceVectorCallbackOutputTraits<pp::FileRef>. This is used as a base
 // class for CallbackOutputTraits below for the case where T is a derived
 // class of pp::Resource.
 template<typename T>
 struct ResourceVectorCallbackOutputTraits {
   typedef PP_ArrayOutput APIArgType;
   typedef ResourceArrayOutputAdapterWithStorage<T> StorageType;

   static inline APIArgType StorageToAPIArg(StorageType& t) {
     return t.pp_array_output();
   }
   static inline std::vector<T>& StorageToPluginArg(StorageType& t) {
     return t.output();
   }

   static inline void Initialize(StorageType* /* t */) {}
 };

 // Specialization of CallbackOutputTraits for vectors. This struct covers both
 // arrays of resources and arrays of POD (ints, structs, etc.) by inheriting
 // from the appropriate base class depending on whether the given type derives
 // from pp::Resource. This trick allows us to do this once rather than writing
 // specializations for every resource object type.
 template<typename T>
 struct CallbackOutputTraits< std::vector<T> >
     : public InheritIf<GenericVectorCallbackOutputTraits<T>,
                        !IsBaseOf<Resource, T>::value>,
       public InheritIf<ResourceVectorCallbackOutputTraits<T>,
                        IsBaseOf<Resource, T>::value> {
 };

 // A specialization of CallbackOutputTraits to provide the callback system
 // the information on how to handle vectors of pp::Var. Vectors of resources
 // and plain data are handled separately. See the above definition for more.
 template<>
 struct CallbackOutputTraits< std::vector<pp::Var> > {
   // All arrays are output via a PP_ArrayOutput type.
   typedef PP_ArrayOutput APIArgType;

   // We store the array as this adapter which combines the PP_ArrayOutput
   // structure with the underlying std::vector that it will write into.
   typedef VarArrayOutputAdapterWithStorage StorageType;

   // Retrieves the PP_ArrayOutput interface for our vector object that the
   // browser will use to write into our code.
   static inline APIArgType StorageToAPIArg(StorageType& t) {
     return t.pp_array_output();
   }

   // Retrieves the underlying vector that can be passed to the plugin.
   static inline std::vector<pp::Var>& StorageToPluginArg(StorageType& t) {
     return t.output();
   }

   static inline void Initialize(StorageType* /* t */) {}
 };

 }  // namespace internal
 }  // namespace pp

 #endif  // PPAPI_CPP_OUTPUT_TRAITS_H_
	// Copyright (c) 2012 The Chromium Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef PPAPI_CPP_OUTPUT_TRAITS_H_
	#define PPAPI_CPP_OUTPUT_TRAITS_H_

	#include <vector>

	#include "ppapi/c/pp_resource.h"
	#include "ppapi/cpp/array_output.h"
	#include "ppapi/cpp/resource.h"

	/// @file
	/// This file defines internal templates for defining how data is passed to the
	/// browser via output parameters and how to convert that data to the
	/// corresponding C++ object types.
	///
	/// It is used by the callback system, it should not be necessary for end-users
	/// to use these templates directly.

	struct PP_Var;

	namespace pp {

	class Var;

	namespace internal {

	// This goop is a trick used to implement a template that can be used to
	// determine if a given class is the base class of another given class. It is
	// used in the resource object partial specialization below.
	template<typename, typename> struct IsSame {
	static bool const value = false;
	};
	template<typename A> struct IsSame<A, A> {
	static bool const value = true;
	};
	template<typename Base, typename Derived> struct IsBaseOf {
	private:
	// This class doesn't work correctly with forward declarations.
	// Because sizeof cannot be applied to incomplete types, this line prevents us
	// from passing in forward declarations.
	typedef char (*EnsureTypesAreComplete)[sizeof(Base) + sizeof(Derived)];

	static Derived* CreateDerived();
	static char (&Check(Base*))[1];
	static char (&Check(...))[2];

	public:
	static bool const value = sizeof Check(CreateDerived()) == 1 &&
	!IsSame<Base const, void const>::value;
	};

	// Template to optionally derive from a given base class T if the given
	// predicate P is true.
	template <class T, bool P> struct InheritIf {};
	template <class T> struct InheritIf<T, true> : public T {};

	// Single output parameters ----------------------------------------------------

	// Output traits for all "plain old data" (POD) types. It is implemented to
	// pass a pointer to the browser as an output parameter.
	//
	// This is used as a base class for the general CallbackOutputTraits below in
	// the case where T is not a resource.
	template<typename T>
	struct GenericCallbackOutputTraits {
	// The type passed to the PPAPI C API for this parameter. For normal out
	// params, we pass a pointer to the object so the browser can write into it.
	typedef T* APIArgType;

	// The type used to store the value. This is used internally in asynchronous
	// callbacks by the CompletionCallbackFactory to have the browser write into
	// a temporary value associated with the callback, which is passed to the
	// plugin code when the callback is issued.
	typedef T StorageType;

	// Converts a "storage type" to a value that can be passed to the browser as
	// an output parameter. This just takes the address to convert the value to
	// a pointer.
	static inline APIArgType StorageToAPIArg(StorageType& t) { return &t; }

	// Converts the "storage type" to the value we pass to the plugin for
	// callbacks. This doesn't actually need to do anything in this case,
	// it's needed for some of more complex template specializations below.
	static inline T& StorageToPluginArg(StorageType& t) { return t; }

	// Initializes the "storage type" to a default value, if necessary. Here,
	// we do nothing, assuming that the default constructor for T suffices.
	static inline void Initialize(StorageType* /* t */) {}
	};

	// Output traits for all resource types. It is implemented to pass a
	// PP_Resource* as an output parameter to the browser, and convert to the
	// given resource object type T when passing to the plugin.
	//
	// Note that this class is parameterized by the resource object, for example
	// ResourceCallbackOutputTraits<pp::FileRef>. This is used as a base class for
	// CallbackOutputTraits below for the case where T is a derived class of
	// pp::Resource.
	template<typename T>
	struct ResourceCallbackOutputTraits {
	// To call the browser, we just pass a PP_Resource pointer as the out param.
	typedef PP_Resource* APIArgType;
	typedef PP_Resource StorageType;

	static inline APIArgType StorageToAPIArg(StorageType& t) {
	return &t;
	}

	// Converts the PP_Resource to a pp::* object, passing any reference counted
	// object along with it. This must only be called once since there will only
	// be one reference that the browser has assigned to us for the out param!
	// When calling into the plugin, convert the PP_Resource into the requested
	// resource object type.
	static inline T StorageToPluginArg(StorageType& t) {
	return T(PASS_REF, t);
	}

	static inline void Initialize(StorageType* t) {
	*t = 0;
	}
	};

	// The general templatized base class for all CallbackOutputTraits. This class
	// covers both resources and POD (ints, structs, etc.) by inheriting from the
	// appropriate base class depending on whether the given type derives from
	// pp::Resource. This trick allows us to do this once rather than writing
	// specializations for every resource object type.
	template<typename T>
	struct CallbackOutputTraits
	: public InheritIf<GenericCallbackOutputTraits<T>,
	!IsBaseOf<Resource, T>::value>,
	public InheritIf<ResourceCallbackOutputTraits<T>,
	IsBaseOf<Resource, T>::value> {
	};

	// A specialization of CallbackOutputTraits for pp::Var output parameters.
	// It passes a PP_Var* to the browser and converts to a pp::Var when passing
	// to the plugin.
	template<>
	struct CallbackOutputTraits<Var> {
	// To call the browser, we just pass a PP_Var* as an output param.
	typedef PP_Var* APIArgType;
	typedef PP_Var StorageType;

	static inline APIArgType StorageToAPIArg(StorageType& t) {
	return &t;
	}

	// Converts the PP_Var to a pp::Var object, passing any reference counted
	// object along with it. This must only be called once since there will only
	// be one reference that the browser has assigned to us for the out param!
	static inline pp::Var StorageToPluginArg(StorageType& t) {
	return Var(PASS_REF, t);
	}

	static inline void Initialize(StorageType* t) {
	*t = PP_MakeUndefined();
	}
	};

	// A specialization of CallbackOutputTraits for bool output parameters.
	// It passes a PP_Bool* to the browser and converts to a bool when passing
	// to the plugin.
	template<>
	struct CallbackOutputTraits<bool> {
	// To call the browser, we just pass a PP_Bool* as an output param.
	typedef PP_Bool* APIArgType;
	typedef PP_Bool StorageType;

	static inline APIArgType StorageToAPIArg(StorageType& t) {
	return &t;
	}

	// Converts the PP_Bool to a bool object.
	static inline bool StorageToPluginArg(StorageType& t) {
	return PP_ToBool(t);
	}

	static inline void Initialize(StorageType* t) {
	*t = PP_FALSE;
	}
	};

	// Array output parameters -----------------------------------------------------

	// Output traits for vectors of all "plain old data" (POD) types. It is
	// implemented to pass a pointer to the browser as an output parameter.
	//
	// This is used as a base class for the general vector CallbackOutputTraits
	// below in the case where T is not a resource.
	template<typename T>
	struct GenericVectorCallbackOutputTraits {
	// All arrays are output via a PP_ArrayOutput type.
	typedef PP_ArrayOutput APIArgType;

	// We store the array as this adapter which combines the PP_ArrayOutput
	// structure with the underlying std::vector that it will write into.
	typedef ArrayOutputAdapterWithStorage<T> StorageType;

	// Retrieves the PP_ArrayOutput interface for our vector object that the
	// browser will use to write into our code.
	static inline APIArgType StorageToAPIArg(StorageType& t) {
	return t.pp_array_output();
	}

	// Retrieves the underlying vector that can be passed to the plugin.
	static inline std::vector<T>& StorageToPluginArg(StorageType& t) {
	return t.output();
	}

	static inline void Initialize(StorageType* /* t */) {}
	};

	// Output traits for all vectors of resource types. It is implemented to pass
	// a PP_ArrayOutput parameter to the browser, and convert the returned resources
	// to a vector of the given resource object type T when passing to the plugin.
	//
	// Note that this class is parameterized by the resource object, for example
	// ResourceVectorCallbackOutputTraits<pp::FileRef>. This is used as a base
	// class for CallbackOutputTraits below for the case where T is a derived
	// class of pp::Resource.
	template<typename T>
	struct ResourceVectorCallbackOutputTraits {
	typedef PP_ArrayOutput APIArgType;
	typedef ResourceArrayOutputAdapterWithStorage<T> StorageType;

	static inline APIArgType StorageToAPIArg(StorageType& t) {
	return t.pp_array_output();
	}
	static inline std::vector<T>& StorageToPluginArg(StorageType& t) {
	return t.output();
	}

	static inline void Initialize(StorageType* /* t */) {}
	};

	// Specialization of CallbackOutputTraits for vectors. This struct covers both
	// arrays of resources and arrays of POD (ints, structs, etc.) by inheriting
	// from the appropriate base class depending on whether the given type derives
	// from pp::Resource. This trick allows us to do this once rather than writing
	// specializations for every resource object type.
	template<typename T>
	struct CallbackOutputTraits< std::vector<T> >
	: public InheritIf<GenericVectorCallbackOutputTraits<T>,
	!IsBaseOf<Resource, T>::value>,
	public InheritIf<ResourceVectorCallbackOutputTraits<T>,
	IsBaseOf<Resource, T>::value> {
	};

	// A specialization of CallbackOutputTraits to provide the callback system
	// the information on how to handle vectors of pp::Var. Vectors of resources
	// and plain data are handled separately. See the above definition for more.
	template<>
	struct CallbackOutputTraits< std::vector<pp::Var> > {
	// All arrays are output via a PP_ArrayOutput type.
	typedef PP_ArrayOutput APIArgType;

	// We store the array as this adapter which combines the PP_ArrayOutput
	// structure with the underlying std::vector that it will write into.
	typedef VarArrayOutputAdapterWithStorage StorageType;

	// Retrieves the PP_ArrayOutput interface for our vector object that the
	// browser will use to write into our code.
	static inline APIArgType StorageToAPIArg(StorageType& t) {
	return t.pp_array_output();
	}

	// Retrieves the underlying vector that can be passed to the plugin.
	static inline std::vector<pp::Var>& StorageToPluginArg(StorageType& t) {
	return t.output();
	}

	static inline void Initialize(StorageType* /* t */) {}
	};

	} // namespace internal
	} // namespace pp

	#endif // PPAPI_CPP_OUTPUT_TRAITS_H_