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