1 // Copyright (c) 2010 Marshall A. Greenblatt. All rights reserved. 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are 5 // met: 6 // 7 // * Redistributions of source code must retain the above copyright 8 // notice, this list of conditions and the following disclaimer. 9 // * Redistributions in binary form must reproduce the above 10 // copyright notice, this list of conditions and the following disclaimer 11 // in the documentation and/or other materials provided with the 12 // distribution. 13 // * Neither the name of Google Inc. nor the name Chromium Embedded 14 // Framework nor the names of its contributors may be used to endorse 15 // or promote products derived from this software without specific prior 16 // written permission. 17 // 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 #ifndef CEF_INCLUDE_INTERNAL_CEF_STRING_TYPES_H_ 31 #define CEF_INCLUDE_INTERNAL_CEF_STRING_TYPES_H_ 32 #pragma once 33 34 // CEF provides functions for converting between UTF-8, -16 and -32 strings. 35 // CEF string types are safe for reading from multiple threads but not for 36 // modification. It is the user's responsibility to provide synchronization if 37 // modifying CEF strings from multiple threads. 38 39 #include <stddef.h> 40 41 #include "include/base/cef_basictypes.h" 42 #include "include/internal/cef_export.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 // CEF string type definitions. Whomever allocates |str| is responsible for 49 // providing an appropriate |dtor| implementation that will free the string in 50 // the same memory space. When reusing an existing string structure make sure 51 // to call |dtor| for the old value before assigning new |str| and |dtor| 52 // values. Static strings will have a NULL |dtor| value. Using the below 53 // functions if you want this managed for you. 54 55 typedef struct _cef_string_wide_t { 56 wchar_t* str; 57 size_t length; 58 void (*dtor)(wchar_t* str); 59 } cef_string_wide_t; 60 61 typedef struct _cef_string_utf8_t { 62 char* str; 63 size_t length; 64 void (*dtor)(char* str); 65 } cef_string_utf8_t; 66 67 typedef struct _cef_string_utf16_t { 68 char16* str; 69 size_t length; 70 void (*dtor)(char16* str); 71 } cef_string_utf16_t; 72 73 /// 74 // These functions set string values. If |copy| is true (1) the value will be 75 // copied instead of referenced. It is up to the user to properly manage 76 // the lifespan of references. 77 /// 78 79 CEF_EXPORT int cef_string_wide_set(const wchar_t* src, 80 size_t src_len, 81 cef_string_wide_t* output, 82 int copy); 83 CEF_EXPORT int cef_string_utf8_set(const char* src, 84 size_t src_len, 85 cef_string_utf8_t* output, 86 int copy); 87 CEF_EXPORT int cef_string_utf16_set(const char16* src, 88 size_t src_len, 89 cef_string_utf16_t* output, 90 int copy); 91 92 /// 93 // Convenience macros for copying values. 94 /// 95 96 #define cef_string_wide_copy(src, src_len, output) \ 97 cef_string_wide_set(src, src_len, output, true) 98 #define cef_string_utf8_copy(src, src_len, output) \ 99 cef_string_utf8_set(src, src_len, output, true) 100 #define cef_string_utf16_copy(src, src_len, output) \ 101 cef_string_utf16_set(src, src_len, output, true) 102 103 /// 104 // These functions clear string values. The structure itself is not freed. 105 /// 106 107 CEF_EXPORT void cef_string_wide_clear(cef_string_wide_t* str); 108 CEF_EXPORT void cef_string_utf8_clear(cef_string_utf8_t* str); 109 CEF_EXPORT void cef_string_utf16_clear(cef_string_utf16_t* str); 110 111 /// 112 // These functions compare two string values with the same results as strcmp(). 113 /// 114 115 CEF_EXPORT int cef_string_wide_cmp(const cef_string_wide_t* str1, 116 const cef_string_wide_t* str2); 117 CEF_EXPORT int cef_string_utf8_cmp(const cef_string_utf8_t* str1, 118 const cef_string_utf8_t* str2); 119 CEF_EXPORT int cef_string_utf16_cmp(const cef_string_utf16_t* str1, 120 const cef_string_utf16_t* str2); 121 122 /// 123 // These functions convert between UTF-8, -16, and -32 strings. They are 124 // potentially slow so unnecessary conversions should be avoided. The best 125 // possible result will always be written to |output| with the boolean return 126 // value indicating whether the conversion is 100% valid. 127 /// 128 129 CEF_EXPORT int cef_string_wide_to_utf8(const wchar_t* src, 130 size_t src_len, 131 cef_string_utf8_t* output); 132 CEF_EXPORT int cef_string_utf8_to_wide(const char* src, 133 size_t src_len, 134 cef_string_wide_t* output); 135 136 CEF_EXPORT int cef_string_wide_to_utf16(const wchar_t* src, 137 size_t src_len, 138 cef_string_utf16_t* output); 139 CEF_EXPORT int cef_string_utf16_to_wide(const char16* src, 140 size_t src_len, 141 cef_string_wide_t* output); 142 143 CEF_EXPORT int cef_string_utf8_to_utf16(const char* src, 144 size_t src_len, 145 cef_string_utf16_t* output); 146 CEF_EXPORT int cef_string_utf16_to_utf8(const char16* src, 147 size_t src_len, 148 cef_string_utf8_t* output); 149 150 /// 151 // These functions convert an ASCII string, typically a hardcoded constant, to a 152 // Wide/UTF16 string. Use instead of the UTF8 conversion routines if you know 153 // the string is ASCII. 154 /// 155 156 CEF_EXPORT int cef_string_ascii_to_wide(const char* src, 157 size_t src_len, 158 cef_string_wide_t* output); 159 CEF_EXPORT int cef_string_ascii_to_utf16(const char* src, 160 size_t src_len, 161 cef_string_utf16_t* output); 162 163 /// 164 // It is sometimes necessary for the system to allocate string structures with 165 // the expectation that the user will free them. The userfree types act as a 166 // hint that the user is responsible for freeing the structure. 167 /// 168 169 typedef cef_string_wide_t* cef_string_userfree_wide_t; 170 typedef cef_string_utf8_t* cef_string_userfree_utf8_t; 171 typedef cef_string_utf16_t* cef_string_userfree_utf16_t; 172 173 /// 174 // These functions allocate a new string structure. They must be freed by 175 // calling the associated free function. 176 /// 177 178 CEF_EXPORT cef_string_userfree_wide_t cef_string_userfree_wide_alloc(); 179 CEF_EXPORT cef_string_userfree_utf8_t cef_string_userfree_utf8_alloc(); 180 CEF_EXPORT cef_string_userfree_utf16_t cef_string_userfree_utf16_alloc(); 181 182 /// 183 // These functions free the string structure allocated by the associated 184 // alloc function. Any string contents will first be cleared. 185 /// 186 187 CEF_EXPORT void cef_string_userfree_wide_free(cef_string_userfree_wide_t str); 188 CEF_EXPORT void cef_string_userfree_utf8_free(cef_string_userfree_utf8_t str); 189 CEF_EXPORT void cef_string_userfree_utf16_free(cef_string_userfree_utf16_t str); 190 191 /// 192 // These functions convert utf16 string case using the current ICU locale. This 193 // may change the length of the string in some cases. 194 /// 195 196 CEF_EXPORT int cef_string_utf16_to_lower(const char16* src, 197 size_t src_len, 198 cef_string_utf16_t* output); 199 CEF_EXPORT int cef_string_utf16_to_upper(const char16* src, 200 size_t src_len, 201 cef_string_utf16_t* output); 202 203 #ifdef __cplusplus 204 } 205 #endif 206 207 #endif // CEF_INCLUDE_INTERNAL_CEF_STRING_TYPES_H_ 208