/* 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.
 */

/**
 * Defines the PPP_Class_Deprecated struct.
 */
label Chrome {
  M39 = 1.0
};

/**
 * Interface for the plugin to implement JavaScript-accessible objects.
 *
 * This interface has no interface name. Instead, the plugin passes a pointer
 * to this interface to PPB_Var_Deprecated.CreateObject that corresponds to the
 * object being implemented.
 *
 * See the PPB_Var_Deprecated interface for more information on these functions.
 * This interface just allows you to implement the "back end" of those
 * functions, so most of the contract is specified in that interface.
 *
 * See
 *   http://code.google.com/p/ppapi/wiki/InterfacingWithJavaScript
 * for general information on using and implementing vars.
 */
interface PPP_Class_Deprecated {
  /**
   * |name| is guaranteed to be an integer or string type var. Exception is
   * guaranteed non-NULL. An integer is used for |name| when implementing
   * array access into the object. This test should only return true for
   * properties that are not methods.  Use HasMethod() to handle methods.
   */
  PP_Bool HasProperty([in] mem_t object,
                      [in] PP_Var name,
                      [out] PP_Var exception);

  /**
   * |name| is guaranteed to be a string-type. Exception is guaranteed non-NULL.
   * If the method does not exist, return false and don't set the exception.
   * Errors in this function will probably not occur in general usage, but
   * if you need to throw an exception, still return false.
   */
  PP_Bool HasMethod([in] mem_t object,
                 [in] PP_Var name,
                 [out] PP_Var exception);

  /**
   * |name| is guaranteed to be a string-type or an integer-type var. Exception
   * is guaranteed non-NULL. An integer is used for |name| when implementing
   * array access into the object. If the property does not exist, set the
   * exception and return a var of type Void. A property does not exist if
   * a call HasProperty() for the same |name| would return false.
   */
  PP_Var GetProperty([in] mem_t object,
                     [in] PP_Var name,
                     [out] PP_Var exception);

  /**
   * Exception is guaranteed non-NULL.
   *
   * This should include all enumerable properties, including methods. Be sure
   * to set |*property_count| to 0 and |properties| to NULL in all failure
   * cases, these should never be unset when calling this function. The
   * pointers passed in are guaranteed not to be NULL, so you don't have to
   * NULL check them.
   *
   * If you have any properties, allocate the property array with
   * PPB_Core.MemAlloc(sizeof(PP_Var) * property_count) and add a reference
   * to each property on behalf of the caller. The caller is responsible for
   * Release()ing each var and calling PPB_Core.MemFree on the property pointer.
   */
  void GetAllPropertyNames([in] mem_t object,
                           [out] uint32_t property_count,
                           [out, size_is(property_count)] PP_Var[] properties,
                           [out] PP_Var exception);

  /**
   * |name| is guaranteed to be an integer or string type var. Exception is
   * guaranteed non-NULL.
   */
  void SetProperty([in] mem_t object,
                   [in] PP_Var name,
                   [in] PP_Var value,
                   [out] PP_Var exception);

  /**
   * |name| is guaranteed to be an integer or string type var. Exception is
   * guaranteed non-NULL.
   */
  void RemoveProperty([in] mem_t object,
                      [in] PP_Var name,
                      [out] PP_Var exception);

  // TODO(brettw) need native array access here.

  /**
   * |name| is guaranteed to be a string type var. Exception is guaranteed
   * non-NULL
   */
  PP_Var Call([in] mem_t object,
              [in] PP_Var method_name,
              [in] uint32_t argc,
              [in, size_is(argc)] PP_Var[] argv,
              [out] PP_Var exception);

  /** Exception is guaranteed non-NULL. */
  PP_Var Construct([in] mem_t object,
                   [in] uint32_t argc,
                   [in, size_is(argc)] PP_Var[] argv,
                   [out] PP_Var exception);

  /**
   * Called when the reference count of the object reaches 0. Normally, plugins
   * would free their internal data pointed to by the |object| pointer.
   */
  void Deallocate([in] mem_t object);
};
