1 /* 2 * Copyright 2012-2016 James Geboski <jgeboski@gmail.com> 3 * 4 * This program is free software: you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License as published by 6 * the Free Software Foundation, either version 2 of the License, or 7 * (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this program. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #ifndef _STEAM_UTIL_H_ 19 #define _STEAM_UTIL_H_ 20 21 /** 22 * SECTION:util 23 * @section_id: steam-util 24 * @short_description: <filename>steam-util.h</filename> 25 * @title: General Utilities 26 * 27 * The general utilities. 28 */ 29 30 #include "steam-glib.h" 31 32 /** 33 * STEAM_UTIL_ENUM_NULL: 34 * 35 * The #NULL terminating #SteamUtilEnum. 36 */ 37 #define STEAM_UTIL_ENUM_NULL {0, NULL} 38 39 typedef struct _SteamUtilEnum SteamUtilEnum; 40 typedef struct _SteamUtilTimeSpan SteamUtilTimeSpan; 41 42 /** 43 * SteamDebugLevel: 44 * STEAM_UTIL_DEBUG_LEVEL_MISC: Miscellaneous message. 45 * STEAM_UTIL_DEBUG_LEVEL_INFO: Information message. 46 * STEAM_UTIL_DEBUG_LEVEL_WARN: Warning message. 47 * STEAM_UTIL_DEBUG_LEVEL_ERROR: Error message. 48 * STEAM_UTIL_DEBUG_LEVEL_FATAL: Fatal message. 49 * 50 * The log message types. 51 */ 52 typedef enum 53 { 54 STEAM_UTIL_DEBUG_LEVEL_MISC, 55 STEAM_UTIL_DEBUG_LEVEL_INFO, 56 STEAM_UTIL_DEBUG_LEVEL_WARN, 57 STEAM_UTIL_DEBUG_LEVEL_ERROR, 58 STEAM_UTIL_DEBUG_LEVEL_FATAL 59 } SteamDebugLevel; 60 61 /** 62 * SteamUtilEnum: 63 * @val: The value. 64 * @ptr: The pointer. 65 * 66 * Represents a value/pointer pair for an enumerator. 67 */ 68 struct _SteamUtilEnum 69 { 70 guint val; 71 gpointer ptr; 72 }; 73 74 /** 75 * SteamUtilTimeSpan: 76 * @name: The name. 77 * @span: The span. 78 * 79 * Represents a name/span pair for a time span. 80 */ 81 struct _SteamUtilTimeSpan 82 { 83 gchar *name; 84 gint64 span; 85 }; 86 87 /** 88 * steam_util_debug: 89 * @level: The #SteamDebugLevel. 90 * @format: The format string literal. 91 * @...: The arguments for @format. 92 * 93 * Logs a debugging message. 94 */ 95 void 96 steam_util_debug(SteamDebugLevel level, const gchar *format, ...) 97 G_GNUC_PRINTF(2, 3); 98 99 /** 100 * steam_util_vdebug: 101 * @level: The #SteamDebugLevel. 102 * @format: The format string literal. 103 * @ap: The #va_list. 104 * 105 * Logs a debugging message. 106 */ 107 void 108 steam_util_vdebug(SteamDebugLevel level, const gchar *format, va_list ap); 109 110 /** 111 * steam_util_debug_misc: 112 * @format: The format string literal. 113 * @...: The arguments for @format. 114 * 115 * Logs a debugging message with the level of 116 * #STEAM_UTIL_DEBUG_LEVEL_MISC. 117 * 118 */ 119 void 120 steam_util_debug_misc(const gchar *format, ...) 121 G_GNUC_PRINTF(1, 2); 122 123 /** 124 * steam_util_debug_info: 125 * @format: The format string literal. 126 * @...: The arguments for @format. 127 * 128 * Logs a debugging message with the level of 129 * #STEAM_UTIL_DEBUG_LEVEL_INFO. 130 * 131 */ 132 void 133 steam_util_debug_info(const gchar *format, ...) 134 G_GNUC_PRINTF(1, 2); 135 136 /** 137 * steam_util_debug_warn: 138 * @format: The format string literal. 139 * @...: The arguments for @format. 140 * 141 * Logs a debugging message with the level of 142 * #STEAM_UTIL_DEBUG_LEVEL_WARN. 143 * 144 */ 145 void 146 steam_util_debug_warn(const gchar *format, ...) 147 G_GNUC_PRINTF(1, 2); 148 149 /** 150 * steam_util_debug_error: 151 * @format: The format string literal. 152 * @...: The arguments for @format. 153 * 154 * Logs a debugging message with the level of 155 * #STEAM_UTIL_DEBUG_LEVEL_ERROR. 156 * 157 */ 158 void 159 steam_util_debug_error(const gchar *format, ...) 160 G_GNUC_PRINTF(1, 2); 161 162 /** 163 * steam_util_debug_fatal: 164 * @format: The format string literal. 165 * @...: The arguments for @format. 166 * 167 * Logs a debugging message with the level of 168 * #STEAM_UTIL_DEBUG_LEVEL_FATAL. 169 * 170 */ 171 void 172 steam_util_debug_fatal(const gchar *format, ...) 173 G_GNUC_PRINTF(1, 2); 174 175 /** 176 * steam_util_enum_ptr: 177 * @enums: The array of #SteamUtilEnum. 178 * @def: The default return value. 179 * @val: The enumerator value. 180 * 181 * Gets the enumerator pointer from its value. 182 * 183 * Returns: The enumerator pointer or #NULL on error. 184 */ 185 gpointer 186 steam_util_enum_ptr(const SteamUtilEnum *enums, gpointer def, guint val); 187 188 /** 189 * steam_util_enum_ptrs: 190 * @enums: The array of #SteamUtilEnum. 191 * @vals: The enumerator values. 192 * 193 * Gets the enumerator pointers from its value. The returned array 194 * should be freed when no longer needed. 195 * 196 * Returns: The enumerator pointer array. 197 */ 198 gpointer * 199 steam_util_enum_ptrs(const SteamUtilEnum *enums, guint vals); 200 201 /** 202 * steam_util_enum_val: 203 * @enums: The array of #SteamUtilEnum. 204 * @ptr: The enumerator pointer. 205 * @def: The default return value. 206 * @cmpfunc: The #GCompareFunc. 207 * 208 * Gets the enumerator value from its pointer. 209 * 210 * Returns: The enumerator value or `0` on error. 211 */ 212 guint 213 steam_util_enum_val(const SteamUtilEnum *enums, guint def, 214 gconstpointer ptr, GCompareFunc cmpfunc); 215 216 /** 217 * steam_util_str_hex2bytes: 218 * @str: The hexadecimal string. 219 * 220 * Converts the hexadecimal string to a #GByteArray. The returned 221 * #GByteArray should be freed with #g_byte_array_free() when no 222 * longer needed. 223 * 224 * Returns: The #GByteArray or #NULL on error. 225 */ 226 GByteArray * 227 steam_util_str_hex2bytes(const gchar *str); 228 229 /** 230 * steam_util_str_iequal: 231 * @s1: The first string. 232 * @s2: The second string. 233 * 234 * Compare two strings case insensitively. This is useful for where 235 * the return value must be a boolean, such as with a #GEqualFunc. 236 * 237 * Returns: #TRUE if the strings are equal, otherwise #FALSE. 238 */ 239 gboolean 240 steam_util_str_iequal(const gchar *s1, const gchar *s2); 241 242 /** 243 * steam_util_time_span_str: 244 * @span: The #GTimeSpan. 245 * 246 * Gets the string representation of the timespan. The returned string 247 * should be freed with #g_free() when no longer needed. 248 * 249 * Returns: The string representation. 250 */ 251 gchar * 252 steam_util_time_span_str(GTimeSpan span); 253 254 /** 255 * steam_util_time_since_utc: 256 * @span: The timestamp (UTC). 257 * 258 * Gets the string representation of the timespan since the given 259 * timestamp. The returned string should be freed with #g_free() when 260 * no longer needed. 261 * 262 * Returns: The string representation. 263 */ 264 gchar * 265 steam_util_time_since_utc(gint64 timestamp); 266 267 /** 268 * steam_util_ustrchr: 269 * @str: The string. 270 * @chr: The character. 271 * 272 * Find the first occurrence of the character in a string not contained 273 * inside quotes (single or double). 274 * 275 * Returns: A pointer to the character or #NULL on error. 276 */ 277 gchar * 278 steam_util_ustrchr(const gchar *str, gchar chr); 279 280 #endif /* _STEAM_UTIL_H_ */ 281