• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
5
6/**
7 * This file defines the <code>PPB_Var</code> struct.
8 */
9
10label Chrome {
11  M14 = 1.0,
12  M18 = 1.1
13};
14
15/**
16 * PPB_Var API
17 */
18interface PPB_Var {
19  /**
20   * AddRef() adds a reference to the given var. If this is not a refcounted
21   * object, this function will do nothing so you can always call it no matter
22   * what the type.
23   *
24   * @param[in] var A <code>PP_Var</code> that will have a reference added.
25   */
26  [version=1.0]
27  void AddRef([in] PP_Var var);
28
29  /**
30   * Release() removes a reference to given var, deleting it if the internal
31   * reference count becomes 0. If the given var is not a refcounted object,
32   * this function will do nothing so you can always call it no matter what
33   * the type.
34   *
35   * @param[in] var A <code>PP_Var</code> that will have a reference removed.
36   */
37  [version=1.0]
38  void Release([in] PP_Var var);
39
40  /**
41   * VarFromUtf8() creates a string var from a string. The string must be
42   * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
43   * specified in <code>len</code>. It is an error if the string is not
44   * valid UTF-8.
45   *
46   * If the length is 0, the <code>*data</code> pointer will not be dereferenced
47   * and may be <code>NULL</code>. Note, however if length is 0, the
48   * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
49   * return <code>NULL</code> on success, even for empty strings.
50   *
51   * The resulting object will be a refcounted string object. It will be
52   * AddRef'ed for the caller. When the caller is done with it, it should be
53   * Released.
54   *
55   * On error (basically out of memory to allocate the string, or input that
56   * is not valid UTF-8), this function will return a Null var.
57   *
58   * @param[in] module A PP_Module uniquely identifying the module or .nexe.
59   * @param[in] data A string
60   * @param[in] len The length of the string.
61   *
62   * @return A <code>PP_Var</code> structure containing a reference counted
63   * string object.
64   */
65  [version=1.0]
66  PP_Var VarFromUtf8([in] PP_Module module, [in] str_t data, [in] uint32_t len);
67
68  /**
69   * VarFromUtf8() creates a string var from a string. The string must be
70   * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
71   * specified in <code>len</code>. It is an error if the string is not
72   * valid UTF-8.
73   *
74   * If the length is 0, the <code>*data</code> pointer will not be dereferenced
75   * and may be <code>NULL</code>. Note, however if length is 0, the
76   * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
77   * return <code>NULL</code> on success, even for empty strings.
78   *
79   * The resulting object will be a refcounted string object. It will be
80   * AddRef'ed for the caller. When the caller is done with it, it should be
81   * Released.
82   *
83   * On error (basically out of memory to allocate the string, or input that
84   * is not valid UTF-8), this function will return a Null var.
85   *
86   * @param[in] data A string
87   * @param[in] len The length of the string.
88   *
89   * @return A <code>PP_Var</code> structure containing a reference counted
90   * string object.
91   */
92  [version=1.1]
93  PP_Var VarFromUtf8([in] str_t data, [in] uint32_t len);
94
95  /**
96   * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
97   * string is NOT NULL-terminated. The length will be placed in
98   * <code>*len</code>. If the string is valid but empty the return value will
99   * be non-NULL, but <code>*len</code> will still be 0.
100   *
101   * If the var is not a string, this function will return NULL and
102   * <code>*len</code> will be 0.
103   *
104   * The returned buffer will be valid as long as the underlying var is alive.
105   * If the instance frees its reference, the string will be freed and the
106   * pointer will be to arbitrary memory.
107   *
108   * @param[in] var A PP_Var struct containing a string-type var.
109   * @param[in,out] len A pointer to the length of the string-type var.
110   *
111   * @return A char* encoded in UTF-8.
112   */
113  [version=1.0]
114  str_t VarToUtf8([in] PP_Var var, [out] uint32_t len);
115};
116
117