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  M34 = 1.2
14};
15
16/**
17 * PPB_Var API
18 */
19interface PPB_Var {
20  /**
21   * AddRef() adds a reference to the given var. If this is not a refcounted
22   * object, this function will do nothing so you can always call it no matter
23   * what the type.
24   *
25   * @param[in] var A <code>PP_Var</code> that will have a reference added.
26   */
27  [version=1.0]
28  void AddRef([in] PP_Var var);
29
30  /**
31   * Release() removes a reference to given var, deleting it if the internal
32   * reference count becomes 0. If the <code>PP_Var</code> is of type
33   * <code>PP_VARTYPE_RESOURCE</code>,
34   * it will implicitly release a reference count on the
35   * <code>PP_Resource</code> (equivalent to PPB_Core::ReleaseResource()).
36   *
37   * If the given var is not a refcounted object, this function will do nothing
38   * so you can always call it no matter what the type.
39   *
40   * @param[in] var A <code>PP_Var</code> that will have a reference removed.
41   */
42  [version=1.0]
43  void Release([in] PP_Var var);
44
45  /**
46   * VarFromUtf8() creates a string var from a string. The string must be
47   * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
48   * specified in <code>len</code>. It is an error if the string is not
49   * valid UTF-8.
50   *
51   * If the length is 0, the <code>*data</code> pointer will not be dereferenced
52   * and may be <code>NULL</code>. Note, however if length is 0, the
53   * "NULL-ness" will not be preserved, as VarToUtf8() will never
54   * return <code>NULL</code> on success, even for empty strings.
55   *
56   * The resulting object will be a refcounted string object. It will be
57   * AddRef'ed for the caller. When the caller is done with it, it should be
58   * Released.
59   *
60   * On error (basically out of memory to allocate the string, or input that
61   * is not valid UTF-8), this function will return a Null var.
62   *
63   * @param[in] module A PP_Module uniquely identifying the module or .nexe.
64   * @param[in] data A string
65   * @param[in] len The length of the string.
66   *
67   * @return A <code>PP_Var</code> structure containing a reference counted
68   * string object.
69   */
70  [version=1.0]
71  PP_Var VarFromUtf8([in] PP_Module module, [in] str_t data, [in] uint32_t len);
72
73  /**
74   * VarFromUtf8() creates a string var from a string. The string must be
75   * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
76   * specified in <code>len</code>. It is an error if the string is not
77   * valid UTF-8.
78   *
79   * If the length is 0, the <code>*data</code> pointer will not be dereferenced
80   * and may be <code>NULL</code>. Note, however if length is 0, the
81   * "NULL-ness" will not be preserved, as VarToUtf8() will never return
82   * <code>NULL</code> on success, even for empty strings.
83   *
84   * The resulting object will be a refcounted string object. It will be
85   * AddRef'ed for the caller. When the caller is done with it, it should be
86   * Released.
87   *
88   * On error (basically out of memory to allocate the string, or input that
89   * is not valid UTF-8), this function will return a Null var.
90   *
91   * @param[in] data A string
92   * @param[in] len The length of the string.
93   *
94   * @return A <code>PP_Var</code> structure containing a reference counted
95   * string object.
96   */
97  [version=1.1]
98  PP_Var VarFromUtf8([in] str_t data, [in] uint32_t len);
99
100  /**
101   * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
102   * string is NOT NULL-terminated. The length will be placed in
103   * <code>*len</code>. If the string is valid but empty the return value will
104   * be non-NULL, but <code>*len</code> will still be 0.
105   *
106   * If the var is not a string, this function will return NULL and
107   * <code>*len</code> will be 0.
108   *
109   * The returned buffer will be valid as long as the underlying var is alive.
110   * If the instance frees its reference, the string will be freed and the
111   * pointer will be to arbitrary memory.
112   *
113   * @param[in] var A PP_Var struct containing a string-type var.
114   * @param[in,out] len A pointer to the length of the string-type var.
115   *
116   * @return A char* encoded in UTF-8.
117   */
118  [version=1.0]
119  str_t VarToUtf8([in] PP_Var var, [out] uint32_t len);
120
121  /**
122   * Converts a resource-type var to a <code>PP_Resource</code>.
123   *
124   * @param[in] var A <code>PP_Var</code> struct containing a resource-type var.
125   *
126   * @return A <code>PP_Resource</code> retrieved from the var, or 0 if the var
127   * is not a resource. The reference count of the resource is incremented on
128   * behalf of the caller.
129   */
130  [version=1.2]
131  PP_Resource VarToResource([in] PP_Var var);
132
133  /**
134   * Creates a new <code>PP_Var</code> from a given resource. Implicitly adds a
135   * reference count on the <code>PP_Resource</code> (equivalent to
136   * PPB_Core::AddRefResource(resource)).
137   *
138   * @param[in] resource A <code>PP_Resource</code> to be wrapped in a var.
139   *
140   * @return A <code>PP_Var</code> created for this resource, with type
141   * <code>PP_VARTYPE_RESOURCE</code>. The reference count of the var is set to
142   * 1 on behalf of the caller.
143   */
144  [version=1.2]
145  PP_Var VarFromResource([in] PP_Resource resource);
146};
147
148