15. DLL-SUPPORT HOMES
The chaper is intended for developers, so it is highly technical, the
program is witten in Delphi, but any language can be used to create the DLL.
A
filter dll must export the following function:
function
init:integer;
|
is
called ones for every "run" result=0 Ok <>0 error
|
|
|
function
desclen:integer;
|
is
called ones for every "run", result=length of description
|
|
|
function
description:TChars;
|
is
called ones for every "run", result is array of chars
|
|
|
function
exit:integer;
|
is
called ones for very "run", result=0 ok <>0 error
|
|
|
function
check(
Context:NWDSContextHandle;
obj:pchar ):boolean;
|
is
called for every user object in selection.
A context handle (do not change context settings!)
name of the user in a nul-terminated char-array
Result=true keep user
Result=False remove user
|
After
selecting the OK-button the program will do the followinactions:
The program does a select the user-objects.
- It will load the filter-dll.
- Then the function init is called, so the dll can do it's initialization.
- If the ini-function rountine return 0, the program continious with a calls to
the desclen function and description function.
- Then it will call for every user-object in the selection the function check.
This routine must return a value "true" for every user to keep and "false" for
any user that must be removed.
- Then the program calls the exit-function, and the dll is unloaded.
- The program then continious with the actions that are selected.
- So the Filter-DLL is loaded and unloaded very "run" of the program.
Select:
Add filter.
On the filter tab: select option "User defined filter with extra DLL"
select the filter dll file.
The
program supports extra (upto 255) dll for template execution, a Template DLL
must export the following fuctions:
function
init:integer
|
is
called at startup of the program result=0 Ok <>0 error
|
|
|
function
start
(Context:NWDSContextHandle):integer
|
is
called at the start of every run. Do not change the contexthandle settings!.
result=0 is Ok, <>0 error.
|
|
|
function
finish
(Context:NWDSContextHandle):integer
|
is
called at the end of every run. return 0 for ok, <>0 for an error.
|
|
|
function
exit:integer;
|
is
called at the end of the program for cleanup, result=0 ok <>0 error
|
|
|
function
Companyname:Tchars
|
Return
a 0 terminated string with the name of the manifacture. Can be called more than
ones.
|
|
|
function
dllName:Tchars;
|
Return
a 0 terminated string with the name of the dll, it can be different for the
real name. Can be called more than ones.
|
|
|
function
Version:integer;
|
Return
version number of the DLL, The number is interpret as major version *100 +
minor version. So 101 is version 1.01. Can be called more than ones.
|
|
|
function
NumberOfAttributes:integer;
|
Return
number of attributes that are supported by this dll. Is called ones.
|
|
|
function
GetAttributeName
(I:integer):Tchars;
|
Return
the name of the attribute that is supported. Input is attribute number. First
attribute is 1. Is called ones for every attribute.
|
|
|
function
SetValue(
context:NWDSContextHandle;
UserObj,TempObj,Attr : TChars):
longword;
|
Is
called for every user and every attribute. Input contextHandle, userobject
name, template object name, attribute name. Return 0=Ok, <>0=Error
|
|
|
function
LogData
(var color:integer):Tchars;
|
After
every call to a function, the program will call this function. If the function
returns a null-string, then there is no information written to the log-file,
otherwise the program writes to string to the logfile. The value of color set
the color of the warning in the log-file.
Color:
0=Black
1=Green
2=Blue
3=Red
4=clGray
Any other value will be displayed in black.
|
Tchars
is an array[0..255] of char.
When is the dll loaded and when is a function called?
The program will read the homes.ini file at startup, and will load all the
dll's given under the section [template dlls]. The program will call the
init-function of each dll, when this function returns a non-zero result, the
program will unload the DLL (and will not call the exit function!) and
issue a error message to the log-file. In case the init-funtion returns 0 (=ok)
the program will keep the dll loaded until the program is stopped. After the
init-rountine the program calls the function NumberOfAttributes to find out how
many attributes are supported by the dll. Then the program calls the function
GetAttrbuteName for obtaining the attribute names, where the first attribute is
1.
At every run of the program (Ok-button) the program will call the start
function, if everything is ok the program continues and will call the function
SetValue with the proper values.
It's allowed to create a dummy support, and only react on an specific attribute
name. This can be useful if you have a set of attributes that belong together,
e.g. groupwise has multiple attribute in the User-object.
At the end of a "run" the program will call the finish function. The
start/finish functions can be handy for opening a file or make a database
connection or anything else.
As part of the cleanup code the program will call the exit-functions of the
dll's and than unload the dlls.
The functions CompanyName, dllName and Version are not used at the moment, but
must exist!
SAMPLES
On the website are a few samples available, you can download them here:
www.hbware.com/samples/homes
|
