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