ggGetScope(3)								GGI							     ggGetScope(3)

NAME

       ggGetScope, ggFromScope, ggDelScope, ggNewScope - Portable code module loading facilities

SYNOPSIS

       #include <ggi/gg.h>

       gg_scope ggGetScope(const char *location);

       void ggDelScope(gg_scope scope);

       void *ggFromScope(gg_scope, const char *symbol);

       typedef	void *(*ggfunc_scope_get)(void * handle, const char * symbol);
       typedef	void (*ggfunc_scope_del)(void * handle);

       gg_scope ggNewScope(const char * location, void * handle,
			   ggfunc_scope_get get, ggfunc_scope_del del)

DESCRIPTION

       LibGG abstracts dynamic code loading (and emulates dynamic code loading for statically linked embedded binaries) through a simple API which
       represents the very lowest level required of any loadable module system.  The actual underlying mechanisms used in various  operating  sys-
       tems  to  load additional code into an application on demand vary drastically, however, minus OS-specific frills, they can all be mapped to
       the above three LibGG API functions.

       ggGetScope finds a loadable collection of symbols known by its location through whatever system	is  available  on  the	operating  system.
       Those  symbols  were once supposed to be code from modules, but the scope abstraction does not impose this restriction. The scopes can have
       different implementations and are not restricted to dynamic libraries. They could also be used as an interface to a attribute/value config-
       uration system.

       Note that when a scope happens to be dynamic library, the symbols are loaded into the address space of the caller, but libgg does not guar-
       antee that the imported symbols will be seen by other modules.

       ggDelScope unloads the symbol collection represented by the handle scope, which must have been previously loaded  with  ggGetScope   (scope
       should  be  a return value from a previous call to ggGetScope.)	Reference counts are kept to ensure that redundantly loaded symbol collec-
       tions are not discarded until their last owner releases them.  Calling ggDelScope on a handle too many times, or on an invalid handle,  may
       produce	undefined results.  Accessing symbols after the collections they were contained in are unloaded will produce undesirable and unde-
       fined results.

       ggFromScope searches the symbol collection represented by the handle scope, which has been loaded with ggGetScope  (and	not  yet  unloaded
       with  ggDelScope, of course) for a symbol named symbol, so that the application may use the item associated with the symbol.  The parameter
       scope should be a return value from a previous call to ggDelScope.  As ggFromScope may have no way of knowing what the  symbol  represents,
       the application must take the responsibility for assigning the item a correct C type.

       ggNewScope allows to register a custom scope to libgg. The primary purpose is to allow libraries to provide builtin modules that are acces-
       sible through the same interface as dynamic ones. location is the string at which the scope can be retreived. handle is	a  opaque  pointer
       provided  by  the  caller  that will be passed to the callbacks. get is a function that take an opaque handle, a symbol name, and that must
       return the requested symbol address, or NULL if not found. del is a function that will take the provided handler,  and  that  must  cleanup
       everything  before the scope is removed from the scope registry. This scheme allows to implement all kind of scopes in a very flexible way.
       Note that ggNewScope will take a reference on the scope.

RETURN VALUE

       On success, ggGetScope returns an opaque pointer to a handle representing a newly loaded symbol collection (which must be retained in order
       to use or free the collection.)	These pointers are not guaranteed to be unique.  On failure, ggGetScope returns NULL.

       ggFromScope  returns the address of the item that the named symbol represents, if it has been loaded into the caller's address space.  Oth-
       erwise it returns NULL. Note that the value associated to a symbol really depends on the scope itself and the  caller  must  know  what	is
       behind it. So a NULL value does not necessarily means failure. It could be a valid value for a specific scope.

       ggNewScope returns an opaque pointer to a handle representing the custom scope.	On failure, ggNewScope returns NULL.

libgg-1.0.x							    2005-08-26							     ggGetScope(3)