Apple APPLESHARE 3.0 File Server Controls

AppleShare File Server 3.0 Control

_____________________________________________________________________________
CHAPTER 1-SERVER CONTROL CALLS
_____________________________________________________________________________

This chapter introduces the server control calls available with the
AppleShare File Server 3.0 and describes how server control calls interact
with the main elements of file server software. The chapter presents each
server control call individually and includes a sample code segment for each
call that demonstrates how you might use the call in your own programs.

Server control calls enable applications to monitor and control the major
functions of the AppleShare File Server 3.0. These control calls let your
programs

- get and modify server configuration information

- check a server's status

- start and stop file service

- get information on users, volumes, and shared items

- disconnect users (including the users of a specific volume)

- send messages to users

- set or clear the copy-protect status of files

- use server event handlers

Server control calls, together with server event handling (described in
Chapter 2), make it possible to create any number of services and utilities
for the AppleShare File Server 3.0. Because you can monitor file usage -- who
uses files, which files are saved to or deleted from a server, where files
are copied to, and so on -- you can create file-usage audit trails, generate
server-usage statistics, and perform other types of accounting services. You
can also control file servers remotely. By monitoring the number of active
users, logging off idle users, and controlling log-on access, you can perform
load-balancing services for a group of related servers. Many other services
are possible. AppleShare File Server 3.0 server control calls and event
handling form a complete interface through which your applications and
programs can control and extend the capabilities of the file server software.
This guide refers to such programs and applications as server additions.

Note Macintosh File Sharing supports a subset of the AppleShare File Server

3.0 server control calls. See Appendix A for a list of these calls.

Main elements of file servers and server control calls

This section describes the software components and data files that make up
the AppleShare File Server 3.0 and Macintosh File Sharing. Because the
AppleShare File Server 3.0 and Macintosh File Sharing perform similar
functions, the components for each are similar and both use the same types of
data files.

AppleShare File Server 3.0 software components

The AppleShare File Server 3.0 is composed of a number of files. The File
Server Extension provides the actual functionality of the file server. The
AppleShare File Server and the AppleShare Admin applications provide the user
interface for the server.

This section describes each of AppleShare File Server 3.0 software
components. The section "Data Files," later in this chapter, describes the
Users & Groups Data File and the AppleShare PDS file.

File Server Extension The File Server Extension contains the actual file
server code. It is an extension of the system and resides in the Extensions
folder. The File Server Extension is a launchable file, though its file type
is 'INIT' instead of 'APPL', which prevents users from starting it from the
Finder. (The 'INIT' file type also tells the system to put the file in the
Extensions folder and causes the extension to be opened during system
startup.) When the File Server Extension is launched, it runs as a background
application.

The File Server Extension contains no user interface of its own. The user
interface is provided by the AppleShare File Server and AppleShare Admin
applications (described next). These applications communicate with the File
Server Extension primarily by means of server control calls. Server control
calls are also the primary means of communication between server additions
and the file server. The File Server Extension communicates with remote
AppleShare clients through Apple Filing Protocol (AFP) sessions, and,
locally, with shared volumes and files by means of Macintosh File Manager
routines.

When the File Server Extension is launched, it checks its environment, the
Users & Groups Data File, and the desktop databases and AppleShare PDS files
of appropriate volumes. (The File Server Extension does not attempt to share
remote volumes, or volumes such as floppy disks or volumes that are ejected
and off line during startup.) If an important required condition is not
satisfied, the offending volume will not be prepared for use with the file
server or the file server will not be enabled.

Once started, the File Server Extension takes over the dispatching of all
file system calls -- both local calls and remote requests. Essentially, the
file server acts as a mediator between the network and your local HFS
volumes. The file server imposes access privilege constraints on AFP requests
and implements some calls that are not implemented in HFS -- such as those
that govern byte-range locking, access privileges, and extended file access
permissions.

AppleShare File Server The AppleShare File Server application provides part
of the user interface for the File Server Extension. Users start the file
server by opening the AppleShare File Server application. The AppleShare File
Server application also provides the interface for controlling and monitoring
the file server while it is running. The AppleShare File Server application
displays the Volume Info window, which lists the volumes that are available
on the server, and the Connected Users window, which lists users who are
currently logged on to the server. The Server menu lets you unmount volumes,
disconnect users, send messages to users, and set the greeting message. (See
the AppleShare Server 3.0 Administrator's Guide for more information about
the features of the AppleShare File Server 3.0 user interface.)

The AppleShare Installer initially installs the AppleShare File Server
application in the System Folder, but the file can reside anywhere on the
server volume. The AppleShare File Server application communicates with the
File Server Extension primarily by means of server control calls.

AppleShare Admin The AppleShare Admin application provides the user
interface for defining users and groups for the server. The AppleShare Admin
application also lets you set preferences, set access privileges, and perform
other administrative tasks for the file server. (See the AppleShare Server

3.0 Administrator's Guide for more information about the administrative
features of the AppleShare File Server 3.0.)

Like the AppleShare File Server application, the AppleShare Admin application
is initially installed in the System Folder but can reside anywhere on the
server volume. It communicates with the File Server Extension primarily by
means of server control calls. It also uses the AppleShare PDS file and the
Users & Groups Data File to store and retrieve information about server
volumes and the users and groups defined for the server, respectively.

Network AppleShare clients Network workstations with AppleShare client
software installed can connect to the File Server Extension. AppleShare
clients communicate with the server through AFP sessions.

File Manager The Macintosh File Manager normally handles local requests for
file access. While the file server is running, however, the File Server
Extension intercepts all file access calls from the File Manager.

Server additions Applications, INITs, extensions, and other types of
programs can access the File Server Extension by using server control calls.
A program that uses server control calls is referred to as a server addition.
This guide tells you how to create server additions by using server control
calls in your own programs.

Macintosh File Sharing software components

Like the AppleShare File Server 3.0, Macintosh File Sharing is composed of a
number of parts distributed across several files in the System Folder. The
File Sharing Extension provides the actual functionality of the AFP server.
Five other files -- the Network Extension, three control panels, and the
Finder -- work together to provide the user interface.

The File Sharing Extension handles all requests for access to files residing
on local volumes, including local requests from the Macintosh File Manager
and server additions, and remote requests from AFP clients.

This section describes the software components of Macintosh File Sharing. The
section "Data Files," later in this chapter, describes the Users & Groups
Data File and the AppleShare PDS file.

File Sharing Extension The File Sharing Extension contains the actual file
server code.

It is a system extension that resides in the Extensions folder. The File
Sharing Extension is a launchable file, though its file type is 'INIT'
instead of 'APPL', which prevents users from starting it from the Finder.
(The 'INIT' file type also tells the system to put the file in the Extensions
folder and causes the extension to be opened during system startup.) When the
File Sharing Extension is launched, it runs as a background application.

The File Sharing Extension contains no user interface of its own. The user
interface is provided by the Network Extension, which allows users to start
and to control the File Sharing Extension. The File Sharing Extension
communicates with the Network Extension primarily by means of server control
calls. The File Sharing Extension communicates with the Finder by means of
PPC events, and with a remote AppleShare client through AFP sessions. The
File Sharing Extension also communicates with local volumes and files by
means of Macintosh File Manager routines, and with server additions by means
of server control calls.

When the File Sharing Extension is launched, it checks its environment, the
Users & Groups Data File, and the desktop databases and AppleShare PDS files
of appropriate volumes. (The File Sharing Extension does not attempt to share
remote volumes, or volumes such as floppy disks or volumes that are ejected
and off line during startup.) If an important required condition is not
satisfied, the offending volume will not be prepared for use with the file
server or file sharing will not be enabled.

Once started, the File Sharing Extension takes over the dispatching of all
file system calls -- both local calls and remote requests. Essentially, the
File Sharing Extension acts as a mediator between the network and your local
HFS volumes. The File Sharing Extension imposes access privilege constraints
on AFP requests and implements some calls that are not implemented in HFS -­such as those that govern byte-range locking, access privileges, and extended
file access permissions.

Network Extension The Network Extension provides the user interface for
Macintosh File Sharing. It is an extension of the Finder and resides in the
Extensions folder. The Network Extension is dynamically linked with the
Finder code at startup time and uses the Finder's code to control its user
interface. The user interface includes what appears to users to be the
Sharing Setup, Users & Groups, and File Sharing Monitor control panels. When
a user opens any one of these control panels, the Network Extension code
intercepts the launch command, opens the appropriate window, and controls the
interaction with the user.

Based on user interactions, the Network Extension communicates with the
server primarily by means of server control calls. The File Server Extension
communicates with users through the Network Extension by sending high-level
Apple events to display dialog boxes. The Network Extension relies on the
AppleShare PDS file and the Users & Groups Data File for information about
server volumes and the users and groups defined for the server, respectively.

Finder The Finder provides part of the Macintosh File Sharing services. The
Sharing menu item in the Finder's File menu lets users view and set the
access privileges for disks and folders. In addition, through its extension
mechanism, the Finder provides an environment for running the Network
Extension code. The Finder communicates with the file server by using
augmented Macintosh File Manager routines.

File Sharing Monitor, Sharing Setup, and Users & Groups These control panel
files trigger execution of the appropriate Network Extension code. The
control panel files themselves contain no executable code.

Network AppleShare clients Network workstations with AppleShare client
software installed can connect to the File Sharing Extension. AppleShare
clients communicate with the server by means of AFP packets.

File Manager The Macintosh File Manager normally handles local requests for
file access. When Macintosh File Sharing is turned on, however, the File
Sharing Extension intercepts all file access calls from the File Manager.

Server additions Applications, INITs, extensions, and other types of
programs can access the File Server Extension by using server control calls.
A program that uses server control calls is referred to as a server addition.
This guide tells you how to create server additions by using server control
calls in your own programs.

Data files

Both the AppleShare File Server 3.0 and Macintosh File Sharing use two data
files to store user and directory information: the Users & Groups Data File
and the AppleShare PDS file.

Users & Groups Data File The Users & Groups Data File contains a database of
the users and groups defined on your computer. You define users and groups
for the AppleShare File Server 3.0 by using the AppleShare Admin application.
You define users and groups with Macintosh File Sharing by using the Users &
Groups control panel. The data file is a B-Tree file. With the AppleShare
File Server 3.0, the AppleShare Admin and File Server Extension files use the
Users & Groups Data File. With Macintosh File Sharing, the Network Extension
and File Sharing Extension files use the Users & Groups Data File.

AppleShare PDS The AppleShare PDS file is an invisible file that resides at
the root of every unlocked volume. PDS stands for parallel directory
structure. The AppleShare PDS file contains the access privilege and share­point information for the volume on which the file resides. The PDS file
determines the access privileges of the volume's users and groups, which are
defined in the Users & Groups Data File. Because the PDS file is created in
conjunction with the Users & Groups Data File, the Users & Groups Data File
must not be removed from the volume. (If the Users & Groups Data File is
lost, the access privilege and share-point information contained in the PDS
file is lost as well.)

The PDS file for CD-ROM drives resides in the File Sharing folder (in the
Preferences folder) for Macintosh File Sharing, and in the File Server folder
(in the Preferences folder) for the AppleShare File Server 3.0.

Using server control calls

This section presents each of the server control calls available with the
AppleShare File Server 3.0. The server control calls are presented in logical
functional groups, more or less in the order in which you would use them in
server additions.

For each server control call, there is a function named MycallName.
Typically, this function shows how to fill in the parameter block, make the
server control call, and retrieve any result values returned by the call.
When necessary, the MycallName functions also include code that makes the
server control calls supported by Macintosh File Sharing behave as much as
possible in the same manner as they behave when used under the AppleShare
File Server 3.0. For example, a MycallName function may return a value that
is normally returned by the AppleShare File Server 3.0 but that is not
supplied by Macintosh File Sharing. In other cases, for example with the
SCGetExpFldr call, the function contains code that makes the call work "as
advertised."

Some of the server control call descriptions are accompanied by a second
segment of sample code that shows a particular use of that call. Each of
these additional code segments performs one of the following tasks:

- gets the server version, status, and setup information and then stores that
information in global variables for later use by other functions

- lists the shared volumes and folders

- lists the installed server event handlers

- lists the users connected to the server

- gets the mount information for a user's mounted volumes or folders

- disconnects a user from the server

- sends a message to all connected users

- disconnects the users of a specified volume

Some of the code samples use global variables to store information that might
be needed by other functions. Here are the global variables used within these
code samples:

- General

- gErr: OSErr

- gHasServerDispatch: Boolean

- Used by SCServerVersion

- gServerExtensionName: Str31

- gServerType: Integer

- gServerVersion: Integer

- Used by SCPollServer

- gServerState: Integer;

- gDisconnectState: Integer;

- gServerError: Integer;

- gSecondsLeft: LongInt;

- Used by SCGetSetupInfo

- gSetupInfoRec: SetupInfoRec;

- gMaxVolumes: Integer

- gMaxExpFolders: Integer

- gCurMaxSessions: Integer

Determining if server control calls are available

Before using any of the other control calls, use the TrapAvailable call to
make sure that the server dispatch trap is available. The following line of
code tests directly for the existence of the server dispatch trap:

gHasServerDispatch := TrapAvailable(ServerDispatch)

The "Compatibility Guidelines" chapter of Inside Macintosh, Volume VI,
contains the source code for the TrapAvailable call.

Calling conventions

After assuring that server control calls are available, issue the
SyncServerDispatch call with the following code:

scErr:=SyncServerDispatch(@scPB);

The actual interface for the SyncServerDispatch call is defined by the server
control call interface file. See Appendix B for a listing of that file. The
SyncServerDispatch call appears in the "Server Control Routine" section of
Appendix B.

Getting and modifying server

configuration information

This section describes the server control calls that you use to get and to
modify server configuration information.

SCServerVersion

The following function calls SCServerVersion to get the name of the file
server extension and the server's type and version.

FUNCTION MySCServerVersion (ExtNamePtr: StringPtr;

VAR ServerType: Integer;

VAR ServerVersion: Integer):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.versionPB.scCode := SCServerVersion;

scPB.versionPB.scExtNamePtr := ExtNamePtr;

MySCServerVersion := SyncServerDispatch(@scPB);

ServerType := scPB.versionPB.scServerType;

ServerVersion := scPB.versionPB.scServerVersion;

END;

The following segment of code gets the server version information and stores
it in global variables for later use. (Global variables and their data types
are listed in "Using Server Control Calls," earlier in this chapter.)

err := MySCServerVersion(@gServerExtensionName,

gServerType, gServerVersion);

SCGetSetupInfo

The following function calls SCGetSetupInfo to get the file server's setup
information. If the server is a Macintosh File Sharing server (type =
MFSType), this function also fills in the fields that aren't returned by the
server control call. Before using this function, you must initialize
gServerType by using the SCServerVersion control call.

FUNCTION MySCGetSetupInfo (SetupPtr: SetupInfoRecPtr;

VAR MaxVolumes: Integer;

VAR MaxExpFolders: Integer;

VAR CurMaxSessions: Integer):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.setupPB.scCode := SCGetSetupInfo;

scPB.setupPB.scSetupPtr := SetupPtr;

MySCGetSetupInfo := SyncServerDispatch(@scPB);

CASE gServerType OF

MFSType:

BEGIN

MaxVolumes := 10;

MaxExpFolders := 10;

CurMaxSessions := SetupPtr^.SIMaxLogins;

END;

OTHERWISE

BEGIN

MaxVolumes := scPB.setupPB.scMaxVolumes;

MaxExpFolders := scPB.setupPB.scMaxExpFolders;

CurMaxSessions := scPB.setupPB.scCurMaxSessions;

END;

END;

END;

The following segment of code gets the server version information and stores
it in global variables for later use. (Global variables and their data types
are listed in "Using Server Control Calls," earlier in this chapter.)

err := MySCGetSetupInfo(@gSetupInfoRec, gMaxVolumes,

gMaxExpFolders, gCurMaxSessions);

SCSetSetupInfo

The following function calls SCSetSetupInfo to set the file server's setup
information.

FUNCTION MySCSetSetupInfo (SetupPtr: SetupInfoRecPtr):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.setupPB.scCode := SCSetSetupInfo;

scPB.setupPB.scSetupPtr := SetupPtr;

MySCSetSetupInfo := SyncServerDispatch(@scPB);

END;

Checking the server's status

This section describes the server control calls that you use to check the
server's status.

SCPollServer

The SCPollServer call returns information about the server's state, its
disconnect state, whether or not there has been an error, and how many
seconds are left before the server shuts down or before it disconnects a
user. The following function calls SCPollServer to get this information.

FUNCTION MySCPollServer (VAR ServerState: Integer;

VAR DisconnectState: Integer;

VAR ServerError: Integer;

VAR SecondsLeft: LongInt): OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.pollServerPB.scCode := SCPollServer;

{ Macintosh File Sharing doesn't return scSecondsLeft }

{ so zero it. }

scPB.pollServerPB.scSecondsLeft := 0;

MySCPollServer := SyncServerDispatch(@scPB);

ServerState := scPB.pollServerPB.scServerState;

DisconnectState := scPB.pollServerPB.scDisconnectState;

ServerError := scPB.pollServerPB.scServerError;

SecondsLeft := scPB.pollServerPB.scSecondsLeft;

END;

The following segment of code gets the server state, disconnect state, server
error, and seconds-left information and stores it in global variables for
later use. (Global variables and their data types are listed in "Using Server
Control Calls," earlier in this chapter.)

err := MySCPollServer(gServerState, gDisconnectState,

gServerError, gSecondsLeft);

SCGetServerStatus

The following function calls SCGetServerStatus to get the file server's
current status information, including the server flags, the number of active
sessions, the date of the last modification of the user list, the level of
server activity, and the date of the last modification of the volume list.

Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCGetServerStatus (NamePtr: StringPtr;

VAR ServerFlags: Integer;

VAR NumSessions: Integer;

VAR UserListModDate: LongInt;

VAR Activity: Integer;

VAR VolListModDate: LongInt):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.statusPB.scCode := SCGetServerStatus;

scPB.statusPB.scNamePtr := NamePtr;

MySCGetServerStatus := SyncServerDispatch(@scPB);

ServerFlags := scPB.statusPB.scServerFlags;

NumSessions := scPB.statusPB.scNumSessions;

UserListModDate := scPB.statusPB.scUserListModDate;

Activity := scPB.statusPB.scActivity;

VolListModDate := scPB.statusPB.scVolListModDate;

END;

Starting and stopping the file service

This section describes the server control calls that you use to start and
stop file servers.

SCStartServer

The following function calls SCStartServer to start the Macintosh File
Sharing server.

!! IMPORTANT The AppleShare File Server 3.0 is normally started by the
AppleShare File Server application. When the AppleShare File Server
application is launched, it checks to see if the file server is running. If
it is, the AppleShare File Server application assumes its role as the file
server's user interface. If the file server is not running, the AppleShare
File Server application starts the server by calling SCStartServer before
assuming its role as user interface.

If a server addition starts the AppleShare File Server 3.0 by calling
SCStartServer, the file service starts up, but the AppleShare File Server
application (the user interface) does not. Unless your program provides the
functionality of the AppleShare File Server application, it should probably
not call SCStartServer to start the AppleShare File Server 3.0. Instead,
start the file server in the usual way -- by launching the AppleShare File
Server application. !!

FUNCTION MySCStartServer: OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.startPB.scCode := SCStartServer;

scPB.startPB.scStartSelect := kCurInstalled;

scPB.startPB.scEventSelect := kFinderExtn;

MySCStartServer := SyncServerDispatch(@scPB);

END;

SCShutDown

The following function calls SCShutDown to shut down the file server.

!! IMPORTANT The AppleShare File Server application automatically quits if
the AppleShare File Server 3.0 is shut down with the SCShutDown call. !!

FUNCTION MySCShutDown (NumMinutes: Integer; Flags: Integer;

MessagePtr: StringPtr): OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.disconnectPB.scCode := SCShutDown;

scPB.disconnectPB.scNumMinutes := NumMinutes;

scPB.disconnectPB.scFlags := Flags;

scPB.disconnectPB.scMessagePtr := MessagePtr;

MySCShutDown := SyncServerDispatch(@scPB);

END;

SCCancelShutDown

The following function calls SCCancelShutDown to cancel a shutdown or
disconnect call in progress.

FUNCTION MySCCancelShutDown: OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.disconnectPB.scCode := SCCancelShutDown;

MySCCancelShutDown := SyncServerDispatch(@scPB);

END;

SCSleepServer

The following function calls SCSleepServer to temporarily shut down the file
server ("put it to sleep"). You might want to put a file server to sleep
before switching networks or temporarily turning off AppleTalk.

- Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCSleepServer (NumMinutes: Integer;

Flags: Integer;

MessagePtr: StringPtr): OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.disconnectPB.scCode := SCSleepServer;

scPB.disconnectPB.scNumMinutes := NumMinutes;

scPB.disconnectPB.scFlags := Flags;

scPB.disconnectPB.scMessagePtr := MessagePtr;

MySCSleepServer := SyncServerDispatch(@scPB);

END;

SCWakeServer

The following function calls SCWakeServer to reactivate an AppleShare File
Server 3.0 that has been temporarily shut down (that is, a file server that
is "sleeping").

Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCWakeServer: OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.startPB.scCode := SCWakeServer;

MySCWakeServer := SyncServerDispatch(@scPB);

END;

Obtaining status information about users, volumes, and shared items

This section describes the server control calls that you use to obtain
information about file server users, volumes, and shared volumes and folders.

SCGetExpFldr

The following function calls SCGetExpFldr to get information from the call's
return parameters about shared volumes and folders at a specified index
position. The return parameters provide information such as a folder's AFP
short name and directory ID, the number of users who have mounted the volume
or folder, and the index of a volume or folder. (See "SCGetExpFldr" in
Chapter 3 for detailed descriptions of the call's return parameters.) Before
using this function, you must initialize gServerType with the value returned
by the SCServerVersion control call.

FUNCTION MySCGetExpFldr (NamePtr: StringPtr;

VAR VRefNum: Integer;

VAR Logins: Integer;

Index: Integer;

VAR DirID: LongInt): OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.standardPB.scCode := SCGetExpFldr;

{ Initialize scVRefNum to 0 so we can tell if }

{ SCGetExpFldr returned something when used with }

{ Macintosh File Sharing }

scPB.standardPB.scVRefNum := 0;

IF Index < 0 THEN

BEGIN

{ File Sharing trashes memory if (scIndex < 0) and }

{ (scNamePtr <> NIL), so we'll prevent that from }

{ happening here. }

scPB.standardPB.scNamePtr := NIL;

{ and we'll return an empty string }

IF NamePtr <> NIL THEN

NamePtr^ := '';

END

ELSE

BEGIN

scPB.standardPB.scNamePtr := NamePtr;

END;

scPB.standardPB.scIndex := Index;

MySCGetExpFldr := SyncServerDispatch(@scPB);

CASE gServerType OF

MFSType:

BEGIN

IF scPB.standardPB.scVRefNum <> 0 THEN

BEGIN

VRefNum := scPB.standardPB.scVRefNum;

Logins := 0;

DirID := scPB.standardPB.scDirID;

END

ELSE { there's nothing at this index position }

{ so force the error code to make it act }

{ like AppleShare }

MySCGetExpFldr := fnfErr;

END;

OTHERWISE

BEGIN

VRefNum := scPB.standardPB.scVRefNum;

Logins := scPB.standardPB.scLogins;

DirID := scPB.standardPB.scDirID;

END;

END;

END;

SERVER CONTROL CALLS

The following procedure creates a list of shared volumes and folders. Before
using this procedure, you must initialize gMaxVolumes and gMaxExpFolders with
the values returned by the SCGetGetupInfo control call.

PROCEDURE GetAllExpFldrs;

VAR

Index: Integer;

shortName: Str13;

VRefNum: Integer;

Logins: Integer;

DirID: LongInt;

err: OSErr;

BEGIN

FOR Index := -gMaxVolumes TO gMaxExpFolders DO

IF Index <> 0 THEN { index 0 is undefined }

BEGIN

err := MySCGetExpFldr(@shortName, VRefNum, Logins,

Index, DirID);

IF err = noErr THEN

BEGIN

IF Index < 0 THEN

BEGIN

{ do something with the shared volume }

{ information }

END

ELSE

BEGIN

{ do something with the shared folder }

{ information }

END;

END

ELSE IF err <> fnfErr THEN

{ fnfErr only means there is nothing at this }

{ Index position }

BEGIN

{ handle any unexpected errors }

END;

END;

END;

SCGetUserNameRec

The following function calls SCGetUserNameRec to get information about a user
connected to the file server.

Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCGetUserNameRec (NamePtr: StringPtr;

VAR Position: LongInt;

VAR UNRecID: LongInt;

VAR UserID: LongInt;

VAR LoginTime: LongInt;

VAR LastUseTime: LongInt;

VAR SocketNum: AddrBlock):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.userInfoPB.scCode := SCGetUserNameRec;

scPB.userInfoPB.scNamePtr := NamePtr;

scPB.userInfoPB.scPosition := Position;

MySCGetUserNameRec := SyncServerDispatch(@scPB);

Position := scPB.userInfoPB.scPosition;

UNRecID := scPB.userInfoPB.scUNRecID;

UserID := scPB.userInfoPB.scUserID;

LoginTime := scPB.userInfoPB.scLoginTime;

LastUseTime := scPB.userInfoPB.scLastUseTime;

SocketNum := scPB.userInfoPB.scSocketNum;

END;

The following procedure creates a list of the users logged on to a file
server.

PROCEDURE GetAllUserNameRecs;

VAR

err: OSErr;

UserName: Str31;

Position: LongInt;

UNRecID: LongInt;

UserID: LongInt;

LoginTime: LongInt;

LastUseTime: LongInt;

SocketNum: AddrBlock;

BEGIN

Position := 0;

REPEAT

err := MySCGetUserNameRec(@UserName, Position, UNRecID,

UserID, LoginTime, LastUseTime, SocketNum);

IF err = noErr THEN

BEGIN

{ do something with the user information returned }

END

ELSE IF err <> fnfErr THEN

{ fnfErr only means there are no more users }

BEGIN

{ handle any unexpected errors }

END;

UNTIL err <> noErr;

END;

SCGetUserMountInfo

The following function calls SCGetUserMountInfo to get information about the
status of a particular volume or shared folder, such as the number of open
files on the volume, the number of files that are open with write access,
whether the volume is mounted, and whether the volume is mounted with owner
privileges (that is, whether the user is a superuser).

Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCGetUserMountInfo (VRefNum: Integer;

VAR FilesOpen: Integer;

VAR WriteableFiles: Integer;

UNRecID: LongInt;

VAR Mounted: Boolean;

VAR MountedAsOwner: Boolean):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.volMountedPB.scCode := SCGetUserMountInfo;

scPB.volMountedPB.scVRefNum := VRefNum;

scPB.volMountedPB.scUNRecID := UNRecID;

MySCGetUserMountInfo := SyncServerDispatch(@scPB);

FilesOpen := scPB.volMountedPB.scFilesOpen;

WriteableFiles := scPB.volMountedPB.scWriteableFiles;

Mounted := scPB.volMountedPB.scMounted;

MountedAsOwner := scPB.volMountedPB.scMountedAsOwner;

END;

The following procedure gets the user-mount information for all of the
volumes and shared folders that a user has mounted. Before using this

procedure, you must

initialize gMaxVolumes and gMaxExpFolders with the values returned by

the SCGetGetupInfo control call.

PROCEDURE GetAllUserMountInfo (UNRecID: LongInt);

VAR

err: OSErr;

Index: Integer;

VRefNum: Integer;

FilesOpen: Integer;

WriteableFiles: Integer;

Mounted: Boolean;

MountedAsOwner: Boolean;

BEGIN

FOR Index := -gMaxVolumes TO gMaxExpFolders DO

IF Index <> 0 THEN { index 0 is undefined }

BEGIN

err := MySCGetUserMountInfo(VRefNum, FilesOpen,

WriteableFiles, UNRecID,

Mounted, MountedAsOwner);

IF (err = noErr) AND Mounted THEN

BEGIN

{ do something with the information returned }

END;

END;

END;

Disconnecting users

This section describes the server control calls that you use to disconnect
users from file servers and from file server volumes.

SCDisconnect

The following function calls SCDisconnect to disconnect specified users from

a file server.

Note Although Macintosh File Sharing implements SCDisconnect, there is no
way to use this call with Macintosh File Sharing because Macintosh File
Sharing does not implement the SCGetUserNameRec call. SCGetUserNameRec
retrieves information -- namely user name record IDs (UNRecID) -- that is
necessary for SCDisconnect to work.

FUNCTION MySCDisconnect (DiscArrayPtr: LongIntPtr;

ArrayCount: Integer;

NumMinutes: Integer;

Flags: Integer;

MessagePtr: StringPtr): OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.disconnectPB.scDiscArrayPtr := DiscArrayPtr;

scPB.disconnectPB.scArrayCount := ArrayCount;

scPB.disconnectPB.scCode := SCDisconnect;

scPB.disconnectPB.scNumMinutes := NumMinutes;

scPB.disconnectPB.scFlags := Flags;

scPB.disconnectPB.scMessagePtr := MessagePtr;

MySCDisconnect := SyncServerDispatch(@scPB);

END;

The following procedure delivers a disconnect message to and disconnects the
specified user after ten minutes.

PROCEDURE DisconnectUser (UNRecID: LongInt);

VAR

err: OSErr;

ArrayCount: Integer;

NumMinutes: Integer;

Flags: Integer;

Message: tLoginMsg;

BEGIN

ArrayCount := 1; { one user }

NumMinutes := 10;

Flags := UNRFSendMsgMask; { send a message }

Message := 'Goodbye.';

err := MySCDisconnect(@UNRecID, ArrayCount, NumMinutes,

Flags, @Message);

IF err = noErr THEN

{ the disconnect was started }

ELSE

BEGIN

{ handle any errors }

END;

END;

SCDisconnectVolUsers

The following function calls SCDisconnectVolUers to disconnect the users of
specified volumes.

Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCDisconnectVolUsers (DiscArrayPtr: LongIntPtr;

ArrayCount: Integer;

NumMinutes: Integer;

Flags: Integer;

MessagePtr: StringPtr):

OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.disconnectPB.scDiscArrayPtr := DiscArrayPtr;

scPB.disconnectPB.scArrayCount := ArrayCount;

scPB.disconnectPB.scCode := SCDisconnectVolUsers;

scPB.disconnectPB.scNumMinutes := NumMinutes;

scPB.disconnectPB.scFlags := Flags;

scPB.disconnectPB.scMessagePtr := MessagePtr;

MySCDisconnectVolUsers := SyncServerDispatch(@scPB);

END;

The following procedure delivers a message to and disconnects the users of
the specified volume after ten minutes.

PROCEDURE DisconnectVolUsers (VRefNum: Integer);

VAR

err: OSErr;

VolToDisconnect: LongInt;

ArrayCount: Integer;

NumMinutes: Integer;

Flags: Integer;

Message: tLoginMsg;

BEGIN

VolToDisconnect := VRefNum; { note: Integer -> LongInt }

ArrayCount := 1;

NumMinutes := 10;

Flags := UNRFSendMsgMask; { send a message }

Message := 'A volume is going away.';

err := MySCDisconnectVolUsers(@VolToDisconnect,

ArrayCount, NumMinutes, Flags, @Message);

IF err = noErr THEN

{ the disconnect was started }

ELSE

BEGIN

{ handle any errors }

END;

END;

Sending messages to users

This section describes the server control call that lets you send messages to
users.

SCSendMessage

The following function calls SCSendMessage to send a message to the users
specified in the array pointed to by DiscArrayPtr.

Note This call is not supported by Macintosh File Sharing.

FUNCTION MySCSendMessage (DiscArrayPtr: LongIntPtr;

ArrayCount: Integer;

Flags: Integer;

MessagePtr: StringPtr): OSErr;

VAR

scPB: SCParamBlockRec;

BEGIN

scPB.disconnectPB.scDiscArrayPtr := DiscArrayPtr;

scPB.disconnectPB.scArrayCount := ArrayCount;

scPB.disconnectPB.scCode := SCSendMessage;

scPB.disconnectPB.scFlags := Flags;

scPB.disconnectPB.scMessagePtr := MessagePtr;

MySCSendMessage := SyncServerDispatch(@scPB);

END;

The following procedure sends a message to all connected users. Before using
this routine, you must initialize gCurMaxSession by using the SCGetSetupInfo
call.

PROCEDURE SendMessageToAll;

{ This routine depends on gCurMaxSessions being }

{ initialized with SCGetSetupInfo. }

VAR

err: OSErr;

ArrayPosPtr: LongIntPtr;

Position: LongInt;

scPB: SCParamBlockRec;