GEOS SDK TechDocs
|
| 
1.4 Saving and Restoring State
| 
1.6 Writing Your Own Libraries
Often, geodes will have to use other geodes. For example, a communications program will use the Serial Driver, and a draw application will use the Graphic Object Library. Normally, this is taken care of by the compiler and the linker when you include a library or driver in your .goc and .gp files.
Other times, however, an application will have to load libraries or drivers on the fly and then free them some time later. This section describes how to load, use, and free libraries and drivers.
GeodeUseLibrary(), GeodeFreeLibrary()
Libraries are always referenced by their file names or by their geode handles. It's easiest, however, to use the file name of the library when loading it--the system will locate the library for you. It's unusual to need to load a library for use with your geode; in almost all cases it's easiest to include the library in your .goc and .gp files and have the system load and link the library automatically. (To do this, include the library's interface definition file in your code file and list the library's geode name in your geode parameters file.)
If you need to load a library dynamically, though, use
GeodeUseLibrary()
. This routine takes the protocol numbers expected of the library (see Protocol Numbers
) and the library geode's filename. It will locate and load the library if not already loaded. If the library is already loaded, it will increment the library's reference count.
When you are done using a library loaded with
GeodeUseLibrary()
, you must free the library's instance with
GeodeFreeLibrary()
.
GeodeUseDriver(), GeodeInfoDriver(), GeodeGetDefaultDriver(), GeodeSetDefaultDriver(), GeodeFreeDriver()
Drivers are referenced by either their permanent names or their geode handles. Most drivers used by applications will be loaded automatically by the kernel; the application must have the driver's permanent name specified in its .gp file. Should an application need to use a driver not included in its parameters file, however, it can do so with the routines described below.
When you need to use a driver, the
GeodeUseDriver()
routine will locate and load it, adding it to the active geodes list. You must pass the desired driver geode's filename as well as the expected protocol levels of the driver. The routine will return the driver's geode handle.
If you load a driver dynamically, you must free it with
GeodeFreeDriver()
when your geode shuts down or otherwise finishes using the driver.
If you know a driver's geode handle, you can easily retrieve information about it with the routine
GeodeInfoDriver()
.
This returns a structure of type
DriverInfoStruct
, which contains the driver's type (
DriverType
), the driver's attributes, and a far pointer to the driver's strategy routine. Many driver types have an expanded information structure, of which
DriverInfoStruct
is just the first field. Video driver information structures, for example, also contain dimensions and color capabilities (among other things) of the particular devices they drive. The driver information structure is shown below.
typedef struct {
void (*DIS_strategy)();
DriverAttrs DIS_driverAttributes;
DriverType DIS_driverType;
} DriverInfoStruct;
The
DIS_strategy
field of the structure contains a pointer to the driver's strategy routine in fixed memory. After the driver has been loaded, its strategy routine is called directly with a driver function name.
The
DIS_driverAttributes
is an attribute record of type
DriverAttrs
, the flags of which are shown below:
DriverExtendedInfo
structure.
The
DIS_driverType
contains the type of driver described by the information structure. The types that may be specified in this field are listed below:
When you want a driver to perform one of its functions, you must call its strategy routine. The strategy routine typically takes a number of parameters, one of which is the function the driver should perform. The
DriverInfoStruct
contains a far pointer to the strategy routine; your application should store this far pointer and call it directly any time one of the driver's functions is needed. However, because the driver may be put in a different location each time it's loaded, you should not save the pointer in a state file. Note that this scheme of accessing drivers directly can only be implemented in assembly language. Some drivers may provide library interfaces as well as their standard driver interface; this allows routines to be written in C.
GEOS
maintains default drivers for the entire system. The types of default drivers are described by
GeodeDefaultDriverType
; all the types are shown below. They are called default drivers because the default for each category of driver used by the system is stored in the GEOS.INI file. GEOS will, upon startup, load in the default driver of each category.
To retrieve the default that GEOS is using, call the routine
GeodeGetDefaultDriver()
with the appropriate driver type (a member of the type
GeodeDefaultDriverType
). This routine will return the geode handle of the default driver of that type.
To set a new default driver for a specified driver type, use
GeodeSetDefaultDriver()
. This routine takes a geode handle and a driver type and sets the system default for that type. Typically, system defaults will be set only by the Preferences Manager application.
GEOS SDK TechDocs
|
| 1.4 Saving and Restoring State
| 1.6 Writing Your Own Libraries