/home/doxygen/libascend/compiler/importhandler.c 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 "importhandler.h"
#include <utilities/config.h>
#include <utilities/error.h>
#include <utilities/ascDynaLoad.h>
#include <utilities/ascPanic.h>
#include <utilities/ascEnvVar.h>
#include <general/table.h>
#include <string.h>

Include dependency graph for importhandler.c:

Data Structures
struct	ImportHandlerSearch
Defines
#define	IMPORTHANDLER_MAX   10
Functions
ASC_DLLSPEC int	importhandler_add (struct ImportHandler *handler)
int	importhandler_attemptimport (const char *partialname, const char *defaultpath, const char *pathenvvar)
char *	importhandler_extlib_filename (const char *partialname)
int	importhandler_extlib_import (const struct FilePath *fp, const char *initfunc, const char *partialpath)
int	importhandler_createlibrary ()
int	importhandler_remove (const char *name)
ImportHandler *	importhandler_lookup (const char *name)
int	importhandler_destroylibrary ()
int	importhandler_printlibrary (FILE *fp)
int	importhandler_printhandler (FILE *fp, struct ImportHandler *handler)
int	importhandler_search_test (struct FilePath *path, void *userdata)
FilePath *	importhandler_findinpath (const char *partialname, char *defaultpath, char *envv, struct ImportHandler **handler)
int	importhandler_createsharedpointertable ()
int	importhandler_setsharedpointer (const char *key, void *ptr)
void *	importhandler_getsharedpointer (const char *key)
Variables
ImportHandler **	importhandler_library = NULL
Table *	importhandler_sharedpointers = NULL
FilePathTestFn	importhandler_search_test

---

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

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

int importhandler_destroylibrary

(

)

Returns:

0 on success

char* importhandler_extlib_filename

(

const char *

partialname

)

Create a filename for an external library (DLL/SO) based on a partial filename.

Parameters:

partialname

The partial filename (eg 'mylib')

Returns:

Complete filename (eg 'libmylib.so' or 'mylib.dlll', etc)

If we don't have ASC_EXTLIB-SUFFIX and -PREFIX then we can do some system-specific stuff here, but it's not as general.

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

Perform the actual importing of an external DLL/SO in to ASCEND. Can assume that the file exists and is readable.

Parameters:

	fp	Location of DLL/SO file
	initfunc	Name of registration function, preferably NULL (so that ASCEND automatically determines it)
	partialpath	as specified in 'IMPORT' statement, for creation of auto_initfunc name

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.

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

int importhandler_search_test	(	struct FilePath *	path,
		void *	userdata
	)

A FilePath 'test' function for passing to the ospath_searchpath_iterate function. This test function will return a match when an importable file having the required name is present in the fully resolved path.

Parameters:

	path	the search path component
	userdata	will be an ImportHandlerSearch object

Returns:

1 if found

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** importhandler_library = NULL

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

struct Table* importhandler_sharedpointers = NULL

Table of registered pointers for use in passing GUI data out to external scripts.

---