App APIs in Pepper: C++ APIs

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/dev/array_dev.h"
+#include "ppapi/cpp/dev/struct_wrapper_base_dev.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.
 
@@ skipping 94 matching lines @@
   // resource object type.
   static inline T StorageToPluginArg(StorageType& t) {
     return T(PASS_REF, t);
   }
 
   static inline void Initialize(StorageType* t) {
     *t = 0;
   }
 };
 
+// This class is parameterized by derived classes of
+// pp::StructWrapperIdentifier, for example,
+// StructWrapperCallbackOutputTraits<pp::alarms::Alarm_Dev>. It is used as a
+// base class for CallbackOutputTraits below.
+template<typename T>
+struct StructWrapperCallbackOutputTraits {
+  typedef typename T::COutputType APIArgType;
+  typedef T StorageType;
+
+  // Returns the underlying C struct of |t|, which can be passed to the browser
+  // as an output parameter.
+  static inline APIArgType StorageToAPIArg(StorageType& t) {
+    return t.StartRawUpdate();
+  }
+
+  // For each |t| passed into StorageToAPIArg(), this method must be called
+  // exactly once in order to match StartRawUpdate() and EndRawUpdate().
+  static inline T& StorageToPluginArg(StorageType& t) {
+    t.EndRawUpdate();
+    return t;
+  }
+
+  static inline void Initialize(StorageType* /* t */) {}
+};
+
 // 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.
+// covers resources, struct wrapper objects and POD (ints, structs, etc.)
+// by inheriting from the appropriate base class depending on whether the given
+// type derives from pp::Resource or pp::StructWrapperIdentifier. This trick
+// allows us to do this once rather than writing specializations for every
+// object type.
 template<typename T>
 struct CallbackOutputTraits
-    : public InheritIf<GenericCallbackOutputTraits<T>,
-                       !IsBaseOf<Resource, T>::value>,
-      public InheritIf<ResourceCallbackOutputTraits<T>,
-                       IsBaseOf<Resource, T>::value> {
+    : public InheritIf<ResourceCallbackOutputTraits<T>,
+                       IsBaseOf<Resource, T>::value>,
+      public InheritIf<StructWrapperCallbackOutputTraits<T>,
+                       IsBaseOf<StructWrapperIdentifier, T>::value>,
+      public InheritIf<GenericCallbackOutputTraits<T>,
+                       !IsBaseOf<Resource, T>::value &&
+                       !IsBaseOf<StructWrapperIdentifier, 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;
@@ skipping 30 matching lines @@
   // 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;
   }
 };
 
+// A specialization of CallbackOutputTraits for pp::Array parameters.
+template<typename T>
+struct CallbackOutputTraits<Array<T> > {

[dmichael (off chromium), 2013/12/17 18:03:25]

Would it be practical to put this in the header for Array instead? I would
rather not add a bunch of includes to this file for clients who don't need them.

Similarly, it would be nice if the StructWrapper stuff could go somewhere else.
I don't think you need StructWrapperIdentifier. Since the code is all generated
anyway, each "struct wrapper" header can put an explicit full specialization of
CallbackOutputTraits in its header. E.g.:
template <>
CallbackOutputTraits<AlarmDev>
    : public StructWrapperCallbackOutputTraits<AlarmDev> {
};

[yzshen1, 2013/12/17 23:52:21]

It seems we put most output traits in this file. For example, the specialization
for Var (and others) is also in this file. If we put output traits
specialization in different files, it might be harder for readers to figure out
which template is applied for a given type .

(But I don't have a very strong preference as long as it is consistent.)
Please see my comments in struct_wrapper_base_dev.h.

Thanks!

+  typedef typename Array<T>::COutputType APIArgType;
+  typedef Array<T> StorageType;
+
+  // Returns the underlying C struct of |t|, which can be passed to the browser
+  // as an output parameter.
+  static inline APIArgType StorageToAPIArg(StorageType& t) {
+    return t.StartRawUpdate();
+  }
+
+  // For each |t| passed into StorageToAPIArg(), this method must be called
+  // exactly once in order to match StartRawUpdate() and EndRawUpdate().
+  static inline Array<T>& StorageToPluginArg(StorageType& t) {
+    t.EndRawUpdate();
+    return t;
+  }
+
+  static inline void Initialize(StorageType* /* t */) {}
+};
+
 // 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.
@@ skipping 76 matching lines @@
     return t.output();
   }
 
   static inline void Initialize(StorageType* /* t */) {}
 };
 
 }  // namespace internal
 }  // namespace pp
 
 #endif  // PPAPI_CPP_OUTPUT_TRAITS_H_