5. Conditionals
###ToDo
6. Functions
6.1. Basics
Let's use the following C-declaration as an example of declaring a function:
WINADVAPI
BOOL
WINAPI
ControlService(
SC_HANDLE hService,
DWORD dwControl,
LPSERVICE_STATUS lpServiceStatus
);
[Options] ReturnValueType [Options] FunctionName ( [ParameterList] )
ReturnValueType:
Specifies the type of the return value of the function. In the example above the type of the return value is BOOL. If the function does not return a value the keyword VOID is used and the translation in Delphi is a Procedure. Please note, that the type identifier can also be "hidden" in an identifier defined using #define.
Options:
Options can be a token specifying the calling convention and/or other keywords telling the compiler how to handle the function in question. The most important item is the calling convention. In the Windows-API header files, the calling convention is usually "hidden" in an identifier declared using #define, so you have to look what is defined. The example above uses the WINAPI symbol which is declared as __stdcall. This is necessary for the translation, too. Every Options item must be assessed for impact and discarded or implemented.
FunctionName:
Specifies the name of the function
ParameterList:
List of parameters passed to the function separated with ",". Parameters are declared via a type identifier or via a type identifier + parameter name combination.
6.2. Calling Conventions
Referring to the example:
WINADVAPI
BOOL
WINAPI
ControlService(
SC_HANDLE hService,
DWORD dwControl,
LPSERVICE_STATUS lpServiceStatus
);
The type of the return value is BOOL. Now let's have a look at the definition of WINAPI. WINAPI is defined in windef.h the following way:
#define WINAPI __stdcall
The __stdcall keyword tells the C-compiler to use the standard-call calling convention for the function, so we have to declare the function using stdcall, too, since the default calling convention is Register in Delphi.
The function accepts three parameters. The first is a parameter with type SC_HANDLE, the second is a DWORD and the third is a pointer to a PServiceStatus structure.
Here is a Delphi translation of the example above:
Function ControlService (hService: SC_Handle;
dwControl: DWORD;
lpServiceStatus: PServiceStatus): Bool; stdcall;
Notes:
SC_Handle is defined in WinSvc.pas.
The C variable hService appears to conflict somewhat with the Delphi convention that employs H as the initial letter for a handle type. Whilst it seems desirable to use an alternative (hndService:HControlService, for example), Delphi will accept duplicate names in a parameter list (e.g. hwnd: HWND). Since Borland does it and it works, I would recommend staying with that convention.
Let's have a look at another function declaration:
ULONG (FAR PASCAL MAPISENDDOCUMENTS)(
ULONG ulUIParam,
LPSTR lpszDelimChar,
LPSTR lpszFilePaths,
LPSTR lpszFileNames,
ULONG ulReserved
);
Well, this declaration contains a trap. The keyword PASCAL has been used to specify the Pascal-calling convention, which was usually used in the 16bit-Windows. But not under Win32. Look at the following line in the windef.h file:
#define PASCAL __stdcall
The windef.h header declares PASCAL as __stdcall, which specifes the stdcall calling convention, so you have to use stdcall calling convention in this case, too.
Notes
It is very important to trace through all the #include files for any #defines which may affect the translation.
The FAR keyword can be ignored in Delphi.
