[PPAPI] Moving pp::VarResource_Dev API into pp::Var (now stable).

ppapi/cpp/var.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_VAR_H_
 #define PPAPI_CPP_VAR_H_
 
 #include <string>
 #include <vector>
 
 #include "ppapi/c/pp_var.h"
 #include "ppapi/cpp/pass_ref.h"
+#include "ppapi/cpp/resource.h"
 
 /// @file
 /// This file defines the API for handling the passing of data types between
 /// your module and the page.
 namespace pp {
 
 /// A generic type used for passing data types between the module and the page.
 class Var {
  public:
   /// Special value passed to constructor to make <code>NULL</code>.
@@ skipping 20 matching lines @@
   ///
   /// @param[in] d A double value.
   Var(double d);
 
   /// A constructor used to create a UTF-8 character <code>Var</code>.
   Var(const char* utf8_str);  // Must be encoded in UTF-8.
 
   /// A constructor used to create a UTF-8 character <code>Var</code>.
   Var(const std::string& utf8_str);  // Must be encoded in UTF-8.
 
+  /// A constructor used to create a resource <code>Var</code>.
+  explicit Var(const pp::Resource& resource);

[yzshen1, 2014/02/06 18:02:58]

Now that all the others are not 'explicit', maybe we should also support
implicit conversion in this case?

[dmichael (off chromium), 2014/02/06 18:33:14]

I think I prefer that the developer has to know that they're converting a
pp::Resource to a pp::Var, and aren't doing it by accident. (Admittedly, you
could say the same thing about the other ones, but I don't really like those
either :-p ).

[yzshen1, 2014/02/06 19:58:18]

I slightly prefer to be consistent. But I am fine with either approach. :)

[Matt Giuca, 2014/02/07 03:11:22]

I briefly discussed this with sammc@ yesterday. He argued that if it's a managed
(ref-counted) type then it should be explicit, but primitives don't have to be.
That was the rationale for making this one explicit.

I don't have a strong preference, though. Can you guys make a decision?

(Note: we can remove "explicit" later without breaking apps, but we cannot add
"explicit".)

[dmichael (off chromium), 2014/02/07 17:45:28]

I agree in thinking this one is a little different from primitives.
Additionally, we have a lot of functions that take pp::Var, and if we add this
constructor as implicit, it will suddenly be possible to accidentally pass a
pp::Resource in, and the compiler won't catch you. We'd be turning something
that currently is a compile-time mistake in to a runtime mistake. There's really
only 1 function where passing a pp::Resource as a pp::Var currently makes sense,
and that's PostMessage. I think the risk of making mistakes in other APIs
outweighs the benefits of being able to say "PostMessage(my_resource)" instead
of "pp::Var(my_resource)".

Yuzhu, are you okay with that direction?

[yzshen1, 2014/02/07 17:49:36]

Yeah. Your argument makes good sense. I agree we should do it with 'explicit'.
Thanks!

+
   /// A constructor used when you have received a <code>Var</code> as a return
   /// value that has had its reference count incremented for you.
   ///
   /// You will not normally need to use this constructor because
   /// the reference count will not normally be incremented for you.
   Var(PassRef, const PP_Var& var) {
     var_ = var;
     is_managed_ = true;
   }
 
@@ skipping 141 matching lines @@
   ///
   /// @return An double version of this <code>Var</code>.
   double AsDouble() const;
 
   /// AsString() converts this <code>Var</code> to a string. If this object is
   /// not a string, it will assert in debug mode, and return an empty string.
   ///
   /// @return A string version of this <code>Var</code>.
   std::string AsString() const;
 
+  /// Gets the resource contained in the var.
+  ///
+  /// @return The <code>pp::Resource</code> that is contained in the var.
+  pp::Resource AsResource() const;
+
   /// This function returns the internal <code>PP_Var</code>
   /// managed by this <code>Var</code> object.
   ///
   /// @return A const reference to a <code>PP_Var</code>.
   const PP_Var& pp_var() const {
     return var_;
   }
 
   /// Detach() detaches from the internal <code>PP_Var</code> of this
   /// object, keeping the reference count the same. This is used when returning
@@ skipping 82 matching lines @@
  private:
   // Prevent an arbitrary pointer argument from being implicitly converted to
   // a bool at Var construction. If somebody makes such a mistake, (s)he will
   // get a compilation error.
   Var(void* non_scriptable_object_pointer);
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_VAR_H_