4.35.1 Windows-specific Operating System Interaction

The predicates in this section are only available on the Windows version of SWI-Prolog. Their use is discouraged if there are portable alternatives. For example, win_exec/2 and win_shell/2 can often be replaced by the more portable shell/2 or the more powerful process_create/3.

win_exec(+Command, +Show)

Windows only. Spawns a Windows task without waiting for its completion. Show is one of the Win32 SW_* constants written in lowercase without the SW_*: hide maximize minimize restore show showdefault showmaximized showminimized showminnoactive showna shownoactive shownormal. In addition, iconic is a synonym for minimize and normal for shownormal.

win_shell(+Operation, +File, +Show)

Windows only. Opens the document File using the Windows shell rules for doing so. Operation is one of open, print or explore or another operation registered with the shell for the given document type. On modern systems it is also possible to pass a URL as File, opening the URL in Windows default browser. This call interfaces to the Win32 API ShellExecute(). The Show argument determines the initial state of the opened window (if any). See win_exec/2 for defined values.

win_shell(+Operation, +File)

Same as win_shell(Operation, File, normal).

win_registry_get_value(+Key, +Name, -Value)

Windows only. Fetches the value of a Windows registry key. Key is an atom formed as a path name describing the desired registry key. Name is the desired attribute name of the key. Value is unified with the value. If the value is of type DWORD, the value is returned as an integer. If the value is a string, it is returned as a Prolog atom. Other types are currently not supported. The default‘root' is HKEY_CURRENT_USER. Other roots can be specified explicitly as HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE or HKEY_USERS. The example below fetches the extension to use for Prolog files (see README.TXT on the Windows version):

?- win_registry_get_value(
       'HKEY_LOCAL_MACHINE/Software/SWI/Prolog',
       fileExtension,
       Ext).

Ext = pl

win_folder(?Name, -Directory)

True if Name is the Windows‘CSIDL' of Directory. If Name is unbound, all known Windows special paths are generated. Name is the CSIDL after deleting the leading CSIDL_ and mapping the constant to lowercase. Check the Windows documentation for the function SHGetSpecialFolderPath() for a description of the defined constants. This example extracts the‘My Documents' folder:

?- win_folder(personal, MyDocuments).

MyDocuments = 'C:/Documents and Settings/jan/My Documents'

win_add_dll_directory(+AbsDir)

This predicate adds a directory to the search path for dependent DLL files. If possible, this is achieved with win_add_dll_directory/2. Otherwise, %PATH% is extended with the provided directory. AbsDir may be specified in the Prolog canonical syntax. See prolog_to_os_filename/2. Note that use_foreign_library/1 passes an absolute path to the DLL if the destination DLL can be located from the specification using absolute_file_name/3. This predicate is available from library library(shlib) and can be autoloaded.

win_add_dll_directory(+AbsDir, -Cookie)

This predicate adds a directory to the search path for dependent DLL files. If the call is successful it unifies Cookie with a handle that must be passed to win_remove_dll_directory/1 to remove the directory from the search path. Error conditions:

• This predicate fails if Windows does not yet support the underlying primitives. These are available in recently patched Windows 7 systems and later.
• This predicate throws an exception if the provided path is invalid or the underlying Windows API returns an error.

If open_shared_object/2 is passed an absolute path to a DLL on a Windows installation that supports AddDllDirectory() and friends,^{148Windows 7 with up-to-date patches or Windows 8.} SWI-Prolog uses LoadLibraryEx() with the flags LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR and LOAD_LIBRARY_SEARCH_DEFAULT_DIRS. In this scenario, directories from %PATH% are not searched. Additional directories can be added using win_add_dll_directory/2.

win_remove_dll_directory(-Cookie)

Remove a DLL search directory installed using win_add_dll_directory/2.

win_process_modules(-FileNames)

This predicate is a wrapper around EnumProcessModules(). FileNames is unified with a list of absolute paths for all modules of the Windows process. Modules are the main executable file and all DLLs loaded into the process, except data DLLs. The returned file names are in canonical Prolog representation. This predicate may be used to debug loading a DLL from an unexpected location and as a helper for packaging all dependencies when creating a distribution. According to the Windows documentation this API may return incorrect results if DLLs are loaded or unloaded while EnumProcessModules() is in progress. See also qsave_program/2.

win_get_user_preferred_ui_languages(+Format, -Languages)

Unifies Languages with a list of the user preferred languages (Windows Display Languages) in order of preference. If Format is name, the list elements are atoms. See Language Names for details. If Format is id, Languages is a list of numeric language ids represented as Prolog integers. This predicate provides Windows alternative to setlocale/3 using the category messages.