Function | Package: windows | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version

## network-shares

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.

#### Case A: machine is the keyword :connected

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:

1. the UNC remote name of the share (as a string) --- if you add a final slash (or backslash) to this string, or call excl:pathname-as-directory on the string, then directory can be called on the resulting value to find the files in the share; and
2. 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.

#### Case B: machine is the keyword :all

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")))
         ...)

#### Case C: machine is the UNC name of a machine

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)))))))

#### Case D: machine is the keyword :tree

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. 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.

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. (For win: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.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version