Create a VarPrivate interface to contain the scripting helper functions of Var.

ppapi/c/pp_var.h

 /* Copyright (c) 2010 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_C_PP_VAR_H_
 #define PPAPI_C_PP_VAR_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_stdint.h"
 
 /**
  * @file
  * This file defines the API for handling the passing of data types between
  * your module and the page.
  */
 
 /**
  *
  * @addtogroup Enums
  * @{
  */
 
 /**
  * PP_VarType is an enumeration of the different types that can be contained
  * within a PP_VAR structure.
  */
 typedef enum {
+  /**
+   * A var with an undefined value.

[dmichael(do not use this one), 2011/04/08 22:16:28]

Maybe just say 'An undefined value.' to be consistent with the others.

+   */
   PP_VARTYPE_UNDEFINED,
+
+  /**
+   * A NULL value. This is similar to undefined, but JavaScript differentiates
+   * the two so we expose it here as well.
+   */
   PP_VARTYPE_NULL,
+
+  /**
+   * A boolean value, use the as_bool member of the var.
+   */
   PP_VARTYPE_BOOL,
+
+  /**
+   * A 32-bit integer value. Use the as_int member of the var.
+   */
   PP_VARTYPE_INT32,
+
+  /**
+   * A double-precision floating point value. Use the as_double member of the
+   * var.
+   */
   PP_VARTYPE_DOUBLE,
+
+  /**
+   * The Var represents a string. The as_id field is used to identify the
+   * string, which may be created and retrieved from the PPB_Var interface.
+   */
   PP_VARTYPE_STRING,
-  PP_VARTYPE_OBJECT
+
+  /**
+   * Represents a JavaScript object. This vartype is not currently usable

[dmichael(do not use this one), 2011/04/08 22:16:28]

maybe take out 'currently'?  We should avoid giving hope that we will provide
that, unless we're sure we will.

+   * from plugins, although it is used internally for some tasks.
+   */
+  PP_VARTYPE_OBJECT,
+
+  /**
+   * Arrays and dictionaries are not currently supported but will be added
+   * in future revisions. These objects are reference counteed so be sure

[dmichael(do not use this one), 2011/04/08 22:16:28]

s/counteed/counted

+   * to properly AddRef/Release them as you would with strings to ensure your
+   * plugin will continue to work with future versions of the API.
+   */
+  PP_VARTYPE_ARRAY,
+  PP_VARTYPE_DICTIONARY

[dmichael(do not use this one), 2011/04/08 22:16:28]

After thinking about it a little more, I still have my doubts that we need to
reference-count these.  For that matter, I would rather see string not be
ref-counted;  it seems like premature optimization.  I think ref counting is
harder to understand than just saying "You are responsible for deleting this
when you are done by calling PPB_Core.MemFree."  Provide a deep-copy for
DICTIONARY.  Users can ref-count with their own scheme if they want.

Ref counting is important for PP_VARTYPE_OBJECT, since it's shared between
browser and plugin, but strint, array, and dictionary can just transfer
ownership.

You guys are probably right, but I just don't understand what the big advantage
is with forcing ref counting on developers when the objects aren't shared
between browser and plugin.

Maybe we can chat about this early next week...

[brettw, 2011/04/09 16:41:34]

If we had designed this API without scripting from the beginning then it's quite
possible we would have come up with a non-refcounting solution.

It seems like it would be a bad idea to have some vars be refcounted and some
require a special free function since it would be impossible to know how to do
any memory management. And given that we have a refcounted API today, I think
it's not really practical to change (and it's worked pretty well, the C++ API is
pretty clean and you don't really have to worry about this stuff).

[dmichael (off chromium), 2011/04/11 00:09:16]

Thanks for explaining.  I think we may still need some special 'free' function,
because removing a ref count from a dictionary with a cycle back to the root
shouldn't delete it.  So a nice 'delete this whole graph' function may be
worthwhile.  But otherwise, I can live with ref counting.

 } PP_VarType;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
 /**
  * @}
  */
 
 /**
  * @addtogroup Structs
  * @{
  */
@@ skipping 20 matching lines @@
    *  for 32-bit x86, and some align on 4-byte boundaries.
    */
   int32_t padding;
 
   union {
     PP_Bool as_bool;
     int32_t as_int;
     double as_double;
 
     /**
-     * Internal ID for strings and objects. The identifier is an opaque handle
-     * assigned by the browser to the plugin. It is guaranteed never to be 0,
-     * so a plugin can initialize this ID to 0 to indicate a "NULL handle."
+     * Internal ID for strings objects, arrays, and dictionaries. The
+     * identifier is an opaque handle assigned by the browser to the plugin. It
+     * is guaranteed never to be 0, so a plugin can initialize this ID to 0 to
+     * indicate a "NULL handle."

[dmichael(do not use this one), 2011/04/08 22:16:28]

if we _don't_ do reference counting, we can use a bare pointer for
array/dictionary.  If we do ref counting, then I agree with the doc.

      */
     int64_t as_id;
   } value;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
 /**
  * @}
  */
 
 /**
@@ skipping 55 matching lines @@
   struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };
   result.value.as_double = value;
   return result;
 }
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PP_VAR_H_ */