/home/doxygen/libascend/compiler/importhandler.h File Reference

---

Detailed Description

Handle the Import Handler library, which is a hash table of additional handlers for external scripts in the IMPORT statement.

#include <utilities/ascConfig.h>
#include <general/ospath.h>

Include dependency graph for importhandler.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ImportHandler
Typedefs
typedef char *	ImportHandlerCreateFilenameFn (const char *partialname)
typedef int	ImportHandlerImportFn (const struct FilePath *fp, const char *initfunc, const char *partialpath)
Functions
ASC_DLLSPEC int	importhandler_add (struct ImportHandler *handler)
int	importhandler_attemptimport (const char *partialname, const char *defaultpath, const char *pathenvvar)
int	importhandler_remove (const char *name)
ImportHandler *	importhandler_lookup (const char *name)
ASC_DLLSPEC int	importhandler_destroylibrary ()
int	importhandler_createlibrary ()
int	importhandler_printlibrary (FILE *fp)
int	importhandler_printhandler (FILE *fp, struct ImportHandler *)
FilePath *	importhandler_findinpath (const char *partialname, char *defaultpath, char *envv, struct ImportHandler **handler)
ASC_DLLSPEC int	importhandler_createsharedpointertable ()
ASC_DLLSPEC int	importhandler_setsharedpointer (const char *key, void *ptr)
ASC_DLLSPEC void *	importhandler_getsharedpointer (const char *key)
Variables
ImportHandler **	ImportHandlerLibrary
ImportHandlerCreateFilenameFn	importhandler_extlib_filename
ImportHandlerImportFn	importhandler_extlib_import

---

Typedef Documentation

typedef char* ImportHandlerCreateFilenameFn(const char *partialname)

This is the 'create filename' function that is use to take a generic 'partial filename' such as 'mystuff' and convert it into a correct filename for the ImportHandler in question. For example, a converted filename might be 'libmystuff.so' or 'mystuff.dll' or 'mystuff.py', etc.

The function should return 0 on success.

typedef int ImportHandlerImportFn(const struct FilePath *fp, const char *initfunc, const char *partialpath)

This is the 'import' function that will actually do the job of importing some external code.

The function should return 0 on success.

Parameters:

	fp	the file to be imported
	initfunc	the 'name' of a registration 'function' to be run in the imported file. This comes from the ASCEND syntax "FROM XXXX IMPORT YYYY" (more or less, as I recall) but should normally be set to NULL so that the default registration function can be used, and simpler 'IMPORT "XXXX"' syntax can be used by the end user.

---

Function Documentation

ASC_DLLSPEC int importhandler_add

(

struct ImportHandler *

handler

)

Function to add a new import handler to the list that will be tried during an IMPORT

Parameters:

handler

Handler struct to be added to the list

Returns:

0 on success

int importhandler_attemptimport	(	const char *	partialname,
		const char *	defaultpath,
		const char *	pathenvvar
	)

Function to attempt import of an external script

Parameters:

	partialname	Name of the external script (without extension), relative to PATH.
	defaultpath	Default value of file search PATH. Is trumped by value of pathenvvar if present in environment.
	pathenvvar	Environment variable containing the user's preferred file search path value.

Returns:

0 on success

ASC_DLLSPEC int importhandler_createsharedpointertable

(

)

Create a new registry. This should be called whenever an import handler library is being created, or when a GUI first wants to register pointers.

Returns:

0 on success

ASC_DLLSPEC int importhandler_destroylibrary

(

)

Returns:

0 on success

struct FilePath* importhandler_findinpath	(	const char *	partialname,
		char *	defaultpath,
		char *	envv,
		struct ImportHandler **	handler
	)

Search through a path (a la unix $PATH variable) as specified by a specific environment variable (or fall back to a default hard-wired file path) and find a file that matches the partial filename specfied. For each directory in the path, the registered importhandlers will be tried, in the order they were registered. If no file matching any of the importhandler filename pattern (eg 'myext' becomes '/path/to/myext.py' for the case of an import handler with a '.py' extension and a path component of '/path/to') then the next component of the search path is tried.

Returns:

NULL if no readable file is found, else return a FilePath structure pointing to the location of the file found.

ASC_DLLSPEC void* importhandler_getsharedpointer

(

const char *

key

)

Retrieve a pointer from the shared pointer table. Returns NULL if the pointer is not found (or if it is found but has NULL value). This should only be used from import handler code.

Returns:

NULL on not found (or NULL value stored in registry)

int importhandler_printlibrary

(

FILE *

fp

)

Returns:

0 on success

ASC_DLLSPEC int importhandler_setsharedpointer	(	const char *	key,
		void *	ptr
	)

Sets a pointer in the shared pointer table. This should only be called from the GUI code.

This is also called from inside Type::getSimulation in the C++ interface.

Returns:

0 on success

---

Variable Documentation

struct ImportHandler** ImportHandlerLibrary

List of import handlers currently in effect. this shouldn't be a global, but unfortunately such globals are 'The ASCEND Way'.

---