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 Wed Dec 14 18:08:00 2011. */ 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_stdint.h" 15 #include "ppapi/c/pp_var.h" 16 17 #define PPB_VAR_INTERFACE_1_0 "PPB_Var;1.0" 18 #define PPB_VAR_INTERFACE_1_1 "PPB_Var;1.1" 19 #define PPB_VAR_INTERFACE PPB_VAR_INTERFACE_1_1 20 21 /** 22 * @file 23 * This file defines the <code>PPB_Var</code> struct. 24 */ 25 26 27 /** 28 * @addtogroup Interfaces 29 * @{ 30 */ 31 /** 32 * PPB_Var API 33 */ 34 struct PPB_Var_1_1 { 35 /** 36 * AddRef() adds a reference to the given var. If this is not a refcounted 37 * object, this function will do nothing so you can always call it no matter 38 * what the type. 39 * 40 * @param[in] var A <code>PP_Var</code> that will have a reference added. 41 */ 42 void (*AddRef)(struct PP_Var var); 43 /** 44 * Release() removes a reference to given var, deleting it if the internal 45 * reference count becomes 0. If the given var is not a refcounted object, 46 * this function will do nothing so you can always call it no matter what 47 * the type. 48 * 49 * @param[in] var A <code>PP_Var</code> that will have a reference removed. 50 */ 51 void (*Release)(struct PP_Var var); 52 /** 53 * VarFromUtf8() creates a string var from a string. The string must be 54 * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be 55 * specified in <code>len</code>. It is an error if the string is not 56 * valid UTF-8. 57 * 58 * If the length is 0, the <code>*data</code> pointer will not be dereferenced 59 * and may be <code>NULL</code>. Note, however if length is 0, the 60 * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never 61 * return <code>NULL</code> on success, even for empty strings. 62 * 63 * The resulting object will be a refcounted string object. It will be 64 * AddRef'ed for the caller. When the caller is done with it, it should be 65 * Released. 66 * 67 * On error (basically out of memory to allocate the string, or input that 68 * is not valid UTF-8), this function will return a Null var. 69 * 70 * @param[in] data A string 71 * @param[in] len The length of the string. 72 * 73 * @return A <code>PP_Var</code> structure containing a reference counted 74 * string object. 75 */ 76 struct PP_Var (*VarFromUtf8)(const char* data, uint32_t len); 77 /** 78 * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This 79 * string is NOT NULL-terminated. The length will be placed in 80 * <code>*len</code>. If the string is valid but empty the return value will 81 * be non-NULL, but <code>*len</code> will still be 0. 82 * 83 * If the var is not a string, this function will return NULL and 84 * <code>*len</code> will be 0. 85 * 86 * The returned buffer will be valid as long as the underlying var is alive. 87 * If the instance frees its reference, the string will be freed and the 88 * pointer will be to arbitrary memory. 89 * 90 * @param[in] var A PP_Var struct containing a string-type var. 91 * @param[in,out] len A pointer to the length of the string-type var. 92 * 93 * @return A char* encoded in UTF-8. 94 */ 95 const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len); 96 }; 97 98 typedef struct PPB_Var_1_1 PPB_Var; 99 100 struct PPB_Var_1_0 { 101 void (*AddRef)(struct PP_Var var); 102 void (*Release)(struct PP_Var var); 103 struct PP_Var (*VarFromUtf8)(PP_Module module, 104 const char* data, 105 uint32_t len); 106 const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len); 107 }; 108 /** 109 * @} 110 */ 111 112 #endif /* PPAPI_C_PPB_VAR_H_ */ 113 114
