5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2008 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/Global Variable Interface
24 * The Global Variable API can be used to set variables as global in the
25 * process or in current thread. On some platforms, like Symbian, global
26 * variables cannot be used directly. This API can be used to write
27 * portable code that can use global variables on all supported platforms.
31 * // Initialize global buffer
32 * silc_global_set_var("somebuf", 256, NULL, FALSE);
34 * // Retrieve the buffer
35 * unsigned char *buf = silc_global_get_var("somebuf", FALSE);
37 * // Set integer and its value global in the current thread
38 * SilcUInt32 integer = 100;
39 * silc_global_set_var("someint", 4, &integer, TRUE);
41 * // Retrieve the integer and change its value
42 * SilcUInt32 *intptr = silc_global_get_var("someint", TRUE);
50 /****f* silcutil/silc_global_set_var
54 * void *silc_global_set_var(const char *name, SilcUInt32 variable_size,
55 * void *initial_value, SilcBool tls);
59 * Sets a variable of size of `variable_size' bytes as a global variable
60 * under the name of `name'. If `initial_value' is non-NULL it is
61 * considered to be the initial value of the stored variable. If it is
62 * NULL this will initialize the variable as all zeroes.
64 * If variable with `name' already exists it will be replaced with the
65 * `initial_value' or as all zeroes, and the old pointer will become
68 * If `tls' is FALSE the variable is visible to all threads in the process.
69 * If it is TRUE the variable is visible only in the current thread. The
70 * variable can be retrieved using the same name by calling the
71 * silc_global_get_var.
73 * Returns NULL and sets silc_errno if the variable could not be added, or
74 * a pointer to the added variable otherwise.
78 * // Initialize global buffer
79 * silc_global_set_var("somebuf", 256, NULL, FALSE);
81 * // Retrieve the buffer
82 * unsigned char *buf = silc_global_get_var("somebuf", FALSE);
84 * // Set integer global
85 * SilcUInt32 integer = 100;
86 * silc_global_set_var("someint", 4, &integer, FALSE);
88 * // Retrieve the integer and change its value
89 * SilcUInt32 *intptr = silc_global_get_var("someint", FALSE);
92 * // Set structure as global in the thread
93 * silc_global_set_var("somestruct", sizeof(*context), NULL, TRUE);
95 * // Retrieve the context
96 * context = silc_global_get_var("somestruct", TRUE);
99 void *silc_global_set_var(const char *name, SilcUInt32 variable_size,
100 void *initial_value, SilcBool tls);
102 /****f* silcutil/silc_global_get_var
106 * void *silc_global_get_var(const char *name, SilcBool tls);
110 * Returns the variable from the global variable storage that has been
111 * stored under the name `name'. If `tls' is FALSE this fetches the
112 * variable from global storage, if it is TRUE it is fetched from the
113 * Thread-local storage. Returns NULL if such variable does not exist
114 * and sets silc_errno.
117 void *silc_global_get_var(const char *name, SilcBool tls);
119 /****f* silcutil/silc_global_del_var
123 * SilcBool silc_global_del_var(const char *name, SilcBool tls);
127 * Deletes the global variable named `name'. Returns TRUE if it was
128 * deleted, FALSE if such variable does not exist and sets silc_errno.
130 * If variable is not deleted before the process or thread is destroyed
131 * it will be deleted and freed automatically when the process or thread
135 SilcBool silc_global_del_var(const char *name, SilcBool tls);
137 #endif /* SILCGLOBAL_H */