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 10 label Chrome { 11 M14 = 1.0, 12 M18 = 1.1 13 }; 14 15 /** 16 * PPB_Var API 17 */ 18 interface 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
