Network Setup Scripting Application
Network Setup Scripting is a faceless background application (FBA) in the Scripting Additions folder. It provides a scripting interface for creating and manipulating Open Transport (OT) configurations for the five OT control panels: AppleTalk, TCP/IP, Modem, Remote Access and InfraRed (the latter is only for machines supporting infrared communication). It even provides commands to make and break Remote Access connections, although this power is also provided by the Remote Access Commands scripting addition. (Note that the old OT/PPP control panel is replaced by the Remote Access control panel in Mac OS 8.5.)
None of the readme files released with Mac OS 8.5 explains how to use Network Setup Scripting, nor does Apple Help help. However, Apple has provided a basic explanation and a few sample scripts in AppleScript: Using Network Setup Scripting in Mac OS 8.5, Tech Info Library article #30829 (10/10/98). This article explains the general strategy for scripting the OT control panels, and the sample scripts show how to switch configurations in these control panels. A far more detailed explanation appears in the Network Setup Scripting article in the AppleScript 1.3.4 SDK. Additional sample scripts appear in the Sample Scripts folder in the SDK; some of them explain a few quirks which are far from obvious. Chapter 5 of Ethan Wilde’s book, AppleScript for the Internet: Visual QuickStart Guide, also includes several sample scripts, including a script to create a new TCP/IP configuration and a script to enable TCP/IP multi-homing. In general, some things in Network Setup Scripting don’t work as expected, but with a little trial and error you can make it work.
To understand Network Setup Scripting, you must understand the conceptual model of the OT control panels. All of the OT control panels except InfraRed contain a Configurations… item under the File menu, which opens a dialog in which you set applicable features, such as the port to which the modem is connected (in the Modem control panel) or whether AppleTalk is connected via Ethernet or through a particular port (in the AppleTalk control panel). More features become available in the dialog if you select a more advanced mode, using the User Mode… command under the Edit menu. You can create multiple configurations for each control panel, saving each configuration under a user-defined name. You make any one configuration in each control panel the active configuration by selecting a named configuration and clicking the Make Active button in the dialog. Behind the scenes, all of this configuration information is saved in a database. Note that the Location Manager can be used to switch OT configurations for all of the OT control panels, without using AppleScript.
What Network Setup Scripting does, in essence, is to let you use AppleScript to read configuration information from the database, and to change existing configurations or create new configurations and save them to the database. You can also use Network Setup Scripting to make particular configurations active, in effect switching between configurations under script control. You would do this if, for example, you wanted to use an external modem instead of an internal modem, to connect to a different Internet Service Provider, or to use a different configuration for any OT service. You can even create configuration sets, which lump together in one object related configurations and transport options from the OT control panels, to make it easy to switch all of the configuration information for a particular purpose at once as if there were a sort of super-OT control panel combining all of the existing control panels.
Network Setup Scripting implements these features using the object model. The Open Transport Suite defines an abstract ‘configuration’ class, from which each of the following real classes descends, corresponding to the OT control panels: ‘AppleTalk configuration’, ‘Infrared configuration’, ‘modem configuration’, ‘Remote Access configuration’ and ‘TCP/IP v4 configuration’. Each of these classes contains elements and properties corresponding to the features that can be set in the configuration dialog of the corresponding control panel, plus some that are not accessible in the control panels. Each class is described in a suite of the same name. One of the suites, the Remote Access Suite, also contains the ‘connect’ and ‘disconnect’ commands and a ‘Remote Access status’ class for monitoring an active connection. You can specify which Remote Access configuration to use when you connect. The Open Transport Suite also contains an abstract ‘transport options’ class defining properties common to all configurations within any one control panel class, and some of the control panel suites implement descendant classes with special-purpose properties. The ‘transport options’ class includes a property telling you whether a particular change requires reconnecting, restarting the machine or the like. Finally, the Open Transport Suite defines a ‘configuration set’ class and commands to ‘add’ or ‘delete’ configurations and transport options to any configuration set. You cannot define named configuration sets manually using the OT control panels, but only with AppleScript. If you ‘tell application Network Setup Scripting to get every configuration set’ before using AppleScript to create any, it will return ‘configuration set My Network Settings’.
The dictionary also provides a Configuration Database Suite containing commands to access the database, as well as a subset of the Standard Suite to determine whether an object exists, to count objects, to make new objects and other staples of the object model. Before reading from or writing to the database, you must open it, although you can make new objects and manipulate them on the fly without opening the database. You must always close the database when done with it. Opening and closing the database keeps it and the legacy preferences files for the control panels (included for backwards compatibility) sychrnonized; for this reason, you should open and close it quickly to preclude users from making changes in the control panels that would be overwritten when you close the database. Interestingly, Network Setup Scripting implements a little-used feature of AppleScript, the ‘begin transaction’ and ‘end transaction’ commands. Before writing to the database, you must begin a transaction; the changes will not be written to the database until you end the transaction, in order to assure its consistency. Other users cannot write to the database while your transaction is open, so close it quickly. Authentication password protection is also implemented.
Although the examples I have seen do not do so, I find it useful (at least during debugging) to open and close the database in ‘try’ blocks, in order to bypass error number -23 on opening it, if it is already open, and error number -24 on closing it, if it is already closed. If you try to access the database without opening it, or to write to it without starting a transaction, you will receive an error. Apple’s Tech Info Library article points out that it is prudent to enclose all actions taken while a write transaction is pending in a ‘try’ block, and in the ‘on error’ block you should abort the transaction and close the database in order to cancel all attempted changes and restore its status. Network Setup Scripting is a faceless background application, which means that you cannot use the ‘display dialog’ command within a ‘tell application Network Setup Scripting’ block; you must ‘tell application Finder to display dialog’ or redirect the command to some other context. The filter reference form ('whose clauses) is supported, but I have not been able to use it to select objects of a specific configuration class from a configuration set: ‘get configurations of current configuration set whose class is TCPIP v4 configuration’ compiles but does not run. The workaround is to use a repeat loop, as in the example below. Don’t forget to quit the Network Setup Scripting application when you are done with it, in order to reclaim the memory used by its process.
The following script gives an idea of how to obtain information about the current OT configuration set:
tell application "Network Setup Scripting"
try
open database
on error number -23 -- database already open
--continue
end try
try
set OTConfigSet to current configuration set
set OTConfigSetName to name of
OTConfigSet set TCPIPConfigName to --initialize
repeat with x from 1 to count
configurations of OTConfigSet
set thisConfig to configuration x of OTConfigSet
if class of thisConfig is TCPIP v4 configuration then
set TCPIPConfigName to name of thisConfig
set TCPIPConnectVia to connecting via of thisConfig
exit repeat
end if
end repeat
close database
quit
tell application "Finder"
activate
beep
display dialog ("The current Open Transport configuration set is "") & (OTConfigSetName & "." & return & return) &
("Its TCP/IP configuration is " & TCPIPConfigName & "" ") & ("connecting via " & TCPIPConnectVia & ".")
buttons {OK} default button OK with icon note
end tell
on error
errText number errNum
try
close database
on error number -24 --database already closed
--ignore
end try
quit
tell application "Finder"
activate
beep
display dialog (errText & return & return & errNum) buttons {OK} default button OK with icon caution
end tell
end try
end tell