| 1 |
/* ASCEND modelling environment |
| 2 |
Copyright (C) 2006 Carnegie Mellon University |
| 3 |
|
| 4 |
This program is free software; you can redistribute it and/or modify |
| 5 |
it under the terms of the GNU General Public License as published by |
| 6 |
the Free Software Foundation; either version 2, or (at your option) |
| 7 |
any later version. |
| 8 |
|
| 9 |
This program is distributed in the hope that it will be useful, |
| 10 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 |
GNU General Public License for more details. |
| 13 |
|
| 14 |
You should have received a copy of the GNU General Public License |
| 15 |
along with this program; if not, write to the Free Software |
| 16 |
Foundation, Inc., 59 Temple Place - Suite 330, |
| 17 |
Boston, MA 02111-1307, USA. |
| 18 |
*//** |
| 19 |
@file |
| 20 |
Handle the Import Handler library, which is a hash table of additional |
| 21 |
handlers for external scripts in the IMPORT statement. |
| 22 |
*//* |
| 23 |
by John Pye |
| 24 |
Created Sept 7, 2006 |
| 25 |
*/ |
| 26 |
|
| 27 |
#ifndef IMPORTHANDLER_H |
| 28 |
#define IMPORTHANDLER_H |
| 29 |
|
| 30 |
#include <general/ospath.h> |
| 31 |
|
| 32 |
/*------------------------------------------------------------------------------ |
| 33 |
DATA STRUCTURES AND TYPES |
| 34 |
*/ |
| 35 |
|
| 36 |
/** |
| 37 |
This is the 'create filename' function that is use to take a generic |
| 38 |
'partial filename' such as 'mystuff' and convert it into a correct |
| 39 |
filename for the ImportHandler in question. For example, a converted |
| 40 |
filename might be 'libmystuff.so' or 'mystuff.dll' or 'mystuff.py', etc. |
| 41 |
|
| 42 |
The function should return 0 on success. |
| 43 |
*/ |
| 44 |
typedef char *ImportHandlerCreateFilenameFn(const char *partialname); |
| 45 |
|
| 46 |
/** |
| 47 |
This is the 'import' function that will actually do the job of importing |
| 48 |
some external code. |
| 49 |
|
| 50 |
The function should return 0 on success. |
| 51 |
|
| 52 |
@param fp the file to be imported |
| 53 |
@param initfunc the 'name' of a registration 'function' to be run in the |
| 54 |
imported file. This comes from the ASCEND syntax "FROM XXXX IMPORT YYYY" |
| 55 |
(more or less, as I recall) but should normally be set to NULL so that |
| 56 |
the default registration function can be used, and simpler 'IMPORT "XXXX"' |
| 57 |
syntax can be used by the end user. |
| 58 |
*/ |
| 59 |
typedef int ImportHandlerImportFn(const struct FilePath *fp,const char *initfunc, const char *partialpath); |
| 60 |
|
| 61 |
struct ImportHandler{ |
| 62 |
const char *name; /**< name of this import handler, eg 'extpy' */ |
| 63 |
ImportHandlerCreateFilenameFn *filenamefn; /**< function which converts a partial filename into a correct filename, eg by adding a suffix */ |
| 64 |
ImportHandlerImportFn *importfn; /**< function which loads an external script module once it has been located */ |
| 65 |
}; |
| 66 |
|
| 67 |
/** |
| 68 |
List of import handlers currently in effect. @TODO this shouldn't be a global, |
| 69 |
but unfortunately such globals are 'The ASCEND Way'. |
| 70 |
*/ |
| 71 |
extern struct ImportHandler **ImportHandlerLibrary; |
| 72 |
|
| 73 |
/** Function to add a new import handler to the list that will be tried during an IMPORT |
| 74 |
@param handler Handler struct to be added to the list |
| 75 |
@return 0 on success |
| 76 |
*/ |
| 77 |
ASC_DLLSPEC(int) importhandler_add(struct ImportHandler *handler); |
| 78 |
|
| 79 |
/** Function to attempt import of an external script |
| 80 |
@param partialname Name of the external script (without extension), relative to PATH. |
| 81 |
@param defaultpath Default value of file search PATH. Is trumped by value of pathenvvar if present in environment. |
| 82 |
@param pathenvvar Environment variable containing the user's preferred file search path value. |
| 83 |
@return 0 on success |
| 84 |
*/ |
| 85 |
int importhandler_attemptimport(const char *partialname,const char *defaultpath, const char *pathenvvar); |
| 86 |
|
| 87 |
/*------------------------------------------------------------------------------ |
| 88 |
FUNCTIONS FOR IMPORT OF DLL/SO external libraries |
| 89 |
*/ |
| 90 |
ImportHandlerCreateFilenameFn importhandler_extlib_filename; |
| 91 |
ImportHandlerImportFn importhandler_extlib_import; |
| 92 |
|
| 93 |
/*------------------------------------------------------------------------------ |
| 94 |
LIST-BASED FUNCTIONS related to IMPORT handler 'library' |
| 95 |
*/ |
| 96 |
|
| 97 |
int importhandler_remove(const char *name); |
| 98 |
struct ImportHandler *importhandler_lookup(const char *name); |
| 99 |
ASC_DLLSPEC(int) importhandler_destroylibrary(); |
| 100 |
int importhandler_createlibrary(); |
| 101 |
int importhandler_printlibrary(FILE *fp); |
| 102 |
int importhandler_printhandler(FILE *fp, struct ImportHandler *); |
| 103 |
|
| 104 |
/*------------------------------------------------------------------------------ |
| 105 |
PATH SEARCH ROUTINES |
| 106 |
*/ |
| 107 |
|
| 108 |
/** |
| 109 |
Search through a path (a la unix $PATH variable) as specified by a specific |
| 110 |
environment variable (or fall back to a default hard-wired file path) and |
| 111 |
find a file that matches the partial filename specfied. For each directory |
| 112 |
in the path, the registered importhandlers will be tried, in the order |
| 113 |
they were registered. If no file matching any of the importhandler filename |
| 114 |
pattern (eg 'myext' becomes '/path/to/myext.py' for the case of |
| 115 |
an import handler with a '.py' extension and a path component of '/path/to') |
| 116 |
then the next component of the search path is tried. |
| 117 |
|
| 118 |
@return NULL if no readable file is found, else return a FilePath structure |
| 119 |
pointing to the location of the file found. |
| 120 |
*/ |
| 121 |
struct FilePath *importhandler_findinpath(const char *partialname |
| 122 |
, char *defaultpath, char *envv, struct ImportHandler **handler |
| 123 |
); |
| 124 |
|
| 125 |
/*------------------------------------------------------------------------------ |
| 126 |
SHARED POINTER TABLE |
| 127 |
*/ |
| 128 |
|
| 129 |
/** |
| 130 |
Create a new registry. This should be called whenever an import handler |
| 131 |
library is being created, or when a GUI first wants to register pointers. |
| 132 |
|
| 133 |
@return 0 on success |
| 134 |
*/ |
| 135 |
ASC_DLLSPEC(int) importhandler_createsharedpointertable(); |
| 136 |
|
| 137 |
/** |
| 138 |
Sets a pointer in the shared pointer table. This should only be called from |
| 139 |
the GUI code. |
| 140 |
|
| 141 |
This is also called from inside Type::getSimulation in the C++ interface. |
| 142 |
|
| 143 |
@return 0 on success |
| 144 |
*/ |
| 145 |
ASC_DLLSPEC(int) importhandler_setsharedpointer(const char *key, void *ptr); |
| 146 |
|
| 147 |
/** |
| 148 |
Retrieve a pointer from the shared pointer table. Returns NULL if the |
| 149 |
pointer is not found (or if it is found but has NULL value). This should |
| 150 |
only be used from import handler code. |
| 151 |
|
| 152 |
@return NULL on not found (or NULL value stored in registry) |
| 153 |
*/ |
| 154 |
ASC_DLLSPEC(void *) importhandler_getsharedpointer(const char *key); |
| 155 |
|
| 156 |
#endif |
Parent Directory
| 
Revision Log