src/gmxlib/vmdplugin.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * This file is part of Gromacs        Copyright (c) 1991-2008
   5  * David van der Spoel, Erik Lindahl, Berk Hess, University of Groningen.
   6  * Copyright (c) 2012, by the GROMACS development team, led by
   7  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   8  * others, as listed in the AUTHORS file in the top-level source
   9  * directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37
  38 /***************************************************************************
  39  *cr
  40  *cr            (C) Copyright 1995-2006 The Board of Trustees of the
  41  *cr                        University of Illinois
  42  *cr                         All Rights Reserved
  43  *cr
  44 Developed by:           Theoretical and Computational Biophysics Group
  45                         University of Illinois at Urbana-Champaign
  46                         http://www.ks.uiuc.edu/
  47
  48 Permission is hereby granted, free of charge, to any person obtaining a copy of
  49 this software and associated documentation files (the Software), to deal with
  50 the Software without restriction, including without limitation the rights to
  51 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
  52 of the Software, and to permit persons to whom the Software is furnished to
  53 do so, subject to the following conditions:
  54
  55 Redistributions of source code must retain the above copyright notice,
  56 this list of conditions and the following disclaimers.
  57
  58 Redistributions in binary form must reproduce the above copyright notice,
  59 this list of conditions and the following disclaimers in the documentation
  60 and/or other materials provided with the distribution.
  61
  62 Neither the names of Theoretical and Computational Biophysics Group,
  63 University of Illinois at Urbana-Champaign, nor the names of its contributors
  64 may be used to endorse or promote products derived from this Software without
  65 specific prior written permission.
  66
  67 THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  68 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  69 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  70 THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  71 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  72 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  73 OTHER DEALINGS WITH THE SOFTWARE.
  74  ***************************************************************************/
  75
  76 /***************************************************************************
  77  * RCS INFORMATION:
  78  *
  79  *      $RCSfile: vmdplugin.h,v $
  80  *      $Author: johns $       $Locker:  $             $State: Exp $
  81  *      $Revision: 1.32 $       $Date: 2009/02/24 05:12:35 $
  82  *
  83  ***************************************************************************/
  84
  85 /** @file
  86  * This header must be included by every VMD plugin library.  It defines the
  87  * API for every plugin so that VMD can organize the plugins it finds.
  88  */
  89
  90 #ifndef VMD_PLUGIN_H
  91 #define VMD_PLUGIN_H
  92
  93
  94 /*
  95  * Preprocessor tricks to make it easier for us to redefine the names of
  96  * functions when building static plugins.
  97  */
  98 #if !defined(VMDPLUGIN)
  99 /**
 100   * macro defining VMDPLUGIN if it hasn't already been set to the name of
 101   * a static plugin that is being compiled.  This is the catch-all case.
 102   */
 103 #define VMDPLUGIN vmdplugin
 104 #endif
 105 /** concatenation macro, joins args x and y together as a single string */
 106 #define xcat(x, y) cat(x, y)
 107 /** concatenation macro, joins args x and y together as a single string */
 108 #define cat(x, y) x ## y
 109
 110 /*
 111  *  macros to correctly define plugin function names depending on whether
 112  *  the plugin is being compiled for static linkage or dynamic loading.
 113  *  When compiled for static linkage, each plugin needs to have unique
 114  *  function names for all of its entry points.  When compiled for dynamic
 115  *  loading, the plugins must name their entry points consistently so that
 116  *  the plugin loading mechanism can find the register, register_tcl, init,
 117  *  and fini routines via dlopen() or similar operating system interfaces.
 118  */
 119 /*@{*/
 120 /** Macro names entry points correctly for static linkage or dynamic loading */
 121 #define VMDPLUGIN_register     xcat(VMDPLUGIN, _register)
 122 #define VMDPLUGIN_register_tcl xcat(VMDPLUGIN, _register_tcl)
 123 #define VMDPLUGIN_init         xcat(VMDPLUGIN, _init)
 124 #define VMDPLUGIN_fini         xcat(VMDPLUGIN, _fini)
 125 /*@}*/
 126
 127
 128 /** "WIN32" is defined on both WIN32 and WIN64 platforms... */
 129 #if (defined(WIN32))
 130 #define WIN32_LEAN_AND_MEAN
 131 #include <windows.h>
 132
 133 #if !defined(STATIC_PLUGIN)
 134 #if defined(VMDPLUGIN_EXPORTS)
 135 /**
 136  *  Only define DllMain for plugins, not in VMD or in statically linked plugins
 137  *  VMDPLUGIN_EXPORTS is only defined when compiling dynamically loaded plugins
 138  */
 139 BOOL APIENTRY DllMain( HANDLE hModule,
 140                        DWORD ul_reason_for_call,
 141                        LPVOID lpReserved
 142                      )
 143 {
 144   return TRUE;
 145 }
 146
 147 #define VMDPLUGIN_API __declspec(dllexport)
 148 #else
 149 #define VMDPLUGIN_API __declspec(dllimport)
 150 #endif /* VMDPLUGIN_EXPORTS */
 151 #else  /* ! STATIC_PLUGIN */
 152 #define VMDPLUGIN_API
 153 #endif /* ! STATIC_PLUGIN */
 154 #else
 155 /** If we're not compiling on Windows, then this macro is defined empty */
 156 #define VMDPLUGIN_API
 157 #endif
 158
 159 /** define plugin linkage correctly for both C and C++ based plugins */
 160 #ifdef __cplusplus
 161 #define VMDPLUGIN_EXTERN extern "C" VMDPLUGIN_API
 162 #else
 163 #define VMDPLUGIN_EXTERN extern VMDPLUGIN_API
 164 #endif  /* __cplusplus */
 165
 166 /*
 167  * Plugin API functions start here
 168  */
 169
 170
 171 /**
 172  * Init routine: called the first time the library is loaded by the
 173  * application and before any other API functions are referenced.
 174  * Return 0 on success.
 175  */
 176 VMDPLUGIN_EXTERN int VMDPLUGIN_init(void);
 177
 178 /**
 179  * Macro for creating a struct header used in all plugin structures.
 180  *
 181  * This header should be placed at the top of every plugin API definition
 182  * so that it can be treated as a subtype of the base plugin type.
 183  *
 184  * abiversion: Defines the ABI for the base plugin type (not for other plugins)
 185  * type: A string descriptor of the plugin type.
 186  * name: A name for the plugin.
 187  * author: A string identifier, possibly including newlines.
 188  * Major and minor version.
 189  * is_reentrant: Whether this library can be run concurrently with itself.
 190  */
 191 #define vmdplugin_HEAD \
 192   int abiversion; \
 193   const char *type; \
 194   const char *name; \
 195   const char *prettyname; \
 196   const char *author; \
 197   int majorv; \
 198   int minorv; \
 199   int is_reentrant
 200
 201 /**
 202   * Typedef for generic plugin header, individual plugins can
 203   * make their own structures as long as the header info remains
 204   * the same as the generic plugin header, most easily done by
 205   * using the vmdplugin_HEAD macro.
 206   */
 207 typedef struct {
 208   vmdplugin_HEAD;
 209 } vmdplugin_t;
 210
 211 /**
 212  * Use this macro to initialize the abiversion member of each plugin
 213  */
 214 #define vmdplugin_ABIVERSION  16
 215
 216 /*@{*/
 217 /** Use this macro to indicate a plugin's thread-safety at registration time */
 218 #define VMDPLUGIN_THREADUNSAFE 0
 219 #define VMDPLUGIN_THREADSAFE   1
 220 /*@}*/
 221
 222 /*@{*/
 223 /** Error return code for use in the plugin registration and init functions */
 224 #define VMDPLUGIN_SUCCESS      0
 225 #define VMDPLUGIN_ERROR       -1
 226 /*@}*/
 227
 228 /**
 229  * Function pointer typedef for register callback functions
 230  */
 231 typedef int (*vmdplugin_register_cb)(void *, vmdplugin_t *);
 232
 233 /**
 234  * Allow the library to register plugins with the application.
 235  * The callback should be called using the passed-in void pointer, which
 236  * should not be interpreted in any way by the library.  Each vmdplugin_t
 237  * pointer passed to the application should point to statically-allocated
 238  * or heap-allocated memory and should never be later modified by the plugin.
 239  * Applications must be permitted to retain only a copy of the the plugin
 240  * pointer, without making any deep copy of the items in the struct.
 241  */
 242 VMDPLUGIN_EXTERN int VMDPLUGIN_register(void *, vmdplugin_register_cb);
 243
 244 /**
 245  * Allow the library to register Tcl extensions.
 246  * This API is optional; if found by dlopen, it will be called after first
 247  * calling init and register.
 248  */
 249 VMDPLUGIN_EXTERN int VMDPLUGIN_register_tcl(void *, void *tcl_interp,
 250     vmdplugin_register_cb);
 251
 252 /**
 253  * The Fini method is called when the application will no longer use
 254  * any plugins in the library.
 255  */
 256 VMDPLUGIN_EXTERN int VMDPLUGIN_fini(void);
 257
 258 #endif   /* VMD_PLUGIN_H */