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  ***/
  28
  29 #ifndef SILCDLL_H
  30 #define SILCDLL_H
  31
  32 /****s* silcutil/SilcDLLAPI/SilcDll
  33  *
  34  * NAME
  35  *
  36  *    typedef void *SilcDll;
  37  *
  38  * DESCRIPTION
  39  *
  40  *    This context represents the shared object and it is allocated by
  41  *    silc_dll_load and is destroyed with silc_dll_close functions.
  42  *    The context is given as argument to all funtions in this interface.
  43  *
  44  ***/
  45 #ifdef SILC_UNIX
  46 typedef void *SilcDll;
  47 #elif SILC_WIN32
  48 typedef HMODULE SilcDll;
  49 #else
  50 typedef void *SilcDll;
  51 #endif /* SILC_UNIX */
  52
  53 /****f* silcutil/SilcDLLAPI/silc_dll_load
  54  *
  55  * SYNOPSIS
  56  *
  57  *    SilcDll silc_dll_load(const char *object_path);
  58  *
  59  * DESCRIPTION
  60  *
  61  *    Load shared object or DLL indicated by the `object_path'.  The path
  62  *    must include the absolute path to the object and the object name.
  63  *    Returns the SilcDll context or NULL on error.  The actual error
  64  *    message may be available by calling silc_dll_error function.  Symbols
  65  *    may be retrieved from the returned context by calling silc_dll_getsym.
  66  *
  67  ***/
  68 SilcDll silc_dll_load(const char *object_path);
  69
  70 /****f* silcutil/SilcDLLAPI/silc_dll_close
  71  *
  72  * SYNOPSIS
  73  *
  74  *    void silc_dll_close(SilcDll dll);
  75  *
  76  * DESCRIPTION
  77  *
  78  *    Closes the shared object indicated by `dll'.  Any symbol retrieved
  79  *    from the `dll' with silc_dll_getsym will become invalid and cannot
  80  *    be used anymore.
  81  *
  82  ***/
  83 void silc_dll_close(SilcDll dll);
  84
  85 /****f* silcutil/SilcDLLAPI/silc_dll_getsym
  86  *
  87  * SYNOPSIS
  88  *
  89  *    void *silc_dll_getsym(SilcDll dll, const char *symbol);
  90  *
  91  * DESCRIPTION
  92  *
  93  *    Returns the memory address of the symbol indicated by `symbol' from
  94  *    the shared object indicated by `dll'.  If such symbol does not exist
  95  *    this returns NULL.
  96  *
  97  ***/
  98 void *silc_dll_getsym(SilcDll dll, const char *symbol);
  99
 100 /****f* silcutil/SilcDLLAPI/silc_dll_error
 101  *
 102  * SYNOPSIS
 103  *
 104  *    const char *silc_dll_error(SilcDll dll);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    This routine may return error string after an error has occured with
 109  *    the shared object indicated by `dll'.  If error string is not available
 110  *    this will return NULL.
 111  *
 112  ***/
 113 const char *silc_dll_error(SilcDll dll);
 114
 115 #endif /* SILCDLL_H */