lib/silcutil/silcdll.h

   1 /*
   2
   3   silcdll.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 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/Shared Object Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Platform independent iterface for loading and using shared objects and
  25  * dynamically linked libraries (DLLs).
  26  *
  27  * EXAMPLE
  28  *
  29  * SilcDll dll;
  30  * SilcFuncCb function;
  31  *
  32  * dll = silc_dll_load("/path/to/my.so");
  33  * function = silc_dll_getsym(dll, "my_function");
  34  *
  35  * // Call the funtion
  36  * function(arg1, arg2);
  37  *
  38  * silc_dll_close(dll);
  39  *
  40  ***/
  41
  42 #ifndef SILCDLL_H
  43 #define SILCDLL_H
  44
  45 /****s* silcutil/SilcDLLAPI/SilcDll
  46  *
  47  * NAME
  48  *
  49  *    typedef void *SilcDll;
  50  *
  51  * DESCRIPTION
  52  *
  53  *    This context represents the shared object and it is allocated by
  54  *    silc_dll_load and is destroyed with silc_dll_close functions.
  55  *    The context is given as argument to all funtions in this interface.
  56  *
  57  ***/
  58 #ifdef SILC_UNIX
  59 typedef void *SilcDll;
  60 #elif SILC_WIN32
  61 typedef HMODULE SilcDll;
  62 #else
  63 typedef void *SilcDll;
  64 #endif /* SILC_UNIX */
  65
  66 /****f* silcutil/SilcDLLAPI/silc_dll_load
  67  *
  68  * SYNOPSIS
  69  *
  70  *    SilcDll silc_dll_load(const char *object_path);
  71  *
  72  * DESCRIPTION
  73  *
  74  *    Load shared object or DLL indicated by the `object_path'.  The path
  75  *    must include the absolute path to the object and the object name.
  76  *    Returns the SilcDll context or NULL on error.  The actual error
  77  *    message may be available by calling silc_dll_error function.  Symbols
  78  *    may be retrieved from the returned context by calling silc_dll_getsym.
  79  *
  80  ***/
  81 SilcDll silc_dll_load(const char *object_path);
  82
  83 /****f* silcutil/SilcDLLAPI/silc_dll_close
  84  *
  85  * SYNOPSIS
  86  *
  87  *    void silc_dll_close(SilcDll dll);
  88  *
  89  * DESCRIPTION
  90  *
  91  *    Closes the shared object indicated by `dll'.  Any symbol retrieved
  92  *    from the `dll' with silc_dll_getsym will become invalid and cannot
  93  *    be used anymore.
  94  *
  95  ***/
  96 void silc_dll_close(SilcDll dll);
  97
  98 /****f* silcutil/SilcDLLAPI/silc_dll_getsym
  99  *
 100  * SYNOPSIS
 101  *
 102  *    void *silc_dll_getsym(SilcDll dll, const char *symbol);
 103  *
 104  * DESCRIPTION
 105  *
 106  *    Returns the memory address of the symbol indicated by `symbol' from
 107  *    the shared object indicated by `dll'.  If such symbol does not exist
 108  *    this returns NULL.
 109  *
 110  ***/
 111 void *silc_dll_getsym(SilcDll dll, const char *symbol);
 112
 113 /****f* silcutil/SilcDLLAPI/silc_dll_error
 114  *
 115  * SYNOPSIS
 116  *
 117  *    const char *silc_dll_error(SilcDll dll);
 118  *
 119  * DESCRIPTION
 120  *
 121  *    This routine may return error string after an error has occured with
 122  *    the shared object indicated by `dll'.  If error string is not available
 123  *    this will return NULL.
 124  *
 125  ***/
 126 const char *silc_dll_error(SilcDll dll);
 127
 128 #endif /* SILCDLL_H */