Visitor Stats


Visits today:29
Visits yesterday:53
Visits in this month:1207
Visits total:104014
Bots today:24


15. DLL-support homes

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.

15.1. Filter 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.

15.1.1. How to select a filter-dll?

Select: Add filter.
On the filter tab: select option "User defined filter with extra DLL"
select the filter dll file.

15.2. Template

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