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