Commands are the action verbs that you use to script Network Setup Scripting, such as open database, close database, and connect (which you use to automate a modem's connection to the Internet). The make command, for instance, allows a script to make a new network configuration, such as a TCP/IP configuration, "on the fly." See the example under the make command section.

Dictionary commands

abort transaction

This command terminates a transaction. None of the changes that the script initiated within a begin/end transaction block will be completed. See begin transaction later in this chapter.

add reference

You can use this command to add a configuration such as a TCP/IP setting to Open Transport's configuration sets. Configuration sets are, as they sound, a group of configurations.

to configuration set

This identifies the configuration set to add the configuration to, as in:

configuration set "My Network Settings" or current configuration set

Example

tell application "Network Setup Scripting"

   set tId to "" -- this var will hold the transaction ID

   try

      open database

      (*use this when the script is changing the open transport database; the 

var tId will hold the transaction id integer *)

      set tId to begin transaction

      add TCPIP v4 configuration "newMacIP" to¬

      configuration set "My Network Settings"

      end transaction

      close database

   on error (* make sure transaction is aborted and database gets closed if 

there is an error *)

      if tId is not equal to "" then

         abort transaction

      end if

      close database

   end try

end tell

authenticate reference

Use this command to determine if a user has permission to access an Open Transport configuration:

set bool to authenticate AppleTalk configuration "my_config" with¬ password "wIsT$"

The command returns a boolean value, true or false.

with password string

This required labeled parameter is the password string.

begin transaction

This command begins a transaction and returns a transaction ID as an integer. An example is:

set transID to begin transaction

begin transaction prevents the database from being changed by any other scripts or applications while the transaction is still active. The transaction is finished or rendered inactive with the command end transaction. See the example in the add reference section.

close database

This command closes the Open Transport configuration database to the reading or writing of data. It is used to close the database following the command open database. See Example 16-1 and the example in the add reference section.

connect Remote Access configuration object

connect makes a connection with a Remote Access configuration, such as one that will access the Web with a dial-up modem. The parameter for the connect command is a Remote Access configuration object, such as connect RAconfig (if Raconfig were a variable holding a Remote Access configuration). See the following example and the Remote Access configuration class description (this command is used with the disconnect command, which is described later in this section):

set err to "" (* this var will hold any error messages to be¬ displayed to 

the user *)

tell application "Network Setup Scripting"

   try

      open database

      set ra to Remote Access configuration "Default"

      (* connect to a remote network, in this case the Web over a dial-up 

connection *)

      connect ra

      delay 60 (* wait 60 seconds before disconnecting, for demo purposes *)

      disconnect ra

      close database

   on error errmesg

      set err to errmesg -- save any error messages

      close database

   end try

end tell

if length of err > 0 then display dialog err (* display any error messages *)

count reference

This command returns a count of objects, such as Open Transport configurations or configuration sets, as an integer. You can use the count configurations, count each configuration, or count every configuration syntax.

each class:

You can optionally use the each keyword, as in tell app "Network Setup Scripting" to count each configuration:

tell application "Network Setup Scripting"

   open database

   set configC to count configurations

   close database

   return configC

end tell

delete reference

You can delete an Open Transport object such as an Open Transport configuration with this command. An example is:

delete TCPIP v4 configuration "local_Lan"

This code would delete one of the configurations that is viewable from the TCP/IP control panel's File menu. You have to open the Open Transport configurations database, issue the delete command, and then close the database for the delete command to work properly. This is because AppleScript has to explicitly open this database before making any changes to it.

disconnect Remote Access configuration

This command disconnects a Remote Access connection such as a dial-up connection to a remote network (e.g., the Internet). It is usually used in scripts that open the connection with the connect command. You follow the disconnect command with the Remote Access configuration object that you are disconnecting, as in disconnect Raobject (if the variable Raobject held a reference to a Remote Access configuration object).

duplicate reference

You can duplicate a configuration with this command:

duplicate AppleTalk configuration "printer_config" with properties¬  

{name:"Test config"}

You have to open and close the Open Transport configurations database to make these changes. You also have to use the begin transaction and end transaction commands to make sure that the new configuration is added to the database.

with properties record

You provide the properties for the new configuration with this labeled parameter, as in with properties{name:"newTCPIP", connecting via:Ethernet}. With duplicate, the new configuration inherits the properties of the original configuration (the one that was duplicated), unless you change those properties with this parameter:

tell application "Network Setup Scripting"

   set tId to "" -- this var will hold the transaction ID

   try -- catch and deal with any errors

      open database

      set tId to begin transaction

      duplicate TCPIP v4 configuration¬

         "newMacIP" with properties {name:"newconfig2"}

      (* test a property to confirm that the config copy inherits the original 

configuration's properties *)

      configuration method of TCPIP v4 configuration¬

      "newconfig2"

      (*see if the new config was added to all of the database's configurations

*)

      set cs to configurations

      end transaction

      close database

   on error (* abort transaction and close database if there is an error *)

      if tId is not "" then

         abort transaction

         close database

      end if

   end try

   return cs -- view the list of configurations

end tell

end transaction

This command is used to complete a transaction that was initiated with the begin transaction command. A transaction constitutes one or more database actions that are executed as a group and rolled back if any of the changes causes an error. begin transaction prevents the database from being changed by any other scripts or applications while the transaction is still alive. The transaction is finished or rendered inactive with the command end transaction. See also the abort transaction command.

exists reference

exists tests whether a certain AppleScript object exists and returns a true/false (boolean) value. An example is:

set bool to ( exists TCPIP v4 configuration "newconfig2" )

This code statement returns true if the specified configuration exists. Then the AppleScript might do something based on the exists return value, such as delete the configuration (if it exists) or make a new one (if it does not exist).

Make sure to open the Open Transport configurations database first, check if the configuration exists or not, then close the database.

If you do not use the open database and close database commands, then the exists command will not raise an error but returns false, even if the configuration you are searching for actually does exist.

get protection property reference

You can find out whether a property of a configuration is locked or unlocked by using the get protection command. For example, the TCP/IP control panel allows you set the user mode (from its EditUser Mode...menu) to basic, advanced, or administration. In administration mode, the control panel user can enter a password then lock or prevent the TCP/IP properties in the TCP/IP control panel from being changed by users who do not know the password. get protection returns either of two constants: locked or unlocked. See the following example and the set protection command description later in this chapter:

tell application "Network Setup Scripting"

   open database

   (* return value is locked or unlocked *)

   get protection of¬

   (configuration method of TCPIP v4 configuration "sygate")

   close database

end tell

make

The make command is used to make a new object, such as a Remote Access or TCPIP v4 configuration. Use the labeled parameters that go with this command (e.g., with data, with properties) to specify the new configuration's elements and properties. with data is used to make new elements; you use with properties to specify the new object's property values.

new class

The script uses this labeled parameter to specify the kind of object that it will create, as in:

make new Remote Access configuration...

or:

make new TCPIP v4 configuration...

at location reference

This parameter is not necessary when making new Open Transport configurations with AppleScript and the make command.

with data anything

You can use the optional with data parameter to make a new element (as opposed to a property) for a configuration that the script has created. An anything object can hold a string, constant, or other class type. Chapter 3, describes the anything data type.

with properties record

Use this command to specify the properties of the new configuration object that the script is creating with the make command. with properties takes a record data type, which is one or more name/value pairs enclosed in curly brackets ({ }). See the following example for how to use with properties:

tell application "Network Setup Scripting"

   set tid to "" -- var tid will hold transaction id

   try

      open database

      set tid to begin transaction (* holds an integer like 25909 *)

      (* make the new TCP/IP config *)

      make new TCPIP v4 configuration¬

         "MYNewIP" with properties¬

         {connecting via:Ethernet, configuration method:DHCP,¬

         subnet mask:"255.255.255.0", uses IEEE8023:false,¬

         user mode:advanced}

      (* make new elements for the TCP/IP configuration *)

      tell TCPIP v4 configuration "MYNewIP"

         make new router address 1 with data "192.168.153.1"

         make new name server address 1 with data "192.168.¬

         153. 1"

      end tell

      end transaction

      close database

      on error (* make sure the transaction is aborted and database closed if 

there's an error *)

      if tid is not "" then

         abort transaction

         close database

      end if

   end try

end tell

open database

This command opens the Open Transport configuration database for reading and writing. Once the script does whatever it has to do with the database, the database is closed with the close database command. You cannot get any data from the Open Transport configuration database without using the open database command first. Most of this chapter's code examples demonstrate how to use open database.

quit

This command quits the Network Setup Scripting application. This application is a "faceless background application," meaning it has no standard user interface (menus and windows) and is controlled by Apple events and script code. It usually quits automatically after the AppleScript statements have finished executing, but you can explicitly quit Network Setup by using quit.

remove reference

This command removes an object such as a configuration from a configuration set, as in:

remove TCPIP v4 configuration "local_TCP" from configuration set "My Network 

Settings"

A configuration set is a group of network settings that usually includes TCP/IP, Remote Access, Modem, and AppleTalk configurations. Removing a configuration from a configuration set does not delete the configuration object from the Open Transport configurations database.

from configuration set

Use this labeled parameter to specify the configuration or transport options to remove from a configuration set. Removing a configuration or transport options from a configuration set does not delete the configuration object from the Open Transport configurations database. See the following example and the transport options class description later in this chapter:

tell application "Network Setup Scripting"

   try

      set tid to "" -- this will hold the transaction id

      open database

      set tid to begin transaction

      set cs to (current configuration set)

      remove Modem configuration "Default" from cs (* remove a Modem config *)

      from the current config set

      set lc to cs's configurations (* var lc will show that the config has 

been removed *)

      end transaction

      close database

      lc (* view the var's value in Script Editor to confirm that the Modem 

config is gone *)

      on error (* if there's an error make sure the transaction is aborted and 

Open Transport database is closed *)

      if tid is not "" then

         abort transaction

         close database

      end if

   end try

end tell

run

This command executes the Network Setup Scripting application. It is not necessary to use run because targeting Network Setup with a tell statement starts up the program:

tell app "Network Setup Scripting"...

set protection property reference

A script may lock or unlock a configuration's property with this command. When the property is locked in administration mode (with an administration password provided), the property cannot be changed by a script unless the script uses the authenticate command with the proper password. The example below shows how to use the set protection command. Also see the authenticate command description elsewhere in this chapter.

to locked/unlocked:

This required labeled parameter sets the property to either of two constants, locked or unlocked. Locking the property requires password authentication to make any changes to it. See the following example:

tell application "Network Setup Scripting"

   set tid to "" -- this will hold the transaction id

   try -- catch any errors

      open database

      set tid to begin transaction

      set ipConfig to TCPIP v4 configuration "sygate"

      (* create administration password *)

      set user mode of ipConfig to administration

      set administration password of ipConfig to "x$1957"

      (* lock the TCP/IP configuration method *)

      set cleared to (authenticate ipConfig with password¬

      "x$1957")

      if cleared then

         set protection (configuration method of ipConfig) to¬ 

      locked

      end if

      end transaction

      close database

      on error (* make sure that transaction is aborted and the database is 

closed if an error occurs *)

      if tid is not "" then

         abort transaction

         close database

      end if

   end try

end tell

Dictionary classes

The Network Setup Scripting classes represent the network-related items that a script targets, mainly network configurations such as a Macintosh's AppleTalk or TCP/IP setup. You can find out a lot of information about a machine's networking configurations by querying the properties of the Network Setup Scripting application class, for instance (not to mention looking at the return values for other Network Setup Scripting objects such as the Remote Access configuration, which is used in part to control dial-up access to the Internet). Here is a list of the classes:

AppleTalk configuration

This class represents an AppleTalk network configuration (group of settings) that can be created or altered with an AppleScript. As a type or subclass of configuration, AppleTalk configuration also has the properties of the parent class (name, active, valid). The following example gets the properties of an AppleTalk configuration for viewing in Script Editor's Event Log (Chapter 2 describes the Script Editor's Event Log window):

tell application "Network Setup Scripting"

   set tId to ""

   try

      open database

      set tId to begin transaction

      set cc to current configuration set

      (* set the conAt var to the AppleTalk configuration that is part of 

       the current configuration set *)

      set conAt to item 1 of AppleTalk configurations of cc

      (* get properties of this config; example return values follow each 

property *)

      conAt's addressing -- dynamic

      conAt's AppleTalk zone -- ""

      conAt's connecting via -- "Printer Port"

      conAt's network ID -- 0

      conAt's node ID -- 123

      conAt's protocol -- AppleTalk

      conAt's user mode -- basic

      conAt's name -- "printer_config"

      conAt's valid -- true

      conAt's active -- true

      end transaction

      close database

   on error

      if tId is not "" then

         abort transaction

         close database

      end if

   end try

end tell

The following are AppleTalk configuration properties:

addressing dynamic/static

This property returns either one of the two constants.

AppleTalk zone string

This property returns the AppleTalk zone as a string (e.g., "Graphics_dep") or an empty string ("") if the configuration is not associated with a zone.

connecting via modem port/printer port/modem printer port/Ethernet or string

connecting via returns one of the port-related constants (e.g., Ethernet) or a string data type. The return value for the AppleTalk configuration that is part of the current configuration set will be the same value as the "Connecting via" pop-up menu in the AppleTalk control panel window. See Figure 16-2.

network ID integer

This property returns a unique ID number such as 0.

node ID linteger

node ID returns an integer such as 123. A node is an outward branch of a network system, if the system is viewed conceptually as a tree-like structure.

protocol AppleTalk (read-only)

This property returns just the constant AppleTalk.

administration password string (write-only)

You can only set, not get the value of, an administration password. Once a password is established, a script has to use the authenticate command to obtain administration permission to change a configuration property. See the authenticate command.

user mode basic/advanced/administration

This property returns one of the three Open Transport configuration user modes (e.g., advanced).

Figure 16-2. The AppleTalk control panel window

AppleTalk options

This is a subclass of the transport options class, so it also has the properties of its parent class (i.e., name, active, consequence, valid). The following example shows all of the available transport options, which provide global values for the various network protocols:

tell application "Network Setup Scripting"

   try

      open database

      repeat with c from 1 to (count of transport options)

         transport options c (* view each transport option in Event Log *)

      end repeat

      close database

      on error

      close database

   end try

end tell

(* example Event Log output *)

open database

count every transport options of current application

--> 4

get transport options 1

--> AppleTalk options "AppleTalk Globals"

get transport options 2

--> transport options "Remote Access Globals"

get transport options 3

--> TCPIP v4 options "TCP/IP Globals"

get transport options 4

--> transport options "Modem Globals"

close database

AppleTalk active boolean

The code phrase AppleTalk active of AppleTalk options returns true or false, depending on whether AppleTalk is active or being used on the machine.

application

This class represents the Network Setup Scripting application itself. The application has three elements: configurations, configuration sets, and transport options objects. The upcoming code example views the return values of these elements in Script Editor's Event Log. See the class descriptions of these elements elsewhere in this chapter.

The following are application elements:

configuration

This is an Open Transport configuration that you would use to connect to a network, as in a Remote Access configuration. See the configuration class description.

configuration set

This object represents a named group of configurations, such as:

configuration set "My Network Settings"

See the configuration set class.

transport options

Each one of the configuration types—AppleTalk, Modem, Remote Access, TCPIP v4—has some global properties that are stored in a transport options object. See the TCPIP v4 options, for instance. You can access one of a configuration set's transport options by its index, as in:

tell app "Network Setup Scripting" to get transport options 2¬

of current configuration set

tell application "Network Setup Scripting"

   try

      open database

      configuration sets -- get list of configuration sets

      transport options 1 (* view return value for first transport options 

object *)

      configurations -- get list of configurations

      close database

      on error

      close database

   end try

end tell

(* Example return values in Event Log *)

get every configuration set

--> {configuration set "My Network Settings"}

get transport options 1

--> AppleTalk options "AppleTalk Globals"

get every configuration

--> {TCPIP v4 configuration "localt", TCPIP v4 configuration 

"mediaone", Remote Access configuration "Default", TCPIP v4 

configuration "NTNET", AppleTalk configuration "Default", 

AppleTalk configuration "printer_config", TCPIP v4 configuration 

"sygate, Modem configuration "Default"}

The following are application properties:

current configuration set (read-only)

This property returns as a configuration set object the group of Open Transport configurations that the computer is using at the moment. For instance, to get a reference to the TCP/IP configuration, you could use the code in the next example. To get any elements or property values of the current configuration set, you have to set it to a variable first:

set cs to (current configuration set)

See the configuration set class description.

tell application "Network Setup Scripting"

   try

      open database

      set cs to (current configuration set)

      set tcp to (every TCPIP v4 configuration of cs)

      close database

     on error

      close database

   end try

end tell

name string (read-only)

The name property returns "Network Setup Scripting." It is primarily used to target the app in a tell statement, as in:

application "Network Setup Scripting"

version version (read-only)

This property returns a string (the version object is implemented as a string) representing the version of the software program, as in "1.1.1."

configuration

This class is the parent class for all the other configuration types, such as Remote Access and TCPIP v4 configurations. You cannot make a new configuration (as in make new configuration), but you can make the subclass types. An example is:

make new Remote Access configuration with properties{...}

See the make command. The configuration child classes inherit these three properties. In other words, a TCPIP v4 configuration has active, name, and valid properties.

name string

This property returns the name of the configuration, such as the "newIP" part of TCPIP v4 configuration "newIP."

active boolean

If the configuration is part of the computer's current Open Transport settings, then its active property is true.

valid boolean (read-only)

If the configuration is a usable, valid Open Transport configuration that the machine can probably make a connection with then this property returns true. You can get the property with code such as:

get valid of TCPIP v4 configuration "newMacIP"

configuration set

This class represents a group of configurations and is implemented as a list type, as in the following return value:

{TCPIP v4 configuration "localt", TCPIP v4 configuration "mediaone", 

Remote Access configuration "Default", AppleTalk configuration "Default", 

Modem configuration "Default"}

In other words, configuration set is a list of configuration objects. This is the object that is returned by the application's current configuration set property. The following are configuration set elements:

configuration

Each configuration set contains one or more configurations. See the example return value in the configuration set description.

transport options

A configuration set may contain one or more transport options. See the transport options class description elsewhere in this chapter.

The following are configuration set properties:

name string

Every configuration set has a name, as in

configuration set "My Network Settings"

active boolean

This property returns true if the configuration set is currently being used for Open Transport network services on the machine. A configuration set can exist but not be active (its active is false).

modem configuration

A modem configuration can be created either with AppleScript or with the Modem control panel. The Open Transport configurations database usually stores at least one modem configuration (called modem configuration "Default"). Most of the modem configuration properties can also be set in the control panel.

These are modem configuration properties:

connecting via modem port/printer port/modem printer port or string

This property returns either one of these constants (e.g., modem port) or a string like "Internal Modem."

dialing method tone/pulse

This property is the script version of the Tone or Pulse radio buttons on the Modem control panel. You set this property to either of the two constants.

ignores dial tone boolean

This true/false value is the script equivalent of the "Ignore dial tone" checkbox on the Modem control panel. You can set this property using code such as the following:

set ignores dial tone to true

modem script name string

If the modem configuration is associated with a Modem script in the startup disk:System Folder:Extensions:Modem Scripts folder, then this property returns the filename as a string. An example return value is "Global Village 28.8-K56."

modem speaker enabled boolean

If you want to enable the modem's speaker during a connect or disconnect, then set the modem speaker enabled property of the configuration, which controls that modem to true.

administration password string (write-only)

You can protect a modem configuration by creating an administration password and locking the various properties, just as you can with other Open Transport configurations. You can only set this property, not get its value with a script (it is write-only). See the authenticate command description in this chapter for how to lock or unlock a property with password protection.

user mode basic/advanced/administration

User mode returns one of the three Open Transport configuration user modes (e.g., advanced) as constants. This property is the script equivalent to setting the User Mode with the Modem control panel (shown in Figure 16-3). For example, you can password-protect a modem configuration's properties by using administration mode as shown.

Figure 16-3. The Modem control panel

Remote Access configuration

This class represents a configuration that you can create with the Remote Access control panel. This Open Transport technology lets you to make a dial-up connection with the Web via an ISP, as well as allow other computers to dial in to your machine and use it as a file server. A Remote Access configuration is identified with its string name:

Remote Access configuration "Default"

Most of its properties are the script equivalents of creating and maintaining Remote Access settings with the Remote Access control panel. See Figure 16-4.

The following are Remote Access configuration properties:

user name string

This property is the username that the configuration must provide to connect to a remote network. It is the script equivalent of the "Name" field in the Remote Access control panel. An example is:

set user name of Remote Access configuration "Default" to¬ "bruce19"

password string

This property is the script equivalent of the "Password" field in the Remote Access control panel (see Figure 16-4). It is the password that would be required to connect with a remote network.

Figure 16-4. The Remote Access control panel

saves password boolean

saves password is the script equivalent of the "Saves password" checkbox in the Remote Access control panel. It is a boolean value, as in:

set saves password of Remote Access configuration "Default" to

¬ true

If false, the connection will request a password every time the script attempts to log in. This value is ignored if the guest access property is true.

guest access boolean

If this property is true, then the script will try to log in to the remote network as a guest rather than as a specific authenticated user. If guest access is true then the user name, password, and saves password properties of this configuration are ignored. This property is the script equivalent to the Guest radio button on the Remote Access control panel.

status Remote access status (read-only)

status returns as a Remote Access status object the status information for a connection (Is it idle? Connecting? Disconnecting?). See the Remote Access status class description elsewhere in this chapter.

phone number string

This string is the phone number that the modem configuration uses to dial in to a remote connection, as in "978 352-3522". It is the property-equivalent to the "Number" field in the Remote Access control panel.

alternate number string

The alternate number property represents the alternate phone number to use when redialing in to a remote connection. This number is used if the redialing property is set to main and alternate.

uses DialAssist boolean

This true/false value is the equivalent of the RemoteAccess DialAssist... menu command in the Remote Access control panel. DialAssist is a control panel that provides detailed settings for dialing outside of local regions.

area code string

You can provide an area code for the modem configuration, as in:

set area code of Modem configuration "Default" to "978"

This property applies only if uses DialAssist is true.

country string

The country property for the configuration can be set to a string, as in "Switzerland." This property corresponds to a pop-up menu choice in the DialAssist control panel. The country property applies only if uses DialAssist is true.

redialing off/main only/main and alternate

You can set redialing for the configuration to any of the three constants. This property corresponds to the Redial pop-up menu in the Remote Access control panel. See Figure 16-5.

times to redial integer

This property specifies how many times to redial while making a remote connection with this modem configuration before the connect attempt quits. An example is:

set times to redial of Remote Access configuration "Default"¬

to 3

The property corresponds to the "Redial" edit field in the Remote Access control panel. See Figure 16-5.

time between redials integer

This property corresponds to the "Time between retries" edit field in the Remote Access control panel. Use it to specify the time in seconds that the configuration should wait before redialing in to the remote network, as in:

set time between redials of Remote Access configuration¬

"Default" to 5

verbose logging boolean

This true/false value is equivalent to checking the "use verbose logging" checkbox in the Remote Access control panel (i.e., the "Connection" tab in the "Options..." window). An example is:

Figure 16-5. Tabbed panels in the Remote Access control panel's Options section

tell Remote Access configuration "Default" to¬

   set verbose logging to true

flashes icon boolean

If this property is true and you make a connection using this configuration, then an icon flashes in the computer's menu bar. The property is the script equivalent to the "Flash icon..." checkbox in the Remote Access control panel.

prompts to stay connected boolean

A script can set this property in the following manner:

tell Remote Access configuration "Default" to ¬

   set prompts to stay connected to false

The latter code fragment unchecks the "Prompt every 5 minutes checkbox..." in the Remote Access control panel.

time between prompts integer

If prompts to stay connected is true, then you can specify the number of minutes between prompts with this property.

disconnects if idle boolean

A script can disconnect a connection after a specified number of minutes, if there is no activity (such as no bytes transferred across the network connection). To disconnect an idle connection automatically, set this property to true then specify the number of minutes with the idle time allowed property.

idle time allowed integer

This property specifies the number of minutes that the connection can remain idle before it is automatically disconnected, if disconnects if idle is true.

protocol PPP/ARAP

This property is the script equivalent of the Use protocol pop-up menu in the Remote Access control panel. The property can be set to one of the two constants, PPP or ARAP.

connects automatically boolean

If you want to specify that the Remote Access configuration will make its connection automatically whenever you make an HTTP request with a browser, then set this property to true. This is the script equivalent to checking the "Connect automatically..." checkbox in the Remote Access control panel.

allows compression boolean

This true/false property allows the Modem to perform error correction and compression. It is the script equivalent to the "Allow error correction..." checkbox on the Remote Access control panel.

uses header compression boolean

This true/false property allows the compression of packet headers during network communications. It is the script equivalent to the "Use TCP header compression" checkbox on the Remote Access control panel.

connects using command line boolean

If this property is set to true, then the configuration specifies the display of a command-line shell when a connection is initiated. It is the script equivalent to the "Connect to a command-line host" checkbox on the Remote Access control panel.

command line type terminal window/connection script

This property specifies the command-line type as either of the two constants. It is the equivalent of the "Use terminal window" and "Use connect script" radio buttons on the Remote Access control panel.

connection script file alias

With some Remote Access connections, it is convenient to specify a script that automatically provides text entries to a command-line window. You can specify this script as a configuration property. An example is:

set connection script file of Remote Access configuration¬ "Default" 

to alias "macintosh hd:con scripts:connector"

administration password string (write-only)

If you want to lock some of these Remote Access properties and thus prevent them from being changed by other users, then set a password with this property (it cannot be read by a script, only set). This is the equivalent of using the administration user mode under the Remote Access control panel's Edit menu.

user mode basic/advanced/administration

This property returns or sets one of the three constants that represent the Open Transport configuration user modes.

Remote Access status

This class represents the object that is returned by the Remote Access configuration's status property. This object's properties give scripts a certain amount of information about the status of a remote connection, such as how long the machine has been connected (time connected) to the remote network. For example, you would use the following code to find out the name (i.e., IP address) of the remote server the machine is connected to:

get server name of (status of Remote Access configuration "Default")

The following are Remote Access status properties:

activity idle/connecting/connected/disconnecting/unknown (read-only)

Get the activity property to find out what the connection is doing at the moment, as in:

get activity of (status of Remote Access configuration

¬ "Default")

This returns one of the constants, such as connected or disconnecting.

time connected integer (read-only)

The time connected property returns a number of seconds:

time connected of (status of Remote Access configuration¬ "Default")

An example return value is 486 (if the connection had been established for eight minutes and six seconds).

time remaining integer (read-only)

This property returns a number of seconds or -1 if the connection has an unlimited amount of time left (i.e., the value for "Time remaining:" in the control panel's Status area is "Unlimited").

user name string (read-only)

This string property is the user name associated with the connection. This is the name that the user or script logged on to the remote network with.

server name string (read-only)

You can get the server name of the remote network by reading the server name property. The return value for this property can be "<Unknown>". The return value can also be the server's IP address, as in "204.167.109.3." An example is:

get server name of (status of Remote Access configuration¬ "Default")

message string (read-only)

This property contains the most recent message received for this connection. These are the messages that appear in the Remote Access control panel's Status area (see Figure 16-4). An example return value for this property is "Connection: 27400 bps."

speed string (read-only)

This property returns the baud rate for the connection as a string. An example return value is "26400."

bytes received integer (read-only)

This property returns the number of bytes received by the computer or client, such as if it received a web page from the remote network over the connection. An example return value is 197374.

bytes sent integer (read-only)

The bytes sent is an integer like 200374. It represents bytes sent from the client machine to the remote network, such as if the connection was established and you opened a browser and made an HTTP request over the connection.

router address

This class represents a router address as a string, such as "192.168.0.1." You can make new router addresses and associate them with a new TCP/IP configuration.

search domain

This class represents a search domain as a string. This is the information that can be entered into the domain name and "Additional Search domains" fields in the TCP/IP control panel. See Figure 16-6. The following Apple Computer tech info library (TIL) article has more information on configuring TCP/IP and search domains: http://til.info.apple.com/techinfo.nsf/artnum/n75085.

TCPIP v4 configuration

This class represents a network configuration that is used to connect to a TCP/IP network, such as the Internet or an Ethernet. A TCPIP v4 configuration object can have zero or more of its elements (e.g., router address). Its properties, such as IP address and configuration method, can also be set manually in the TCP/IP control panel (see Figure 16-6). You can access this object by its name:

set tcp to TCPIP v4 configuration "Default"

This type of configuration also has the three properties of its parent class configuration (i.e., name, active, and valid).

Figure 16-6. TCP/IP control panel

The following are TCPIP v4 configuration elements:

router address

This is the IP address of the router in string form. One way to access the router address is by its index:

get router address 1 of TCPIP v4 configuration "Default"

See the router address class description.

name server address

This is the IP address of the name server in string form. One way to try to access the name server address is by its index:

get name server address 1 of TCPIP v4 configuration "Default"

See the name server class description.

search domain

This is the string value returned for the search domain field, which involves advanced TCP/IP configuration.

The following are TCPIP v4 configuration properties:

connecting via Ethernet/MacIP/PPP or string

The return value of this property is either a string or one of the three constants (e.g., Ethernet):

get connecting via of TCPIP v4 configuration "sygate"

configuration method BootP/DHCP/MacIP manual/MacIP server/manual/RARP/PPP server

The configuration method is one of the seven constants, as in:

set configuration method of TCPIP v4 configuration "sygate" to¬ DHCP

IP address string

This property returns the machine's active IP address as a string, such as "192.168.0.5." This value will be "0.0.0.0" if the configuration method is DHCP, for instance. This is because the client machine (the one running the script) gets its IP address from the server software.

subnet mask string

This property returns the machine's subnet mask as a string, such as "255.255.255.0." This value will be "0.0.0.0" if the configuration method is DHCP. This is because the client machine's IP address is allocated by the server software.

implicit search start string

This property involves the mapping of domain names (e.g., "apple.com") to IP addresses and may return an empty string ("") if the configuration does not have any specified implicit search paths.

implicit search end string

This property involves domain name searches and the mapping of domain names (e.g., "apple.com") to IP addresses. The property may return an empty string ("") if the configuration does not have any implicit search paths.

DHCP client ID string

This property applies only if the configuration's configuration method is DHCP.

MacIP server zone string

An example return value for the MacIP server zone (from my active TCPIP v4 configuration) is "*".

uses IEEE8023 boolean

This true/false value is the script equivalent to the "Use 802.3" checkbox on the TCP/IP control panel. If the checkbox control is checked, then this property is true. This checkbox only appears if the configuration connects via Ethernet.

protocol TCPIP v4 (read-only)

This property returns the constant TCPIP v4.

administration password string (write-only)

This is a settable-only property (you cannot read it with script) for the configurations with which you want to lock or prevent any unauthorized changes to properties. When a TCPIP v4 configuration has locked properties, little padlock icons appear next to the properties (e.g., "Connect via") on the TCP/IP control panel. See the authenticate command description elsewhere in this chapter for working with passwords and locked/unlocked properties.

user mode basic/advanced/administration

This property returns one of the three Open Transport configuration user modes for TCP/IP (e.g., advanced). You can also change the user mode from the TCP/IP control panel's Edit:User Mode... menu.

TCPIP v4 options

This class represents the options that apply to all TCPIP v4 configurations that are part of an Open Transport configurations database. TCPIP v4 options also has the properties of its transport options parent class: name, active, consequence, and valid. See the upcoming example.

TCPIP active boolean

Test this true/false property to find out if TCP/IP is an active networking protocol on the computer. The next example finds out whether TCP/IP is active and, if so, gets the value of all of its options (e.g., consequence). consequence means, what happens if you change these option's settings (i.e., do you have to restart the computer for the network protocol to work properly?).

tell application "Network Setup Scripting"

   open database

   set tpt to TCPIP v4 options 1 (* get TCPIP v4 options object by its index *)

   if (active of tpt) then (* if its active property is true then get vals for 

other properties *)

      tpt's name

      tpt's TCPIP active

      tpt's valid

      tpt's consequence

   end if

   close database

end tell

(* Sample return values viewed in Script Editor's Event Log *)

open database

get TCPIP v4 options 1

--> TCPIP v4 options "TCP/IP Globals"

get active of TCPIP v4 options "TCP/IP Globals"

--> true

get name of TCPIP v4 options "TCP/IP Globals"

--> "TCP/IP Globals"

get TCPIP active of TCPIP v4 options "TCP/IP Globals"

--> true

get valid of TCPIP v4 options "TCP/IP Globals"

--> true

get consequence of TCPIP v4 options "TCP/IP Globals"

--> benign

transport options

This is the parent class for the AppleTalk and TCPIP v4 options. Thus, those two classes inherit the four transport options' properties. The transport options apply to all of the configurations of the same class. So if you set the TCPIP v4 options, they apply to each instance or copy of a TCPIP v4 configuration (see the TCPIP v4 options class description elsewhere in this chapter). You can gain access to the various transport options by name or by index:

tell app "Network Setup Scripting" to get transport options 3

The following are transport options properties:

name string

Each transport option object has a name, as in:

TCPIP v4 options "TCP/IP Globals"

The name is "TCP/IP Globals."

active boolean

If the transport options object is active or associated with a network protocol (like TCP/IP) that is used on the computer, then this value is true.

consequence benign/may affect services/must restart configuration/must restart protocol/must restart computer (read-only)

This property returns one of the five constants (e.g., benign). The constant return value reflects the consequences of any changes to the option's settings. You get the return value with code such as the following:

consequence of (TCPIP v4 options "TCP/IP Globals")

valid boolean (read-only)

If the options are usable and valid on the computer then this boolean value returns true.