lib/silcutil/silcglobal.h

   1 /*
   2
   3   silcglobal.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcutil/Global Variable Interface
  21  *
  22  * DESCRIPTION
  23  *
  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.
  28  *
  29  * EXAMPLE
  30  *
  31  * // Initialize global buffer
  32  * unsigned char buffer[256];
  33  * silc_global_set_va("somebuf", sizeof(buffer), NULL, FALSE);
  34  *
  35  * // Retrieve the buffer
  36  * unsigned char *buf = silc_global_get_var("somebuf", FALSE);
  37  *
  38  * // Set integer and its value global in the current thread
  39  * SilcUInt32 integer = 100;
  40  * silc_global_set_var("someint", 4, &integer, TRUE);
  41  *
  42  * // Retrieve the integer and change its value
  43  * SilcUInt32 *intptr = silc_global_get_var("someint", TRUE);
  44  * *intptr = 200;
  45  *
  46  ***/
  47
  48 #ifndef SILCGLOBAL_H
  49 #define SILCGLOBAL_H
  50
  51 /****f* silcutil/silc_global_set_var
  52  *
  53  * SYNOPSIS
  54  *
  55  *    void *silc_global_set_var(const char *name, SilcUInt32 variable_size,
  56  *                              void *initial_value, SilcBool tls);
  57  *
  58  * DESCRIPTION
  59  *
  60  *    Sets a variable of size of `variable_size' bytes as a global variable
  61  *    under the name of `name'.  If `initial_value' is non-NULL it is
  62  *    considered to be the initial value of the stored variable.  If it is
  63  *    NULL this will initialize the variable as all zeroes.
  64  *
  65  *    If variable with `name' already exists it will be replaced with the
  66  *    `initial_value' or as all zeroes, and the old pointer will become
  67  *    invalid.
  68  *
  69  *    If `tls' is FALSE the variable is visible to all threads in the process.
  70  *    If it is TRUE the variable is visible only in the current thread.  The
  71  *    variable can be retrieved using the same name by calling the
  72  *    silc_thread_global_get_var.
  73  *
  74  *    Returns NULL and sets silc_errno if the variable could not be added, or
  75  *    a pointer to the added variable otherwise.
  76  *
  77  * EXAMPLE
  78  *
  79  *    // Initialize global buffer
  80  *    unsigned char buffer[256];
  81  *    silc_global_set_va("somebuf", sizeof(buffer), NULL, FALSE);
  82  *
  83  *    // Retrieve the buffer
  84  *    unsigned char *buf = silc_global_get_var("somebuf", FALSE);
  85  *
  86  *    // Set integer global
  87  *    SilcUInt32 integer = 100;
  88  *    silc_global_set_var("someint", 4, &integer, FALSE);
  89  *
  90  *    // Retrieve the integer and change its value
  91  *    SilcUInt32 *intptr = silc_global_get_var("someint", FALSE);
  92  *    *intptr = 200;
  93  *
  94  *    // Set structure as global in the thread
  95  *    silc_global_set_va("somestruct", sizeof(*context), NULL, TRUE);
  96  *
  97  *    // Retrieve the context
  98  *    context = silc_global_get_var("somestruct", TRUE);
  99  *
 100  ***/
 101 void *silc_global_set_var(const char *name, SilcUInt32 variable_size,
 102                           void *initial_value, SilcBool tls);
 103
 104 /****f* silcutil/silc_global_get_var
 105  *
 106  * SYNOPSIS
 107  *
 108  *    void *silc_global_get_var(const char *name, SilcBool tls);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Returns the variable from the global variable storage that has been
 113  *    stored under the name `name'.  If `tls' is FALSE this fetches the
 114  *    variable from global storage, if it is TRUE it is fetched from the
 115  *    Thread-local storage.  Returns NULL if such variable does not exist
 116  *    and sets silc_errno.
 117  *
 118  ***/
 119 void *silc_global_get_var(const char *name, SilcBool tls);
 120
 121 /****f* silcutil/silc_global_del_var
 122  *
 123  * SYNOPSIS
 124  *
 125  *    SilcBool silc_global_del_var(const char *name, SilcBool tls);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Deletes the global variable named `name'.  Returns TRUE if it was
 130  *    deleted, FALSE if such variable does not exist and sets silc_errno.
 131  *
 132  *    If variable is not deleted before the process or thread is destroyed
 133  *    it will be deleted and freed automatically.
 134  *
 135  ***/
 136 SilcBool silc_global_del_var(const char *name, SilcBool tls);
 137
 138 #endif /* SILCGLOBAL_H */