|
Allegro CL version 11.0 | ||||||||
Function, windows package
Arguments: dir
dir must be a pathname object or pathname namewstring. (If the argument is a namestring, the slash after the final directory name may be either included or excluded.) This function takes dir and returns a list of pathnames for its immediate subdirectories.
This function is provided on Windows simply because it is faster than deriving the same information by using more general functions such as directory or map-over-directory.
This function is defined in the :winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.
Function, windows package
Arguments: device-name
Returns a plist containing miscellaneous information about a particular filesystem. device-name may be a character (such as #\C); a string ("C" or "C:"); or a symbol (:c), in which case the printname will be used. If the information cannot be determined for any reason, nil is returned. Typically, if device-name names a CD drive whose door is open or which does not contain a CD, or a floppy drive without a floppy, nil is returned.
A plist is a list with an even number of elements where the 1st, 3rd, etc. elements are labels, often keywords, and the 2nd, 4th, etc. elements are values associated with the corresponding label.
:winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.Function, windows package
Arguments: device-name
Returns a keyword indicating the physical type of drive named by device. device-name may be a character (such as #\C); a string ("C" or "C:"); or a symbol (:c), in which case the printname will be used. Possible returned values include :removable (includes diskette drives), :fixed (regular hard disks), :remote (a networked drive on another machine), :cdrom, :ramdisk, :no-root-directory (for a drive that appears not to be set up), :unknown (drive type cannot be determined). If the filesystem is not mounted, nil is returned.
:winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.Function, windows package
Arguments:
Returns a list of the device names of all file systems that are available on the machine, both local and networked, both mounted and unmounted. The values in the list are suitable as arguments to file-system-info and file-system-type.
This function is defined in the :winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.
Function, windows package
Arguments:
This function combines the information returned by the functions file-systems, file-system-type, and file-system-info into a single list.
Each member of the returned list is itself a list that describes one file system. This sublist is a plist where the first key/value pair is :name with the the name of the file-system (as returned by file-systems), followed by :type with the value returned by file-system-type, followed by the plist values returned by file-system-info. The Tools menu | Inspect System Data | Online File Systems command inspects the list returned by this function.
Note that a drive for which file-system-info returns nil has an entry in the list returned by file-systems-info even though they are not ready for use. Thus, if G is the CD drive, and there is no CD inserted, file-system-info returns nil but (:NAME "G:" :TYPE :CDROM) is in the list returned by file-systems-info. Similarly, if A is the floppy drive and no floppy is inserted, file-system-info returns nil and (:NAME "A:" :TYPE :REMOVABLE) is in the list returned by file-systems-info. Therefore, if you are interested in whether a drive is ready, you may want to apply file-system-info to its name after discovering its name from file-systems-info. (In fact, analysis of the whole list returned by file-systems-info can tell you whether the drive is ready -- ready drives typically have volume names and other attributes not appearing in the list of an unready drive.)
MSDN (MicroSoft Developer Network) information suggests that it is possible that a call to file-systems-info will not complete if a CD drive or a floppy drive (or such) is not ready, as the system will display a modal dialog saying the drive is not ready when it tries to get information about the drive. In practice, this does not seem to happen (it has never been reported), but wrapping the call to file-systems-info as follows will guarantee that it will not happen.
(let* (former-error-mode)
(unwind-protect
(progn
(setq former-error-mode (win:SetErrorMode 1))
(cg:file-systems-info))
(when former-error-mode
(win:SetErrorMode former-error-mode))))This function is defined in the :winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only. In releases prior to 7.0, the symbol naming this function was exported from the common-graphics package. Starting in release 7.0, it is exported only from the windows package.
Function, windows package
Arguments: file
Returns the file version information (VERSIONINFO) from a file on the Microsoft Windows platform. The can include general attributes of the file such as a description of the file and the name of the company that supplies it, though the Microsoft API refers to this block of information as "file version info". This information appears, for example, on the Version tab of the properties dialog for a file in Microsoft's File Explorer.
file should be the pathname or path namestring of a file. The file is typically an EXE or DLL file.
The return value will be a plist of the version info strings that exist in the file, where the keys are keywords that match the keyword parameters of set-file-version-info (see that function for a list of the file attribute keywords). The value for each of these keys will be a list of the length of the field and the string that's currently in the field (where the current string may be shorter than the field length). The plist will include entries only for the subset of the allowed attributes that are defined in the specified file.
The returned plist will also contain entries for :language-id (an integer), :language-name (a string), and :code-page (an integer). These indicate the language in which the information strings are defined. An exception is that if there is no file version info resource in the file at all, then nil is returned.
(file-version-info "c:/windows/system32/charmap.exe")
A value similar to following is returned.
(:company-name (21 "Microsoft Corporation")
:file-description (13 "Character Map")
:file-version (33 "5.1.2600.0 (xpclient.010817-1148)")
:internal-name (11 "charmap.exe")
:legal-copyright (45 "© Microsoft Corporation. All rights reserved.")
:original-filename (11 "charmap.exe")
:product-name (36 "Microsoft® Windows® Operating System")
:product-version (10 "5.1.2600.0")
:language-id 1033
:language-name "English (United States)"
:code-page 1200)The function generate-application takes a file-version-info argument which allows users to specify the VERSIONINFO of the application executable. See Setting the VERSIONINFO of the application executable on Windows in delivery.html.
Function, windows package
Arguments:
Returns a property list that contains statistics about the real and virtual memory of the computer. This function is a thin layer on the Microsoft function GlobalMemoryStatusEx, and is therefore available only on the Windows platform. It is in the :windows module, which is always present in the IDE, and which can be loaded with the form (require :windows) in a base Lisp.
For more information, look up the MEMORYSTATUSEX structure on Microsoft's developer web site http://msdn.com. Here is how the keys of the property list that is returned by memory-status map to the Microsoft structure:
Property List Key MEMORYSTATUSEX Slot
:total-physical dwTotalPhys
:available-physical dwAvailPhys
:total-paging dwTotalPageFile
:available-paging dwAvailPageFile
:total-addressable dwTotalVirtual
:available-addressable dwAvailVirtual
:load dwMemoryLoadIn addition, the property list includes a :percent-used key, whose value is computed by the following formula (partly to round the value to two decimal places):
(- 100 (/ (round (* 100 (/ (* 100.0 (+ dwAvailPhys dwAvailPageFile))
(+ dwTotalPhys dwTotalPageFile))))
100.0))Function, windows package
Arguments: global return-tree
Returns a list of all computers in the local area network. Each member of the returned list is itself a list of (1) the UNC remote network name of a computer, such as "\\beast", and (2) the "comment" for the machine, such as "Support PC (Win XP)". Each of these two values is always a string, where the null string will be returned for the comment when no comment has been set up for a machine. See also network-shares.
When the global keyword argument is nil (the default), only the "current and default network context" is searched. When true, the entire network is searched.
When return-tree is true and global keyword argument is true, the returned list will be a tree structure similar to the "My Network Places" tree in the Windows File Manager. When return-tree is nil (the default), a simple list of all machines will be returned as before.
Here is a snippet of a typical returned value:
(("\\\\ADMIN" "")
("\\\\BEAST" "Samba 2.0.7")
...
("\\\\SOULCHEESE" "Masako's PC") ...)This function is defined in the :winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.
This function is used by ask-user-for-new-or-existing-directory.
Implementation note: On Windows, this function returns information as provided by the function WNetEnumResource in the Windows Networking (WNet) area of the Windows API.
If an unknown error occurs in network-machines (or network-shares) while trying to access a particular machine, then the symbol :unknown-error will be returned rather than signaling an error. This is similar to returning :access-denied when a machine does not allow access.
Function, windows package
Arguments: machine global
Returns a value that describes the logical filesystems that are currently offered for sharing by one or more computers in the local area network. The form of the returned value depends on the value of the machine argument.
When the global keyword argument is nil (the default), only the "current and default network context" is searched. When true, the entire network is searched.
The following describes the two special cases of the machine argument (A and B), followed by the general case (C) where machine is a machine name. Finally, case (D) is described, where a tree of values is returned.
If machine is the keyword :connected, then a list is returned that contains one member for each share that is currently connected to the computer where the call was made, such as:
(("\\\\BEAST\\pc" "Z:")
("\\\\SPOT\\ACL" nil)
("\\\\ROMEO\\smith" nil))where each member of the list represents a share, and is itself a list consisting of:
the UNC remote name of the share (as a string) --- if you add a final slash (or backslash) to this string, or call pathname-as-directory on the string, then directory can be called on the resulting value to find the files in the share; and
the local name that this computer maps to this share, if any (this is typically a drive letter, such as "z:"), and otherwise nil.
When non-nil, this is always a string.
If machine is the keyword :all, then a list is returned where there is a member for each machine that is returned by network-machines, and each of these members is a list of (1) the UNC machine name (a string) and (2) either (a) the symbol :access-denied, when that machine does not allow the current user access to its shares, or else (b) the list of shares that would be returned if machine were the machine name, as in case C. This can take a while to run, since it asks every machine in the network what its shares are.
Sample returned value:
(("\\\\ADMIN" :access-denied)
("\\\\BEAST"
(("\\\\BEAST\\cdroms" "")
("\\\\BEAST\\support" "Support Directories")
("\\\\BEAST\\home1" "Home Directories")))
...)Otherwise machine should be the UNC name (a string) of a machine in the network (including the two backslashes at the front), such as "\\beast"; a list of all such names is returned by network-machines. In this case, either (1) the symbol :access-denied is returned, if the machine will not allow the current user access to its shares, or (2) a list of that machine's shares is returned, where each share is a list of: (a) the UNC name of the share, such as "\\beast\pc", and (b) the "comment" for the share (which is always a string).
Example: The following expression would find an accessible share and return a list of its name and the top-level files in it:
(dolist (machine (network-machines))
(let* ((shares (network-shares (first machine))))
(unless (or (null shares)
(eq shares :access-denied))
(let* ((directory-name (concatenate 'string
(caar shares)
"/")))
(return (list directory-name
(directory directory-name)))))))win:network-shares returns the set of all networked machines and their shares as a tree rather than a list (when the global argument is true). When global is nil, :tree is the same as :all.
This function is defined in the :winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.
Implementation note: On Windows, this function returns information as provided by the function WNetEnumResource in the Windows Networking (WNet) area of the Windows API.
If an unknown error occurs in win:network-machines (or network-shares) while trying to access a particular machine, then the symbol :unknown-error will be returned rather than signaling an error. (For network-shares, this symbol would replace the list of shares for a particular machine in the returned list.) This is similar to returning :access-denied when a machine does not allow access.
Function, windows package
Arguments:
Returns a plist (a list with alternating keys and values) with information about the operating system provided by calls to the Windows API. Keys are all keywords, including :major-version, :minor-version, :build-number, and :platform.
This function is defined in the :winapi module. If that module is not loaded, evaluate (require :winapi). This function is available on Windows machines only.
Function, windows package
Arguments: existing-exe icon-file &key (resource-name "ACLICON")
This function is useful for replacing the application icon inside an executable file for delivery. It simply calls set-exe-icons-nt if the operating system is a member of the NT branch of Windows (which includes win2000 and XP), and otherwise calls set-exe-icons. Refer to those functions for complete information.
The resource-name argument is passed as the icon-name argument to those functions, and existing-exe and icon-file are passed as the similarly named arguments of those functions.
On the non-NT branch, set-application-icon handles the creation of a temporary exe path to pass to set-exe-icons, and the deletion of the no-longer-used copy of the exe file. It leaves a single resulting exe file at the original existing-exe path.
This function is called directly by generate-application when it is passed a non-null icon-file argument, as described in delivery.html. It is also called by the IDE's File | Build Project Distribution command when the current project has a non-null icon-file property.
Function, windows package
Arguments: exe option-strings
exe should be a pathname or string which represents the executable image program for which you want to change the default command line arguments. By default we mean the command line arguments are not given in an actual call to the program, but the program behaves as if they were given. option-strings is a list of strings representing command line arguments, such as '("+m" "+R"). For example:
(win:set-default-command-line-arguments "foo.exe" '("-I" "bar.dxl"))would cause foo.exe to load
(win:set-default-command-line-arguments "foo.exe" '("+B" "+cn"))would cause foo.exe to start without a splash screen and to not grab the focus on startup.
A typical use of this function is to call it on the executable created with generate-application:
(generate-application "foo" "foo/" ...)
#+windows
(win:set-default-command-line-arguments "foo/foo.exe" '("+B" ...))See Command line arguments in startup.html for a list of command-line arguments accepted by Allegro CL.
Function, windows package
Arguments: existing-exe new-exe icon-name icon-file
This function is useful for replacing the application icon inside an executable file for delivery. It copies the executable at existing-exe to the path specified by new-exe, replacing the embedded icon resource whose name is icon-name with the icon from icon-file.
The newer function set-exe-icons-nt is preferable to this one if you are on the NT branch of Windows (which includes win2000 and XP).
existing-exe should be a pathname or path namestring that specifies the .exe executable file whose application icon is to be replaced.
new-exe should be a pathname or path namestring at which to create a copy of existing-exe with the replacement icon. (existing-exe is not modified.)
icon-name should be the name of the icon resource to be replaced. In an Allegro CL executable file (either a development lisp or a generated application), the application icon is named "ACLICON". This is the icon that will appear in the Windows taskbar and alt-tab window when the application is running, and in the File Explorer and Start Menu to represent the .exe file.
icon-file should be a pathname or path namestring that specifies a .ico icon file. The file should contain either one or two images, where each one is 4 bits-per-pixel and either 32 by 32 or 16 by 16 pixels large. The newer function set-exe-icons-nt does not have this restriction, though it works only on the NT branch of Windows. That function is also more robust and is therefore preferable when running NT.
The following example would copy myapp.exe to temp.exe, replacing the Franz icon in temp.exe with the custom icon defined in myicon.ico.
(win:set-exe-icons "c:/foo/myapp.exe" "c:/foo/temp.exe"
"ACLICON" "c:/foo/myicon.ico")See the description of the icon-file keyword argument to generate-application, described in delivery.html for more information on setting the icon for an application on Windows. Either this function of the related set-exe-icons-nt function (as appropriate for the operating system) will be called. See also set-application-icon.
Function, windows package
Arguments: existing-exe icon-name icon-file
This function is useful for replacing the application icon in an executable file for delivery. It modifies existing-exe to replace the embedded icon resource whose name is icon-name with the icon from icon-file.
existing-exe should be a pathname or path namestring that specifies the .exe executable file whose application icon is to be replaced.
icon-name should be the name of the icon resource to be replaced. In an Allegro CL executable file (either a development lisp or a generated application), the application icon is named "ACLICON". This is the icon that will appear in the Windows taskbar and alt-tab window when the application is running, and in the File Explorer and Start Menu to represent the .exe file.
icon-file should be a pathname or path namestring that specifies a .ico icon file. Any valid .ico file should work (unlike with set-exe-icons). Generally it's best if the .ico file contains at least two images for the common 32 by 32 and 16 by 16 sizes, so that Windows doesn't need to interpolate pixels.
The following example would replace the Franz icon in myapp.exe with the custom icon defined in
(win:set-exe-icons-nt "c:/foo/myapp.exe"
"ACLICON" "c:/foo/myicon.ico")See the description of the icon-file keyword argument to generate-application, described in delivery.html for more information on setting the icon for an application on Windows. Either this function of the related set-exe-icons function (as appropriate for the operating system) will be called. See also set-application-icon.
Function, windows package
Arguments: *file &rest &key comments company-name file-description file-version internal-name legal-copyright legal-trademarks original-filename product-name product-version private-build special-build
Returns the file version info strings from a file on the Microsoft Windows platform, after optionally modifying some of the existing fields in the file. See file-version-info for a description of the returned value.
file should be the pathname or path namestring of a file. The file is typically an EXE or DLL file.
The specified file must not be executing when this function is called, or else it will fail when it attempts to obtain write access to the file. (If you want to modify the .exe file which is running Lisp -- allegro.exe or mlisp.exe or whatever -- you have to operate on a copy of that file because the one executing should not be modified.)
Any keyword argument that is passed should be a string to replace the existing string for that field in the file, if any. If that field currently does not have a value in the file, or the file has no file version info resource at all, then the new value is not written.
If the field does exist in the file but the field is not long enough for the new value, then the new value is truncated to fit the existing field size. There is no way to increase the length of a field or to add the fields that are not defined already. The plist that is returned reflects the state of the file after any fields have been updated, reflecting any such truncation that was done.
It is a good idea to first call file-version-info to see which attributes are defined in the file, and the length of the field for each one. The field length that is returned for each attribute is the maximum character length of a lisp string that will fit in the field.
If the file is an application that was built with Allegro, then the EXE file is actually a copy of a standard lisp EXE, and so the fields will be limited to the lengths of the fields that Franz established when creating this EXE file.
(set-file-version-info "c:/temp/my-app.exe"
:company-name "Our Company"
:file-version "3.6.15.4"
:file-description "This is our latest killer app."
:comments "Nothing more to say.")The function generate-application takes a file-version-info argument which allows users to specify the VERSIONINFO of the application executable. See Setting the VERSIONINFO of the application executable on Windows in delivery.html.
Function, windows package
Arguments: directory-identifier &key create
This function finds a special Windows directory such as the My Documents folder or the Start Menu folder. This is useful if an application needs to find files in one of these special folders or to place files there.
Two values are returned. The first value is the directory pathname if it was found, or nil otherwise.
The second value indicates the status of the requested directory. If the directory was found, then the second value is nil. If the directory specifier is valid on this version of Windows but the directory itself does not exist, then the second value will be :not-found. If the directory specifier is not valid on this version of Windows, then the second value will be :invalid. If some other error code is returned then the second value will be :unknown.
directory-identifier should be one of the keywords listed below, or the SHGetFolderPath integer constant to which it corresponds.
If create is true and the requested directory is valid on this version of Windows but does not exist, then Windows will be asked to create the directory. It may not actually create it, however. If it does create the directory, its path will be returned.
Here are the possible keyword values for the directory-identifier argument. For their meanings, look up the Windows API function SHGetFolderPath at http://msdn.com and refer to the similarly named "CSIDL" constants.
Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.
|
Allegro CL version 11.0 | ||||||||