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