AppleScript in a Nutshell-@Team LiB

Network Setup Scripting

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.

Dictionary commands

Example

Dictionary classes

Figure 16-2. The AppleTalk control panel window

Figure 16-3. The Modem control panel

Figure 16-4. The Remote Access control panel

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

Figure 16-6. TCP/IP control panel