network-machines

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. In earlier releases, the global argument was not provided and this function worked as if global were true. Now the default is nil, so the function, in the default, works differently.

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. In releases prior to 7.0, the symbol naming this function was in the common-graphics package. Starting in release 7.0, it is in the windows package.

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.

Behavior when an error occurs

If an unknown error occurs in win:network-machines (or win: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.

Copyright (c) 1998-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. The object described on this page has been modified in the 8.1 release; see the Release Notes.
Created 2007.4.30.