Chapter 12. The Shared Library (SLIB) Component

Chapter 12. The Shared Library (SLIB) Component
	Part II. C-Language Components

Description

A sharedlibrary object represents a shared library (in Windows a DLL) in an operating system. To access functions in a shared library, the findfunction() method of the sharedlibrary object is called and the name of the function and the appropriate parameters must be passed. This returns a sharedlibraryfunction object and places it in the ring of functions.

	Note
	The use of this functionality will prevent the program from operating successfully on other platforms, unless equivalent functionality is added to the program for each target platform. Whenever possible, avoid using this functionality if the same result can be achieved using libraries provided by SIMPOL.

Type Tags

None

Object Value

The value of a sharedlibrary object is undefined and it is an error to attempt to either get or set it.

sharedlibrary.new()

Description

Creates a new sharedlibrary object for the specified shared library.

Prototype

sharedlibrary.new ( string filename, integer error )

Parameters

Parameter	Default value	Type name	Description
filename	None	string	Specifies the file name (which should be a full path name if the file is not in the path or the current directory).
error	`.nul`	integer	Specifies an object which is used to output any error code generated during creation of the sharedlibrary object. If `error` is not specified or is `.nul` then any error which occurs during object creation will halt the program. If an error object is specified and an error occurs during object creation then the error code is output into that object and the `new` method returns `.nul`.

Properties

Property	Type	Description
_	type(*)	This property is provided for use by the user to attach any object of any type to the type in which this property is provided.
__	type(*)	This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property.
filename	string	Provides the file name of the shared library that was opened.
firstfunction	sharedlibraryfunction	Contains a reference to the first function that is being made available through the use of the shared library. Only functions that have been retrieved using the `findfunction()` method appear in the ring of functions. For information about the available functions for a given shared library, see the associated library or operating system documentation. The makers of SIMPOL are not able to provide assistance on functionality that is accessed in this way.
type	type	Specifies the sharedlibrary type object.

Methods

findfunction()

Description

Creates a new sharedlibraryfunction object for a specific function in a shared library.

Prototype

sharedlibraryvar.findfunction ( string functionname, string name, string returntype, string parameters, integer error )

Parameters

Parameter	Default value	Type name	Description
functionname	None	string	Specifies the name of the function within the shared library that is to be made available. Currently it is not possible to access functions in a Windows DLL by ordinal, only by name. Either this parameter or else the `name` must be provided. If only one is provided, it will be assumed that it is the same for both.
name	None	string	Specifies the name to use when accessing the function using the member (!) operator as an argument of the sharedlibrary object. Either this parameter or else the `functionname` must be provided. If only one is provided, it will be assumed that it is the same for both.
returntype	""	string	Specifies the data type returned by the function. If this is the empty string, then the function is not expected to a return a value. This parameter must be either "" (if the return is void), or else a valid entry in the form "xyyy" where x is the letter representing the type and yyy is the size. Valid types are: u\|U — unsigned int s\|S — signed int f\|F — float Valid sizes are: p\|P — pointer, the same size as a pointer for the current machine, but the type has to be a u\|U 8\|16\|32 — for types s\|S and u\|U on a 32-bit machine 32\|64 — for f\|F (or the number of bits in a float or a double on the target machine)
parameters	""	string	Specifies the data type being passed to the function. If this is the empty string, then the function is expecting any parameters. This parameter must be either "", or else a valid set of parameters in the form "xyyy" where x is the letter representing the type and yyy is the size. Valid types are: b\|B() — byte u\|U — unsigned int s\|S — signed int f\|F — float t\|T() — text p\|P[] — pointer Valid sizes are: p\|P — pointer, the same size as a pointer for the current machine, but the type has to be a u\|U 8\|16\|32 — for types s\|S and u\|U on a 32-bit machine 8\|16 — for type t\|T (8-bit or 16-bit characters) 32\|64 — for f\|F (or the number of bits in a float or a double on the target machine) In addition, the "t" and "b" parameters also require a value in parentheses, that indicates the size of the buffer being passed. It is also possible to pass a pointer to a structure, including the definition of the structure and having the elements created for the structure. To pass a buffer that can be modified, the parameter must be passed preceded by the "+" character. For full details on how to use shared library functions, see the chapter on them in the Programmer's Guide.
error	`.nul`	integer	Specifies an object which is used to output any error code generated during creation of the UTOSdirectoryentry object. If `error` is not specified or is `.nul` then any error which occurs during object creation will halt the program. If an error object is specified and an error occurs during object creation then the error code is output into that object and the `getentry` method returns `.nul`.


wxsystemvalues()		sharedlibraryfunction