Tony Marston - 1st May 2003

Sometimes the functions that are built into UNIFACE just don't do the job, so developers want to access some of the functions that are available within the Windows operating system. These are known as Application Program Interfaces, or API's for short. With UNIFACE Seven and above this is relatively simple to do provided that you have the following:-

Details of the relevant API that you wish to access. A good place to start is Dan Appleman's Visual Basic Programmer's Guide to the Windows API.
A component signature for each API that you wish to access.

This article describes some of the Windows API's that I have used, and their signatures are available in an export file which can be downloaded from here. This contains a single component called "winapi" which has a separate operation for each API. Note that you also have to update the [userdlls] section in your usys.ini file in order to point to the Windows DLL file that contains each API.

1. Copy a file

This will copy a file.

This requires the "CopyFile" API which resides in kernel32.dll. The calling sequence is as follows:-

COPYFILE (string from, string to, boolean failifexists)

lv_fromfile = "test1.txt"
lv_tofile   = "test2.txt"
lv_failifexists = "T" or "F"
activate "winapi".copyfile(lv_fromfile,lv_tofile,lv_failifexists)
($status: 0=fail, >0=success)

2. Delete a file

This will delete a file.

This requires the "DeleteFile" API which resides in kernel32.dll. The calling sequence is as follows:-

DELETEFILE (string file)

activate "winapi".deletefile(lv_filename)
($status: 0=fail, >0=success)

3. Find program associated with a file extension

This obtains from the system registry the name of the application which is associated with a particular file extension.

This requires the "FindExecutable" API which resides in shell32.dll. The calling sequence is as follows:-

FINDEXECUTABLE (string file, string defaultdirectory, string result)

lv_File = "test.html"
lv_Directory = ""
; note that lv_Program must be pre-initialised with spaces
lv_Program = "                                                   "
activate "winapi".findexecutable(lv_file,lv_directory,lv_Program)
(lv_Program now contains "C:\PROGRA~1\INTERN~1\iexplore.exe")

4. Get current directory

This obtains the name of the current working directory.

This requires the "GetCurrentDirectory" API which resides in kernel32.dll. The calling sequence is as follows:-

GETCURRENTDIRECTORY (numeric buflen, string path)

; note that lv_directory must be pre-initialised with spaces
lv_directory = "                                         "
activate "winapi".getcurrentdirectory(128, lv_directory)
(lv_directory now contains "F:\UNIFACE\7206\sample")

5. Get full path name

This converts a relative path name into a full path name.

This requires the "GetFullPathName" API which resides in kernel32.dll. The calling sequence is as follows:-

GETFULLPATHNAME (string filename, numeric buflen, string buffer, numeric filepart)

lv_filename = "test.html"
; note that lv_FullPath must be pre-initialised with spaces
lv_FullPath = "                                          "
activate "winapi".getfullpathname(lv_filename, 128, lv_FullPath, 0)
(lv_fullpath now contains "F:\UNIFACE\7206\sample\test.html")

6. Get string from .INI file

This will retrieve a string from a Windows INI file.

This requires the "GetIniString" API which resides in kernel32.dll. The calling sequence is as follows:-

GETINISTRING (string section, string keyname, string default, string returnstring, numeric size)

  file HTMLHELP.INI contains:
    [htmlhelp]
    test1=test-one.htm
    test2=test-two.htm#two

lv_Section = "HTMLHELP"
lv_keyname = "test1"
lv_filename = ".\htmlhelp.ini"
; note that lv_string must be pre-initialised with spaces
lv_string = "                                        "
lv_length = 40
lv_default = "default"
activate "winapi".getinistring(lv_Section %\
                              ,lv_keyname %\
                              ,lv_Default %\
                              ,lv_string %\
                              ,lv_length %\
                              ,lv_filename)
(lv_string now contains "test-one.htm"

7. Get username

This retrieves the username from the Windows logon.

This requires the "GetUserName" API which resides in advapi32.dll. The calling sequence is as follows:-

GETUSERNAME (string name, numeric size)

; note that lv_UserName must be pre-initialised with spaces
lv_UserName = "                    "
lv_BufLen = 20
activate "winapi".getusername(lv_UserName, lv_BufLen)
(lv_UserName now contains "AJM")

8. Process a file with registered application

This simulates the act of double-clicking on a file.

This requires the "ShellExecute" API which resides in shell32.dll. The calling sequence is as follows:-

SHELLEXECUTE (numeric handle, string verb, string file, string parameters, string directory, numeric noshowcmd)

lv_filename = "http://www.marston-home.demon.co.uk"
activate "winapi".shellexecute(0,"",lv_filename,"","",1)
(will open a browser window at that URL)

lv_filename = "something.doc"
activate "winapi".shellexecute(0,"",lv_filename,"","",1)
(will open that file using the registered word processor)

9. Browse for a folder

This will open a dialog box which allows the user to select a folder rather than a file.

This requires the "SHBrowseForFolder" and "SHGetPathFromIdList" API's which resides in shell32.dll. The calling sequence is as follows:-

SHBROWSEFORFOLDER (numeric pid)
SHGETPATHFROMIDLIST (numeric pid, string foldername)

activate "winapi".browseforfolder(lv_pointer)
($status now contains pathid)

activate "winapi".getpathfromidlist($status, lv_foldername)
(lv_foldername now contains the name of the chosen folder)

If anyone has other API signatures that they would like added to this collection please let me know.

Tony Marston
1st May 2003

mailto:tony@tonymarston.net
mailto:TonyMarston@hotmail.com
http://www.tonymarston.net

counter

Signatures for calling Windows API functions