[Android] Implement 3-way sensor fallback for Device Orientation.
[chromium-blink-merge.git] / ppapi / api / ppb_var.idl
blobcc12b1bb3b759039afd3c51afe44cc61ea029419
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 */
6 /**
7 * This file defines the <code>PPB_Var</code> struct.
8 */
10 label Chrome {
11 M14 = 1.0,
12 M18 = 1.1,
13 M34 = 1.2
16 /**
17 * PPB_Var API
19 interface 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.
25 * @param[in] var A <code>PP_Var</code> that will have a reference added.
27 [version=1.0]
28 void AddRef([in] PP_Var var);
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()).
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.
40 * @param[in] var A <code>PP_Var</code> that will have a reference removed.
42 [version=1.0]
43 void Release([in] PP_Var var);
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.
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.
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.
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.
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.
67 * @return A <code>PP_Var</code> structure containing a reference counted
68 * string object.
70 [version=1.0]
71 PP_Var VarFromUtf8([in] PP_Module module, [in] str_t data, [in] uint32_t len);
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.
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.
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.
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.
91 * @param[in] data A string
92 * @param[in] len The length of the string.
94 * @return A <code>PP_Var</code> structure containing a reference counted
95 * string object.
97 [version=1.1]
98 PP_Var VarFromUtf8([in] str_t data, [in] uint32_t len);
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.
106 * If the var is not a string, this function will return NULL and
107 * <code>*len</code> will be 0.
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.
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.
116 * @return A char* encoded in UTF-8.
118 [version=1.0]
119 str_t VarToUtf8([in] PP_Var var, [out] uint32_t len);
122 * Converts a resource-type var to a <code>PP_Resource</code>.
124 * @param[in] var A <code>PP_Var</code> struct containing a resource-type var.
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.
130 [version=1.2]
131 PP_Resource VarToResource([in] PP_Var var);
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)).
138 * @param[in] resource A <code>PP_Resource</code> to be wrapped in a var.
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.
144 [version=1.2]
145 PP_Var VarFromResource([in] PP_Resource resource);