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_