Apple Network Card Network Setup User Manual

I N S I D E M A C I N T O S H  
Network Setup  
© Apple Computer, Inc. 2000  
 
Contents  
Preface  
About This Manual  
9
Conventions Used in This Manual  
9
Database Structure 16  
Database Structure Example  
Database Operations  
Preference Coherency  
19  
21  
Legacy Issues  
Legacy Synchronization Algorithm  
22  
Chapter 2 Using Network Setup  
Listing All Entities  
30  
Finding an Active Entity  
34  
Reading and Writing Preferences  
Reading Fixed-size Preferences  
Reading Variable-size Preferences  
34  
35  
37  
3
 
111  
Protocol Structures  
TCP/IP Structures  
Modem Structures  
Infrared Structures  
TCP/IP Constants and Other Data Types  
160  
Apple Remote Access Constants and Other Data Types  
163  
AppleTalk Constants and Other Data Types  
Infrared Constants and Other Data Types  
170  
172  
173  
Glossary  
Index  
175  
179  
5
 
6
 
Chapter 1  
About Network Setup  
11  
Figure 1-1  
Figure 1-2  
Figure 1-3  
Figure 1-4  
Figure 1-5  
Figure 1-6  
Network configuration prior to Network Setup  
Network Setup in Mac OS 8.5 through the present  
12  
13  
14  
Structure of the Network Setup Library  
Sample organization of the default area  
Reading and writing the default area  
15  
18  
20  
Table 1-1  
Network Setup versions  
23  
Chapter 2  
Using Network Setup  
25  
Figure 2-1  
42  
Listing 2-1  
Listing 2-2  
Listing 2-3  
Listing 2-4  
Listing 2-5  
Listing 2-6  
Listing 2-7  
Listing 2-8  
26  
27  
28  
29  
Finding all entities of a particular class and type  
Printing the user-visible name for an entity 33  
Reading a fixed-size preference 35  
Reading the DHCP lease info preference in a TCP/IP network  
Calling OTCfgGetPrefsSize to read a variable-size preference  
Writing a preference 39  
Finding the active set entity 44  
Finding the active entity of a given class and type  
Finding the active TCP/IP entity 47  
Packing and unpacking the kOTCfgTCPInterfacesPref  
preference 50  
Encrypting the user’s password  
31  
Listing 2-9  
Listing 2-10  
Listing 2-11  
Listing 2-12  
Listing 2-13  
Listing 2-14  
Listing 2-15  
Listing 2-16  
37  
38  
40  
46  
Listing 2-17  
54  
7
 
 
8
 
P
R
E
F A  
C
E
About This Manual  
This manual describes Network Setup, which is a programming interface that  
allows you to manipulate the contents of the Network Setup database. The  
Network Setup database contains settings for all of the network protocols  
installed on the system. Using Network Setup, you can programmatically  
modify any network setting that the user can see in the various networking  
control panels.  
Conventions Used in This Manual  
0
The Courier font is used to indicate text that you type or see displayed. This  
manual includes special text elements to highlight important or supplemental  
information:  
Note  
Text set off in this manner presents sidelights or interesting  
points of information.  
N
IMPORTANT  
Text set off in this manner—with the word Important—  
presents important information or instructions.  
L
L
W AR N I N G  
Text set off in this manner—with the word Warning—  
indicates potentially serious problems.  
L
9
 
   
P
R
E
F A  
C
E
For More Information  
0
The following sources provide additional information that may be of interest to  
developers who use the Network Setup programming interface:  
I Inside AppleTalk, Second Edition.  
I Inside Macintosh: Networking with Open Transport.  
I Open Transport Advanced Client Programming, available at  
http://developer.apple.com/macos/opentransport/OTAdvancedClientProg/  
OTAdvancedClientProg.html  
10  
 
 
C
H
A
P
T
E
R
1
Figure 1-0  
Listing 1-0  
Table 1-0  
About Network Setup  
1
Network Setup is a system service that allows you to manipulate network  
configurations. You can use Network Setup to read, create, modify, and delete  
network configurations. Any option that is accessible to the user through the  
network control panels provided by Apple is also available to you through the  
Network Setup programming interface.  
This chapter describes the overall Network Setup architecture and introduces  
the terminology needed to understand how to use Network Setup. It assumes  
that you are familiar with the existing network control panels provided by  
Apple (for example, the TCP/IP control panel) from a user's perspective,  
especially the configurations window used to select, duplicate, and rename  
network configurations.  
Network Setup Architecture  
1
Prior to the introduction of Network Setup, each network protocol stack used  
its own private mechanism to store preferences and make those preferences  
active. Network preferences were stored as resources in files in the Preferences  
folder. Figure 1-1 shows the overall network configuration architecture prior to  
the introduction of Network Setup.  
Network Setup Architecture  
11  
 
         
C H A P T E R  
1
About Network Setup  
Figure 1-1  
Network configuration prior to Network Setup  
Control panels  
TCP/IP  
AppleTalk  
Remote Access,  
Modem,  
Dial Assist,  
Infrared, ...  
TCP/IP  
protocol  
stack  
Private interface  
AppleTalk  
protocol  
stack  
Private  
preferences files  
TCP/IP preferences  
AppleTalk preferences  
The architecture shown in Figure 1-1 had a number of drawbacks:  
I There was a control panel for each protocol type, leading to an unnecessary  
proliferation of control panels.  
I There was no programming interface for changing network settings. With the  
explosion of interest in networking prompted by the rise of the Internet, this  
proved to be a problem. Internet setup programs, whether provided by  
Apple or by third parties, were required to reverse engineer the network  
preferences file format. After changing the files “underneath” the protocol  
stacks, these programs had to force the protocol stack to read the new  
preferences through a variety of unsupported means.  
I The dependence of third-party applications on the preferences file format  
and private interfaces to the protocol stack made it difficult for Apple to ship  
modern network features, such as TCP/IP multihoming, and to support the  
multiple users feature in Mac OS 9.  
I Resource files are susceptible to corruption when the system crashes.  
Network Setup was designed to eliminate these problems by giving developers,  
both inside and outside of Apple, a programming interface to modify network  
preferences without relying on internal implementation details of the individual  
protocol stacks.  
Network Setup is being introduced in two stages. The architecture of the first  
stage (Mac OS 8.5 to the present day) is shown in Figure 1-2.  
12  
Network Setup Architecture  
 
       
C H A P T E R  
1
About Network Setup  
Figure 1-2  
Network Setup in Mac OS 8.5 through the present  
Network  
Setup  
scripting  
Network Setup  
aware applications  
Third-party  
application  
Legacy  
control  
panels  
Public interface  
Legacy  
protocol  
stacks  
Network Setup library  
Legacy  
preferences  
files  
Network Setup database  
The following key points are to be taken from Figure 1-2:  
I The Network Setup library provides a standard programming interface for  
manipulating network configurations stored in the Network Setup database.  
The database is designed to store network preferences reliably even if the  
system crashes while preferences are being modified.  
I The Network Setup library provides automatic synchronization between the  
database and legacy preference files. Synchronization allows existing  
software with dependencies on the format of those files (such as third-party  
Internet setup software, Apple control panels, and protocol stacks) to  
continue working in the new environment.  
I Third-party developers are encouraged to migrate to the Network Setup  
programming interface, but in so doing, their existing applications in the  
field will not break.  
I Network Setup scripting is a bridge between the Network Setup  
programming interface and AppleScript. It allows script developers to  
manipulate network configurations through a standard AppleScript object  
model interface.  
The primary disadvantage of the current Network Setup architecture is that the  
synchronization between the legacy preferences files and the Network Setup  
database is a time consuming operation. Consequently, Apple intends to  
Network Setup Architecture  
13  
 
       
C H A P T E R  
1
About Network Setup  
remove support for legacy preferences files as soon as possible. Figure 1-3  
shows the future Network Setup architecture.  
Figure 1-3  
Future Network Setup architecture  
Network  
control  
panel  
Network  
Setup  
scripting  
Third-party Network Setup  
application aware applications  
Updated  
protocol  
stacks  
Public interface  
Network Setup library  
Network Setup database  
In the future Network Setup architecture, all developers, applications that  
manipulate network preferences will be required to use the Network Setup  
programming interface. If you have an application that manipulates legacy  
preferences files directly, to guarantee future compatibility you must update it  
to use the Network Setup programming interface.  
Inside the Network Setup Library  
1
Figure 1-4 shows the structure of the Network Setup library itself and its  
relationship to the applications that call it. This structure is mostly irrelevant to  
programmers who call the programming interface — Network Setup acts like a  
“black box”—- but it helps to explain how Network Setup works.  
14  
Inside the Network Setup Library  
 
       
C H A P T E R  
1
About Network Setup  
Figure 1-4  
Structure of the Network Setup Library  
Network Setup  
aware applications  
High-level framework  
Legacy  
Synchronization  
module  
Mid-level database (OTCfg)  
Low-level database (Cfg)  
Network Setup  
extension  
As shown in Figure 1-4, the Network Setup library is divided into four key  
components:  
I The low-level database, which is an internal component of the Network  
Setup Extension file. The low-level database contains the core database  
manipulation engine. It knows nothing about networking — it just moves  
bits around. The low-level database is not visible to developers except insofar  
as its prefix (“Cfg”) is used by some Network Setup identifiers.  
I The mid-level database, which is the actual programming interface exported  
to developers. Its routine names start with “OTCfg”. The mid-level database  
passes most requests directly to the low-level database, which actually  
also interfaces with the legacy synchronization module.  
I The legacy synchronization module, which in combination with the  
mid-level database, ensures that the database is synchronized with the legacy  
preferences files. This module will be removed in a future version of  
Network Setup. See “Legacy Synchronization Algorithm” (page 22) for more  
information about legacy file synchronization.  
I Most users of the Network Setup programming interface use a high-level  
framework to assist them in their task. Apple software uses an  
Apple-internal C++ framework for this. This framework is statically linked  
into software like the Network Setup Scripting application. Third-party  
developers commonly use the MoreNetworkSetup framework, available as  
sample code.  
Inside the Network Setup Library  
15  
 
         
C H A P T E R  
1
About Network Setup  
Network Setup Database Fundamentals  
1
This section describes the fundamental structure of and operations on the  
Network Setup database.  
Database Structure  
1
The Network Setup database consists of multiple areas. There are two types of  
areas: named areas store preferences, while temporary areas are used as part of  
the preference modification process. The system currently uses a single named  
area, known as the default area (sometimes referred to as the current area) to  
store all network preferences. While it is possible to create and manipulate other  
named areas within the database, doing so does not affect any network settings.  
Areas are identified by a unique area ID.  
Each area contains a number of entities having the following properties:  
I entity reference. An entity reference uniquely identifies an entity. The entity  
reference contains an area ID, which identifies the area in which the entity  
resides.  
I entity name. A user-visible name for the entity that need not be unique.  
I entity class and type. These values, both of type OSType, determine the type  
of data contained within an entity. There are three entity classes:  
I network connection entity. A network connection entity contains  
information about a single instance of a network protocol on a port.  
Typically there is one active network connection entity per protocol stack,  
but on a multihomed computer there can be more. The entity type for an  
network connection entity indicates the network protocol of the  
connection.  
I global protocol entity. A global protocol entity contains configuration for  
a protocol stack on a computer. There is only one active global protocol  
entity for each protocol stack. The entity type for a global protocol entity  
indicates the network protocol whose configuration it contains.  
I set entity. A set entity groups global protocol and network connection  
entities into a set. The set entity contains entity references to each entity in  
the set. An area can contain multiple set entities, but there is one and only  
16  
Network Setup Database Fundamentals  
 
                         
C H A P T E R  
1
About Network Setup  
one active set entity. The entities referenced by the active set entity  
comprise the active network preferences. All set entities have the same  
type.  
I icon. An entity can include a reference to a custom icon. The custom icon is  
not currently used, but may be used by future system software to display a  
visual representation of the entity.  
Within each entity there are zero or more preferences, distinguished by a  
preference type (an OSType). A preference is the atomic unit of data in the  
database. When you read or write data, you do so one preference at a time.  
Typically the data for a preference is protocol-dependent. Its format is  
determined by the entity class and type and by the preference type itself. To  
read or write a preference meaningfully, you must know the format of the  
preference data. The reference section of this document describes the format of  
every preference used by the Apple protocol stacks. In most cases, this  
description includes a C structure that mirrors the structure of the preference  
itself.  
Note  
For most preferences, the data format is the same as for the  
equivalent resource in the legacy preference files. If you are  
familiar with the legacy file format, you should be able to  
easily understand the preference data format. See “Legacy  
Issues” (page 21) for more information on how Network  
Setup synchronizes the database with the legacy  
preferences files.  
Database Structure Example  
1
Figure 1-5 shows an example of how the Network Setup database might be  
structured on a particular computer.  
Network Setup Database Fundamentals  
17  
 
         
C H A P T E R  
1
About Network Setup  
Figure 1-5  
Sample organization of the default area  
Default area  
AppleTalk global protocol entity  
'opts' preference  
...  
TCP/IP global protocol entity  
'opts' preference  
...  
"LocalTalk for Printer" AppleTalk network protocol entity  
'atfp' preference  
general AppleTalk preference  
user-visible name of this port  
'port' preference  
...  
"Company Ethernet" AppleTalk network protocol entity  
'aftp' preference  
general AppleTalk preference  
user-visible name of this port  
'port' preference  
...  
"AirPort" TCP/IP network protocol entity  
'idns' preference  
DNS configuration  
'port' preference  
user-visible name of this port  
...  
"Work/DHCP" TCP/IP network protocol entity  
'idns' preference  
DNS configuration  
'port' preference  
user-visible name of this port  
...  
Active  
Active  
"Home" set entity  
AppleTalk global protocol entity  
TCP/IP global protocol entity  
"LocalTalk for Printer" AppleTalk network protocol entity  
"AirPort" TCP/IP network protocol entity  
"Work" set entity  
AppleTalk global protocol entity  
TCP/IP global protocol entity  
"Company Ethernet" AppleTalk network protocol entity  
"Work/DHCP" TCP/IP network protocol entity  
18  
Network Setup Database Fundamentals  
 
 
C H A P T E R  
1
About Network Setup  
For simplicity, this example assumes a computer with two places of operation,  
home and work, and two protocol stacks, TCP/IP and AppleTalk. Thus, there  
are four network connection entities:  
I “AirPort,” a TCP/IP network connection entity that configures a TCP/IP  
interface to use an AirPort card to access an AirPort Base Station at home.  
I “LocalTalk for Printer,” an AppleTalk network connection entity that  
configures an AppleTalk interface to use LocalTalk over the Printer port, to  
talk to a LocalTalk printer at home.  
I Work/DHCP,” a TCP/IP network connection entity which configures a  
TCP/IP interface to use DHCP over the Ethernet port.  
I “Company Ethernet,” an AppleTalk network connection entity that  
configures an AppleTalk interface to use the Ethernet port in a zone that only  
exists on the “Work” network.  
The area also has two global protocol entities, one for TCP/IP and one for  
AppleTalk. These settings do not need to change between home and work, so  
there is only one of each.  
Finally, the area has two set entities:  
I “Home,” which references the two global protocol entities and the two home  
network connection entities: “AirPort” for TCP/IP and “LocalTalk for  
Printer” for AppleTalk.  
I Work,” which references the two global protocol entities but also references  
two network connection entities: “Work/DHCP” for TCP/IP and “Company  
Ethernet” for AppleTalk.  
The “Work” set entity is marked as active, so the network connection entities  
that it references are active. When the user moves from work to home, a  
program (such as the Location Manager) can simply mark the “Work” entity as  
inactive and the “Home” entity as active and the network configuration will  
switch accordingly.  
Database Operations  
1
Before reading or writing preferences, an application must open the database.  
The first step is to create a database reference. This reference identifies the  
calling application to the Network Setup library and is passed to subsequent  
calls that access the database. After creating the database reference, the process  
diverges for readers and writers. When an application opens the default area for  
Network Setup Database Fundamentals  
19  
 
     
C H A P T E R  
1
About Network Setup  
reading, it reads the area directly. Network Setup simply notes that the area is  
open for synchronization purposes (see the section “Preference Coherency”  
(page 21)). For writing, the process is somewhat different.  
When an application opens an area for writing, Network Setup creates a  
temporary area that is an exact duplicate of the default area. It then returns the  
temporary area ID to the application. The application can now change the  
temporary area without affecting running network services. When the  
application is done making changes, it commits the changes to the database.  
Committing changes is an atomic process that overwrites the default area with  
the contents of the temporary area and causes the protocol stacks to reconfigure  
Alternatively, the writing application can choose to abort the modifications, in  
response to which Network Setup discards the temporary area and the system  
continues to use the configuration in the default area.  
Figure 1-6 shows this process diagrammatically.  
Figure 1-6  
Reading and writing the default area  
Reading  
Writing  
Default area  
Default area  
Open for reading  
Open for write  
abort  
Default area  
being read  
Temporary area  
being written  
Close for reading  
Commit  
Default area  
Updated default area  
Multiple applications can open the Network Setup database for reading, but  
only one application at a time can open the database for writing.When an  
application commits changes to the default area, Network Setup notifies each  
application that has opened the database for reading that a change has  
occurred, as explained in the next section, “Preference Coherency.”  
20  
Network Setup Database Fundamentals  
 
         
C H A P T E R  
1
About Network Setup  
Preference Coherency  
1
When an application commits changes to the default area, it is important that  
applications that are reading the database be informed of those changes. For  
example, an application might be displaying the DHCP client ID preference. If  
another application changes this preference in the database, it is important that  
the original application update its display.  
Prior to Network Setup 1.0.2, the mechanism by which readers learned of  
changes was somewhat primitive. When a writing application committed its  
changes, Network Setup tagged each reading application’s database reference  
with an error. Any subsequent calls using that database connection failed with  
an error (kCfgErrDatabaseChanged). The reading application responded by  
closing its database reference and opening the database again. It then read the  
new preferences.  
Network Setup 1.0.2 introduces a new, notifier-based mechanism for learning  
about preference changes. The reading application attaches a notifier to the  
database reference. When changes are committed to the database, Network  
Setup calls each installed notifier to inform the reading application that a  
change has occurred. The reading application should respond by re-reading any  
preferences it has cached.  
Legacy Issues  
1
As described in the section “Network Setup Architecture” (page 11), current  
versions of Network Setup automatically synchronize the legacy preferences  
files with the database. This synchronization mechanism is transparent to  
applications calling Network Setup, but there are two issues that you should be  
aware of:  
I Legacy synchronization is slow. Depending on the speed of the computer  
and the number of entities, a full synchronization can take seconds. You  
should do all that you can to avoid synchronizations. The best way to avoid  
synchronizations is to adopt Network Setup and avoid modifying the legacy  
preferences files directly.  
I Legacy preferences files do not support multihoming.  
Legacy Issues  
21  
 
       
C H A P T E R  
1
About Network Setup  
Given that legacy synchronization is slow and that legacy preferences files do  
not support multihoming, future system software will not support legacy  
synchronization.  
Legacy Synchronization Algorithm  
1
Network Setup synchronizes the database and the legacy preferences files at the  
following times:  
I When the database is opened. Network Setup checks the modification dates  
of each legacy preferences file against modification dates stored in the  
database. If the dates are different, Network Setup assumes that some  
application has changed one or more legacy preferences files and imports  
preferences from the modified files.  
I When changes are committed to the database. Network Setup determines  
whether the committed changes affect a legacy preferences file. If they do,  
Network Setup exports the database to the legacy preferences file and  
records the modification date of the legacy preferences file in the database.  
The legacy import mechanism makes good use of the structure of the legacy  
preferences files. Most preferences files are resource files having the following  
attributes:  
I A resource having a well known resource type ('cnam').  
I All resources with a resource ID of a 'cnam'resource belong to that  
configuration. The contents of these resources are the preferences for that  
configuration.  
I There is one fixed resource whose type is 'ccfg'and whose ID is 1 that  
contains the resource ID of the active configuration.  
I Any resources with IDs other than those used for configurations are global  
preferences.  
When importing a legacy preferences file, Network Setup creates an entity for  
each 'cnam'resource and, for each resource with the same ID as the 'cnam'  
resource, creates a preference in the entity whose preference type is the resource  
ID and whose data is the resource data. If the 'ccfg'resource indicates that the  
configuration is active, Network Setup places the entity in the active set.  
The legacy export process is similar to the legacy import mechanism. For each  
network connection entity of a particular type, Network Setup creates a 'cnam'  
resource with a unique ID in the legacy file. Then, for each preference in the  
22  
Legacy Issues  
 
   
C H A P T E R  
1
About Network Setup  
entity, it creates a resource containing the preference data with the resource type  
matching the preference type and the resource ID the same as the 'cnam'  
resource.  
Network Setup uses a number of private preferences to ensure a reliable round  
trip conversion between legacy preferences files and the database. The  
preference types are described in “Common Preference Types” (page 106), but  
your application should not depend on their presence, their content, or their  
semantics.  
If you find undocumented preferences (such as a preference of type 'vers') in a  
global protocol entity, do not be concerned. Network Setup itself does not  
actually look at the data as it imports from and exports to legacy preferences  
files.  
Network Setup Version History  
1
Table 1-1 summarizes the different versions of Network Setup, their features,  
and their release vehicles.  
Table 1-1  
Network Setup versions  
Version  
Mac OS version  
Mac OS 8.5  
New features  
1.0  
OTCfgGetAreaName  
1.0.1  
1.0.2  
Not released  
Mac OS 8.6  
OTCfgInstallNotifier,  
OTCfgRemoveNotifier  
1.1  
Not released  
Mac OS 9.0  
OTCfgEncrypt,  
OTCfgDecrypt  
1.1.1  
There is no easy way to determine the version of Network Setup installed on a  
system. The best way to test for the presence of a specific Network Setup API  
enhancement is to weak link to its symbol, as described in TN 1083, “Weak  
Linking to a Code Fragment Manager-based Shared Library.”  
Network Setup Version History  
23  
 
       
C H A P T E R  
1
About Network Setup  
24  
Network Setup Version History  
 
C
H
A
P
T
E
R
2
Figure 2-0  
Listing 2-0  
Table 2-0  
Using Network Setup  
2
This chapter explains how to use the Network Setup programming interface to  
read and write network preferences. It assumes that you are familiar with basic  
Network Setup concepts. If not, you should read Chapter 1, “About Network  
Setup,”for important background material. This chapter concentrates on  
practical examples of coding with Network Setup.  
Opening and Closing the Network Setup Database  
2
This section explains how your application should open the Network Setup  
database for reading and writing and then discusses how to close the database  
and, in the case where the database has been opened for writing, either  
committing or discarding your modifications.  
Opening the Database for Reading  
2
The MyOpenDatabaseForReadingroutine shown in Listing 2-1 shows how to open  
the default (or current) area in the Network Setup database for reading. It starts  
by calling OTCfgOpenDatabase, which returns a database reference (of type  
CfgDatabaseRef) that identifies your application’s connection to the database. It  
then calls OTCfgGetCurrentArea, which returns an area identifier (of type  
CfgAreaID) that identifies the default area. Finally, it opens the default area for  
reading by calling OTCfgOpenArea.  
The MyOpenDatabaseForReadingroutine returns both the database reference  
(dbRef) and the default area identifier (readArea). You must know these values  
in order to read preferences and eventually close the database.  
Opening and Closing the Network Setup Database  
25  
 
         
C H A P T E R  
2
Using Network Setup  
Listing 2-1  
Opening the database for reading  
static OSStatus MyOpenDatabaseForReading(CfgDatabaseRef *dbRef,  
CfgAreaID *readArea)  
{
OSStatus err;  
assert(dbRef  
!= nil);  
assert(readArea != nil);  
err = OTCfgOpenDatabase(dbRef);  
if (err == noErr) {  
err = OTCfgGetCurrentArea(*dbRef, readArea);  
if (err == noErr) {  
err = OTCfgOpenArea(*dbRef, *readArea);  
}
if (err != noErr) {  
(void) OTCfgCloseDatabase(dbRef);  
}
}
if (err != noErr) {  
*dbRef  
= nil;  
*readArea = kInvalidCfgAreaID;  
}
return err;  
}
Opening the Database for Writing  
2
The MyOpenDatabaseForWritingroutine shown in Listing 2-2 shows how to open  
the default (or current) area in the Network Setup database for writing. The  
approach is similar to that used for opening the database for reading except that  
instead of calling OTCfgOpenAreato open the area for reading, the routine calls  
OTCfgBeginAreaModificationsto open the area for writing.  
The OTCfgBeginAreaModificationsfunction returns another area identifier that  
references a writable temporary area. The MyOpenDatabaseForWritingroutine  
returns both the original default area identifier and the writable temporary area  
identifier. You must keep both of these area identifiers because you need them  
both in order to close the database. You can only make changes to the writable  
26  
Opening and Closing the Network Setup Database  
 
       
C H A P T E R  
2
Using Network Setup  
area, but you can read from both the original area and the writable area to  
access, respectively, the currently active network settings and your proposed  
changes to the network settings.  
Listing 2-2  
Opening the database for writing  
static OSStatus MyOpenDatabaseForWriting(CfgDatabaseRef *dbRef,  
CfgAreaID *readArea,  
CfgAreaID *writeArea)  
{
OSStatus err;  
assert(dbRef  
!= nil);  
assert(writeArea != nil);  
err = OTCfgOpenDatabase(dbRef);  
if (err == noErr) {  
err = OTCfgGetCurrentArea(*dbRef, readArea);  
if (err == noErr) {  
err = OTCfgBeginAreaModifications(*dbRef, *readArea,  
writeArea);  
}
if (err != noErr) {  
(void) OTCfgCloseDatabase(dbRef);  
}
}
if (err != noErr) {  
*dbRef  
= nil;  
*readArea = kInvalidCfgAreaID;  
*writeArea = kInvalidCfgAreaID;  
}
return err;  
}
Opening and Closing the Network Setup Database  
27  
 
   
C H A P T E R  
2
Using Network Setup  
Closing the Database After Reading  
2
The MyCloseDatabaseAfterReadingroutine shown in Listing 2-3 shows how to  
close the database after you are done reading from it. The routine simply calls  
OTCfgCloseAreato close the read area and then calls OTCfgCloseDatabaseto close  
the database itself. This code discards error results from both of these routines  
because if the database fails to close there isn’t anything your application can do  
to force it to close, but it does log any errors with the standard C assertmacro  
so that you can detect this sort of error during testing.  
Listing 2-3  
Closing the database after reading  
static void MyCloseDatabaseAfterReading(CfgDatabaseRef dbRef,  
CfgAreaID readArea)  
{
OSStatus junk;  
assert(dbRef  
!= nil);  
assert(readArea != kInvalidCfgAreaID);  
junk = OTCfgCloseArea(dbRef, readArea);  
assert(junk == noErr);  
junk = OTCfgCloseDatabase(&dbRef);  
assert(junk == noErr);  
}
Closing the Database After Writing  
2
The MyCloseDatabaseAfterWritingroutine shown in Listing 2-4 shows how to  
close the database after you have finished making changes. The first three  
routine parameters (the database reference, the read area identifier, and the  
write area identifier) were obtained when the database was opened the  
database for writing. The fourth parameter, commit, indicates whether the  
changes are to be committed to the database or discarded.  
If commitis true, the routine calls OTCfgCommitAreaModifications, which  
overwrites the current settings in the read area with the new settings in the  
write area and notifies the network protocol stacks that their preferences have  
changed so that they can reconfigure themselves.  
28  
Opening and Closing the Network Setup Database  
 
         
C H A P T E R  
2
Using Network Setup  
If commitis false, the routine calls OTCfgAbortAreaModificationsto discard the  
changes made in the writable temporary area. The read area is not changed, and  
the network protocol stacks continue unaffected.  
In contrast to MyCloseDatabaseAfterReadingshown in Listing 2-3,  
MyCloseDatabaseAfterWritingdoes not always throw away error results. If  
OTCfgCommitAreaModificationsreturns an error, the  
MyCloseDatabaseAfterWritingroutine aborts. Your application may respond to  
this by calling the same routine again, this time with commitset to false.  
Listing 2-4  
Closing the database after writing  
static OSStatus MyCloseDatabaseAfterWriting(CfgDatabaseRef dbRef,  
CfgAreaID readArea,  
CfgAreaID writeArea,  
Boolean commit)  
{
OSStatus err;  
OSStatus junk;  
assert(dbRef  
!= nil);  
assert(readArea != kInvalidCfgAreaID);  
assert(writeArea != kInvalidCfgAreaID);  
if ( commit ) {  
err = OTCfgCommitAreaModifications(dbRef, readArea, writeArea);  
} else {  
junk = OTCfgAbortAreaModifications(dbRef, readArea);  
assert(junk == noErr);  
err = noErr;  
}
if (err == noErr) {  
err = OTCfgCloseDatabase(&dbRef);  
}
return err;  
}
Opening and Closing the Network Setup Database  
29  
 
   
C H A P T E R  
2
Using Network Setup  
Working with Entities  
2
Once you have a reference to the database and an area identifier for the default  
area, the next step is to look for appropriate entities within that area. Regardless  
of what you want to do to an entity, you must first obtain a reference to it. An  
entity reference is an opaque data structure that Network Setup uses to  
uniquely identify each entity within an area.  
Typically there are two ways to get the entity reference for an entity within an  
area.  
I You can list all of the entities of a particular class and type and display that  
network connection entities so that the user can choose the one to make  
active. The section “Listing All Entities” (page 30) explains how to do this.  
You can also create, duplicate, rename, and delete entities. These tasks are easy  
to do and are not explained in detail in this chapter. See “Network Setup  
Reference” (page 57) for information about OTCfgCreateEntity(page 76),  
OTCfgDuplicateEntity(page 78), OTCfgSetEntityName(page 81), and  
OTCfgDeleteEntity(page 78).  
Listing All Entities  
2
Listing 2-5 shows the routine MyGetEntitiesList, which generates a list of all of  
the entities within an area of the database. The routine’s database reference and  
area identifier parameters are obtained by opening the database, as explained in  
“Opening the Database for Reading” (page 25). The entityClassand entityType  
parameters specify the entities to list. Some common scenarios include:  
I Getting all entities of a specific class and type. Set the entityClassand  
entityTypeparameters to that class and type. For example, to find all TCP/IP  
network connection entities, supply a class of kOTCfgClassNetworkConnection  
and a type of kOTCfgTypeTCPv4. See “Entity Classes and Types” (page 104) for  
a list of the defined classes and types.  
30  
Working with Entities  
 
       
C H A P T E R  
2
Using Network Setup  
I Getting all entities. Set entityClassand entityTypeto the wildcard values  
kCfgClassAnyEntityand kCfgTypeAnyEntity, respectively.  
The entityRefsand entityInfosparameters are handles containing an array of  
elements of type CfgEntityRefand CfgEntityInfo, respectively. You must create  
these handles before calling MyGetEntitiesList. You can set entityInfosto NULL  
if you’re not interested in the information returned in that handle. The  
MyGetEntitiesListroutine resizes the handles appropriately to hold  
information about each of the entities that it finds.  
The MyGetEntitiesListroutine calls two key Network Setup functions:  
OTCfgGetEntitiesCountto count the number of entities of the specified class and  
type and OTCfgGetEntitiesListto get the actual entity information. The rest of  
the MyGetEntitiesListroutine is just memory management.  
Listing 2-5  
Finding all entities of a particular class and type  
static OSStatus MyGetEntitiesList(CfgDatabaseRef dbRef,  
CfgAreaID area,  
OSType entityClass,  
OSType entityType,  
CfgEntityRef **entityRefs,  
CfgEntityInfo **entityInfos)  
{
OSStatus err;  
ItemCount entityCount;  
CfgEntityRef *paramRefs;  
CfgEntityInfo *paramInfos;  
SInt8 sRefs;  
SInt8 sInfos;  
assert(dbRef != nil);  
assert(area != kInvalidCfgAreaID);  
assert((entityRefs != nil) || (entityInfos != nil));  
assert((entityRefs == nil) || (*entityRefs != nil));  
assert((entityInfos == nil) || (*entityInfos != nil));  
err = OTCfgGetEntitiesCount(dbRef, area, entityClass, entityType, &entityCount);  
if ((err == noErr) && (entityRefs != nil)) {  
Working with Entities  
31  
 
 
C H A P T E R  
2
Using Network Setup  
SetHandleSize( (Handle) entityRefs, entityCount * sizeof(CfgEntityRef) );  
err = MemError();  
}
if ((err == noErr) && (entityInfos != nil)) {  
SetHandleSize( (Handle) entityInfos, entityCount * sizeof(CfgEntityInfo) );  
err = MemError();  
}
if (err == noErr) {  
if (entityRefs == nil) {  
paramRefs = nil;  
} else {  
sRefs = HGetState( (Handle) entityRefs );  
HLock( (Handle) entityRefs );  
paramRefs = *entityRefs;  
assert(MemError() ==  
assert(MemError() ==  
noErr);  
noErr);  
}
if (entityInfos == nil) {  
paramInfos = nil;  
} else {  
sInfos = HGetState( (Handle) entityInfos );  
assert(MemError() ==  
assert(MemError() ==  
noErr);  
noErr);  
HLock( (Handle) entityInfos );  
paramInfos = *entityInfos;  
}
err = OTCfgGetEntitiesList(dbRef, area,  
entityClass, entityType,  
&entityCount, paramRefs, paramInfos);  
if (entityRefs != nil) {  
HSetState( (Handle) entityRefs, sRefs );  
assert(MemError() ==  
assert(MemError() ==  
noErr);  
}
if (entityInfos != nil) {  
HSetState( (Handle) entityInfos, sInfos );  
noErr);  
32  
Working with Entities  
 
C H A P T E R  
2
Using Network Setup  
}
}
return err;  
}
entity references for all of the TCP/IP network connection entities in the default  
area (using the MyGetEntitiesListroutine in Listing 2-5), and prints their  
user-visible names. This routine calls a routine, MyGetEntityUserVisibleName,  
which hasn’t been documented yet. It is shown in Listing 2-9 in the section  
“Reading and Writing Preferences” (page 34).  
Listing 2-6  
Printing the user-visible name for an entity  
static void PrintAllTCPEntityNames(void)  
{
OSStatus  
err;  
CfgDatabaseRef dbRef;  
CfgAreaID  
readArea;  
CfgEntityRef **entityRefs;  
ItemCount  
ItemCount  
Str255  
entityCount;  
entityIndex;  
userVisibleName;  
entityRefs = (CfgEntityRef **) NewHandle(0);  
err = MemError();  
if (err == noErr) {  
err = MyOpenDatabaseForReading(&dbRef, &readArea);  
if (err == noErr) {  
err = MyGetEntitiesList(dbRef, readArea,  
kOTCfgClassNetworkConnection, kOTCfgTypeTCPv4,  
entityRefs, nil);  
}
if (err == noErr) {  
HLock( (Handle) entityRefs );  
assert(MemError() ==  
noErr);  
printf("List of TCP/IP Network Connection Entities\n");  
Working with Entities  
33  
 
 
C H A P T E R  
2
Using Network Setup  
entityCount = GetHandleSize( (Handle) entityRefs ) / sizeof(CfgEntityRef);  
for (entityIndex = 0; entityIndex < entityCount; entityIndex++) {  
err = MyGetEntityUserVisibleName(dbRef,  
&(*entityRefs)[entityIndex],  
userVisibleName);  
if (err == noErr) {  
printf("%ld) "%#s"\n", entityIndex, userVisibleName);  
}
}
}
MyCloseDatabaseAfterReading(dbRef, readArea);  
}
if (entityRefs != nil) {  
DisposeHandle( (Handle) entityRefs );  
assert(MemError() ==  
noErr);  
}
if (err != noErr) {  
printf("Failed with error %ld.\n", err);  
}
}
Finding an Active Entity  
2
Currently, only one entity can be active for any given network connection type.  
protocol stacks. When you look for an active entity for a particular network  
protocol, you should be aware that, in the future, there may be more than one.  
Because of the complexity of this algorithm and because its implementation  
relies on concepts that haven’t been discussed yet, the steps and sample code  
for finding an active entity are shown in “Working with Sets” (page 42), later in  
this chapter.  
Reading and Writing Preferences  
2
Once you have an entity reference, reading and writing preferences in the entity  
is a straightforward exercise. The basic steps are to open the entity, read and  
34  
Reading and Writing Preferences  
 
       
C H A P T E R  
2
Using Network Setup  
write the desired preferences, and close the entity. This section describes this  
process for reading variable-length and fixed-size preferences and for writing  
preferences.  
Reading Fixed-size Preferences  
2
Many Network Setup preferences are of a fixed size. Reading a fixed size  
preference is easy because you simply read it into the C structure that  
corresponds to the preference. The code in Listing 2-7 shows a simple wrapper  
routine you can use to read a fixed size preference from an entity within the  
database. The prefTypeparameter controls the preference that is read. The  
preference data is put in the buffer described by bufferand bufferSize.  
Listing 2-7  
Reading a fixed-size preference  
static OSStatus MyReadFixedSizePref(CfgDatabaseRef dbRef,  
const CfgEntityRef *entity,  
OSType prefType,  
void *buffer,  
ByteCount bufferSize)  
{
OSStatus err;  
OSStatus err2;  
CfgEntityAccessID accessID;  
assert(dbRef != nil);  
assert(entity != nil);  
assert(buffer != nil);  
err = OTCfgOpenPrefs(dbRef, entity, false, &accessID);  
if (err == noErr) {  
err = OTCfgGetPrefs(accessID, prefType, buffer, bufferSize);  
err2 = OTCfgClosePrefs(accessID);  
if (err == noErr) {  
err = err2;  
}
}
return err;  
}
Reading and Writing Preferences  
35  
 
     
C H A P T E R  
2
Using Network Setup  
Note  
The sample shown in Listing 2-7, which opens and closes  
the entity before reading each preference, is implemented  
in an inefficient manner for the sake of clarity. If you are  
reading multiple preferences, it is more efficient to open the  
entity once. Then read the preferences by calling  
OTCfgGetPrefsor OTCfgSetPrefsmultiple times and close  
the entity when you’re done.  
N
A noteworthy point about reading preferences is that the OTCfgOpenPrefs  
function does not take an area parameter. This is because the CfgEntityRefitself  
implicitly includes the area. The significant of this point is demonstrated in the  
section “Working with Sets” (page 42).  
You can use the MyReadFixedSizePrefroutine shown in Listing 2-7 to read  
specific preferences within an entity. For example, Listing 2-8 shows how to  
read the DHCP lease information from a TCP/IP network connection entity.  
The routine calls MyReadFixedSizePref, passing it the appropriate preference  
type (kOTCfgTCPDHCPLeaseInfoPref), a pointer to the corresponding C structure,  
and the size of the structure.  
Listing 2-8  
Reading the DHCP lease info preference in a TCP/IP network  
connection entity  
static OSStatus MyReadDHCPLeaseInfo(CfgDatabaseRef dbRef,  
const CfgEntityRef *entity,  
OTCfgTCPDHCPLeaseInfo *dhcpInfo)  
{
OSStatus err;  
assert(dbRef  
assert(entity  
!= nil);  
!= nil);  
assert(dhcpInfo != nil);  
err = MyReadFixedSizePref(dbRef, entity, kOTCfgTCPDHCPLeaseInfoPref,  
dhcpInfo, sizeof(*dhcpInfo));  
return err;  
}
36  
Reading and Writing Preferences  
 
 
C H A P T E R  
2
Using Network Setup  
IMPORTANT  
You can derive the C structure for a specific preference type  
“Pref” from the end. For example, the C structure for  
kOTCfgTCPDHCPLeaseInfoPrefis OTCfgTCPDHCPLeaseInfo. The  
preference type constants and preference structures for all  
of the Apple-defined preferences are provided in Chapter 4,  
“Network Setup Protocol Structures and Data Types.” L  
Reading Variable-size Preferences  
2
size preferences that have a known maximum size that internally includes the  
size of the preference. The user-visible name preference  
(kOTCfgUserVisibleNamePref), which contains a packed Pascal string, is an  
example. The maximum length of a Pascal string is 256 bytes, and the first byte  
denotes the length of the actual string data. Listing 2-9 shows how to use  
MyReadFixedSizePrefto read this type of variable size preference.  
Listing 2-9  
Reading the user-visible name preference  
static OSStatus MyGetEntityUserVisibleName(CfgDatabaseRef dbRef,  
const CfgEntityRef *entity,  
Str255 name)  
{
OSStatus err;  
assert(dbRef != nil);  
assert(entity != nil);  
assert(name != nil);  
err = MyReadFixedSizePref(dbRef, entity, kOTCfgUserVisibleNamePref,  
name, sizeof(Str255));  
return err;  
}
If the variable size preference you want to read does not have a known  
maximum size and does not store its size internally, you need to know how big  
a buffer to allocate before you call OTCfgGetPrefs. You can get this information  
Reading and Writing Preferences  
37  
 
       
C H A P T E R  
2
Using Network Setup  
by calling OTCfgGetPrefsSizebefore you read the preference, as shown in  
Listing 2-10.  
Listing 2-10  
Calling OTCfgGetPrefsSize to read a variable-size preference  
static OSStatus MyReadVariableSizePref(CfgDatabaseRef dbRef,  
const CfgEntityRef *entity,  
OSType prefType,  
Handle buffer)  
{
OSStatus err;  
OSStatus err2;  
CfgEntityAccessID accessID;  
ByteCount prefSize;  
SInt8 s;  
assert(dbRef != nil);  
assert(entity != nil);  
assert(buffer != nil);  
err = OTCfgOpenPrefs(dbRef, entity, false, &accessID);  
if (err == noErr) {  
err = OTCfgGetPrefsSize(accessID, prefType, &prefSize);  
if (err == noErr) {  
SetHandleSize(buffer, prefSize);  
err = MemError();  
}
if (err == noErr) {  
s = HGetState(buffer);  
assert(MemError()  
assert(MemError()  
== noErr);  
== noErr);  
HLock(buffer);  
err = OTCfgGetPrefs(accessID, prefType, *buffer, prefSize);  
HSetState(buffer, s); assert(MemError()  
== noErr);  
}
err2 = OTCfgClosePrefs(accessID);  
if (err == noErr) {  
err = err2;  
}
38  
Reading and Writing Preferences  
 
 
C H A P T E R  
2
Using Network Setup  
}
return err;  
}
Writing Preferences  
2
Listing 2-11 shows the routine MyWritePref, which demonstrates the basic  
mechanism for writing preferences. Writing a preference is similar to reading a  
preference, with the following exceptions:  
I When you open the entity, open the entity for writing by passing truein the  
writerparameter of OTCfgOpenPrefs.  
I The entity that is opened must be in a writable temporary area. Attempting  
to open for writing an entity in a read-only area will result in an error.  
Note  
You don’t need provide the area identifier when you call  
OTCfgOpenPrefsbecause an entity “knows” the area to  
which it belongs. N  
Listing 2-11  
Writing a preference  
static OSStatus MyWritePref(CfgDatabaseRef dbRef,  
const CfgEntityRef *entity,  
OSType prefType,  
const void *buffer,  
ByteCount bufferSize)  
{
OSStatus err;  
OSStatus err2;  
CfgEntityAccessID accessID;  
assert(dbRef  
assert(entity  
assert(buffer  
!= nil);  
!= nil);  
!= nil);  
err = OTCfgOpenPrefs(dbRef, entity, true, &accessID);  
if (err == noErr) {  
err = OTCfgSetPrefs(accessID, prefType, buffer, bufferSize);  
Reading and Writing Preferences  
39  
 
       
C H A P T E R  
2
Using Network Setup  
err2 = OTCfgClosePrefs(accessID);  
if (err == noErr) {  
err = err2;  
}
}
return err;  
}
Note  
The sample shown in Listing 2-11, which opens and closes  
the entity for each preference written, is implemented in an  
inefficient manner for the sake of clarity. If you are writing  
multiple preferences, it is more efficient to open the entity,  
write your preferences by calling OTCfgSetPrefsmultiple  
times, and close the entity when you’re done. N  
Iterating the Preferences in an Entity  
2
Network Setup provides functions for iterating all of the preferences in an  
entity. You will rarely need to do this, but the code in Listing 2-12 gives an  
example. The code first calls OTCfgGetPrefsTOCCount(TOC stands for “Table of  
Contents”) to get a count of the number of preferences in the entity and then  
calls OTCfgGetPrefsTOCto get an array of CfgPrefsHeaderstructures. Each  
structure represents a preference in the entity, with fields for the preference’s  
type and size.  
Listing 2-12  
Printing an entity’s table of contents  
static void PrintPrefsTOC(CfgDatabaseRef dbRef, const CfgEntityRef *entity)  
{
OSStatus err;  
OSStatus err2;  
CfgEntityAccessID accessID;  
ItemCount prefsTOCCount;  
ItemCount prefsTOCIndex;  
CfgPrefsHeader *prefsTOC;  
OSType  
prefType;  
ByteCount prefSize;  
40  
Reading and Writing Preferences  
 
       
C H A P T E R  
2
Using Network Setup  
assert(dbRef != nil);  
assert(entity != nil);  
prefsTOC = nil;  
err = OTCfgOpenPrefs(dbRef, entity, false, &accessID);  
if (err == noErr) {  
err = OTCfgGetPrefsTOCCount(accessID, &prefsTOCCount);  
if (err == noErr) {  
prefsTOC = (CfgPrefsHeader *) NewPtr(prefsTOCCount *  
sizeof(CfgPrefsHeader));  
err = MemError();  
}
if (err == noErr) {  
err = OTCfgGetPrefsTOC(accessID, &prefsTOCCount, prefsTOC);  
}
if (err == noErr) {  
for (prefsTOCIndex = 0; prefsTOCIndex < prefsTOCCount; prefsTOCIndex++) {  
prefType = prefsTOC[prefsTOCIndex].fType;  
prefSize = prefsTOC[prefsTOCIndex].fSize;  
printf("type = '%4.4s', size = %ld\n", &prefType, prefSize);  
}
}
err2 = OTCfgClosePrefs(accessID);  
if (err == noErr) {  
err = err2;  
}
}
if (prefsTOC != nil) {  
DisposePtr( (Ptr) prefsTOC );  
assert(MemError() ==  
noErr);  
}
if (err != noErr) {  
printf("Failed with error %ld.\n", err);  
}
}
Reading and Writing Preferences  
41  
 
 
C H A P T E R  
2
Using Network Setup  
Working with Sets  
2
The Network Setup database uses set entities to store collections of other entity  
references. When network entities are grouped into sets, they can be activated  
and deactivated as a group. All of the network entities in all of the sets reside in  
a single area, so there are no limits on the way entities can be grouped. For  
IMPORTANT  
Sets contain entity references — not the entities  
themselves. L  
Figure 2-1 shows the relationship between set entities, network connection  
entities, and global protocol entities.  
Figure 2-1  
Set entities reference other entities  
Default Area  
Set Entities  
Work  
Home  
class 'otsc'  
type 'otst'  
class 'otsc'  
type 'otst'  
Work/DHCP Company  
Ethernet  
AirPort  
LocalTalk  
for Printer  
TCP/IP  
Globals  
AppleTalk  
Globals  
class 'otnc'  
type 'tcp4'  
class 'otnc' class 'otnc' class 'otnc'  
type 'atlk' type 'tcp4' type 'atlk'  
class 'otgl'  
type 'tcp4'  
class 'otgl'  
type 'atlk'  
Network Connection Entities  
Global Protocol Entities  
42  
Working with Sets  
 
     
C H A P T E R  
2
Using Network Setup  
There are a few basic rules for set entities:  
I Each set entity contains a preference, kOTCfgSetsStructPref, that has a flag  
that determines whether the set is active.  
I At all times, there must be one and only one active set.  
I Each set entity contains a preference, kOTCfgSetsVectorPref, that includes, as  
elements of an unbounded array, the entity references of all entities in the set.  
I For legacy synchronization to work correctly, each set entity must contain  
one and only one entity of each type of network connection and global  
protocol entity. This restriction will be relaxed in future versions of Mac OS.  
When you make changes to a set entity, you must follow these rules:  
I If you mark a set as active, you must deactivate the previously active set.  
I When you add an entity to a set entity, you must remove the first entity in  
the array of the same class and type as the entity you are adding. If there is  
more than one entity of the same class and type, you can safely leave the  
other entities in the set entity because you are running on a system that  
supports multihoming.  
I When you delete an entity, you must delete its reference from all set entities,  
whether they are active or not.  
I You must not delete the last remaining entity of a particular class and type  
from a set entity.  
I Do not add a set entity reference to another set entity. Network Setup does  
not support nested set entities.  
Finding the Active Set Entity  
2
The basic algorithm for finding the active entity of a particular class and type is:  
1. Get a list of all set entities.  
2. Search the list for the active set entity.  
3. Get the contents of that set entity. (The contents of a set entity is a list of  
entity references.)  
4. Search the set’s entity references for the entity reference having the  
appropriate class and type.  
Working with Sets  
43  
 
               
C H A P T E R  
2
Using Network Setup  
The MyFindActiveSetroutine in Listing 2-13 implements the first two steps. It  
starts by getting a list of all of the set entities by calling the MyGetEntitiesList  
routine (Listing 2-5). Then MyFindActiveSetiterates through all of the set  
entities, reading the kOTCfgSetsStructPrefpreference of each set entity. That  
preference maps to the CfgSetsStructstructure, which contains an fFlags  
member. One bit of the fFlagsmember, kOTCfgSetsFlagActiveMask, indicates  
whether this set entity is the active set entity. If it is, the routine breaks out of  
the loop and returns the set’s entity reference to the caller.  
Listing 2-13  
Finding the active set entity  
static OSStatus MyFindActiveSet(CfgDatabaseRef dbRef,  
CfgAreaID area,  
CfgEntityRef *activeSet)  
{
OSStatus  
err;  
CfgEntityRef **entityRefs;  
ItemCount  
ItemCount  
Boolean  
entityCount;  
entityIndex;  
found;  
CfgSetsStruct  
thisStruct;  
assert(dbRef != nil);  
assert(area != kInvalidCfgAreaID);  
entityRefs = (CfgEntityRef **) NewHandle(0);  
err = MemError();  
if (err == noErr) {  
err = MyGetEntitiesList(dbRef, area,  
kOTCfgClassSetOfSettings, kOTCfgTypeSetOfSettings,  
entityRefs, nil);  
}
if (err == noErr) {  
HLock( (Handle) entityRefs );  
assert(MemError() ==  
noErr);  
entityCount = GetHandleSize( (Handle) entityRefs ) / sizeof(CfgEntityRef);  
found = false;  
for (entityIndex = 0; entityIndex < entityCount; entityIndex++) {  
err = MyReadFixedSizePref(dbRef, &(*entityRefs)[entityIndex],  
44  
Working with Sets  
 
 
C H A P T E R  
2
Using Network Setup  
kOTCfgSetsStructPref,  
&thisStruct, sizeof(thisStruct));  
if ((err == noErr) && ((thisStruct.fFlags & kOTCfgSetsFlagActiveMask) !=  
0)) {  
found = true;  
break;  
}
if (err != noErr) {  
break;  
}
}
if ( ! found ) {  
err = kCfgErrEntityNotFound;  
}
}
if (err == noErr) {  
*activeSet = (*entityRefs)[entityIndex];  
}
if (entityRefs != nil) {  
DisposeHandle( (Handle) entityRefs );  
assert(MemError() ==  
noErr);  
}
return err;  
}
The remaining two steps for finding the set entity of a particular class and type  
are implemented by the MyFindFirstActiveEntityroutine, shown in Listing  
2-14. It calls MyFindActiveSet(Listing 2-13) to find the entity reference of the  
active set entity. The MyFindFirstActiveEntityroutine then reads the  
kOTCfgSetsVectorPrefpreference out of the active set entity. This preference is a  
count field followed by an unbounded array of CfgSetsElementstructures, each  
of which represents an entity in the set. Because of its variable size,  
MyFindFirstActiveEntityreads the preference by calling  
MyReadVariableSizePref(Listing 2-10). Once it has the array of information  
about entities contained in the set, MyFindFirstActiveEntityiterates over that  
array looking for the first element whose class and type matches the required  
class and type specified by the caller. When it finds the correct entity in the set,  
MyFindFirstActiveEntitybreaks out of the loop and returns the found entity  
reference to the caller.  
Working with Sets  
45  
 
C H A P T E R  
2
Using Network Setup  
Listing 2-14  
Finding the active entity of a given class and type  
static OSStatus MyFindFirstActiveEntity(CfgDatabaseRef dbRef,  
CfgAreaID area,  
OSType entityClass,  
OSType entityType,  
CfgEntityRef *activeEntity)  
{
OSStatus  
err;  
CfgEntityRef activeSet;  
CfgSetsVector **entitiesInSet;  
ItemCount  
Boolean  
entityIndex;  
found;  
CfgEntityInfo thisEntityInfo;  
entitiesInSet = (CfgSetsVector **) NewHandle(0);  
err = MemError();  
if (err == noErr) {  
err = MyFindActiveSet(dbRef, area, &activeSet);  
}
if (err == noErr) {  
err = MyReadVariableSizePref(dbRef, &activeSet, kOTCfgSetsVectorPref, (Handle )  
entitiesInSet);  
}
if (err == noErr) {  
HLock( (Handle) entitiesInSet );  
found = false;  
for (entityIndex = 0; entityIndex < (**entitiesInSet).fCount; entityIndex++) {  
thisEntityInfo = (**entitiesInSet).fElements[entityIndex].fEntityInfo;  
found = ( thisEntityInfo.fClass == entityClass && thisEntityInfo.fType ==  
entityType );  
if (found) {  
break;  
}
}
if ( ! found ) {  
err = kCfgErrEntityNotFound;  
}
}
if (err == noErr) {  
46  
Working with Sets  
 
 
C H A P T E R  
2
Using Network Setup  
*activeEntity = (**entitiesInSet).fElements[entityIndex].fEntityRef;  
OTCfgChangeEntityArea(activeEntity, area);  
}
if (entitiesInSet != nil) {  
DisposeHandle( (Handle) entitiesInSet );  
assert(MemError() ==  
noErr);  
}
return err;  
}
The code in Listing 2-15 pulls together the process of finding an active set entity  
by finding the active TCP/IP set entity. It opens the database, calls  
MyFindFirstActiveEntity(Listing 2-14) with kOTCfgClassNetworkConnectionand  
kOTCfgTypeTCPv4as parameters, calls MyGetEntityUserVisibleName(Listing 2-9)  
to get and print the entity’s user visible name, and calls  
MyCloseDatabaseAfterReading(Listing 2-3) to close the database.  
Listing 2-15  
Finding the active TCP/IP entity  
static void PrintActiveTCPEntity(void)  
{
OSStatus  
err;  
CfgDatabaseRef dbRef;  
CfgAreaID  
CfgEntityRef  
Str255  
readArea;  
activeTCPEntity;  
userVisibleName;  
err = MyOpenDatabaseForReading(&dbRef, &readArea);  
if (err == noErr) {  
err = MyFindFirstActiveEntity(dbRef, readArea,  
kOTCfgClassNetworkConnection,  
kOTCfgTypeTCPv4,  
&activeTCPEntity);  
if (err == noErr) {  
err = MyGetEntityUserVisibleName(dbRef, &activeTCPEntity, userVisibleName);  
}
if (err == noErr) {  
Working with Sets  
47  
 
 
C H A P T E R  
2
Using Network Setup  
printf("User-visible name of active TCP/IP entity = "%#s"\n",  
userVisibleName);  
}
MyCloseDatabaseAfterReading(dbRef, readArea);  
}
if (err != noErr) {  
printf("Failed with error %ld.\n", err);  
}
}
Areas and Sets  
2
When working with sets you need to be very careful about area identifiers.  
There are three key points to remember:  
I The area identifier is embedded in the entity reference.  
I All modifications to the database are done in a temporary area.  
I The temporary area is destroyed when changes are committed to the  
database.  
So, the area identifier that is embedded in the entity reference in a set is an area  
identifier for an area that no longer exists. This can cause your software to fail.  
For example, consider the following sequence:  
1. Start with a database whose default area identifier is 1370.  
2. A program opens the database for writing, which creates a temporary area  
whose identifier is 6288.  
3. The program adds an entity reference to the active set entity in the temporary  
area. Because the added entity reference describes an entity in the temporary  
area, its area identifier is 6288.  
4. The writing program commits its changes to the database, overwriting area  
1370 with the content of area 6288. The active set entity in area 1370 now  
contains an entity reference whose area identifier is 6288.  
5. Your program opens the database for reading. It then opens the active set  
entity and reads the entity references contained therein. When it tries to use  
one of those entities, the program fails because the entity’s area identifier is  
6288, not 1370.  
48  
Working with Sets  
 
       
C H A P T E R  
2
Using Network Setup  
The solution to this problem is very simple: assume that all entity references in  
a set refer to entities that are in the same area as the set. This has two practical  
consequences.  
I When comparing two entity references that might have come from a set  
entity, always pass kOTCfgIgnoreAreawhen calling OTCfgIsSameEntityRef. The  
OTCfgIsSameEntityReffunction will then compare the entities as if they were  
in the same area.  
I When opening an entity whose reference you have obtained from a set,  
always call OTCfgChangeEntityAreato reset its area identifier to that of the  
area in which you are working.  
Listing 2-14 demonstrates this technique.  
Protocol-specific Topics  
2
This section contains hints and tips for working with the Network Setup  
preferences of certain protocol stacks provided by Apple.  
TCP/IP Notes  
2
contain the following preferences:  
I kOTCfgTCPInterfacesPref, which contains the core TCP/IP configuration  
OTCfgTCPInterfacesUnpacked(page 112), OTCfgTCPInterfacesPacked  
(page 114), and OTCfgTCPInterfacesPackedPart(page 114).  
I kOTCfgTCPDeviceTypePref, which contains data needed by the current TCP/IP  
control panel. For details, see OTCfgTCPDeviceTypePrefin the section “TCP/IP  
Constants and Other Data Types” (page 160).  
I kOTCfgTCPRoutersListPref, which contains the list of configured routers. For  
details, see OTCfgTCPRoutersList(page 119).  
I kOTCfgTCPSearchListPref, which contains the strings which make up the  
implicit search path for DNS. For details, see OTCfgTCPSearchList(page 120).  
Protocol-specific Topics  
49  
 
       
C H A P T E R  
2
Using Network Setup  
I kOTCfgTCPDNSServersListPref, which contains the list of configured DNS  
servers. For details, see OTCfgTCPDNSServersList(page 116).  
I kOTCfgTCPSearchDomainsPref, which contains the list of additional domains to  
be searched. For details, see OTCfgTCPSearchDomains(page 120).  
I kOTCfgTCPUnloadAttrPref, which specifies how TCP/IP loads and unloads.  
For details, see OTCfgTCPUnloadAttr(page 121).  
I kOTCfgTCPLocksPref, which is used by the TCP/IP control panel to remember  
which preferences are locked. For details, see OTCfgTCPLocks(page 116).  
The only complex preference in a TCP/IP network connection entity is the  
kOTCfgTCPInterfacesPrefpreference. The data for this preference is packed in  
an unusual way that makes the preference tricky to access from C. To help solve  
this problem, Network Setup declares two sets of C structures for this  
preference.  
I OTCfgTCPInterfacesPackedand OTCfgTCPInterfacesPackedParthelp you  
access the preference in its packed format.  
I OTCfgTCPInterfacesUnpackedis an unpacked form of the preference that you  
can use internally within your code. When you read the preference, you can  
unpack it into this structure. You can then manipulate the unpacked  
structure and only pack it again when you write it.  
Listing 2-16 provides sample code that unpacks and packs a  
kOTCfgTCPInterfacesPrefpreference.  
Listing 2-16  
Packing and unpacking the kOTCfgTCPInterfacesPref preference  
static OSStatus MyPackTCPInterfacesPref(const OTCfgTCPInterfacesUnpacked *unpackedPref,  
OTCfgTCPInterfacesPacked *packedPref,  
ByteCount *packedPrefSize)  
{
UInt8 *cursor;  
assert(unpackedPref  
assert(packedPref  
!= nil);  
!= nil);  
assert(packedPrefSize != nil);  
// Start the cursor at the beginning of the packed preference.  
50  
Protocol-specific Topics  
 
     
C H A P T E R  
2
Using Network Setup  
cursor = (UInt8 *) packedPref;  
// For each field in the unpacked pref, copy the field to the  
// packed preference cursor and advance the cursor appropriately.  
if (unpackedPref->fCount != 1) goto prefDataErr;  
*((UInt16 *) cursor) = unpackedPref->fCount;  
cursor += sizeof(UInt16);  
*cursor = unpackedPref->fConfigMethod;  
cursor += sizeof(UInt8);  
*((InetHost *) cursor) = unpackedPref->fIPAddress;  
cursor += sizeof(InetHost);  
*((InetHost *) cursor) = unpackedPref->fSubnetMask;  
cursor += sizeof(InetHost);  
// Writing an AppleTalk zone longer than 32 characters is an error.  
if ( unpackedPref->fAppleTalkZone[0] > 32 ) goto prefDataErr;  
BlockMoveData(unpackedPref->fAppleTalkZone, cursor, unpackedPref->fAppleTalkZone[0]  
+ 1);  
cursor += (unpackedPref->fAppleTalkZone[0] + 1);  
BlockMoveData(unpackedPref->path, cursor, 36);  
cursor += 36;  
BlockMoveData(unpackedPref->module, cursor, 32);  
cursor += 32;  
*((UInt32 *) cursor) = unpackedPref->framing;  
cursor += sizeof(UInt32);  
// Now calculate the packed preference size by taking the difference  
// between the final cursor position and the initial cursor position.  
*packedPrefSize = (cursor - ((UInt8 *) packedPref));  
return noErr;  
prefDataErr:  
return paramErr;  
}
Protocol-specific Topics  
51  
 
 
C H A P T E R  
2
Using Network Setup  
static OSStatus MyUnpackTCPInterfacesPref(const OTCfgTCPInterfacesPacked *packedPref,  
ByteCount packedPrefSize,  
OTCfgTCPInterfacesUnpacked *unpackedPref)  
{
UInt8 *cursor;  
assert(packedPref  
!= nil);  
assert(unpackedPref != nil);  
// Put the cursor at the beginning of the packed preference data.  
cursor = (UInt8 *) packedPref;  
// Walk through the packed preference data and extract the fields.  
unpackedPref->fCount = *((UInt16 *) cursor);  
if (unpackedPref->fCount != 1) goto prefDataErr;  
cursor += sizeof(UInt16);  
unpackedPref->fConfigMethod = *cursor;  
cursor += sizeof(UInt8);  
// The following code accesses a long off a word.  
// Network Setup is PowerPC only, and the emulated PowerPC processor handles these  
// misaligned accesses.  
unpackedPref->fIPAddress = *((InetHost *) cursor);  
cursor += sizeof(InetHost);  
unpackedPref->fSubnetMask = *((InetHost *) cursor);  
cursor += sizeof(InetHost);  
// fAppleTalkZone is a Str32. A longer string in the 'iitf' preference causes an  
error.  
if ( *cursor > 32 ) goto prefDataErr;  
BlockMoveData(cursor, unpackedPref->fAppleTalkZone, *cursor + 1);  
cursor += (*cursor + 1);  
BlockMoveData(cursor, unpackedPref->path, 36);  
cursor += 36;  
BlockMoveData(cursor, unpackedPref->module, 32);  
cursor += 32;  
unpackedPref->framing = *((UInt32 *) cursor);  
cursor += sizeof(UInt32);  
52  
Protocol-specific Topics  
 
 
C H A P T E R  
2
Using Network Setup  
// If the cursor doesn’t stop at the end of the packed preference data, a data  
format error occurs.  
if ( (cursor - ((UInt8 *) packedPref)) != packedPrefSize) goto prefDataErr;  
return noErr;  
prefDataErr:  
return paramErr;  
}
Remote Access Notes  
2
A Remote Access network connection entity has a class of  
kOTCfgClassNetworkConnectionand a type of kOTCfgTypeRemoteand typically  
contains the following preferences:  
I kOTCfgRemoteConnectPref, which contains core connection preferences. For  
details, see OTCfgRemoteConnect(page 127).  
I kOTCfgRemoteUserPref, which contains the user name. For details, see  
OTCfgRemoteUserPrefin the section “Apple Remote Access Constants and  
Other Data Types” (page 163).  
I kOTCfgRemotePasswordPref, which contains the user’s encrypted password.  
For details, see the sample code below and OTCfgRemotePassword(page 135).  
I kOTCfgRemoteAddressPref, which contains the phone number to dial. For  
details, see OTCfgRemoteAddressPrefin the section “Apple Remote Access  
Constants and Other Data Types” (page 163).  
I kOTCfgRemoteDialingPref, which contains redial preferences. For details, see  
OTCfgRemoteDialing(page 131).  
I kOTCfgRemoteClientMiscPref, which controls the “dial on demand” feature of  
IPCP. For details, see OTCfgRemoteClientMisc(page 127).  
typically set this preference to a default value obtained by calling  
OTCfgGetDefault(page 90). For details, see OTCfgRemoteIPCP(page 132).  
I kOTCfgRemoteLCPPref, which contains low-level preferences for LCP. You  
typically set this preference to a default value obtained by calling  
OTCfgGetDefault(page 90). For details, see OTCfgRemoteLCP(page 133).  
Protocol-specific Topics  
53  
 
     
C H A P T E R  
2
Using Network Setup  
I kOTCfgRemoteLogOptionsPref, which contains the “verbose logging” option.  
For details, see OTCfgRemoteLogOptions(page 135).  
I kOTCfgRemoteClientLocksPref, which is used by the Remote Access control  
panel to remember which preferences are locked. For details, see  
OTCfgRemoteClientLocks(page 125).  
To create the kOTCfgRemotePasswordPref, you must encrypt the user’s password.  
The code in Listing 2-17 shows a technique for doing this.  
Listing 2-17  
Encrypting the user’s password  
static void EncodeRemotePasswordNetworkSetup(  
ConstStr255Param userName,  
ConstStr255Param password,  
Str255 encodedPassword)  
{
BlockZero(encodedPassword, sizeof(Str255));  
BlockMoveData(password + 1, encodedPassword, password[0]);  
(void) OTCfgEncrypt( (UInt8 *) userName,  
encodedPassword,  
sizeof(Str255));  
}
Modem Notes  
2
A Remote Access network connection entity has a class of  
kOTCfgClassNetworkConnectionand a type of kOTCfgTypeModem. The entity  
typically contains the following preferences:  
I kOTCfgModemGeneralPrefs, which contains the core modem preferences. For  
details, see OTCfgModemGeneral(page 141).  
I kOTCfgModemLocksPref, which is used by the Modem control panel to  
remember which preferences are locked. For details, see OTCfgModemLocks  
(page 143).  
When creating the kOTCfgModemGeneralPrefspreference, you have to supply the  
name of a serial port that is visible to Open Transport. For information about  
building a list of Open Transport serial ports and their user-visible names, see  
54  
Protocol-specific Topics  
 
       
C H A P T E R  
2
Using Network Setup  
DTS Technote 1119 Serial Port Apocrypha available at  
http://developer.apple.com/technotes/tn/tn1119.html.  
Notes for Third Parties  
2
This section contains miscellaneous hints and tips for third-party developers  
who want to use Network Setup to store their own preferences.  
Storing Third-party Preferences in Apple Entities  
2
It is reasonable for third-party developers to store custom preferences inside  
Apple Computer’s protocol entities. For example, a TCP/IP virtual private  
network (VPN) implementation might store per-connection preferences inside  
Apple Computer’s TCP/IP network connection entity. This is perfectly legal —  
in fact it is encouraged — but you need to follow one important rule: The  
preference type for your preference must be registered as a unique creator code  
with DTS at http://developer.apple.com/dev/cftype. Registering preference  
types will prevent two different developers from using the same preference  
type for conflicting preferences.  
Network Setup and Third-party Protocol Stacks  
2
If you're writing a third-party protocol stack, you can use the Network Setup  
database to store your preferences in much the same way as the Apple protocol  
stacks do. There are a few important things to remember.  
I It is recommended that you use the existing classes,  
kOTCfgClassNetworkConnectionand kOTCfgClassGlobalSettings, for your  
global protocol and network connection entities.  
I You should register a unique creator code with DTS at  
http://developer.apple.com/dev/cftypeand use it as the type for your  
entities. This will ensure that your work does not conflict with Apple  
Computer or other developers.  
Your protocol stack configurator should call OTCfgInstallNotifier(page 94) to  
install a Network Setup notifier to watch for changes to its preferences by your  
control panel or by third-party software.  
Notes for Third Parties  
55  
 
       
C H A P T E R  
2
Using Network Setup  
56  
Notes for Third Parties  
 
C
H
A
P
T
E
R
3
Figure 3-0  
Listing 3-0  
Table 3-0  
Network Setup Reference  
3
3
This chapter describes the functions, structures, and data types for calling  
Network Setup. For protocol-specific preferences, see Chapter 4, “Network  
Setup Protocol Structures and Data Types.”  
Network Setup Functions  
The Network Setup functions are described in these sections:  
I “Opening and Closing the Network Setup Database” (page 57)  
I “Managing Areas” (page 59)  
I “Managing Entities” (page 72)  
I “Managing Preferences” (page 83)  
I “Preference Utilities” (page 92)  
I “Installing and Removing a Notification Callback” (page 94)  
3
Network Setup database. Be sure to close the database when you are done. The  
functions are:  
I OTCfgOpenDatabase(page 58) opens the Network Setup database.  
I OTCfgCloseDatabase(page 58) closes the Network Setup database.  
Network Setup Functions  
57  
 
       
C H A P T E R  
3
Network Setup Reference  
OTCfgOpenDatabase  
3
Opens a session with the Network Setup database.  
OSStatus OTCfgOpenDatabase (CfgDatabaseRef* dbRef);  
dbRef  
On input, a pointer to a value of type CfgDatabaseRef(page 98).  
On output, dbRefis a reference to the opened database that is  
passed as a parameter to other Network Setup functions.  
function result A value of noErrif the database was opened. For a list of other  
possible result codes, see “Result Codes” (page 110).  
DISCUSSION  
The OTCfgOpenDatabasefunction opens a session with the Network Setup  
database. Your application must call OTCfgOpenDatabasesuccessfully before it  
can call any other Network Setup function.  
OTCfgCloseDatabase  
3
Closes the Network Setup database.  
OSStatus OTCfgCloseDatabase (OTCfgDatabaseRef* dbRef);  
dbRef  
A pointer to value of type CfgDatabaseRef(page 98) that  
represents the database session you want to close.  
function result A value of noErrif the database was closed. For a list of other  
possible result codes, see “Result Codes” (page 110).  
DISCUSSION  
The OTCfgCloseDatabasefunction closes the database session represented by  
dbRef.  
58  
Network Setup Functions  
 
       
C H A P T E R  
3
Network Setup Reference  
Note  
Closing a database session automatically removes any  
notification callback that has been installed for the session  
represented by dbRef. N  
Managing Areas  
3
The following functions manage areas in the Network Setup database:  
I OTCfgGetCurrentArea(page 60) obtains the default area in the database.  
I OTCfgSetCurrentArea(page 61) sets the default area in the database.  
I OTCfgCloseArea(page 62) closes an area in the database.  
I OTCfgBeginAreaModifications(page 63) creates a temporary area for  
modifying the database.  
I OTCfgCommitAreaModifications(page 64) commits changes made in a  
I OTCfgAbortAreaModifications(page 65) discards a temporary area and all  
modifications made to it.  
I OTCfgIsSameAreaID(page 65) determines whether two area IDs are the same.  
I OTCfgGetAreaName(page 66) gets the name of an area in the database.  
database.  
I OTCfgCreateArea(page 70) creates a new area in the database.  
I OTCfgDuplicateArea(page 71) copies the contents of an area to another area.  
I OTCfgDeleteArea(page 72) deletes an area in the database.  
Network Setup Functions  
59  
 
 
C H A P T E R  
3
Network Setup Reference  
IMPORTANT  
Areas other than the default area (also known as the  
current area) do not affect any network setting, so many of  
the area manipulation functions described in this section  
are not commonly used. You rarely need to call  
OTCfgGetAreaName, OTCfgSetAreaName, OTCfgGetAreasCount,  
OTCfgGetAreasList, OTCfgCreateArea, OTCfgDuplicateArea,  
or OTCfgDeleteArea. L  
OTCfgGetCurrentArea  
3
Obtains the default area.  
OSStatus OTCfgGetCurrentArea (CfgDatabaseRef dbRef,  
CfgAreaID* areaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a pointer to a value of type CfgAreaID(page 98). On  
output, areaIDpoints to the area ID of the current area.  
function result A value of noErrindicates that OTCfgGetCurrentAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetCurrentAreafunction obtains the area ID of the default area. The  
default area is sometimes referred to as the current area.  
60  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgSetCurrentArea  
3
Sets the default area.  
OSStatus OTCfgSetCurrentArea (CfgDatabaseRef dbRef,  
CfgAreaID areaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a value of type CfgAreaID(page 98) containing the  
area does not exist, OTCfgSetCurrentAreareturns  
kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgSetCurrentAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgSetCurrentAreafunction makes the area ID specified by the areaID  
parameter the default area. The default area is sometimes referred to as the  
current area.  
L
W AR N I N G  
Do not change the default area. If you want to modify  
settings, make changes to the entities within the default  
area. L  
OTCfgOpenArea  
3
Opens an area in the Network Setup database for reading.  
OSStatus OTCfgOpenArea (CfgDatabaseRef dbRef,  
CfgAreaID areaID);  
Network Setup Functions  
61  
 
       
C H A P T E R  
3
Network Setup Reference  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
area that is to be opened. If the area specified by areaIDdoes not  
exist, OTCfgOpenAreareturns kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgOpenAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgOpenAreafunction opens the specified area in the Network Setup  
database for reading.  
OTCfgCloseArea  
3
Closes an area in the Network Setup database.  
OSStatus OTCfgCloseArea (CfgDatabaseRef dbRef,  
CfgAreaID areaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
area that is to be closed. If the area specified by areaIDdoes not  
exist, OTCfgCloseAreareturns kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgCloseAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgCloseAreafunction closes an area in the database that was previously  
opened for reading by calling OTCfgOpenArea(page 61).  
62  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgBeginAreaModifications  
3
Creates a temporary area for modifying an area.  
OSStatus OTCfgBeginAreaModifications (CfgDatabaseRef dbRef,  
CfgAreaID readAreaID,  
CfgAreaID* writeAreaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
readAreaID  
On input, a value of type CfgAreaID(page 98) obtained by  
calling OTCfgGetCurrentArea(page 60). If the area specified by  
readAreaIDdoes not exist, OTCfgBeginAreaModificationsreturns  
kCfgErrAreaNotFound.  
writeAreaID  
On input, a pointer to a value of type CfgAreaID(page 98). On  
application should use to modify, delete, enumerate, or read  
data in the area.  
function result A value of noErrindicates that OTCfgBeginAreaModifications  
returned successfully. For a list of other possible result codes,  
see “Result Codes” (page 110).  
DISCUSSION  
The OTCfgBeginAreaModificationsfunction creates a temporary area and returns  
in the writeAreaIDparameter an area ID for it. The area ID for the temporary  
area can be passed as a parameter to subsequent calls for creating or modifying  
entities in the temporary area.  
If you need to read the area’s original, unmodified data, you can continue using  
readAreaIDto do so.  
IMPORTANT  
Only one program can open an area of writing at any one  
time. If another program has already opened the area for  
writing, OTCfgBeginAreaModificationsreturns  
kCfgErrConfigLocked. L  
Network Setup Functions  
63  
 
   
C H A P T E R  
3
Network Setup Reference  
Call OTCfgCommitAreaModifications(page 64) to write the temporary area to the  
area identified by writeAreaID, dispose of the temporary area, and close the area  
represented by writeAreaID, or call OTCfgAbortAreaModifications(page 65) to  
close the area represented by readAreaIDand discard the temporary area.  
OTCfgCommitAreaModifications  
3
Closes an area for writing and commits modifications.  
OSStatus OTCfgCommitAreaModifications (CfgDatabaseRef dbRef,  
CfgAreaID readAreaID,  
CfgAreaID writeAreaID);  
dbRef  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
readAreaID  
On input, a value of type CfgAreaID(page 98). If readAreaIDdoes  
not exist or does not match the writeAreaIDreferred to by  
OTCfgBeginAreaModifications(page 63),  
OTCfgCommitAreaModificationsreturns kCfgErrAreaNotFound.  
writeAreaID  
On input, a value of type CfgAreaID(page 98) previously  
obtained by calling OTCfgBeginAreaModifications(page 63). If  
passed to OTCfgBeginAreaModifications(page 63),  
OTCfgCommitAreaModificationsreturns kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgCommitAreaModifications  
returned successfully. For a list of other possible result codes,  
see “Result Codes” (page 110).  
DISCUSSION  
The OTCfgCommitAreaModificationsfunction writes the temporary area  
represented by writeAreaIDto the area represented by readAreaIDand closes the  
write area.  
Readers of the area represented by readAreaIDare informed that the database  
has been modified.  
64  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgAbortAreaModifications  
3
Closes an area for writing without committing modifications.  
OSStatus OTCfgAbortAreaModifications (CfgDatabaseRef dbRef,  
CfgAreaID readAreaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
OTCfgOpenDatabase(page 58).  
readAreaID  
On input, a value of type CfgAreaID(page 98) that identifies an  
area that has been opened for writing. If readAreaIDdoes not  
exist or you have not called OTCfgBeginAreaModifications  
(page 63) for the area represented by readAreaID,  
OTCfgAbortAreaModificationsreturns kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgAbortAreaModifications  
returned successfully. For a list of other possible result codes,  
see “Result Codes” (page 110).  
DISCUSSION  
The OTCfgAbortAreaModificationsfunction closes an area that was opened for  
writing without writing the modifications to the area presented by readAreaID.  
OTCfgIsSameAreaID  
3
Compares two area IDs.  
Boolean OTCfgIsSameAreaID (CfgAreaID areaID1,  
CfgAreaID areaID2);  
areaID1  
areaID2  
On input, a value of type CfgAreaID(page 98) representing one  
of the area IDs that is to be compared.  
On input, a value of type CfgAreaID(page 98) representing the  
other area ID that is to be compared.  
Network Setup Functions  
65  
 
       
C H A P T E R  
3
Network Setup Reference  
function result A Boolean value that is TRUEif the area IDs are the same and  
FALSEif the area IDs are different.  
DISCUSSION  
The OTCfgIsSameAreaIDfunction determines whether two area IDs represent to  
the same area.  
OTCfgGetAreaName  
3
Obtains the user-visible name of an area.  
OSStatus OTCfgGetAreaName (CfgDatabaseRef dbRef,  
CfgAreaID areaID,  
Str255 areaName);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a value of type CfgAreaID(page 98) that identifies the  
area whose name is to be obtained. If the area specified by  
areaIDdoes not exist, OTCfgGetAreaNamereturns  
kCfgErrAreaNotFound.  
areaName  
On input, a value of type Str255. On output, areaNamecontains  
the user-visible name of the area specified by areaID.  
function result A value of noErrindicates that OTCfgGetAreaNamereturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetAreaNamefunction gets the user-visible name of the specified area.  
Note  
The OTCfgGetAreaNamefunction is available in Network  
Setup version 1.0.1 and later. N  
66  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgSetAreaName  
3
Sets the user-visible name of an area.  
OSStatus OTCfgSetAreaName (CfgDatabaseRef dbRef,  
CfgAreaID areaID,  
ConstStr255Param areaName,  
CfgAreaID* newAreaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a value of type CfgAreaID(page 98) that identifies the  
area whose name is to be set. If the area specified by areaIDdoes  
not exist, OTCfgSetAreaNamereturns kCfgErrAreaNotFound.  
areaName  
newAreaID  
On input, a value of type ConstStr255Paramthat specifies the  
name to set. If an area of the name specified by areaNamealready  
exists, OTCfgSetAreaNamereturns kCfgErrAreaAlreadyExists.  
output, newAreaIDpoints to a new area ID that your application  
should use for any subsequent calls for the area.  
function result A value of noErrindicates that OTCfgSetAreaNamereturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgSetAreaNamefunction changes the user-visible name of the specified  
area and returns a new area ID for that area.  
L
W AR N I N G  
Do not change the name of the default area. L  
Network Setup Functions  
67  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgGetAreasCount  
3
Obtains the number of areas in the Network Setup database.  
OSStatus OTCfgGetAreasCount (CfgDatabaseRef dbRef,  
ItemCount* itemCount);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
itemCount  
On input, a pointer to value of type ItemCount. On output,  
itemCountpoints to the number of areas in the database.  
function result A value of noErrindicates that OTCfgGetAreasCountreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetAreasCountfunction obtains the number of areas that are currently  
defined in the database. Having the number of areas allows you to call  
OTCfgGetAreasList(page 68) to get the ID and name of each area.  
OTCfgGetAreasList  
3
Obtains the IDs and names of areas in the Network Setup database.  
OSStatus OTCfgGetAreasList (CfgDatabaseRef dbRef,  
ItemCount* itemCount,  
CfgAreaID areaID[],  
Str255 areaName[]);  
dbRef  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
itemCount  
On input, a pointer to a value of type ItemCountthat specifies  
the number of areas for which information is requested. Call  
OTCfgGetAreasCount(page 68) to determine the number of areas  
68  
Network Setup Functions  
 
       
C H A P T E R  
3
Network Setup Reference  
that are available. On output, itemCountpoints to the number of  
areas for which information was actually returned, which may  
be less that expected if areas were deleted between calling  
OTCfgGetAreasCount(page 68) and calling OTCfgGetAreasList.  
areaID  
On input, an array of elements of type CfgAreaID(page 98) that  
is large enough to hold the number of area IDs specified by  
itemCount. On output, each array element contains an area ID. If  
you don’t want to get area IDs, set areaIDto NULL.  
areaName  
On input, an array of elements of type Str255that is large  
enough to hold the number of area names specified by  
itemCount. On output, each array element contains an area  
ID in the first element of the array specified by areaID, and so  
on. If you don’t want to get area names, set areaNameto NULL.  
function result A value of noErrindicates that OTCfgGetAreasListreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetAreasListfunction obtains the IDs and names of areas in the  
the other containing area names. Each area ID and area name pair identifies an  
area in the database.  
When you allocate the arrays for the areaIDand areaNameparameters, be sure to  
allocate enough elements to hold the number of areas returned by  
OTCfgGetAreasCount(page 68). The actual number of items returned in each  
array may be lower than the number returned by OTCfgGetAreasCount(page 68)  
if areas have been deleted in the meantime.  
Network Setup Functions  
69  
 
C H A P T E R  
3
Network Setup Reference  
OTCfgCreateArea  
3
Creates an area in the Network Setup database.  
OSStatus OTCfgCreateArea (CfgDatabaseRef dbRef,  
ConstStr255Param areaName,  
CfgAreaID* areaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaName  
On input, a value of type ConstStr255Paramthat specifies the  
user-visible name of the area to create. If an area of the name  
specified by areaNamealready exists, OTCfgCreateAreareturns  
kCfgErrAreaAlreadyExists.  
areaID  
On input, a pointer to a value of type CfgAreaID(page 98). On  
output, areaIDcontains the ID of the area that was created.  
function result A value of noErrindicates that OTCfgCreateAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgCreateAreafunction creates an area of the specified name in the  
database.  
IMPORTANT  
The OTCfgCreateAreafunction has almost no purpose in the  
version of Network Setup described by this document. N  
70  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgDuplicateArea  
3
Copies the contents of one area to another area.  
OSStatus OTCfgDuplicateArea (CfgDatabaseRef dbRef,  
CfgAreaID sourceAreaID,  
CfgAreaID destAreaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
sourceAreaID On input, a value of type CfgAreaID(page 98) that identifies the  
area that is to be duplicated. If the area specified by areaIDdoes  
not exist, OTCfgDuplicateAreareturns kCfgErrAreaNotFound.  
destAreaID  
On input, a value of type CfgAreaID(page 98) that identifies the  
by areaIDdoes not exist, OTCfgDuplicateAreareturns  
kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgDuplicateAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgDuplicateAreafunction copies the contents of the area specified by  
sourceAreaIDinto the area specified by destAreaID. Both areas must exist before  
you call OTCfgDuplicateArea. To create an area, call OTCfgCreateArea(page 70).  
IMPORTANT  
The OTCfgDuplicateAreafunction has almost no purpose in  
the version of Network Setup described by this  
document. N  
Network Setup Functions  
71  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgDeleteArea  
3
Deletes an area in the Network Setup database.  
OSStatus OTCfgDeleteArea (CfgDatabaseRef dbRef,  
CfgAreaID areaID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
area that is to be deleted. If the area specified by areaIDdoes not  
exist, OTCfgDeleteAreareturns kCfgErrAreaNotFound.  
function result A value of noErrindicates that OTCfgDeleteAreareturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgDeleteAreafunction removes the specified area from the database.  
IMPORTANT  
The OTCfgDeleteAreafunction has almost no purpose in the  
version of Network Setup described by this document. N  
Managing Entities  
3
Use the following functions to create, modify, and delete entities within an area:  
I OTCfgIsSameEntityRef(page 76) determines whether two entity references are  
the same.  
I OTCfgCreateEntity(page 76) creates an entity in an area.  
I OTCfgDeleteEntity(page 78) deletes an entity from an area.  
72  
Network Setup Functions  
 
     
C H A P T E R  
3
Network Setup Reference  
entity.  
I OTCfgGetEntityLogicalName(page 79) gets the name of an entity.  
I OTCfgGetEntityName(page 80) gets the name of an entity.  
I OTCfgSetEntityName(page 81) sets the name of an entity in an area.  
I OTCfgGetEntityArea(page 82) gets the area ID of an entity.  
I OTCfgChangeEntityArea(page 82) changes an entity’s area.  
OTCfgGetEntitiesCount  
3
Obtains the number of entities of a specified class and type in an area.  
OSStatus OTCfgGetEntitiesCount (CfgDatabaseRef dbRef,  
CfgAreaID areaID,  
CfgEntityClass entityClass,  
CfgEntityType entityType,  
ItemCount* itemCount);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a value of type CfgAreaID(page 98) that identifies the  
area that is to be searched. If the area specified by areaIDdoes  
kCfgErrAreaNotFound.  
entityClass  
entityType  
On input, a value of type CfgEntityClassthat specifies the class  
that is to be matched. To specify all classes, set entityClassto  
Classes and Types” (page 104).  
On input, a value of type CfgEntityTypethat specifies the type  
that is to be matched. To specify all types, set entityTypeto  
kCfgTypeAnyEntity. For a list of possible types, see “Entity  
Classes and Types” (page 104).  
Network Setup Functions  
73  
 
   
C H A P T E R  
3
Network Setup Reference  
itemCount  
itemCountcontains the number of entities that matched the  
specified class and type.  
function result A value of noErrindicates that OTCfgGetEntitiesCountreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetEntitiesCountfunction obtains the number of entities of the  
specified class and type in the specified area. With the number of entities, you  
can call OTCfgGetEntitiesList(page 74) to get the list of entities in the area.  
OTCfgGetEntitiesList  
3
Obtains information about entities in an area.  
OSStatus OTCfgGetEntitiesList (CfgDatabaseRef dbRef,  
CfgAreaID areaID,  
CfgEntityClass entityClass,  
CfgEntityType entityType,  
ItemCount* itemCount,  
CfgEntityRef entityRef[],  
CfgEntityInfo entityInfo[]);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a value of type CfgAreaID(page 98) that identifies the  
area that is to be searched. If the area specified by areaIDdoes  
kCfgErrAreaNotFound.  
entityClass  
On input, a value of type CfgEntityClassthat specifies the class  
that is to be matched. To specify all classes, set entityClassto  
kCfgClassAnyEntity. For a list of possible classes, see “Entity  
Classes and Types” (page 104).  
74  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
entityType  
itemCount  
On input, a value of type CfgEntityTypethat specifies the type  
kCfgTypeAnyEntity. For a list of possible types, see “Entity  
Classes and Types” (page 104).  
On input, a pointer to a value of type ItemCountthat specifies  
the number of entities to list. Call OTCfgGetEntitiesCount  
(page 73) to get the current number of entities in the area  
represented by areaID. On output, itemCountpoints to the  
number of entities for which information was actually obtained.  
entityRef  
On input, an array of elements of type CfgEntityRef(page 99)  
that is large enough to hold the number of entity references  
specified by itemCount, or NULLif you do not want to receive  
entity references. If not NULLon input, each element of the  
entityRefarray corresponds to an element of the entityInfo  
array on output.  
entityInfo  
On input, an array of CfgEntityInfo(page 99) structures that is  
specified by itemCount, or NULLif you do not want to receive  
CfgEntityInfostructures.  
function result A value of noErrindicates that OTCfgGetEntitiesListreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetEntitiesListfunction obtains an array of entity references, each of  
information structures, each of which contains information about its respective  
entity. The information includes the entity’s class, type, user-visible name, and  
icon.  
You can use the entity reference to call other Network Setup functions, such as  
OTCfgOpenPrefs(page 84).  
Network Setup Functions  
75  
 
C H A P T E R  
3
Network Setup Reference  
OTCfgIsSameEntityRef  
3
Compares two entity references.  
Boolean OTCfgIsSameEntityRef (const CfgEntityRef* entityRef1,  
const CfgEntityRef* entityRef2,  
Boolean ignoreArea);  
entityRef1  
entityRef2  
ignoreArea  
On input, a pointer to a value of type CfgEntityRef(page 99) for  
one of the entity references that is to be compared.  
On input, a pointer to a value of type CfgEntityRef(page 99) for  
the second entity reference that is to be compared.  
On input, a Boolean value. If ignoreAreais kCfgIgnoreArea,  
OTCfgIsSameEntityRefignores the area ID when comparing  
entityRef1and entityRef2. If ignoreAreais kCfgDontIgnoreArea,  
OTCfgIsSameEntityRefdoes not ignore the area ID when  
comparing entityRef1and entityRef2.  
function result TRUEif the entity references represent the same entity; FALSEif  
the entity references represent different entities.  
DISCUSSION  
The OTCfgIsSameEntityReffunction determines whether two entity references  
represent the same area. For a discussion of the circumstances in which calling  
OTCfgIsSameEntityRefis particularly useful, see “Areas and Sets” (page 48).  
OTCfgCreateEntity  
3
Creates an entity in an area.  
OSStatus OTCfgCreateEntity (CfgDatabaseRef dbRef,  
CfgAreaID areaID,  
CfgEntityInfo* entityInfo,  
CfgEntityRef* entityRef);  
76  
Network Setup Functions  
 
         
C H A P T E R  
3
Network Setup Reference  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
areaID  
On input, a value of type CfgAreaID(page 98) that identifies the  
area in which the entity is to be created. If the area specified by  
areaIDis not writable, OTCfgCreateEntityreturns the error  
kCfgErrLocked. If the area specified by areaIDdoes not exist,  
OTCfgCreateEntityreturns the error kCfgErrAreaNotFound.  
entityInfo  
entityRef  
On input, a pointer to a CfgEntityInfo(page 99) structure that  
specifies the class, type, user-visible name, and icon for the  
entity that is to be created. If an entity of the specified name  
already exists, OTCfgCreateEntityreturns the error  
kCfgErrEntityAlreadyExists.  
On output, entityRefpoints to an entity reference for the  
created reference.  
function result A value of noErrindicates that OTCfgCreateEntityreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgCreateEntityfunction creates an entity in the area specified by areaID  
with the class, type, user-visible name, and icon specified by the entityInfo  
parameter.  
The area represented by areaIDmust have been opened by calling  
OTCfgBeginAreaModifications(page 63).  
The OTCfgCreateEntityfunction returns a reference to the created entity that can  
be passed as a parameter to other Network Setup functions, such as  
OTCfgOpenPrefs(page 84).  
Network Setup Functions  
77  
 
C H A P T E R  
3
Network Setup Reference  
OTCfgDeleteEntity  
3
Deletes the specified entity.  
OSStatus OTCfgDeleteEntity (CfgDatabaseRef dbRef,  
const CfgEntityRef* entityRef);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
entityRef  
On input, a pointer to a value of type CfgEntityRef(page 99)  
representing the entity that is to be deleted. If entityRef  
represents an entity that does not reside in an area that is open  
for writing, OTCfgDeleteEntityreturns the error  
by entityRefdoes not exist, OTCfgDeleteEntryreturns the error  
kCfgErrEntityNotFound.  
function result A value of noErrindicates that OTCfgDeleteEntityreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgDeleteEntityfunction deletes the specified entity.  
OTCfgDuplicateEntity  
3
Copies the contents of one entity to another entity.  
OSStatus OTCfgDuplicateEntity (CfgDatabaseRef dbRef,  
const CfgEntityRef* entityRef,  
const CfgEntityRef* newEntityRef);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
78  
Network Setup Functions  
 
           
C H A P T E R  
3
Network Setup Reference  
entityRef  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that identifies the entity reference that is to be duplicated. If the  
entity represented by entityRefdoes not exist,  
OTCfgDuplicateEntryreturns the error kCfgErrEntityNotFound.  
newEntityRef On input, a pointer to a value of type CfgEntityRef(page 99)  
that identifies the entity that is to be overwritten by the contents  
reside in an area that is open for writing, OTCfgDuplicateEntity  
returns the error kCfgErrAreaNotOpenor kCfgErrLocked.  
function result A value of noErrindicates that OTCfgDuplicateEntityreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgDuplicateEntityfunction copies the contents of the entity specified by  
entityRefto the entity specified by newEntityRef. Any data stored in  
newEntityRefbefore OTCfgDuplicateEntityis called is overwritten by the  
contents of entityRefwhen OTCfgDuplicateEntityreturns.  
OTCfgGetEntityLogicalName  
3
Obtains the user-visible name of an entity.  
OSStatus OTCfgGetEntityLogicalName( CfgDatabaseRef dbRef,  
const CfgEntityRef *entityRef,  
Str255 entityName );  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
entityRef  
entityName  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that identifies the entity whose name is to be obtained. To obtain  
the reference for an entity, call OTCfgGetEntitiesList(page 74).  
On input, a value of type Str255. On output, entityNamecontains  
the user-visible name of the entity represented by entityRef.  
Network Setup Functions  
79  
 
   
C H A P T E R  
3
Network Setup Reference  
function result A value of noErrindicates that OTCfgGetEntityLogicalName  
returned successfully. For a list of other possible result codes,  
see “Result Codes” (page 110).  
DISCUSSION  
The OTCfgGetEntityLogicalNamefunction obtains the user-visible name of the  
entity represented by entityRef.  
Note  
The OTCfgGetEntityLogicalNamefunction is available in  
Network Setup 1.2 and later. If  
OTCfgGetEntityLogicalName is not available, you can get  
the user-visible name of an entity by calling OTCfgGetPrefs  
(page 86) and specifying kOTCfgUserVisibleNamePrefas the  
preference to get. N  
OTCfgGetEntityName  
3
Obtains the name of an entity.  
void OTCfgGetEntityName (const CfgEntityRef *entityRef,  
Str255 entityName);  
entityRef  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that identifies the entity whose name is to be obtained. To obtain  
the reference for an entity, call OTCfgGetEntitiesList(page 74).  
entityName  
On input, a value of type Str255. On output, entityNamecontains  
the name of the entity represented by entityRef.  
function result None.  
DISCUSSION  
The OTCfgGetEntityNamefunction obtains the name of the entity represented by  
entityRef.  
80  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
L
W AR N I N G  
The OTCfgGetEntityNamefunction does not return the  
user-visible name of the entity. Instead, OTCfgGetEntityName  
returns an internal name in entityName. To get the  
user-visible name, call OTCfgGetPrefs(page 86) passing  
kOTCfgUserVisibleNamePrefin the prefsTypeparameter or  
call OTCfgGetEntityLogicalName(page 79) if that function is  
available. L  
OTCfgSetEntityName  
3
Sets the user-visible name of an entity.  
OSStatus OTCfgSetEntityName (CfgDatabaseRef dbRef,  
const CfgEntityRef* entityRef,  
ConstStr255Param entityName,  
CfgEntityRef* newEntityRef);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
OTCfgOpenDatabase(page 58).  
entityRef  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that represents the entity whose name is to be set. To obtain the  
entity reference for an entity, call OTCfgGetEntitiesList  
(page 74). If entityRefdoes not refer to a valid entity,  
OTCfgSetEntityNamereturns the error kCfgEntityNotFoundErr.  
entityName  
On input, a value of type ConstStr255Paramthat specifies the  
new user-visible name for the entity.  
newEntityRef On input, a pointer to a value of type CfgEntityRef(page 99).  
represents the renamed entity. Your application should use  
newEntityReffor future references to the renamed entity.  
function result A value of noErrindicates that OTCfgSetEntityNamereturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
Network Setup Functions  
81  
 
     
C H A P T E R  
3
Network Setup Reference  
DISCUSSION  
The OTCfgSetEntityNamefunction sets the user-visible name of the specified  
entity and returns a new entity reference for the renamed entity.  
OTCfgGetEntityArea  
3
Obtains the area ID of an entity.  
void OTCfgGetEntityArea (const CfgEntityRef *entityRef,  
CfgAreaID *areaID);  
entityRef  
areaID  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that identifies the entity reference whose area is to be obtained.  
To obtain the entity reference for an entity, call  
OTCfgGetEntitiesList(page 74).  
On input, a pointer to a value of type CfgAreaID(page 98). On  
output, areaIDpoints to the area ID of the entity represented by  
entityRef.  
function result None.  
DISCUSSION  
The OTCfgGetEntityAreafunction obtains the area ID of the entity represented  
by entityRef.  
OTCfgChangeEntityArea  
3
Changes the area of an entity.  
void OTCfgChangeEntityArea (CfgEntityRef *entityRef,  
CfgAreaID newAreaID);  
82  
Network Setup Functions  
 
       
C H A P T E R  
3
Network Setup Reference  
entityRef  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that represents the entity reference whose area is to be changed.  
To obtain the entity reference for an entity, call  
OTCfgGetEntitiesList(page 74) or use the entity reference  
returned by a Network Setup function that creates an entity.  
newAreaID  
On input, a value of type CfgAreaID(page 98) that specifies the  
new area ID for the specified entity.  
function result None.  
DISCUSSION  
The OTCfgChangeEntityAreafunction changes the area ID of the specified entity.  
This function does not actually move the entity. Instead, it changes the entity  
reference to point to the same entity in the area specified by newAreaID.  
Managing Preferences  
3
entity:  
I OTCfgOpenPrefs(page 84) opens an entity so that its preferences can be  
accessed.  
I OTCfgClosePrefs(page 85) closes an entity.  
I OTCfgGetPrefsSize(page 85) gets the size of a preference.  
I OTCfgGetPrefs(page 86) gets the value of a preference.  
I OTCfgSetPrefs(page 87) sets the value of a preference.  
I OTCfgGetPrefsTOCCount(page 88) gets the number of preferences in an entity.  
I OTCfgGetPrefsTOC(page 89) gets a list of a preferences in an entity.  
I OTCfgGetDefault(page 90) gets the default value for a preference.  
I OTCfgDeletePrefs(page 90) deletes a preference from an entity.  
I OTCfgGetTemplate(page 91) gets a preference’s template.  
Network Setup Functions  
83  
 
 
C H A P T E R  
3
Network Setup Reference  
OTCfgOpenPrefs  
3
Opens an entity so that its preferences can be accessed.  
OSStatus OTCCfgOpenPrefs (CfgDatabaseRef dbRef,  
const CfgEntityRef* entityRef,  
Boolean writer,  
CfgEntityAccessID* accessID);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
entityRef  
On input, a pointer to a value of type CfgEntityRef(page 99)  
that represents the entity whose preferences are to be read or  
written. If the entity does not exist, OTCfgOpenPrefsreturns the  
error kCfgErrEntityNotFound.  
writer  
On input, a Boolean value. If writeris TRUE, the entity  
calling OTCfgBeginAreaModifications(page 63); otherwise,  
OTCfgOpenPrefsreturns the error kCfgErrLocked. If writer is  
area [opened by calling OTCfgBeginAreaModifications(page 63)  
or OTCfgOpenArea(page 61)]; otherwise, OTCfgOpenPrefsreturns  
the error kCfgErrAreaNotOpen.  
accessID  
(page 100). On output, use accessIDin subsequent calls to get  
and set preferences.  
function result A value of noErrindicates that OTCfgOpenPrefsreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgOpenPrefsfunction opens the specified entity so that your application  
can get or set the value of the preferences the entity contains.  
If the value of the writerparameter is TRUE, you can set preferences as well as  
get preferences; otherwise, you can only get preferences.  
84  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgClosePrefs  
3
Closes an entity.  
OSStatus OTCCfgClosePrefs (CfgEntityAccessID accessID);  
accessID  
obtained by previously calling OTCfgOpenPrefs(page 84), that  
identifies the entity that is to be closed.  
function result A value of noErrindicates that OTCfgClosePrefsreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgClosePrefsfunction closes the specified entity.  
OTCfgGetPrefsSize  
3
Gets the size of a preference.  
OSStatus OTCCfgGetPrefsSize (CfgEntityAccessID accessID.  
OSType prefsType,  
ByteCount * length);  
accessID  
On input, a value of type CfgEntityAccessID(page 100),  
obtained by previously calling OTCfgOpenPrefs(page 84), that  
identifies the entity containing the preference whose size is to be  
obtained.  
prefsType  
length  
On input, a value of type prefsType that identifies the type of  
the preference whose size is to be obtained.  
On input, a pointer to a value of type ByteCount. On output,  
lengthcontains the size in bytes of the preference specified by  
prefsType.  
Network Setup Functions  
85  
 
       
C H A P T E R  
3
Network Setup Reference  
function result A value of noErrindicates that OTCfgGetPrefsSizereturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetPrefsSizefunction gets the size in bytes of the preference specified  
by prefsTypein the entity represented by accessID.  
For variable-length preferences, you should call OTCfgGetPrefsSizeto get the  
size of a preference before it calls OTCfgGetPrefs(page 86) to get the value of  
that preference.  
OTCfgGetPrefs  
3
Gets the value of a preference.  
OSStatus OTCCfgGetPrefs (CfgEntityAccessID accessID.  
OSType prefsType,  
void* data,  
ByteCount length);  
accessID  
On input, a value of type CfgEntityAccessID(page 100),  
identifies the entity containing the preference whose value is to  
be obtained.  
prefsType  
data  
On input, a value of type OSType that identifies the preference  
whose value is to be obtained. See“Protocol Constants and  
Other Data Types” (page 159) for protocol-specific preferences.  
On input, a pointer to the buffer into which the value of the  
preference is to be placed. On output, datacontains the value of  
the preference specified by prefsType.  
length  
On input, a value of type ByteCountthat is the size in bytes of  
the buffer pointed to by data.  
function result A value of noErrindicates that OTCfgGetPrefsreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
86  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
DISCUSSION  
The OTCfgGetPrefsfunction gets the value of the preference specified by  
prefsTypein the entity represented by accessID and stores it in data.  
Before calling OTCfgGetPrefs, you may call OTCfgGetPrefsSize(page 85) to  
obtain the size of the entity so that you can allocate a dataparameter of the  
appropriate size.  
If the dataparameter is too small to hold the value, OTCfgGetPrefsstores as  
much of the value in dataas possible and returns the error  
kCFGErrDataTruncated.  
OTCfgSetPrefs  
3
Sets the value of a preference.  
OSStatus OTCCfgSetPrefs (CfgEntityAccessID accessID.  
OSType prefsType,  
const void* data,  
ByteCount length);  
accessID  
On input, a value of type CfgEntityAccessID(page 100),  
obtained by previously calling OTCfgOpenPrefs(page 84). The  
entity in which the preference represented by accessIDresides  
must itself reside in an area that has been opened for writing by  
calling OTCfgBeginAreaModifications(page 63).  
prefsType  
On input, a value of type OSType that identifies the preference to  
set. If a preference of the type specified by prefsTypealready  
exists OTCfgSetPrefsoverwrites the value of the preference.  
Otherwise, OTCfgSetPrefscreates the new preference.  
data  
On input, a pointer to the data that is to be set.  
length  
On input, a value of type ByteCountthat contains the length in  
bytes of the data in data.  
function result A value of noErrindicates that OTCfgSetPrefsreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
Network Setup Functions  
87  
 
   
C H A P T E R  
3
Network Setup Reference  
DISCUSSION  
The OTCfgSetPrefsfunction sets the preference represented by prefsTypeto the  
value specified by data.  
The accessIDparameter must have been created by calling OTCfgOpenPrefs  
(page 84) with the writerparameter set to TRUE; otherwise, OTCfgSetPrefs  
returns the error kCfgErrLocked.  
OTCfgGetPrefsTOCCount  
3
Gets the number of preferences in an entity.  
OSStatus OTCfgGetPrefsTOCCount (CfgEntityAccessID accessID.  
ItemCount *itemCount);  
accessID  
On input, a value of type CfgEntityAccessID(page 100),  
obtained by previously calling OTCfgOpenPrefs(page 84) that  
identifies the entity whose preferences are to be counted.  
itemCount  
itemCountcontains the number of preferences in the entity  
represented by accessID.  
function result A value of noErrindicates that OTCfgGetPrefsTOCCountreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetPrefsTOCCountfunction gets the number of preferences in the entity  
represented by accessID.  
You should call OTCfgPrefsTOCCountto find out how many preferences are  
present before calling OTCfgGetPrefsTOC(page 89).  
88  
Network Setup Functions  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgGetPrefsTOC  
3
Gets a list of the preferences in an entity.  
OSStatus OTCfgGetPrefsTOC (CfgEntityAccessID accessID.  
ItemCount* itemCount,  
CfgPrefsHeader prefsTOC[]);  
accessID  
itemCount  
prefsTOC  
On input, a value of type CfgEntityAccessID(page 100),  
obtained by previously calling OTCfgOpenPrefs(page 84) that  
identifies the entity whose preferences are to be obtained.  
On input, a pointer to a value of type ItemCountthat specifies  
the requested number of preferences. On output, itemCount  
contains the number of preferences that were obtained.  
prefsTOCparameter must have enough CfgPrefsHeader  
structures to store all of the preferences in the entity.  
function result A value of noErrindicates that OTCfgGetPrefsTOCreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetPrefsTOCfunction obtains information about the specified number  
preferences in the entity represented by accessIDand stores them in the  
prefsTOCarray.  
Before you call OTCfgPrefsTOC, you must should find out how many preferences  
are available by calling OTCfgGetPrefsTOCCount(page 88).  
L
W AR N I N G  
Early versions of Network Setup do not determine whether  
there is enough space in prefsTOC(as specified on input by  
itemCount) and can write beyond the end of the array. You  
should always call OTCfgGetPrefsTOCCountbefore calling  
OTCfgGetPrefsTOC. When you call OTCfgGetPrefsTOC, set  
itemCountto the value returned by OTCfgGetPrefsTOCCount  
in the itemCountparameter. L  
Network Setup Functions  
89  
 
   
C H A P T E R  
3
Network Setup Reference  
OTCfgGetDefault  
3
Returns a handle containing the default value for a preference.  
Handle OTCfgGetDefault (OSType entityType,  
OSType entityClass,  
OSType prefsType);  
entityType  
entityClass  
prefsType  
On input, a value of type OSTypethat identifies the entity type of  
the default preference that is to be obtained. For possible values,  
see “Entity Classes and Types” (page 104).  
On input, a value of type OSTypethat identifies the entity class of  
the default preference that is to be obtained. For possible values,  
see “Entity Classes and Types” (page 104).  
On input, a value of type OSTypethat identifies the preference  
whose default value is to be obtained.  
function result A handle or NULLif no preference of the specified entity type,  
class, and preference type exists, or if there is not enough  
memory to obtain the handle.  
DISCUSSION  
The OTCfgGetDefaultfunction returns a handle containing the default value for  
a preference of the specified entity, class, and preference type.  
Note  
You are responsible for disposing of the handle that  
OTCfgGetDefaultobtains by calling the Memory Manager  
function DisposeHandle. N  
OTCfgDeletePrefs  
3
Deletes a preference.  
OSStatus OTCfgDeletePrefs (CfgEntityAccessID accessID,  
OSType prefsType);  
90  
Network Setup Functions  
 
         
C H A P T E R  
3
Network Setup Reference  
accessID  
On input, a value of type CfgEntityAccessID(page 100),  
obtained by previously calling OTCfgOpenPrefs(page 84) that  
identifies the entity from which a preference is to be deleted.  
prefsType  
On input, a value of type OSTypethat identifies the preference  
type of the preference that is to be deleted.  
function result A value of noErrindicates that OTCfgDeletePrefsreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgDeletePrefsfunction deletes the preference of the type specified by  
prefsTypefrom the entity specified by accessID.  
Note  
The OTCfgDeletePrefsfunction is available in Network  
Setup version 1.2 and later.  
OTCfgGetTemplate  
3
Gets the default value for a specific preference.  
OSStatus OTCfgGetTemplate(CfgEntityClass entityClass,  
CfgEntityType entityType,  
OSType prefsType,  
void *data,  
ByteCount *dataSize);  
entityClass  
entityType  
prefsType  
On input, a value of type CfgEntityClassthat specifies the class  
of the preference whose default value is to be obtained.  
On input, a value of type CfgEntityTypethat specifies the type of  
the preference whose default value is to be obtained.  
On input, a value of type OSTypethat specifies the preference  
type of the preference whose default value is to be obtained.  
Network Setup Functions  
91  
 
   
C H A P T E R  
3
Network Setup Reference  
data  
On input, a pointer to the buffer into which the default value is  
to be placed. On output, datapoints to the default value. If the  
buffer is too small to hold the default value, OTCfgGetTemplate  
returns as much data as possible and returns the error  
kCFGErrDataTruncated. If you want to get the size of the default  
value but not the default value itself, set data to NULL.  
dataSize  
On input, a pointer to a value of type ByteCount. On output,  
by data. On input, if datais NULL, on output, dataSizepoints to  
the size in bytes of the default value for the specified preference.  
function result A value of noErrindicates that OTCfgGetTemplatereturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgGetTemplatefunction gets the default value for the preference  
identified by the entityClass, entityType, and prefsTypeparameters and stores  
IMPORTANT  
The OTCfgGetTemplatefunction is available in Network  
Setup version 1.2 and later. It returns the same data that  
OTCfgGetDefault(page 90) returns, but the parameters have  
been changed to be consistent with the parameters of other  
Network Setup functions. If you rely on Network Setup 1.2  
or later, call OTCfgGetTemplate. If you need to work with  
earlier versions of Network Setup, you can safely continue  
to call OTCfgGetDefault.  
L
Preference Utilities  
3
Use the following functions to encrypt and decrypt preferences:  
I OTCfgDecrypt(page 93) decrypts data.  
I OTCfgEncrypt(page 93) encrypts data.  
92  
Network Setup Functions  
 
 
C H A P T E R  
3
Network Setup Reference  
OTCfgEncrypt  
3
Encrypts data.  
SInt16 OTCCfgEncrypt (const UInt8 *key.  
UInt8 *data,  
SInt16 dataLen);  
key  
On input, a pointer to a Pascal string containing the encryption  
key. For Remote Access password, the encryption key is a user  
name.  
data  
On input, a pointer to an array of bytes that contains data that is  
to be encrypted. Usually, the data is a password. On output,  
datacontains the encrypted password.  
dataLen  
On input, a value of type SInt16that specifies the number of  
bytes in the data array.  
function result The length of the encrypted data.  
DISCUSSION  
The OTCfgEncryptfunction encrypts the contents of the dataparameter using the  
key specified by the keyparameter. For sample code, see Listing 2-17 in Chapter  
2, “Using Network Setup.”  
Note  
The OTCCfgEncryptfunction is available in Network Setup  
version 1.1 and later. N  
OTCfgDecrypt  
3
Decrypts data.  
SInt16 OTCCfgDecrypt (const UInt8 *key.  
UInt8 *data,  
SInt16 dataLen);  
Network Setup Functions  
93  
 
         
C H A P T E R  
3
Network Setup Reference  
key  
On input, a pointer to a Pascal string containing the encryption  
key. Usually the encryption key is a user name.  
data  
On input, a pointer to an array of bytes containing data that was  
previously encrypted by OTCfgEncrypt(page 93). On output,  
datacontains the decrypted data.  
dataLen  
On input, a value of type SInt16that specifies the length of data.  
function result The length in bytes of the decrypted data.  
DISCUSSION  
The OTCfgDecryptfunction decrypts the contents of the dataparameter using  
the key specified by the keyparameter.  
Note  
The OTCCfgDecryptfunction is available in Network Setup  
version 1.1 and later. N  
3
You can use the following functions to install and remove a notification  
callback:  
I OTCfgInstallNotifier(page 94) installs a notification callback.  
I OTCfgRemoveNotifier(page 96) removes a notification callback.  
OTCfgInstallNotifier  
3
Installs a notification callback.  
OSStatus OTCfgInstallNotifier (CfgDatabaseRef dbRef.  
CfgEntityClass theClass,  
CfgEntityType theType,  
OTNotifyProcPtr notifier,  
void* contextPtr);  
94  
Network Setup Functions  
 
       
C H A P T E R  
3
Network Setup Reference  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
OTCfgOpenDatabase(page 58).  
theClass  
On input, a value of type CfgEntityClassthat specifies the class  
for which the notification callback is to be called. For possible  
Types” (page 104). Constants that define wildcards are valid.  
theType  
On input, a value of type CfgEntityTypethat specifies the type  
for which the notification callback is to be called. For possible  
values, see the constants described in “Entity Classes and  
Types” (page 104). Constants that define wildcards are valid.  
notifier  
On input, a value of type OTNotifyProcPtrthat points to the  
notification callback that is to be installed.  
contextPtr  
On input, a pointer to an arbitrary data type that is passed to the  
notification callback when it is called.  
function result A value of noErrindicates that OTCfgInstallNotifierreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110)  
DISCUSSION  
The OTCfgInstallNotifierfunction installs a notification callback that is called  
when changes to preferences of the specified class and type occur. Calling  
OTCfgInstallNotifierwhen you have already installed a notification callback  
causes the current notification callback to be replaced by the new notification  
callback.  
Note  
The OTCfgInstallNotifierfunction is available in Network  
Setup version 1.0.2 and later. N  
To remove an installed notification callback, call OTCfgRemoveNotifier(page 96).  
Notification callbacks are removed automatically when the database session  
represented by dbRefis closed.  
Network Setup Functions  
95  
 
C H A P T E R  
3
Network Setup Reference  
OTCfgRemoveNotifier  
3
Removes a notification callback.  
OSStatus OTCfgRemoveNotifier (CfgDatabaseRef dbRef.  
CfgEntityClass theClass,  
CfgEntityType theType);  
dbRef  
On input, a value of type CfgDatabaseRef(page 98) that  
represents a database session previously opened by calling  
OTCfgOpenDatabase(page 58).  
theClass  
theType  
On input, a value of type CfgEntityClassspecifying the class  
that was specified when the notification callback was installed.  
On input, a value of type CfgEntityTypespecifying the type that  
was specified when the notification callback was installed.  
function result A value of noErrindicates that OTCfgRemoveNotifierreturned  
successfully. For a list of other possible result codes, see “Result  
Codes” (page 110).  
DISCUSSION  
The OTCfgRemoveNotifierfunction removes the specified notification callback  
that was previously installed by OTCfgInstallNotifier(page 94).  
Note  
The OTCfgRemoveNotifierfunction is available in Network  
Setup version 1.0.2 and later. N  
Notification callbacks are removed automatically when the database session  
represented by dbRefis closed.  
Application-Defined Routines  
3
This section describes the application-defined routine that you can provide:  
I A notification callback routine, which is called when changes occur in the  
Network Setup database.  
96  
Network Setup Functions  
 
     
C H A P T E R  
3
Network Setup Reference  
Notification Callback Routine  
3
Receives notifications of changes to the Network Setup database.  
typedef CALLBACK_API_C( void, OTNotifyProcPtr ) (  
void *contextPtr,  
OTEventCode code,  
OSStatus result,  
void *cookie);  
contextPtr  
code  
A pointer to the untyped value that was specified when you  
called OTCfgInstallNotifier(page 94) to install the notification  
callback routine.  
A value of type OTEventCode.Your notification callback routine  
should ignore callbacks when this is any value other than  
kCfgDatabaseChanged.  
result  
cookie  
A notification-dependent value of type OSStatus. When the  
value of code is kCfgDatabaseChanged, the value of result is  
kCfgErrDatabaseChanged.  
Reserved.  
DISCUSSION  
Your notification callback routine is called at system task time (but not  
necessarily in the context of your application) when a change occurs to the  
database. When your notification callback routine is called, you should reread  
any preferences that were previously read.  
Network Setup Structures and Data Types  
3
This section describes structures used by the Network Setup functions. The  
structures and data types are  
I CfgDatabaseRef(page 98), which refers to an open database session.  
I CfgAreaID(page 98), which identifies an area.  
I CfgEntityRef(page 99), which refers to an open entity.  
Network Setup Structures and Data Types  
97  
 
 
C H A P T E R  
3
Network Setup Reference  
area.  
I CfgEntityAccessID(page 100), which identifies an open preference within an  
entity.  
I CfgPrefsHeader(page 100), which is used to return information about the  
preferences within an entity.  
I CfgSetsStruct(page 101), which stores information about a set entity.  
I CfgSetsElement(page 103), which represents an element in a CfgSetsVector  
(page 103) structure.  
I CfgSetsVector(page 103), which stores references to a set of entities.  
CfgDatabaseRef  
3
A value of type CfgDatabaseRef refers to an open session with the Network  
Setup database.  
typedef struct OpaqueCfgDatabaseRef* CfgDatabaseRef;  
CfgDatabaseRef  
A pointer to an opaque value that identifies the open  
session.  
Call OTCfgOpenDatabase(page 58) to open the database and obtain a value of  
type CfgDatabaseRef. Network Setup requires a value of type CfgDatabaseRefto  
open an area, make changes in an area, list and create entities in an area, and to  
open an entity.  
A CfgDatabaseRefwhose value is NULLis never a valid database reference.  
CfgAreaID  
3
A value of type CfgAreaIDidentifies an area.  
typedef UInt32 CfgAreaID;  
CfgAreaID  
An unsigned 32-bit value that uniquely identifies an area.  
98  
Network Setup Structures and Data Types  
 
     
C H A P T E R  
3
Network Setup Reference  
Network Setup uses a value of type CfgAreaIDto identify the area in which an  
entity resides. For example, a value of type CfgAreaIDis a member of the  
CfgEntityRef(page 99) structure. Use the constant kInvalidCfgAreaID(page 109)  
to determine whether an area ID is valid.  
CfgEntityRef  
3
A CfgEntityRefstructure refers to a specific entity.  
struct CfgEntityRef {  
CfgAreaID fLoc;  
UInt32 fReserved;  
Str255 fID;  
};  
typedef struct CfgEntityRef CfgEntityRef;  
Field descriptions  
fLoc  
The area in which the entity resides.  
Reserved.  
fReserved  
fID  
The entity ID.  
For example, OTCfgCreateEntity(page 76) returns a CfgEntityRefstructure to  
refer to the newly created entity, and OTCfgGetEntitiesList(page 74) returns a  
CfgEntityReffor each entity in an area.  
CfgEntityInfo  
3
The CfgEntityInfostructure stores various attributes of an entity.  
struct CfgEntityInfo {  
CfgEntityClass fClass;  
CfgEntityType fType;  
Str255 fName;  
CfgResourceLocator fIcon;  
};  
typedef struct CfgEntityInfo CfgEntityInfo;  
Network Setup Structures and Data Types  
99  
 
       
C H A P T E R  
3
Field descriptions  
fClass  
The entity’s class. See “Entity Classes and Types”  
fType  
The entity’s type. See “Entity Classes and Types” (page 104)  
for possible values.  
fName  
fIcon  
The entity’s user-visible name.  
The entity’s custom icon. For details, see the definition of  
CfgResourceLocator(page 101).  
CfgEntityInfostructures are used when calling OTCfgCreateEntity(page 76)  
and when calling OTCfgGetEntitiesList(page 74).  
CfgEntityAccessID  
3
A CfgEntityAccessID refers to an open preference.  
typedef void *CfgEntityAccessID;  
CfgEntityAccessID A pointer to an arbitrary data type whose value represents  
an open entity  
Call OTCfgOpenPrefs(page 84) to open an entity and received a value of type  
CfgEntityAccessID. Pass CfgEntityAccessIDas a parameter to OTCfgGetPrefsSize  
(page 85) and then OTCfgGetPrefs(page 86) to get the value of a preference and  
to OTCfgSetPrefs(page 87) to set its value.  
A CfgEntityAccessIDwhose value is NULLis never a valid entity access ID.  
CfgPrefsHeader  
3
The CfgPrefsHeaderstructure is used to return information about preferences in  
an entity.  
struct CfgPrefsHeader {  
UInt16 fSize;  
UInt16 fVersion;  
100  
Network Setup Structures and Data Types  
 
       
C H A P T E R  
3
Network Setup Reference  
OSType fType;  
};  
typedef struct CfgPrefsHeader CfgPrefsHeader;  
Field descriptions  
fSize  
The size in bytes of the preference, not including the  
CfgPrefsHeaderstructure itself.  
fVersion  
fType  
this document.  
An OS type that uniquely identifies the preference within  
the entity.  
To get the CfgPrefsHeaderstructures for an entity, call OTCfgGetPrefsTOC  
(page 89).  
CfgResourceLocator  
3
The CfgResourceLocatorstructure contains a file specification and a resource ID  
for an entity’s custom icon.  
struct CfgResourceLocator {  
FSSpec  
SInt16  
fFile;  
fResID;  
};  
Field descriptions  
fFile  
A file specification.  
A resource ID.  
fResID  
The CfgResourceLocatorstructure is a member of the CfgEntityInfo(page 99)  
structure. Custom icons are currently not displayed, so you should initialize  
this structure to zero for any entities that you create.  
CfgSetsStruct  
3
The CfgSetsStructstructure holds information about a set entity.  
Network Setup Structures and Data Types  
101  
 
       
C H A P T E R  
3
Network Setup Reference  
struct CfgSetsStruct  
{
UInt32 fFlags;  
UInt32 fTimes[ kOTCfgIndexSetsLimit ];  
};  
typedef struct CfgSetsStruct CfgSetsStruct;  
Field descriptions  
fFlags  
Flags for this set. For possible values, see the enumeration  
for the fFlagsfield that follows.  
fTimes  
An array of time stamps used during legacy import and  
export indexed by the enumeration for the fTimesfield that  
follows.  
The following enumerations define bits and masks for the fFlagsfield:  
enum {  
kOTCfgSetsFlagActiveBit = 0  
};  
enum {  
kOTCfgSetsFlagActiveMask = 0x0001  
};  
If the active bit is set, this set entity is the active set. The default area must  
always contain exactly one active set.  
The following enumeration defines values for the fTimesfield:  
enum {  
kOTCfgIndexSetsActive = 0,  
kOTCfgIndexSetsEdit,  
kOTCfgIndexSetsLimit  
};  
Constant descriptions  
kOTCfgIndexSetsActiveThis index yields the time stamp of the active legacy  
preferences file.  
kOTCfgIndexSetsEditSets edit index.  
kOTCfgIndexSetsLimitThis value is defined to allow the declaration of the fTimes  
field of the CfgSetsStruct(page 101) structure.  
102  
Network Setup Structures and Data Types  
 
C H A P T E R  
3
Network Setup Reference  
The preference type for the CfgSetsStructstructure is kOTCfgSetsStructPref,  
which is defined as 'stru'.  
CfgSetsElement  
3
The CfgSetsElementstructure represents an element in a CfgSetsVector  
structure.  
struct CfgSetsElement {  
CfgEntityRef fEntityRef;  
CfgEntityInfo fEntityInfo;  
};  
typedef struct CfgSetsElement CfgSetsElement;  
Field descriptions  
fEntityRef  
An entity reference for the entity to be included in this set.  
fEntityInfo  
A CfgEntityInfo(page 99) structure that describes the  
entity referenced by fEntityRef.  
The fEntityRefentity typically has an area ID that doesn’t match the area of the  
set entity. See the section “Areas and Sets” (page 48) for why this happens and  
how you can work around the mismatch.  
CfgSetsVector  
3
The CfgSetsVectorstructure holds references to a set of entities.  
struct CfgSetsVector  
{
UInt32 fCount;  
CfgSetsElement fElements[1];  
};  
typedef struct CfgSetsVector CfgSetsVector;  
Field descriptions  
fCount  
The number of elements in the set.  
Network Setup Structures and Data Types  
103  
 
       
C H A P T E R  
3
Network Setup Reference  
fElements  
An unbounded array consisting of the number of  
CfgSetsElement(page 103) structures specified by fCount.  
All of the entities in this array are considered to be part of  
the set.  
The preference type for the CfgSetsVectorstructure is kOTCfgSetsVectorPref,  
which is defined as 'vect'.  
Network Setup Constants  
3
The following sections describe the Network Setup constants:  
I “Entity Classes and Types” (page 104)  
I “Common Preference Types” (page 106)  
Entity Classes and Types  
3
Network Setup can distinguish between several classes of entities and several  
types within each class. Using classes allows you to store different types of  
information in the same database. Third-party developers can define additional  
entity classes and types. If you define an entity class or type, it should be  
unique and registered with Developer Technical Support (DTS).  
The following enumeration defines constants for the classes and types for the  
entities defined by Apple Computer:  
enum {  
kOTCfgClassNetworkConnection  
kOTCfgClassGlobalSettings  
kOTCfgClassServer  
kOTCfgTypeGeneric  
kOTCfgTypeAppleTalk  
kOTCfgTypeTCPv4  
= 'otnc',  
= 'otgl',  
= ‘otsv’,  
= 'otan',  
= 'atlk',  
= 'tcp4',  
= 'tcp6',  
= ‘dns ‘,  
= 'ara ',  
= 'dial',  
= 'modm',  
= 'infr',  
kOTCfgTypeTCPv6  
kOTCfgTypeDNS  
kOTCfgTypeRemote  
kOTCfgTypeDial  
kOTCfgTypeModem  
kOTCfgTypeInfrared  
104  
Network Setup Constants  
 
       
C H A P T E R  
3
Network Setup Reference  
kOTCfgClassSetOfSettings  
kOTCfgTypeSetOfSettings  
};  
= 'otsc',  
= 'otst',  
Constant descriptions  
kOTCfgClassNetworkConnection  
The class code for network connection entities.  
kOTCfgClassGlobalSettings  
The class code global protocol entities.  
kOTCfgClassServer The class code for server setting entities.  
kOTCfgTypeGeneric The type code for non-specific entities.  
kOTCfgTypeAppleTalkThe type code for AppleTalk entities.  
kOTCfgTypeTCPv4  
The type code for version 4 of the Transmission Control  
Protocol/Internet Protocol (TCP/IP) entities.  
kOTCfgTypeTCPv6  
The type code for TCP/IP version 6 entities.  
kOTCfgTypeRemote The type code for Apple Remote Access (ARA) entities.  
kOTCfgTypeDial  
kOTCfgTypeModem  
The type code for Dial Assist entities.  
The type code for Modem entities.  
kOTCfgTypeInfrared The type code for Infrared entities.  
kOTCfgClassOfSettingsThe class code for set entities.  
kOTCfgSetOfSettingsThe type code for set entities.  
kOTCfgTypeDNS  
The type code for Domain Name System (DNS) entities.  
Wildcard Classes and Types  
3
The following enumeration defines wildcard values for matching or not  
matching entity classes and entity types:  
enum {  
kCfgClassAnyEntity  
kCfgClassUnknownEntity  
kCfgTypeAnyEntity  
= '****',  
= '????',  
= '****',  
= '????'  
kCfgTypeUnknownEntity  
};  
Network Setup Constants  
105  
 
 
C H A P T E R  
3
Network Setup Reference  
Constant descriptions  
kCfgClassAnyEntity Matches the class type for any entity. This constant is  
typically used when calling OTCfgGetEntitiesCount  
kCfgClassUnknownEntityDoes not match the class type for any entity. Use this  
constant as a “NULL” equivalent.  
kCfgTypeAnyEntity Matches the type for any entity. This constant is typically  
used when calling OTCfgGetEntitiesCount(page 73) and  
OTCfgGetEntitiesList(page 74).  
kCfgTypeUnknownEntityDoes not match the entity type for any entity. Use this  
constant as a “NULL” equivalent.  
Common Preference Types  
3
This section describes preferences that are used by many different protocols. For  
protocol-specific preferences, see Chapter 4, “Network Setup Protocol  
Structures and Data Types.”  
Per-connection Preference Types  
3
The following enumeration defines per-connection preference types:  
enum  
{
kOTCfgUserVisibleNamePref  
kOTCfgVersionPref  
= 'pnam',  
= 'cvrs',  
= 'port',  
= 'prot',  
= 'pwrd',  
= 'opts',  
= ‘free’  
kOTCfgPortUserVisibleNamePref  
kOTCfgProtocolUserVisibleNamePref  
kOTCfgAdminPasswordPref  
kOTCfgProtocolOptionsPref  
kCfgFreePref  
};  
Constant descriptions  
kOTCfgUserVisibleNamePref  
Each connection entity has a preference of this type that  
contains the user-visible name of the entity as a Pascal  
string  
106  
Network Setup Constants  
 
       
C H A P T E R  
3
Network Setup Reference  
kOTCfgVersionPref Some protocols store the version of the protocol in this  
preference. Typically, this preference is a UInt16whose  
value is 1.  
kOTCfgPortUserVisibleNamePref  
Some protocols use this preference to store the user-visible  
name of the port over which the protocol is running as a  
Pascal string.  
kOTCfgProtocoltUserVisibleNamePref  
Some protocols store a user-visible description of the  
protocol in this preference as a C string. For TCP/IP the  
value of this preference is “tcp”. For AppleTalk, the value  
of this preference is “ddp”.  
kOTCfgAdminPasswordPref  
This preference is not documented.  
kOTCfgProtocolOptionsPref  
Many protocols use this preference (a UInt32) to store  
protocol-specific flags.  
kCfgFreePref  
A dummy preference type used for free blocks in an entity.  
Global Preference Types  
3
The following enumeration defines global preference types:  
enum  
{
kOTCfgUserModePref  
= 'ulvl',  
= 'wpos',  
kOTCfgPrefWindowPositionPref  
};  
Constant descriptions  
kOTCfgUserModePref Preference type for the user mode preference for TCP/IP  
and AppleTalk only.  
kOTCfgPrefWindowPositionPref  
Preference type for the location (in global coordinates) of  
the control panel window for TCP/IP, AppleTalk, and  
Infrared.  
Network Setup Constants  
107  
 
 
C H A P T E R  
3
Network Setup Reference  
Set Entity Preference Types  
3
The following enumeration defines preference types for set entities:  
enum {  
kOTCfgSetsStructPref= 'stru',  
kOTCfgSetsVectorPref= 'vect',  
};  
Constant descriptions  
kOTCfgSetsStructPrefPreference type for the CfgSetsStruct(page 101) structure.  
kOTCfgSetsVectorPrefPreference type for the CfgSetsVector(page 103) structure.  
Backward Compatibility Preference Types  
3
The following enumeration defines per-connection backward compatibility  
preference types:  
enum  
{
kOTCfgCompatNamePref  
= 'cnam',  
= 'resn',  
kOTCfgCompatResourceNamePref  
};  
These preferences are used by the Network Setup backward compatibility  
mechanism to ensure an accurate conversion between legacy preference files  
and the Network Setup database.  
Global Backward Compatibility Preference Types  
3
The following enumeration defines global backward compatibility preference  
types:  
enum  
{
kOTCfgCompatSelectedPref  
kOTCfgCompatResourceIDPref  
= 'ccfg',  
= 'resi',  
};  
108  
Network Setup Constants  
 
     
C H A P T E R  
3
Network Setup Reference  
These preferences are used by the Network Setup backward compatibility  
mechanism to ensure an accurate conversion between legacy preference files  
and the Network Setup database.  
OTCfgUserMode Preference  
3
For most control panels that support a concept of “user mode,” the  
OTCfgUserModepreference holds (or is used as a field in another preference to  
hold) the current user mode as a UInt16. The exceptions are the ARA and  
Modem control panels, where the user mode is stored as a UInt32.  
enum unsigned short OTCfgUserMode  
{
kOTCfgBasicUserMode  
kOTCfgAdvancedUserMode = 2,  
kOTCfgAdminUserMode = 3,  
= 1,  
};  
typedef UInt32 OTCfgUserMode32;  
Constant descriptions  
kOTCfgBasicUserMode  
Basic user mode.  
kOTCfgAdvancedUserMode  
Advanced user mode.  
kOTCfgAdminUserMode  
Administration user mode. This mode is used by the  
control panel at runtime but is never valid in a preference.  
It is defined here for completeness only.  
Invalid Area ID  
3
The constant kInvalidCfgAreaIDrepresents an invalid area ID.  
Network Setup Constants  
109  
 
       
C H A P T E R  
3
Network Setup Reference  
Result Codes  
3
The result codes specific to Network Setup are listed here. Network Setup  
functions can also return system error codes, which do not appear in this list.  
kCfgErrDatabaseChanged  
–3290  
The database has changed  
since the last call. Close  
and reopen the database.  
The specified area does not  
exist.  
kCfgErrAreaNotFound  
–3291  
–3292  
–3293  
–3294  
–3295  
–3296  
–3297  
–3298  
kCfgErrAreaAlreadyExists  
kCfgErrAreaNotOpen  
The specified area already  
exists.  
The specified area is not  
open.  
kCfgErrConfigLocked  
The specified area is  
locked. Try again later.  
An entity of the specified  
name does not exist.  
An entity of the specified  
name already exists.  
A record of the specified  
type does not exist.  
Data was truncated  
because the read buffer is  
too small.  
kCfgErrEntityNotFound  
kCfgErrEntityAlreadyExists  
kCfgErrPrefsTypeNotFound  
kCfgErrDataTruncated  
kCfgErrFileCorrupted  
–3299  
The database is corrupted.  
110  
Result Codes  
 
   
C
H
A
P
T
E
R
4
Figure 4-0  
Listing 4-0  
Table 4-0  
Network Setup  
Protocol Structures and  
Data Types  
4
This chapter describes the structures and data types for protocols provided by  
Apple Computer.  
Protocol Structures  
4
This section describes the structures that organize the information in the  
Network Setup database.  
I The section “TCP/IP Structures” (page 111) describes the structures used by  
TCP/IP preferences.  
I The section “Apple Remote Access Structures” (page 122) describes the  
structures used by Apple Remote Access (ARA) preferences.  
modem preferences.  
I The section “AppleTalk Structures” (page 144) describes the structures used  
by AppleTalk preferences.  
I The section “Infrared Structures” (page 158) describes the structures used by  
Infrared preferences.  
TCP/IP Structures  
4
This section describes structures that store TCP/IP preferences. The structures  
are  
I OTCfgTCPInterfacesUnpacked(page 112) stores information about the  
configured TCP/IP interfaces in unpacked format.  
Protocol Structures  
111  
 
       
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
I OTCfgTCPInterfacesPacked(page 114) stores information about the configured  
I OTCfgTCPInterfacesPackedPart(page 114) is a member of the  
OTCfgTCPInterfacesPacked(page 114) structure that stores port, module, and  
framing information for TCP/IP interfaces in packed format.  
I OTCfgTCPDHCPLeaseInfo(page 115) stores information about a DHCP lease.  
I OTCfgTCPLocks(page 116) stores information about whether a preference is  
locked.  
I OTCfgTCPRoutersList(page 119) stores an array of OTCfgTCPRoutersListEntry  
(page 119) structures.  
I OTCfgTCPRoutersListEntry(page 119) stores the IP address of the router that  
I OTCfgTCPSearchDomains(page 120) stores the list of domains that are searched  
after the implicit search domains.  
I OTCfgTCPSearchList(page 120) stores DNS configuration information.  
I OTCfgTCPUnloadAttr(page 121) defines values that indicate when TCP/IP is  
loaded.  
OTCfgTCPInterfacesUnpacked  
4
The OTCfgTCPInterfacesUnpackedstructure stores information about the  
configured TCP/IP interfaces in unpacked format. See Listing 2-16 in Chapter 2,  
“Using Network Setup,” for sample code that packs and unpacks this structure.  
IMPORTANT  
You must pack this structure before you write it to the  
database and you must unpack this structure after you  
reading it from the database. L  
struct OTCfgTCPInterfacesUnpacked {  
UInt16  
UInt8  
fCount;  
pad1;  
OTCfgTCPConfigMethodfConfigMethod;  
112  
Protocol Structures  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
InetHost  
InetHost  
Str32  
fIPAddress;  
fSubnetMask;  
fAppleTalkZone;  
pad2;  
UInt8  
UInt8  
path[kMaxPortNameSize];  
module[kMaxModuleNameSize];  
framing;  
UInt8  
UInt32  
};  
Field descriptions  
fCount  
Transport.  
pad1  
A pad byte. Remove this pad byte when you pack this  
structure.  
fConfigMethod  
The configuration method. For possible values, see the  
section OTCfgTCPConfigMethod(page 162).  
fIPAddress  
The IP address that has been assigned to this interface.  
The subnet mask.  
fSubnetMask  
fAppleTalkZone  
The AppleTalk zone for this interface. Remove trailing  
bytes when you pack this structure.  
pad2  
A pad byte. Remove this pad byte when you pack this  
structure.  
path  
The name of the port over which this interface  
communicates.  
module  
framing  
The name of the module that controls the port over which  
this interface communicates.  
Ethernet framing options. Constants are defined in the file  
“OpenTransportProviders.h,” an OpenTransport header  
file.  
The preference type for OTCfgTCPInterfacesUnpackedis  
kOTCfgTCPInterfacesPref, which is defined as 'iitf'.  
Protocol Structures  
113  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgTCPInterfacesPacked  
4
The OTCfgTCPInterfacesPackedstructure stores information about the  
configured TCP/IP interfaces in packed format. See Listing 2-16 in Chapter 2,  
“Using Network Setup,” for sample code that packs and unpacks this structure.  
IMPORTANT  
You must pack this structure before you write it to the  
database and you must unpack this structure after you  
reading it from the database. L  
struct OTCfgTCPInterfacesPacked {  
UInt16 fCount;  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
fConfigMethod;  
fIPAddress[4];  
fSubnetMask[4];  
fAppleTalkZone[256];  
part[sizeof(OTCfgTCPInterfacesPackedPart)];  
};  
Field descriptions  
fCount  
A value that is always 1 in the current versions of Open  
Transport.  
fConfigMethod  
The configuration method. For possible values, see  
OTCfgTCPConfigMethod(page 162).  
fIPAddress  
The IP address that has been assigned to this interface.  
The subnet mask.  
fSubnetMask  
fAppleTalkZone  
The AppleTalk zone for this interface. Remove trailing  
bytes when you pack this structure.  
part  
A OTCfgTCPInterfacesPackedPart(page 114) structure  
containing port, module, and framing information.  
OTCfgTCPInterfacesPackedPart  
4
The OTCfgTCPInterfacesPackedPartstructure is a member of the  
OTCfgTCPInterfacesPacked(page 114) structure and stores port, module and  
framing information about the configured TCP/IP interfaces.  
114  
Protocol Structures  
 
           
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
struct OTCfgTCPInterfacesPackedPart  
{
UInt8  
UInt8  
path[kMaxPortNameSize];  
module[kMaxModuleNameSize];  
UInt32 framing;  
};  
Field descriptions  
path  
The name of the port over which this interface  
communicates.  
module  
The name of the module that controls the port over which  
this interface communicates.  
framing  
Ethernet framing options. Constants are defined in the file  
“OpenTransportProviders.h,” an Open Transport header  
file.  
OTCfgTCPDHCPLeaseInfo  
4
The OTCfgTCPLeaseDHCPInfostructure stores information about the DHCP lease  
for an interface.  
struct OTCfgTCPDHCPLeaseInfo  
{
InetHost  
InetHost  
UInt32  
ipIPAddr;  
ipConfigServer;  
ipLeaseGrantTime;  
ipLeaseExpirationTime;  
UInt32  
};  
Field descriptions  
ipIPAddr  
The IP address that has been assigned.  
The IP address of the DHCP server.  
ipConfigServer  
ipLeaseGrantTime The time at which the lease was acquired. The time is in  
seconds as returned by GetDateTime.  
ipLeaseExpirationTime  
The time at which the lease expires. The time is in seconds  
as returned by GetDateTime.  
Protocol Structures  
115  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
The preference type for OTCfgTCPLeaseDHCPInfois kOTCfgTCPDHCPLeaseInfoPref,  
which is defined as 'dclt'.  
OTCfgTCPDNSServersList  
4
The OTCfgTCPDNSServersListstructure stores the list of name servers that have  
been configured for an interface.  
struct OTCfgTCPDNSServersList  
{
UInt16  
fCount;  
InetHost  
fAddressesList[1];  
};  
Field descriptions  
fCount  
The number of IP addresses in the list.  
fAddressesList  
An unbounded array containing the IP addresses of name  
servers.  
The preference type for OTCfgTCPDNSServersListis  
kOTCfgTCPDNSServersListPref, which is defined as 'idns'.  
OTCfgTCPLocks  
4
The OTCfgTCPLocksstructure stores information about whether a preference has  
been locked by the administration mode of the control panel.  
struct OTCfgTCPLocks  
{
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
pad1;  
lockConnectViaPopup;  
pad2;  
lockConfigurePopup;  
pad3;  
lockAppleTalkZone;  
pad4;  
lockIPAddress;  
116  
Protocol Structures  
 
           
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
UInt8  
pad5;  
lockLocalDomainName;  
pad6;  
lockSubnetMask;  
pad7;  
lockRoutersList;  
pad8;  
lockDNSServersList;  
pad9;  
lockAdminDomainName;  
pad10;  
lockSearchDomains;  
pad11;  
lockUnknown;  
pad12;  
lock8023;  
pad13;  
lockDHCPClientID;  
pad14;  
};  
Field descriptions  
pad1  
Always zero.  
lockConnectViaPopup  
Set to TRUEto lock the Connect Via popup menu.  
pad2  
Always zero.  
lockConfigurePopup Set to TRUEto lock the Configure popup menu.  
Always zero.  
pad3  
lockAppleTalkZone Set to TRUEto lock the AppleTalk zone that appears when  
the TCP/IP control panel is configured for MacIP.  
pad4  
Always zero.  
lockIPAddress  
pad5  
Set to TRUEto lock the IP address.  
Always zero.  
lockLocalDomainName  
Set to TRUEto lock the starting domain address.  
Always zero.  
pad6  
lockSubnetMask  
pad7  
Set to TRUEto lock the “Subnet mask” text field.  
Always zero.  
Protocol Structures  
117  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
lockRoutersList  
pad8  
Set to TRUEto lock the “Router address” text field.  
Always zero.  
lockDNSServersList Set to TRUEto lock the “Name server addr.” text field.  
pad9  
Always zero.  
lockAdminDomainName  
Set to TRUEto lock the “Ending domain name” text field.  
pad10  
Always zero.  
lockSearchDomains Set to TRUEto lock the “Additional search domains” text  
field.  
pad11  
Always zero.  
lockUnknown  
pad12  
Reserved.  
Always zero.  
lock8023  
pad13  
Set to TRUEto lock the Use 802.3 checkbox.  
Always zero.  
lockDHCPClientID Set to TRUEto lock the DHCP Client ID text field. This field  
was added to the OTCfgTCPLocksstructure in  
Open Transport 2.0.  
pad14  
Always zero. This field was added to the OTCfgTCPLocks  
structure in Open Transport 2.0.  
Depending on the version of Open Transport, the size of the OTCfgTCPLocks  
structure is 25 bytes (pre-Open Transport 2.0) or 27 bytes (Open Transport 2.0  
and later). The following preference size constants are defined for this structure:  
enum {  
kOTCfgTCPLocksPrefPre2_0Size = 25,  
kOTCfgTCPLocksPref2_0Size  
= 27,  
kOTCfgTCPLocksPrefCurrentSize = kOTCfgTCPLocksPref2_0Size,  
};  
When reading or writing this preference, be sure to use the appropriate  
preference type for the version of Open Transport that is being used.  
The preference type for OTCfgTCPLocksis kOTCfgTCPLocksPref, which is defined  
as 'stng'.  
118  
Protocol Structures  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgTCPRoutersList  
4
The OTCfgTCPRoutersListstructure holds an array of OTCfgTCPRoutersListEntry  
(page 119) structures.  
struct OTCfgTCPRoutersList  
{
UInt16  
fCount;  
OTCfgTCPRoutersListEntry  
fList[1];  
};  
Field descriptions  
fCount  
The number of elements in the fListarray.  
fList  
An unbounded array consisting of a  
OTCfgTCPRoutersListEntry(page 119) structures.  
The preference type for this preference is kOTCfgTCPRoutersListPref, which is  
defined as 'irte'.  
OTCfgTCPRoutersListEntry  
4
The OTCfgTCPRoutersListEntrystructure is a sub-structure of the  
OTCfgTCPRoutersList(page 119) structure and stores the IP address of the router  
that has been configured as the default gateway for this interface.  
struct OTCfgTCPRoutersListEntry  
{
InetHost  
InetHost  
UInt16  
fToHost;  
fViaHost;  
fLocal;  
fHost;  
UInt16  
};  
Field descriptions  
fToHost  
A reserved field that you should initialize to zero.  
fViaHost  
fLocal  
fHost  
The IP address of the router.  
A reserved field that you should initialize to zero.  
A reserved field that you should initialize to zero.  
Protocol Structures  
119  
 
         
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgTCPSearchDomains  
4
The OTCfgTCPSearchDomainsstructure stores the list of domains that are searched  
after the implicit search domains.  
IMPORTANT  
You must pack this structure before you write it to the  
database and you must unpack this structure after you  
reading it from the database. L  
struct OTCfgTCPSearchDomains {  
UInt16 fCount;  
Str255 fFirstSearchDomain;  
};  
typedef struct OTCfgTCPSearchDomains OTCfgTCPSearchDomains;  
Field descriptions  
fCount  
The number of domains in the list  
fFirstSearchDomain The first domain to be searched. The other search domains  
are packed after this fFirstSearchDomain.  
Note  
This preference is stored in string list format (the same  
format as a ‘STR#resource). N  
The preference type for this preference is kOTCfgTCPSearchDomainsPref, which is  
defined as 'isdm'.  
OTCfgTCPSearchList  
4
The OTCfgTCPSearchListstructure stores DNS configuration information.  
IMPORTANT  
You must pack this structure before you write it to the  
database and you must unpack this structure after you  
reading it from the database. L  
120  
Protocol Structures  
 
           
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
struct OTCfgTCPSearchList {  
UInt8  
fPrimaryInterfaceIndex;  
Str255 fLocalDomainName[256];  
Str255 fAdmindomain[256];  
};  
Field descriptions  
fPrimaryInterfaceIndex  
A value that must be 1 in the current versions of Open  
Transport.  
fLocalDomainName The local domain name in Pascal string format. You must  
unpack this field when you read this structure from the  
database and pack this file when you write this structure to  
the database.  
fAdmindomain  
The administrative domain name in Pascal string format.  
You must unpack this field when you read this structure  
from the database and pack this file when you write this  
structure to the database.  
The preference type for this preference is kOTCfgTCPSearchListPref, which is  
defined as 'ihst'.  
OTCfgTCPUnloadAttr  
4
The OTCfgTCPUnloadAttrenumeration defines values that indicate whether  
TCP/IP is loaded on demand, always loaded, or inactive. These values are used  
in the kOTCfgTCPUnloadAttrPrefpreference.  
typedef UInt16 OTCfgTCPUnloadAttr  
enum {  
kOTCfgTCPActiveLoadedOnDemand = 1,  
kOTCfgTCPActiveAlwaysLoaded = 2,  
kOTCfgTCPInactive = 3  
};  
Constant descriptions  
kOTCfgTCPActiveLoadedOnDemand  
TCP/IP is loaded when needed and unloaded when  
inactive for two minutes.  
Protocol Structures  
121  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOTCfgTCPActiveAlwaysLoaded  
TCP/IP is always loaded.  
kOTCfgTCPInactive TCP/IP is never loaded.  
The preference type for this preference is kOTCfgTCPDHCPUnloadAttrPref, which  
is defined as 'unld'.  
Apple Remote Access Structures  
4
This section describes structures that store Apple Remote Access (ARA)  
preferences. The structures are  
I OTCfgRemoteApplication(page 123) stores information used by the Remote  
Access and the Open Transport/PPP applications.  
I OTCfgRemoteClientLocks(page 125) stores information about whether a  
preference is locked.  
I OTCfgRemoteClientMisc(page 127) stores automatic connection information.  
configurations.  
I OTCfgRemoteDialAssist(page 130) stores area and country code dialing  
information.  
I OTCfgRemoteDialing(page 131) stores settings for outgoing ARA connections.  
Protocol Control Protocol (IPCP) layer of PPP.  
Control Protocol (LCP) layer of PPP.  
ARA.  
I OTCfgRemotePassword(page 135) holds the user’s dialup password in  
encrypted form  
I OTCfgRemoteServer(page 136) stores an array of port configuration IDs used  
to locate the configuration for a particular port on a Remote Access server.  
122  
Protocol Structures  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
the personal server.  
I OTCfgRemoteTerminal(page 138) stores information used by the PPP terminal  
window.  
I OTCfgRemoteUserMode(page 139) stores the current user mode and the  
administration password for the control panel.  
I OTCfgRemoteX25(page 140) stores X.25 connection information.  
OTCfgRemoteAlternateAddress  
4
The OTCfgRemoteAlternateAddressstructure stores an alternate number to dial  
for outgoing ARA connections.  
struct OTCfgRemoteAlternateAddress  
{
UInt32  
Str255  
pad;  
alternateAddress;  
};  
Field descriptions  
pad  
Must be zero.  
alternateAddress A string containing the alternate number to dial.  
The preference type for this preference is kOTCfgRemoteAlternateAddressPref,  
which is defined as 'cead'.  
OTCfgRemoteApplication  
4
The OTCfgRemoteApplicationstructure stores information for the Remote Access  
application (or OT/PPP).  
struct OTCfgRemoteApplication  
{
UInt32  
Point  
version;  
fWindowPosition;  
Protocol Structures  
123  
 
       
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
UInt32  
OTCfgUserMode32 fUserMode;  
UInt32 fSetupVisible;  
tabChoice;  
};  
version  
Must be 1 for Open Transport/PPP or 3 for ARA.  
tabChoice  
Currently active tab in the Options dialog box. Use 1 for the  
Redialing tab, 2 for the Connection tab, or 3 for the Protocol  
tab.  
fUserMode  
The current user mode. See the OTCfgUserModepreference  
(page 109) enumeration for possible values.  
fSetupVisible  
Set to 1 to display the set up or zero to hide it.  
The preference type for this preference is kOTCfgRemoteApplicationPref, which  
is defined as 'capt'.  
OTCfgRemoteARAP  
4
The OTCfgRemoteARAPstructure stores connection information used by the ARAP  
modules.  
struct OTCfgRemoteARAP  
{
UInt32  
char  
version;  
lowerLayerName[kMaxProviderNameSize];  
};  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
lowerLayerName  
A C string containing the name of the underlying modem  
port, which must be “Script”.  
The preference type for this preference is kOTCfgRemoteARAPPref, which is  
defined as 'arap'.  
124  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteClientLocks  
4
The OTCfgRemoteClientLocksstructure stores information about preferences that  
have been locked by the administration mode of the control panel.  
struct OTCfgRemoteClientLocks  
{
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
version;  
name;  
password;  
number;  
errorCheck;  
headerCompress;  
termWindow;  
reminder;  
autoConn;  
redial;  
useProtocolLock;  
useVerboseLogLock;  
regUserOrGuestLock;  
dialAssistLock;  
savePasswordLock;  
reserved[2];  
};  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
name  
The Name field in the control panel is locked when the name  
field is set to 1 and unlocked when the namefield is set to  
zero.  
password  
number  
The Password field in the control panel is locked when the  
passwordfield is set to 1 and unlocked when the password  
field is set to zero.  
The Number field in the control panel is locked when the  
numberfield is set to 1 and unlocked when the numberfield  
is set to zero.  
Protocol Structures  
125  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
errorCheck  
The “Allow error correction and compression in modem”  
checkbox in the control panel is locked when the  
errorCheckfield is set to 1 and unlocked when the  
errorCheckfield is set to zero.  
headerCompress  
The “Use TCP header compression” checkbox in the  
control panel is locked when the headerCompressfield is set  
to 1 and unlocked when the headerCompressfield is set to  
zero.  
termWindow  
reminder  
autoConn  
The “Connect to a command-line host” checkbox in the  
control panel is locked when the termWindowfield is set to 1  
and unlocked when the termWindowfield is set to zero.  
The Reminders options in the control panel are locked  
when the reminderfield is set to 1 and unlocked when the  
reminderfield is set to zero.  
The “Connect automatically when starting TCP/IP  
applications” checkbox in the control panel is locked when  
the autoConnfield is set to 1 and unlocked when the  
autoConnfield is set to zero.  
redial  
The Redialing tab in the control panel is locked when the  
redialfield is set to 1 and unlocked with the redialfield is  
set to zero.  
useProtocolLock  
The “Use protocol” pop-up menu in the control panel is  
locked when the useProtocolLockfield is set to 1 and  
unlocked when the useProtocolLockfield is set to zero.  
useVerboseLogLock The “Use verbose logging” checkbox in the control panel is  
locked when the useVerboseLogLockfield is set to 1 and  
unlocked when the useVerboseLogLockfield is set to zero.  
regUserOrGuestLock The Register User and Guest radio buttons in the control  
panel are locked when the regUserOrGuestLockfield is set to  
1 and unlocked when the regUserOrGuestLockfield is set to  
zero.  
dialAssistLock  
The Use DialAssist checkbox in the control panel is locked  
when the dialAssistLockfield is set to 1 and unlocked  
when the dialAssistLockfield is set to zero.  
savePasswordLock The “Save password” checkbox in the control panel is  
locked when the savePasswordLockfield is set to 1 and  
unlocked when the savePasswordLockfield is set to zero.  
reserved  
Must be zero.  
126  
Protocol Structures  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
The preference type for this preference is OTCfgRemoteClientLocks, which is  
defined as 'clks'.  
OTCfgRemoteClientMisc  
4
The OTCfgRemoteClientMiscstructure stores automatic connection information.  
struct OTCfgRemoteClientMisc  
{
UInt32  
UInt32  
version;  
connectAutomatically;  
};  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
connectAutomatically  
Set to 1 to connect automatically when the first TCP/IP  
application starts up. Set to zero to not connect  
automatically.  
The preference type for this preference is kOTCfgRemoteClientMiscPref, which is  
defined as 'cmsc'.  
OTCfgRemoteConnect  
4
The OTCfgRemoteConnectstructure store core connection information for ARA  
configurations.  
struct OTCfgRemoteConnect {  
UInt32  
UInt32  
UInt32  
UInt32  
version;  
fType;  
isGuest;  
canInteract;  
Protocol Structures  
127  
 
           
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
UInt32  
UInt32  
UInt32  
UInt32  
SInt32  
UInt32  
UInt32  
showStatus;  
passwordSaved;  
flashConnectedIcon;  
issueConnectedReminders;  
reminderMinutes;  
connectManually;  
allowModemDataCompression;  
OTCfgRemotePPPConnectScript chatMode;  
OTCfgRemoteProtocol  
UInt32  
serialProtocolMode;  
passwordPtr;  
UInt32  
userNamePtr;  
UInt32  
addressLength;  
addressPtr;  
UInt32 *  
Str63  
chatScriptName;  
chatScriptLength;  
chatScriptPtr;  
additional;  
UInt32  
UInt32  
UInt32  
UInt32  
useSecurityModule;  
securitySignature;  
securityDataLength;  
securityDataPtr;  
OSType  
UInt32  
UInt32  
};  
typedef struct OTCfgRemoteConnect OTCfgRemoteConnect;  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
fType  
Must be zero.  
isGuest  
Set to zero if the user is a registered user; set to 1 if the user  
is to log on as Guest.  
canInteract  
showStatus  
Must be 1.  
Must be zero.  
passwordSaved  
Set to 1 to use the password preference  
(kOTCfgRemotePasswordPref) or set to zero to prompt the  
user for a password.  
128  
Protocol Structures  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
flashConnectedIcon Set to zero if the menu bar flashes when a disconnection  
occurs; set to 1 if the menu bar does not flash when a  
disconnection occurs.  
issueConnectedReminders  
Set to 1 to flash an icon in the menu bar to remind the user  
that the connection is active; set to zero to not flash an icon.  
reminderMinutes  
If Notification Manager reminders are enabled, the number  
of minutes that are to elapse between reminders.  
allowModemDataCompression  
to 1 if modem data compression is allowed.  
chatMode  
The chat mode. For possible values, see the  
OTCfgRemotePPPConnectScript(page 166) enumeration.  
serialProtocolMode The serial protocol mode (PPP, ARAP, or both). For  
possible values, see the OTCfgRemoteProtocol(page 167)  
enumeration.  
passwordPtr  
userNamePtr  
addressLength  
addressPtr  
Run-time use only. Initialize passwordPtrto zero, ignore it  
when you read it, and preserve its value when you write it.  
Run-time use only. Initialize userNamePtrto zero, ignore it  
when you read it, and preserve its value when you write it.  
The length in bytes of the telephone number stored in the  
kOTCfgRemoteAddressPref.  
Run-time use only. Initialize addressPtrto zero, ignore it’s  
value when you read it, and preserve it’s value when you  
write it.  
chatScriptName  
The user-visible name of the chat script for this  
configuration.  
chatScriptLength The length in bytes of the chat script.  
chatScriptPtr  
Run-time use only. Initialize chatScriptPtrto zero, ignore  
it’s value when you read it, and preserve it’s value when  
you write it.  
additionalPtr  
Run-time use only. Initialize additionalPtrto zero, ignore  
it’s value when you read it, and preserve it’s value when  
you write it.  
useSecurityModule Must be zero.  
securitySignature Must be zero.  
Protocol Structures  
129  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
securityDataLength Must be zero.  
securityData  
Must be zero.  
The preference type for OTCfgRemoteConnectis kOTCfgRemoteConnectPref, which  
is defined as 'conn'.  
OTCfgRemoteDialAssist  
4
The OTCfgRemoteDialAssiststructure stores area and country code information  
used by the Dial Assist facility.  
struct OTCfgRemoteDialAssist {  
UInt32 version;  
UInt32 isAssisted;  
Str31  
Str31  
areaCodeStr;  
countryCodeStr;  
};  
typedef struct OTCfgRemoteDialAssist  
OTCfgRemoteDialAssist;;  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
isAssisted  
Set isAssistedto zero for no assistance (the default); set  
isAssistedto 1 to use Dial Assist. When isAssistedis set to  
zero, areaCodeStrand countryCodeStrare ignored.  
areaCodeStr  
A string containing an area code that is to be dialed as part  
of the sequence for making a connection.  
countryCodeStr  
A string containing a country code that is to be dialed as  
part of the sequence for making a connection.  
The preference type for this preference is kOTCfgRemoteDialAssistPref, which is  
defined as 'dass'.  
130  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteDialing  
4
The OTCfgRemoteDialingstructure stores settings for outgoing ARA connections.  
struct OTCfgRemoteDialing {  
UInt32  
version;  
UInt32  
fType;  
UInt32  
additionalPtr;  
dialMode;  
redialTries;  
redialDelay;  
pad;  
OTCfgRemoteRedialMode  
UInt32  
UInt32  
UInt32  
};  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
set it to kOTCfgRemoteDefaultVersion.  
fType  
Must be ‘dial’.  
additionalPtr  
dialMode  
Must be zero.  
The redial mechanism to use. For possible values, see the  
OTCfgRemoteDialMode(page 168) enumeration.  
redialTries  
redialDelay  
The number of times to redial if a connection cannot be  
made. Only valid if dialModeis not kOTCfgRemoteRedialNone.  
The number of milliseconds to wait before redialing. The  
value of redialDelayis only valid if dialModeis not  
kOTCfgRemoteRedialNone.  
pad  
A pad byte whose value must be zero.  
The preference type for this preference is kOTCfgRemoteDialingPref, which is  
defined as 'cdia'.  
Protocol Structures  
131  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteIPCP  
4
The OTCfgRemoteIPCPstructure stores information for configuring the Internet  
Protocol Control Protocol (IPCP) layer of PPP. This information is also used as  
part of a Remote Access server configuration. This structure is not used for  
ARAP connections.  
struct OTCfgRemoteIPCP {  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt16  
UInt16  
UInt32  
version;  
reserved[2];  
maxConfig;  
maxTerminate;  
maxFailureLocal;  
maxFailureRemote;  
timerPeriod;  
localIPAddress;  
remoteIPAddress;  
allowAddressNegotiation;  
idleTimerEnabled;  
compressTCPHeaders;  
idleTimerMilliseconds;  
};  
typedef struct OTCfgRemoteIPCP OTCfgRemoteIPCP;  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
reserved  
Must be zero.  
Must be 10.  
Must be 10.  
Must be 10.  
maxConfig  
maxTerminate  
maxFailureLocal  
maxFailureRemote Must be 10.  
timerPeriod  
In milliseconds. Must be 10000.  
localIPAddress  
remoteIPAddress  
Must be zero.  
Must be zero.  
132  
Protocol Structures  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
allowAddressNegotiation  
Must be 1.  
idleTimerEnabled  
Set idleTimerEnabledto 1 to cause a connection that has  
been idle for the number of milliseconds specified by the  
idletTimerMillisecondsfield to be disconnected. Set  
idleTimerEnabledto zero to disable the idle timer.  
compressTCPHeaders Set compressTCPHeadersto 1 to allow Van Jacobsen header  
compression. Set compressTCPHeadersto zero to disallow  
header compression.  
idleTimerMilliseconds  
The number of milliseconds to wait before disconnecting a  
connection that is idle.  
The preference type for this preference is kOTCfgRemoteIPCPPref, which is  
defined as 'ipcp'.  
OTCfgRemoteLCP  
4
The OTCfgRemoteLCPstructure stores information for configuring the Link  
Control Protocol (LCP) layer of PPP. The information in this structure is used  
for PPP connections and is ignored for ARAP connections. This information is  
also used as part of a Remote Access server configuration.  
struct OTCfgRemoteLCP {  
UInt32  
UInt32  
char  
version;  
reserved[2];  
lowerLayerName[36];  
maxConfig;  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
maxTerminate;  
maxFailureLocal;  
maxFailureRemote;  
timerPeriod;  
echoTrigger;  
echoTimeout;  
echoRetries;  
compressionType;  
mruSize;  
upperMRULimit;  
lowerMRULimit;  
Protocol Structures  
133  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
UInt32  
UInt32  
UInt32  
txACCMap;  
rcACCMap;  
isNoLAPB;  
};  
typedef struct OTCfgRemoteLCP OTCfgRemoteLCP;  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
reserved  
Must be zero.  
lowerLayerName  
A C string containing the name of the underlying modem  
port. Must be ‘Script’.  
maxConfig  
Must be 10.  
Must be 10.  
Must be 10.  
maxTerminate  
maxFailureLocal  
maxFailureRemote Must be 10.  
timerPeriod  
echoTrigger  
echoTimeout  
echoRetries  
compressionType  
mruSize  
In milliseconds. Must be 10000.  
In milliseconds. Must be 10000.  
In milliseconds. Must be 10000.  
Must be 5.  
Must be 3.  
Must be 1500.  
upperMRULimit  
lowerMRULimit  
txACCMap  
Must be 4500.  
Must be zero.  
Must be zero.  
rcACCMap  
Must be zero.  
isNoLAPB  
Must be zero.  
The preference type for this preference is kOTCfgRemoteLCPPref, which is defined  
as 'lcp'.  
134  
Protocol Structures  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteLogOptions  
4
The OTCfgRemoteLogOptionsstructure controls the level of logging performed by  
ARA.  
struct OTCfgRemoteLogOptions {  
UInt32 version;  
UInt32 fType;  
UInt32 additionalPtr;  
OTCfgRemoteLogLevel logLevel;  
UInt32 reserved[4];  
};  
typedef struct OTCfgRemoteLogOptions OTCfgRemoteLogOptions;  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
fType  
additional  
Run-time use only. Initialize to zero. When reading, ignore  
the value of additionalPtr. When writing additionalPtr,  
preserve its value.  
logLevel  
reserved  
The log level. For possible values, see the  
OTCfgRemoteLogLevel(page 168) enumeration.  
Reserved.  
The preference type for this preference is kOTCfgRemoteLogOptionsPref, which is  
defined as 'logo'.  
OTCfgRemotePassword  
4
The OTCfgRemotePasswordstructure holds the user’s dialup password in  
encrypted form. For sample code, see Listing 2-17 in Chapter 2, “Using  
Network Setup.”  
Protocol Structures  
135  
 
           
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
struct OTCfgRemotePassword {  
UInt8  
data[256];  
};  
typedef struct OTCfgRemotePassword OTCfgRemotePassword;  
data  
The encrypted password. Call OTCfgEncrypt(page 93) to  
encrypt the password.  
The preference type for this preference is kOTCfgRemotePasswordPref, which is  
defined as 'pass'.  
OTCfgRemoteServer  
4
The OTCfgRemoteServerstructure stores an array of port configuration IDs used  
to locate the configuration for a particular port.  
struct OTCfgRemoteServer {  
UInt32 version;  
SInt16 configCount;  
SInt16 configIDs[1];  
};  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
configCount  
configIDs  
The number of active Remote Access server configurations.  
Must be 1 for the personal server.  
Array of port configuration IDs. For the personal server,  
there can be only one port configuration ID whose value is  
zero.  
The preference type for this preference is kOTCfgRemoteServerPref, which is  
defined as 'srvr'.  
136  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteServerPort  
4
The OTCfgRemoteServerPortstructure stores core configuration information for  
the personal server.  
struct OTCfgRemoteServerPort {  
UInt32  
version;  
SInt16  
configID;  
Str255  
password;  
OTCfgRemoteAnswerMode  
Boolean  
answerMode;  
limitConnectTime;  
pad;  
UInt8  
UInt32  
maxConnectSeconds;  
serialProtoFlags;  
OTCfgRemoteProtocol  
OTCfgRemoteNetworkProtocol networkProtoFlags;  
OTCfgRemoteNetAccessMode  
netAccessMode;  
Boolean  
char  
requiresCCL;  
portName[64];  
char  
serialLayerName[kMaxProviderNameSize];  
localIPAddress;  
InetHost  
};  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
configID  
The ID of this port configuration. The ID must match an  
(page 136) structure. For the personal server, configIDmust  
be zero.  
password  
The security zone bypass password in plain text.  
answerMode  
The answer mode. For possible values, see the  
OTCfgRemoteAnswerMode(page 169) enumerations.  
limitConnectTime Set to 1 to limit the length of incoming connections. Set to  
zero for unlimited connection time.  
pad  
Must be zero.  
maxConnectSeconds The maximum length of a incoming connection in seconds  
if limitConnectTimeis set to 1. The default is 3600.  
Protocol Structures  
137  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteProtocol(page 167).  
networkProtoFlags Network protocol flags. For possible values, see the  
OTCfgRemoteNetworkProtocol(page 169) enumeration.  
netAccessMode  
Access mode flags. For possible values, see the  
OTCfgRemoteNetAccessMode(page 170) enumeration.  
requiresCCL  
portName  
Must be TRUE.  
C string containing the name of the underlying port.Must  
the empty string for the personal server.  
serialLayerName  
localIPAddress  
C string containing the Open Transport name of the serial  
port.  
IP address to offer to the client.  
The preference type for OTCfgRemoteServerPortis kOTCfgRemoteServerPortPref,  
which is defined as 'port'.  
OTCfgRemoteTerminal  
4
The OTCfgRemoteTerminalstructure stores information used by the PPP terminal  
window.  
struct OTCfgRemoteTerminal {  
UInt32  
Boolean  
Boolean  
Boolean  
Boolean  
Boolean  
Boolean  
Boolean  
Boolean  
Rect  
fVersion;  
fLocalEcho;  
fNonModal;  
fPowerUser;  
fQuitWhenPPPStarts;  
fDontAskVarStr;  
fNoVarStrReplace;  
fLFAfterCR;  
fAskToSaveOnQuit;  
fWindowRect;  
fTypedCharStyle;  
fPrintedCharStyle;  
fEchoedCharStyle;  
pad;  
Style  
Style  
Style  
UInt8  
SInt16  
fFontSize;  
138  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
Str255  
fFontName;  
};  
typedef struct OTCfgRemoteTerminal OTCfgRemoteTerminal;  
fVersion  
Must be 1.  
fLocalEcho  
Set to TRUEfor the terminal window to echo typed  
characters; otherwise, set to FALSE. The default is FALSE.  
fNonModal  
Must be FALSE.  
Must be FALSE.  
fPowerUser  
fQuitWhenPPPStarts Set to TRUEto cause the terminal window to quit when the  
PPP connection is made. The default is TRUE.  
fDontAskVarStr  
fNoVarStrReplace  
fLFAfterCR  
The default is FALSE.  
Must be FALSE.  
Must be FALSE.  
fAskToSaveOnQuit Set to TRUEto cause ARA to ask to save changes when the  
terminal window closes. The default is FALSE.  
fWindowRect  
Must be zero.  
fTypedCharStyle  
Style used for typed characters. The default is bold.  
fPrintedCharStyle Style used for characters sent by the other end of the  
connection. The default is plain.  
fEchoedCharStyle Style used for echoed characters. The default is italic.  
pad  
Must be zero.  
fFontSize  
fFontName  
The font size. The default is 9 point.  
The font in which characters are displayed. The default is  
Monaco on Roman systems.  
The preference type for this preference is kOTCfgRemoteTerminalPref, which is  
defined as 'term'.  
OTCfgRemoteUserMode  
4
The OTCfgRemoteUserModestructure stores the current user mode and the  
administration password.  
Protocol Structures  
139  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
struct OTCfgRemoteUserMode {  
UInt32  
OTCfgUserMode32 userMode;  
Str255 adminPassword;  
version;  
};  
typedef struct OTCfgRemoteUserMode OTCfgRemoteUserMode;  
version  
Depending how the preference was constructed, version  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
userMode  
Current user mode. See the OTCfgUserModepreference  
(page 109) enumeration for possible values.  
adminPassword  
The administration password. The format is not  
documented.  
The preference type for this preference is kOTCfgRemoteUserModePref, which is  
defined as 'usmd'.  
OTCfgRemoteX25  
4
The OTCfgRemoteX25structure stores X.25 connection information.  
struct OTCfgRemoteX25 {  
UInt32  
UInt32  
UInt32  
FSSpec  
UInt8  
version;  
fType;  
additionalPtr;  
script;  
address[256];  
userName[256];  
closedUserGroup[5];  
reverseCharge;  
UInt8  
UInt8  
Boolean  
};  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
140  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
fType  
Must be zero for standard dial-up connections.  
Must be zero for standard dial-up connections.  
Must be zero for standard dial-up connections.  
Must be zero for standard dial-up connections.  
additionalPtr  
script  
address  
userName  
Must be zero for standard dial-up connections.  
Must be zero for standard dial-up connections.  
Must be zero for standard dial-up connections.  
closedUserGroup  
reverseCharge  
The preference type for this preference is kOTCfgRemoteX25Pref, which is defined  
as 'x25 '.  
IMPORTANT  
Using Network Setup to configure X.25 connections is not  
supported. L  
Modem Structures  
4
This section describes structures that store Modem control panel settings. The  
structures are  
I OTCfgModemGeneral(page 141) stores per-connection modem preferences.  
I OTCfgModemApplication(page 142) stores the current user mode setting and  
the window position of the Modem control panel.  
I OTCfgModemLocks(page 143) stores the lock settings for the Modem control  
panel.  
OTCfgModemGeneral  
4
The OTCfgModemGeneralstructure stores most of the per-connection modem  
preferences.  
struct OTCfgModemGeneral  
{
UInt32  
version;  
Boolean  
useModemScript;  
Protocol Structures  
141  
 
       
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
UInt8  
pad;  
FSSpec  
modemScript;  
Boolean  
modemSpeakerOn;  
Boolean  
modemPulseDial;  
OTCfgModemDialogToneMode  
char  
modemDialToneMode;  
lowerLayerName[kMaxProviderNameSize];  
};  
Field descriptions  
version  
Depending how the preference was constructed, version  
may be kOTCfgRemoteDefaultVersionor  
kOTCfgRemoteAcceptedVersion. When reading the version  
field, accept either value. When writing the versionfield,  
set it to kOTCfgRemoteDefaultVersion.  
useModemScript  
Set useModemScriptto TRUEto indicate that a modem script  
is to be used.  
pad  
A value that must be zero.  
modemScript  
The modem script that is to be used; this field is ignored if  
a modem script is not to be used.  
modemSpeakerOn  
modemPulseDial  
Set modemSpeakerOnto TRUEto indicate dialing with the  
Set modemPulseDialto TRUEto indicate pulse dialing.  
Otherwise, set modemPulseDialto FALSEfor tone dialing.  
modemDialToneMode The dial tone mode that controls the way in which the  
modem handles dial tone. For possible values, see the  
OTCfgModemDialingToneMode(page 171) enumeration.  
lowerLayerName  
The name of the underlying serial port in C string format.  
The preference type for the OTCfgModemGeneralstructure is  
kOTCfgModemGeneralPrefs, which is defined as 'ccl '.  
OTCfgModemApplication  
4
The OTCfgModemApplicationstructure stores the current user mode setting and  
the window position of the Modem control panel.  
142  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
struct OTCfgModemApplication {  
UInt32  
Point  
version;  
windowPos;  
OTCfgUserMode32 userMode;  
};  
Field descriptions  
version  
Must be 1.  
windowPos  
userMode  
Window position in global coordinates of the modem  
control panel.  
Must be kOTCfgBasicUserModeUsermode because the  
Modem control panel does not support any other mode.  
The preference type for the OTCfgModemApplicationstructure is  
kOTCfgModemApplicationPref, which is defined as 'mapt'.  
OTCfgModemLocks  
4
The OTCfgModemLocksstructure stores the lock settings for the Modem control  
panel.  
struct OTCfgModemLocks {  
UInt32 version;  
UInt32 port;  
UInt32 script;  
UInt32 speaker;  
UInt32 dialing;  
};  
typedef struct OTCfgModemLocks OTCfgModemLocks;  
Field descriptions  
version  
Must be 1.  
port  
Set portto 1 to lock the setting for the underlying serial  
port or to zero to unlock the setting.  
script  
Set script to 1 to lock the modem script (CCL) or to zero to  
unlock the setting.  
speaker  
Set speakerto 1 to lock the speaker setting or to zero to  
unlock the speaker setting.  
Protocol Structures  
143  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
dialing  
Set dialingto lock the setting for pulse or tone dialing, or  
set dialingto zero to unlock the setting.  
The preference type for the OTCfgModemLocksstructure is kOTCfgModemLocksPref,  
which is defined as 'lkmd'.  
AppleTalk Structures  
4
structures are  
preferences for each AppleTalk protocol.  
Address Resolution protocol (AARP).  
I OTCfgATalkGeneralADSP(page 147) stores information for the AppleTalk Data  
Stream Protocol (ADSP).  
Session Protocol (ASP).  
Transaction Protocol (ATP).  
Delivery Protocol (DDP).  
Protocol (NBP).  
I OTCfgATalkGeneralPAP(page 154) stores information for the Printer Access  
Protocol (PAP).  
Protocol (ZIP).  
preferences have been locked.  
I OTCfgATalkNetworkArchitecture(page 157) stores information about whether  
classic networking or Open Transport is selected.  
I OTCfgATalkPortDeviceType(page 158) stores information about the port for  
which AppleTalk is configured.  
144  
Protocol Structures  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgATalkGeneral  
4
The OTCfgATalkGeneralstructure consists of structures for each AppleTalk  
protocol.  
struct OTCfgATalkGeneral  
{
UInt16  
fVersion;  
fNumPrefs;  
fPort;  
UInt16  
OTPortRef  
void*  
fLink;  
void*  
fPrefs[8];  
aarpPrefs;  
ddpPrefs;  
nbpPrefs;  
zipPrefs;  
atpPrefs;  
adspPrefs;  
papPrefs;  
aspPrefs;  
OTCfgATalkGeneralAARP  
OTCfgATalkGeneralDDP  
OTCfgATalkGeneralNBP  
OTCfgATalkGeneralZIP  
OTCfgATalkGeneralATP  
OTCfgATalkGeneralADSP  
OTCfgATalkGeneralPAP  
OTCfgATalkGeneralASP  
};  
Field descriptions  
fVersion  
Must be zero.  
fNumPrefs  
OTPortRef  
fLink  
Must be zero.  
A reference to the port to which this configuration applies.  
Must be null. This field is used during run time.  
fPrefs  
All elements must be initialized to null. This field is used  
during run time.  
aarpPrefs  
ddpPrefs  
nbpPrefs  
zipPrefs  
adspPrefs  
papPrefs  
aspPrefs  
An OTCfgATalkGeneralAARP(page 146) structure.  
An OTCfgATalkGeneralDDP(page 151) structure.  
An OTCfgATalkGeneralNBP(page 153) structure.  
An OTCfgATalkGeneralZIP(page 155) structure.  
An OTCfgATalkGeneralADSP(page 147) structure.  
An OTCfgATalkGeneralPAP(page 154) structure.  
An OTCfgATalkGeneralASP(page 149) structure.  
Protocol Structures  
145  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
The preference type for the OTCfgATalkGeneralstructure is  
kOTCfgATalkGeneralPref, which is defined as 'atpf'.  
OTCfgATalkGeneralAARP  
4
The OTCfgATalkGeneralAARPstructure defines parameters for the AppleTalk  
Address Resolution Protocol (AARP) component of the AppleTalk protocol  
stack and is a sub-structure of the OTCfgATalkGeneralstructure.  
struct OTCfgATalkGeneralAARP {  
UInt16  
UInt16  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
fVersion;  
fSize;  
fAgingCount;  
fAgingInterval;  
fProtAddrLen;  
fHWAddrLen;  
fMaxEntries;  
fProbeInterval;  
fProbeRetryCount;  
fRequestInterval;  
fRequestRetryCount;  
};  
typedef struct OTCfgAARPPrefs OTCfgAARPPrefs;  
Field descriptions  
fVersion  
Always 1.  
fSize  
The size of this structure.  
The default is 8.  
fAgingCount  
fAgingInterval  
fProtAddrLen  
The aging interval in milliseconds. The default is 1000.  
The length of protocol addresses in bytes. Always 4. This  
field is ignored by current versions of Open Transport.  
fHWAddrLen  
The length of hardware addresses. Always 6. This field is  
ignored by current versions of Open Transport.  
fMaxEntries  
The default is 100.  
fProbeInterval  
The probe interval in milliseconds. The default probe  
interval is 200 milliseconds.  
146  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
fProbeRetryCount The number of times to retry a probe. The default is 10.  
interval is 200 milliseconds.  
fRequestRetryCount The number of times to retry a request. The default is 8.  
For a detailed descriptions of AARP, see Inside AppleTalk, Second edition.  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralADSP  
4
The OTCfgATalkGeneralADSPstructure defines parameters for the AppleTalk Data  
Stream Protocol (ADSP) component of the AppleTalk protocol stack and is a  
sub-structure of the OTCfgATalkGeneralstructure.  
struct OTCfgATalkGeneralADSP  
{
UInt16  
UInt16  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt32  
UInt8  
fVersion;  
fSize;  
fDefaultSendBlocking;  
fTSDUSize;  
fETSDUSize;  
fDefaultOpenInterval;  
fDefaultProbeInterval;  
fMinRoundTripTime;  
fDefaultSendInterval;  
fDefaultRecvWindow;  
fDefaultOpenRetries;  
fDefaultBadSeqMax;  
fDefaultProbeRetries;  
fMaxConsecutiveDataPackets;  
fDefaultChecksum;  
fDefaultEOM;  
UInt8  
UInt8  
UInt8  
Boolean  
Boolean  
};  
Field descriptions  
fVersion  
Must be 1.  
Protocol Structures  
147  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
fSize  
Must be the size in bytes of this structure.  
fDefaultSendBlockingBytes, default is 16.  
fTSDUSize  
The Transport Service Data Unit (TSDU), which is the  
maximum amount of data that packets of this protocol can  
carry. The default is 572.  
fETSDUSize  
The extended TSDU (ETSDU) size. The default is 572.  
fDefaultOpenInterval  
The default open interval in milliseconds. The default is  
3000.  
fDefaultProbeInterval  
The default probe interval in milliseconds. The default is  
30000.  
fMinRoundTripTime  
The minimum round trip time in milliseconds. The default  
is 100.  
fDefaultSendInterval  
The default send interval in milliseconds. The default is  
100.  
fDefaultRecvWindow The default receive window in bytes. Must be 27648. This  
value is ignored by current versions of Open Transport.  
fDefaultOpenRetries  
The default number of open retries allowed. The default  
value is 3.  
fDefaultBadSeqMax The default maximum number of sequence errors. The  
default value is 3.  
fDefaultProbeRetries  
The default number of probe retries. The default value is 3.  
fMaxConsecutiveDataPackets  
The maximum number of consecutive data packets. The  
default value is 48.  
fDefaultChecksum Whether checksumming is enabled. The default value is  
FALSE.  
fDefaultEOM  
The default end of header. The default value is FALSE.  
For a detailed description ADSP, see Inside Macintosh: Networking with Open  
Transport and Inside AppleTalk, Second edition.  
148  
Protocol Structures  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralASP  
4
The OTCfgATalkGeneralASPstructure defines parameters for the AppleTalk  
Session Protocol (ASP) component of the AppleTalk protocol stack and is a  
sub-structure of the OTCfgATalkGeneralstructure.  
IMPORTANT  
Open Transport does not currently include a native  
implementation of ASP. The classic AppleTalk  
implementation of ASP ignores these preferences. L  
struct OTCfgATalkGeneralASP  
{
UInt16  
UInt16  
UInt32  
UInt8  
fVersion;  
fSize;  
fDefaultTickleInterval;  
fDefaultTickleRetries;  
fDefaultReplies;  
UInt8  
};  
Field descriptions  
fVersion  
Must be 1.  
fSize  
The size in bytes of this structure.  
fDefaultTickleInterval  
The default tickle interval in milliseconds. This value must  
be 30000. This value is ignored by current versions of Open  
Transport.  
fDefaultTickleRetries  
The default number of times to retry sending a tickle. The  
default value is 8. This value is ignored by current versions  
of Open Transport.  
fDefaultReplies  
Must be 8. This field is ignored by current versions of Open  
Transport.  
Protocol Structures  
149  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
For a detailed description of ASP, see Inside AppleTalk, Second Edition.  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralATP  
4
The OTCfgATalkGeneralATPstructure defines parameters for the AppleTalk  
Transaction Protocol (ATP) component of the AppleTalk protocol stack and is a  
sub-structure of the OTCfgATalkGeneralstructure.  
struct OTCfgATalkGeneralATP  
{
UInt16  
UInt16  
UInt32  
UInt32  
UInt32  
UInt8  
fVersion;  
fSize;  
fTSDUSize;  
fDefaultRetryInterval;  
fDefaultRetryCount;  
fDefaultReleaseTimer;  
fDefaultALOSetting;  
Boolean  
};  
Field descriptions  
fVersion  
Must be 1.  
fSize  
Must be sizeof(OTCfgATalkGeneralATP).  
fTSDUSize  
The maximum amount of data that packets of this protocol  
can carry. The default is 578.  
fDefaultRetryInterval  
The default retry interval in milliseconds. By default, this  
value is 2000.  
fDefaultRetryCount The default retry count. By default, this value is 8.  
fDefaultReleaseTimer  
The default release timer. The default value is zero. This  
field has the same format as ATP_OPT_RELTIMERwhich is  
described in Inside Macintosh: Networking with Open  
Transport.  
150  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
is FALSE.  
For a detailed descriptions ATP, see Inside Macintosh: Networking with Open  
Transport and Inside AppleTalk, Second edition.  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralDDP  
4
The OTCfgATalkGeneralDDPstructure defines parameters for the Datagram  
Delivery Protocol (DDP) component of the AppleTalk protocol stack.  
struct OTCfgATalkGeneralDDP {  
UInt16  
UInt16  
UInt32  
UInt8  
fVersion;  
fSize;  
fTSDUSize;  
fLoadType;  
UInt8  
fNode;  
UInt16  
UInt16  
UInt16  
UInt32  
UInt32  
UInt32  
UInt32  
Boolean  
Boolean  
UInt8  
fNetwork;  
fRTMPRequestLimit;  
fRTMPRequestInterval;  
fAddressGenLimit;  
fBRCAgingInterval;  
fRTMPAgingInterval;  
fMaxAddrTries;  
fDefaultChecksum;  
fIsFixedNode;  
fMyZone[kZIPMaxZoneLength+1];  
};  
typedef struct OTCfgATalkGeneralDDP OTCfgATalkGeneralDDP;  
Field descriptions  
fVersion  
Must be 1.  
fSize  
The size of this structure.  
Protocol Structures  
151  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
fTSDUSize  
The maximum amount of data that packets of this protocol  
can carry. Must be 586, which is the basic AppleTalk  
datagram size.  
fLoadType  
fNode  
Whether AppleTalk is active. See discussion below for  
possible values.  
Most recently acquired node number or the fixed node  
number to use.  
fNetwork  
Most recently acquired network number or the fixed  
network number.  
fRTMPRequestLimit Must be 3. This field is ignored by current versions of Open  
Transport.  
fRTMPRequestInterval  
The request interval in milliseconds. This field must be 200.  
This field is ignored by current versions of Open Transport.  
fAddressGenLimit Address generation limit. The default is 250.  
fBRCAgingInterval The Best Routing Cache (BRC) aging interval in  
milliseconds. This field must be 4000. This field is ignored  
by current versions of Open Transport.  
fRTMPAgingInterval The Router Table Maintenance Protocol (RTMP) aging  
interval in milliseconds. This field must be 5000. This field  
is ignored by current versions of Open Transport.  
fMaxAddrTries  
The maximum number of retries that OT makes when  
trying to acquire an address. The default is 4096.  
fDefaultChecksum When set to TRUE, a checksum is performed on the DDP  
packet. When set to FALSE, no checksum is performed. The  
default is FALSE.  
fIsFixedNode  
Set to TRUEwhen fixed node and network numbers are  
being used. The default value is FALSE.  
fMyZone  
The most recently acquired zone.  
For a detailed description of DDP, see Inside Macintosh: Networking with Open  
Transport and Inside AppleTalk, Second edition.  
The value of the fLoadTypefield controls whether AppleTalk is active. The  
original definition of this field was as an inactivity timeout (in minutes), similar  
to the inactivity timeout implemented for TCP/IP in current versions of Open  
Transport.  
Before Open Transport 1.0 was released, it was realized that loading and  
unloading AppleTalk on demand was not possible, so the fLoadTypefield was  
152  
Protocol Structures  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
redefined as a flag, with zero meaning inactive and non-zero meaning active.  
However, the default preferences were not updated to reflect this change. So, it  
is possible to see the following values stored in this field:  
typedef UInt8 OTCfgATalkUnloadOptions  
enum {  
kOTCfgATalkInactive  
kOTCfgATalkDefaultUnloadTimeout = 5,  
kOTCfgATalkActive = 0xFF  
= 0,  
};  
When reading, treat a value of zero as meaning that AppleTalk is inactive, and  
treat any non-zero values as meaning that AppleTalk is active. When writing,  
set fLoadTypeto kOTCfgATalkInactiveor kOTCfgATalkActive. Never set fLoadType  
to kOTCfgATalkDefaultUnloadTimeout.  
No preference type is defined for the OTCfgATalkGeneralDDPstructure. Instead,  
access this structure through the OTCfgATalkGeneral(page 145) structure, which  
has a preference type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralNBP  
4
The OTCfgATalkGeneralNBPstructure defines parameters for the Name Bind  
Protocol (NBP) component of the AppleTalk protocol stack and is a  
sub-structure of the OTCfgATalkGeneralstructure.  
struct OTCfgATalkGeneralNBP  
{
UInt16  
UInt16  
UInt32  
UInt32  
UInt32  
Boolean  
UInt8  
fVersion;  
fSize;  
fTSDUSize;  
fDefaultRetryInterval;  
fDefaultRetryCount;  
fCaseSensitiveCompare;  
fPad;  
};  
Field descriptions  
fVersion  
Must be 1.  
Protocol Structures  
153  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
fSize  
The size in bytes of this structure.  
fTSDUSize  
The maximum amount of data that packets of this protocol  
can carry. The default is 584.  
fDefaultRetryInterval  
The default retry interval in milliseconds. By default, this  
value is 800.  
fDefaultRetryCount The default retry count. By default, this value is 3.  
fCaseSensitiveCompare  
Whether comparisons are case sensitive. The default value  
is FALSE.  
fPad  
A pad byte whose value must be zero.  
For a detailed description of NBP, see Inside Macintosh: Networking with Open  
Transport and Inside AppleTalk, Second edition.  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralPAP  
4
The OTCfgATalkGeneralPAPstructure defines parameters for the Printer Access  
Protocol (PAP) component of the AppleTalk protocol stack and is a  
sub-structure of the OTCfgATalkGeneralstructure.  
struct OTCfgATalkGeneralPAP  
{
UInt16  
UInt16  
UInt32  
UInt32  
UInt8  
fVersion;  
fSize;  
fDefaultOpenInterval;  
fDefaultTickleInterval;  
fDefaultOpenRetries;  
fDefaultTickleRetries;  
fDefaultReplies;  
fDefaultPAPEOMEnabled;  
UInt8  
UInt8  
Boolean  
};  
154  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
Field descriptions  
fVersion  
Must be 1.  
fSize  
The size in bytes of this structure.  
fDefaultOpenInterval  
The default open interval in milliseconds. The default value  
is 2000.  
fDefaultTickleInterval  
The default tickle interval in milliseconds. The default  
value is 15000.  
fDefaultOpenRetries  
The default number of times to retry an opening. The  
default value is 0.  
fDefaultTickleRetries  
The default number of times to retry sending a tickle. The  
default value is 8.  
fDefaultReplies  
Must be 8. This field is ignored by current versions of Open  
Transport.  
fDefaultPAPEOMEnabled  
By default, FALSE.  
For a detailed description of PAP, see Inside Macintosh: Networking with Open  
Transport and Inside AppleTalk, Second edition.  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkGeneralZIP  
4
The OTCfgATalkGeneralZIPstructure defines parameters for the Zone  
Information Protocol (ZIP) component of the AppleTalk protocol stack and is a  
sub-structure of the OTCfgATalkGeneralstructure.  
struct OTCfgATalkGeneralZIP  
{
UInt16  
UInt16  
UInt32  
fVersion;  
fSize;  
fGetZoneInterval;  
Protocol Structures  
155  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
UInt32  
UInt16  
UInt8  
fZoneListInterval;  
fDDPInfoTimeout;  
fGetZoneRetries;  
fZoneListRetries;  
fChecksumFlag;  
fPad;  
UInt8  
Boolean  
UInt8  
};  
Field descriptions  
fVersion  
Must be 1.  
fSize  
The size in bytes of this structure.  
fGetZoneInterval The “get zone” interval in milliseconds. The default is 2000.  
fZoneListInterval The “zone list” interval in milliseconds. The default is 2000.  
fDDPInfoTimeout  
The “DDP info” timeout in milliseconds. The default is  
4000.  
fGetZoneRetries  
The “get zone” retry limit. The default is 4.  
fZoneListRetries The “zone list” retry limit. The default is 4.  
fChecksumFlag  
fPad  
A pad byte whose value must be zero.  
For a detailed description of ZIP, see Inside AppleTalk, Second edition.  
No preference type is defined for this structure. Instead, access this structure  
through the OTCfgATalkGeneral(page 145) structure, which has a preference  
type of kOTCfgATalkGeneralPref.  
OTCfgATalkLocks  
4
The OTCfgATalkLocksstructure stores information about whether AppleTalk  
preferences have been locked by the administration mode in the control panel.  
struct OTCfgATalkLocks  
{
UInt16 fLocks;  
};  
Field descriptions  
fLocks  
A bit field.  
156  
Protocol Structures  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
The following enumeration defines mask values for the fLocksfield:  
enum {  
kOTCfgATalkPortLockMask  
kOTCfgATalkZoneLockMask  
=
=
0x01,  
0x02,  
0x04,  
0x08,  
0x10  
kOTCfgATalkAddressLockMask =  
kOTCfgATalkConnectionLockMask=  
kOTCfgATalkSharingLockMask =  
};  
Constant descriptions  
kOTCfgATalkPortLockMask  
The bit set by this mask indicates that the port used by  
AppleTalk is locked.  
kOTCfgATalkZoneLockMask  
The bit set by this mask indicates that the AppleTalk zone is  
locked.  
kOTCfgATalkAddressLockMask  
The bit set by this mask indicates that the AppleTalk  
address is locked.  
kOTCfgATalkConnectionLockMask  
The bit set by this mask indicates that the AppleTalk  
Connection pop-up menu is locked.  
kOTCfgATalkSharingLockMask  
Reserved.  
The preference type for the OTCfgATalkLocksstructure is kOTCfgATalkLocksPref,  
which is defined as 'lcks'.  
OTCfgATalkNetworkArchitecture  
4
The OTCfgATalkNetworkArchitecturestructure was used by the Network  
Software Selector in System 7.5.3 through 7.5.5. Despite its name and location,  
this preference controlled both AppleTalk and TCP/IP services.  
struct OTCfgATalkNetworkArchitecture  
{
UInt32 fVersion;  
Protocol Structures  
157  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OSType fNetworkArchitecture;  
};  
typedef struct OTCfgATalkNetworkArchitecture OTCfgATalkNetworkArchitecture;  
Field descriptions  
fVersion  
Must be zero.  
fNetworkArchitecture  
Must be 'OTOn'.  
The preference type for the OTCfgATalkNetworkArchitecturestructure is  
kOTCfgATalkNetworkArchitecturePref, which is defined as 'neta'.  
OTCfgATalkPortDeviceType  
4
The OTCfgATalkPortDeviceTypestructure stores information about the port for  
which AppleTalk is configured. This structure is not used by the AppleTalk  
protocol stack, but it is used by the current AppleTalk control panel.  
struct OTCfgATalkPortDeviceType  
{
UInt16 fDeviceType;  
};  
Field descriptions  
fDeviceType  
The Open Transport device type (such as  
kOTEthernetDevice) or an ADEV ID for the current port.  
The preference type for the OTCfgATalkPortDeviceTypestructure is  
kOTCfgATalkPortDeviceTypePref, which is defined as 'ptfm'.  
Infrared Structures  
4
This section describes structure that stores Infrared preferences. The structure is  
I OTCfgIRGeneral(page 159)  
158  
Protocol Structures  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgIRGeneral  
4
The OTCfgIRGeneralstructure stores per-connection infrared settings.  
struct OTCfgIRGeneral  
{
UInt32  
fVersion;  
fPortRef;  
OTPortRef  
OTCfgIRPortSettingfPortSetting;  
Boolean  
Boolean  
fNotifyOnDisconnect;  
fDisplayIRControlStrip;  
};  
Field descriptions  
fVersion  
Must be zero.  
fPortRef  
Reference to the infrared port.  
OTCfgIRPortSetting A value that specifies the infrared protocol. For possible  
values, see the OTCfgIRPortSetting(page 174) enumeration.  
fNotifyOnDisconnect  
TRUEif the user is to be notified when the IrDA protocol  
disconnects; otherwise, FALSE.  
fDisplayIRControlStrip  
TRUEif the Infrared control strip is to be displayed;  
otherwise, FALSE.  
The preference type for the OTCfgIRGeneralstructure is kOTCfgIRGeneralPref,  
which is defined as 'atpf'.  
for the protocols that use Network Setup:  
I “TCP/IP Constants and Other Data Types” (page 160)  
I “Apple Remote Access Constants and Other Data Types” (page 163)  
I “Modem Constants and Other Data Types” (page 170)  
Protocol Constants and Other Data Types  
159  
 
       
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
I “AppleTalk Constants and Other Data Types” (page 172)  
I “Infrared Constants and Other Data Types” (page 173)  
TCP/IP Constants and Other Data Types  
4
The following enumeration defines type codes for the TCP/IP preferences.  
enum {  
kOTCfgTCPInterfacesPref  
kOTCfgTCPDeviceTypePref  
kOTCfgTCPRoutersListPref  
kOTCfgTCPSearchListPref  
= 'iitf',  
= 'dtyp',  
= 'irte',  
= 'ihst',  
kOTCfgTCPDNSServersListPref = 'idns',  
kOTCfgTCPSearchDomainsPref = 'isdm',  
kOTCfgTCPDHCPLeaseInfoPref = 'dclt',  
kOTCfgTCPDHCPClientIDPref  
kOTCfgTCPUnloadAttrPref  
kOTCfgTCPLocksPref  
= 'dcid',  
= 'unld',  
= 'stng',  
= 'crpt',  
kOTCfgTCPPushBelowIPPref  
kOTCfgTCPPushBelowIPListPref= 'blip',  
};  
Constant descriptions  
kOTCfgTCPInterfacesPref  
Preference type for the OTCfgTCPInterfacesUnpacked  
(page 112) structure.  
kOTCfgTCPDeviceTypePref  
Preference type for the TCP device type. Constants are  
defined in Inside Macintosh: Networking with Open Transport  
available at http://developer.apple.com/techpubs/mac/  
NetworkingOT/NetworkingWOT-2.html.  
kOTCfgTCPRoutersListPref  
Preference type for the OTCfgTCPRoutersList(page 119)  
structure.  
kOTCfgTCPSearchListPref  
Preference type for the OTCfgTCPSearchList(page 120)  
structure.  
160  
Protocol Constants and Other Data Types  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOTCfgTCPDNSServersListPref  
Preference type for the OTCfgTCPDNSServersList(page 116)  
structure.  
kOTCfgTCPSearchDomainsPref  
Preference type for the OTCfgTCPSearchDomains(page 120)  
structure.  
kOTCfgTCPDNSServersListPref  
Preference type for the OTCfgTCPDNSServersList(page 116)  
structure.  
kOTCfgTCPDHCPLeaseInfoPref  
Preference type for the OTCfgTCPDHCPLeaseInfo(page 115)  
structure.  
kOTCfgTCPDHCPClientIDPref  
Preference type for the DHCP client ID, stored as a Pascal  
string.  
kOTCfgTCPUnloadAttrPref  
Preference type for the OTCfgTCPUnloadAttr(page 121)  
structure.  
kOTCfgTCPLocksPref Preference type for the OTCfgTCPLocks(page 116) structure.  
kOTCfgTCPPushBelowIPPref  
Preference type for a Pascal string containing the name of a  
module to be pushed below IP.  
kOTCfgTCPPushBelowIPListPref  
Preference type for a list of modules to be pushed below IP  
in ‘STR#resource format.  
Masks for the kOTCfgProtocolOptionsPref Preference  
4
The following enumeration defines masks for the kOTCfgProtocolOptionsPref  
preference when it is in a TCP/IP entity:  
enum {  
kDontDoPMTUDiscoveryMask  
= 0x0001,  
kDontShutDownOnARPCollisionMask = 0x0002,  
kDHCPInformMask  
= 0x0004,  
Protocol Constants and Other Data Types  
161  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOversizeOffNetPacketsMask  
kDHCPDontPreserveLeaseMask  
= 0x0008,  
= 0x0010,  
};  
Constant descriptions  
kDontDoPMTUDiscoveryMask  
If set, this bit turns off path MTU discovery.  
kDontShutDownOnARPCollisionMask  
If set, this bit disables ARP collision shutdown.  
kDHCPInformMask  
If set, this bit enables DHCPINFORM instead of  
DHCPREQUEST.  
kOversizeOffNetPacketsMask  
If set and with path MTU discovery off, this bit disables  
limiting off-network packets to 576 bytes.  
kDHCPDontPreserveLeaseMask  
If set, this bit disables DHCP INIT-REBOOT capability.  
For details about kDHCPInformMaskand kDHCPDontPreserveLeaseMask, see Tech  
Info Library article 58372 available at http://til.info.apple.com/techinfo.nsf/  
artnum/n58372.  
OTCfgTCPConfigMethod  
4
The OTCfgTCPConfigMethodenumeration defines values that indicate how the  
interface acquires an IP address:  
enum UInt8 OTCfgTCPConfigMethod {  
kOTCfgManualConfig,  
kOTCfgRARPConfig,  
kOTCfgBOOTPConfig,  
kOTCfgDHCPConfig,  
kOTCfgMacIPConfig  
};  
Constant descriptions  
kOTCfgManualConfig Use the IP address that is stored in the fIPAddressfield.  
kOTCfgRARPConfig Obtain an address from a RARP server.  
162  
Protocol Constants and Other Data Types  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOTCfgBOOTPConfig Obtain an address from a BOOTP server.  
kOTCfgDHCPConfig Obtain an address from a DHCP server.  
kOTCfgMacIPConfig Configure TCP/IP to use MacIP.  
Note  
The TCP/IP control panel’s “PPP Server” address  
acquisition method is actually implemented by setting  
fConfigMethodto kOTCfgManualConfigand setting  
fIPAddressto zero. N  
Apple Remote Access Constants and Other Data Types  
4
The following enumeration defines constants for the versionfield that appears  
in Apple Remote Access (ARA) structures:  
enum {  
kOTCfgRemoteDefaultVersion = 0x00020003,  
kOTCfgRemoteAcceptedVersion = 0x00010000  
};  
Constant descriptions  
kOTCfgRemoteDefaultVersion  
The version number with which new Remote Access  
preferences should be created.  
kOTCfgRemoteAcceptedVersion  
A version number that is acceptable for existing Remote  
Access preferences.  
ARA Per-Connection Preferences Types  
4
The following enumeration defines per-connection preference types for ARA:  
enum {  
kOTCfgRemoteARAPPref  
kOTCfgRemoteAddressPref  
kOTCfgRemoteChatPref  
kOTCfgRemoteDialingPref  
= 'arap',  
= 'cadr',  
= 'ccha',  
= 'cdia',  
Protocol Constants and Other Data Types  
163  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOTCfgRemoteAlternateAddressPref= 'cead',  
kOTCfgRemoteClientLocksPref  
kOTCfgRemoteClientMiscPref  
kOTCfgRemoteConnectPref  
kOTCfgRemoteUserPref  
= 'clks',  
= 'cmsc',  
= 'conn',  
= 'cusr',  
= 'dass',  
= 'ipcp',  
= 'lcp ',  
= 'logo',  
= 'pass',  
= 'term',  
= 'usmd',  
= 'csec',  
= 'x25 ',  
kOTCfgRemoteDialAssistPref  
kOTCfgRemoteIPCPPref  
kOTCfgRemoteLCPPref  
kOTCfgRemoteLogOptionsPref  
kOTCfgRemotePasswordPref  
kOTCfgRemoteTerminalPref  
kOTCfgRemoteUserModePref  
kOTCfgRemoteSecurityDataPref  
kOTCfgRemoteX25Pref  
};  
Constant descriptions  
kOTCfgRemoteARAPPref  
structure.  
kOTCfgRemoteAddressPref  
'TEXT'format, with a maximum of 255 characters. See also  
OTCfgRemoteConnect(page 127).  
kOTCfgRemoteChatPref  
The preference type for that stores the log sin (chat) script,  
in 'TEXT'format. See also OTCfgRemoteConnect(page 127).  
The preference type for the OTCfgRemoteDialing(page 131)  
structure.  
The preference type for the OTCfgRemoteAlternateAddress  
(page 123) structure.  
The preference type for the OTCfgRemoteClientLocks  
(page 125) structure.  
kOTCfgRemoteClientMiscPref  
The preference type for the OTCfgRemoteClientMisc  
(page 127) structure.  
164  
Protocol Constants and Other Data Types  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOTCfgRemoteConnectPref  
The preference type for the OTCfgRemoteConnect(page 127)  
structure.  
kOTCfgRemoteConnectPref  
The preference type for the OTCfgRemoteConnect(page 127)  
structure.  
kOTCfgRemoteUserPref  
The preference type that stores the user name as a Pascal  
string.  
kOTCfgRemoteDialAssistPref  
The preference type for OTCfgRemoteDialAssist(page 130)  
structure.  
kOTCfgRemoteIPCPPref  
The preference type for the OTCfgRemoteIPCP(page 132)  
structure.  
The preference type for the OTCfgRemoteLCP(page 133)  
structure.  
kOTCfgRemoteLogOptionsPref  
The preference type for the OTCfgRemoteLogOptions  
(page 135) structure.  
kOTCfgRemotePasswordPref  
The preference type for the OTCfgRemotePassword(page 135)  
structure.  
kOTCfgRemoteTerminalPref  
The preference type for the OTCfgRemoteTerminal(page 138)  
structure.  
kOTCfgRemoteUserModePref  
The preference type for the OTCfgRemoteUserMode(page 139)  
structure.  
kOTCfgRemoteSecurityDataPref  
The preference type for a preference that stores data for a  
plug-in security module. The format of the data is  
determined by the security module. For external security  
modules the format of the data is untyped.  
kOTCfgRemoteX25Pref  
The preference type for the OTCfgRemoteX25(page 140)  
structure.  
Protocol Constants and Other Data Types  
165  
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
ARA Global Preference Types  
4
The following enumeration defines global preference types for Apple Remote  
Access (ARA)  
enum {  
kOTCfgRemoteServerLocksPref  
kOTCfgRemoteServerPortPref  
kOTCfgRemoteServerPref  
= 'slks',  
= 'port',  
= 'srvr',  
= 'capt'  
kOTCfgRemoteApplicationPref  
};  
kOTCfgRemoteServerLocksPref  
Defined but not used by ARA.  
kOTCfgRemoteServerPortPref  
The preference type for the OTCfgRemoteServerPort  
(page 137) structure.  
The preference type for the OTCfgRemoteServer(page 136)  
structure.  
kOTCfgRemoteApplicationPref  
The preference type for the OTCfgRemoteApplication  
(page 123) structure.  
OTCfgRemotePPPConnectScript  
4
The OTCfgRemotePPPConnectScriptenumeration defines constants for use in the  
chatModefield of the OTCfgRemoteConnect(page 127) structure:  
typedef UInt32 OTCfgRemotePPPConnectScript;  
enum {  
OTCfgRemotePPPConnectScriptNone = 0,  
OTCfgRemotePPPConnectScriptTerminalWindow = 1,  
OTCfgRemotePPPConnectScriptScript = 2  
};  
166  
Protocol Constants and Other Data Types  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
Constant descriptions  
OTCfgRemotePPPConnectScriptNone  
No connect script is configured.  
OTCfgRemotePPPConnectScriptTerminalWindow  
A terminal window is used to make the connection.  
OTCfgRemotePPPConnectScriptScript  
A chat script is used to make the connection.  
OTCfgRemoteProtocol  
4
The OTCfgRemoteProtocolenumeration defines constant s for use in the  
serialProtocolModefield of the OTCfgRemoteConnect(page 127) structure:  
typedef UInt32 OTCfgRemoteProtocol;  
enum {  
kRemoteProtocolPPP = 1,  
kRemoteProtocolARAP = 2,  
kRemoteProtocolAuto = 3  
};  
Constant descriptions  
kRemoteProtocolPPP The protocol is PPP only.  
kRemoteProtocolARAP  
The protocol is ARAP only.  
kRemoteProtocolAuto  
Auto-detect PPP or ARAP (not supported in ARA 3.5 and  
later).  
AppleTalk Remote Access Protocol (ARAP), an Apple Computer proprietary  
dialup AppleTalk protocol, was developed before the AppleTalk Control  
Protocol (ATCP, an implementation of AppleTalk over PPP) and is now  
deprecated.  
Protocol Constants and Other Data Types  
167  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteLogLevel  
4
The OTCfgRemoteLogLevelstructure defines values for use in the logLevelfield of  
the OTCfgRemoteLogOptions(page 135) structure:  
typedef UInt32 OTCfgRemoteLogLevel;  
enum {  
kOTCfgRemoteLogLevelNormal = 0,  
kOTCfgRemoteLogLevelVerbose = 1  
};  
Constant descriptions  
kOTCfgRemoteLogLevelNormal  
Normal ARA logging.  
kOTCfgRemoteLogLevelVerbose  
Verbose ARA logging.  
OTCfgRemoteDialMode  
4
The OTCfgRemoteRedialModeenumeration defines values for the dialModefield of  
the OTCfgRemoteDialing(page 131) structure:  
typedef UInt32 OTCfgRemoteRedialMode;  
enum {  
kOTCfgRemoteRedialNone,  
kOTCfgRemoteRedialMain,  
kOTCfgRemoteRedialMainAndAlternate  
};  
Constant descriptions  
kOTCfgRemoteRedialNone  
Do not redial if the an attempt to dial fails.  
kOTCfgRemoteRedialMain  
Redial the main number only if an attempt to dial fails.  
kOTCfgRemoteRedialMain  
Redial the main number and the alternate number if an  
attempt to dial fails.  
168  
Protocol Constants and Other Data Types  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgRemoteAnswerMode  
4
The OTCfgRemoteAnswerModeenumeration defines constants for the answerMode  
field of the OTCfgRemoteServerPort(page 137) structure:  
typedef UInt32 OTCfgRemoteAnswerMode;  
enum {  
kAnswerModeOff = 0,  
kAnswerModeNormal = 1,  
kAnswerModeTransfer = 2,  
kAnswerModeCallback = 3  
};  
Constant descriptions  
kAnswerModeOff  
Answering is disabled.  
kAnswerModeNormal Answering is enabled.  
kAnswerModeTransferAnswering as a callback server. This value is not valid for  
the personal server.  
kAnswerModeCallbackAnswering enabled in callback mode.  
OTCfgRemoteNetworkProtocol  
4
The OTCfgRemoteNetworkProtocolenumeration defines constants for the  
networkProtoFlagsfield of the OTCfgRemoteServerPort(page 137) structure:  
typedef UInt32 OTCfgRemoteNetworkProtocol;  
enum {  
kOTCfgNetProtoNone = 0,  
kOTCfgNetProtoIP = 1,  
kOTCfgNetProtoAT = 2,  
kOTCfgNetProtoAny = (kOTCfgNetProtoIP | kOTCfgNetProtoAT)  
};  
Constant descriptions  
kOTCfgNetProtoNone Do not allow any connections.  
kOTCfgNetProtoIP Allow IPCP connections.  
Protocol Constants and Other Data Types  
169  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kOTCfgNetProtoAT Allow AppleTalk connections (ATCP and ARAP).  
kOTCfgNetProtoAny Allow IPCP and AppleTalk connections.  
OTCfgRemoteNetAccessMode  
4
The OTCfgRemoteNetAccessModeenumeration defines constants for the  
netAccessModefield of the OTCfgRemoteServerPort(page 137) structure:  
typedef UInt8 OTCfgRemoteNetAccessMode;  
enum {  
kOTCfgNetAccessModeUnrestricted = 0,  
kOTCfgNetAccessModeThisMacOnly  
};  
Constant descriptions  
kOTCfgNetAccessModeUnrestricted  
The connected client can see other entities on the server’s  
network.  
kOTCfgNetAccessModeThisMacOnly  
The connected client can only see entities on the server  
machine.  
Modem Constants and Other Data Types  
4
The following enumeration defines per-connection preference types for modem  
preferences:  
enum {  
kOTCfgModemGeneralPrefs  
kOTCfgModemLocksPref  
= 'ccl ',  
= 'lkmd',  
= 'mdpw',  
kOTCfgModemAdminPasswordPref  
};  
170  
Protocol Constants and Other Data Types  
 
     
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
Constant descriptions  
kOTCfgModemGeneralPrefs  
The preference type for the OTCfgModemGeneral(page 141)  
structure.  
kOTCfgModemLocksPref  
The preference type for the OTCfgModemLocks(page 143)  
structure.  
kOTCfgModemAdminPasswordPref  
Preference type for the preference that contains the  
administration password.  
Modem Global Preference Types  
4
The following enumeration defines the global preference type for modem  
preferences:  
enum {  
kOTCfgModemApplicationPref  
= 'mapt',  
};  
Constant descriptions  
kOTCfgModemApplicationPref  
Preference type for the OTCfgModemApplication(page 142)  
structure.  
OTCfgModemDialingToneMode  
4
The OTCfgModemDialogToneModeenumeration defines constants for the  
modemDialToneModefield of the OTCfgModemGeneral(page 141) structure:  
typedef UInt32 OTCfgModemDialogToneMode;  
enum {  
kModemDialToneNormal,  
Protocol Constants and Other Data Types  
171  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
kModemDialToneIgnore,  
kModemDialToneManual  
};  
Constant descriptions  
kModemDialToneNormalWait for dial tone.  
kModemDialToneIgnoreDo not wait for dial tone.  
kModemDialToneManualManual dialing.  
AppleTalk Constants and Other Data Types  
4
The following enumerations define masks for the kOTCfgProtocolOptionsPref  
preference when used in an AppleTalk entity:  
enum {  
kOTCfgATalkNoBadRouterUpNotification  
kOTCfgATalkNoAllNodesTakenNotification  
kOTCfgATalkNoFixedNodeTakenNotification  
= 1 << 0,  
= 1 << 1,  
= 1 << 2,  
kOTCfgATalkNoInternetAvailableNotification = 1 << 3,  
kOTCfgATalkNoCableRangeChangeNotification  
kOTCfgATalkNoRouterDownNotification  
kOTCfgATalkNoRouterUpNotification  
= 1 << 4,  
= 1 << 5,  
= 1 << 6,  
= 1 << 7,  
kOTCfgATalkNoFixedNodeBadNotification  
};  
Each bit determines whether the AppleTalk protocol stack posts notifications for  
the corresponding network event.  
Per-connection AppleTalk Preference Types  
4
The following enumeration defines constants for per-connection AppleTalk  
preference types:  
172  
Protocol Constants and Other Data Types  
 
 
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
enum {  
kOTCfgATalkGeneralPref  
kOTCfgATalkLocksPref  
= 'atpf',  
= 'lcks',  
kOTCfgATalkPortDeviceTypePref= 'ptfm',  
};  
Global AppleTalk Preference Types  
4
The following enumeration defines constants for global AppleTalk preference  
types:  
enum {  
kOTCfgATalkNetworkArchitecturePref = 'neta'  
};  
Infrared Constants and Other Data Types  
4
The following enumeration defines type codes for infrared preferences.  
enum {  
kOTCfgTypeInfraredPrefs  
kOTCfgTypeInfraredGlobal  
= 'atpf',  
= 'irgo'  
};  
Constant descriptions  
kOTCfgTypeInfraredPrefs  
Type code for a preference that contains per-connection  
infrared settings.  
kOTCfgTypeInfraredGlobal  
Type code for a preference that contains global infrared  
settings.  
Protocol Constants and Other Data Types  
173  
 
   
C H A P T E R  
4
Network Setup Protocol Structures and Data Types  
OTCfgIRPortSetting  
4
The OTCfgIRPortSettingenumeration defines constants for use in the  
OTCfgIRPortSettingfield of the OTCfgIRGeneral(page 159) structure:  
typedef UInt16 OTCfgIRPortSetting;  
enum {  
kOTCfgIRIrDA = 0,  
kOTCfgIRIRTalk = 1  
};  
Constant descriptions  
kOTCfgIRIrDA  
Specifies the Infrared Data Association (IrDA) protocol.  
kOTCfgIRIRTalk  
Specifies the IRTalk protocol, Apple’s proprietary Infrared  
protocol that was developed prior to the development of  
IrDA.  
174  
Protocol Constants and Other Data Types  
 
 
Glossary  
AARP See AppleTalk Address Resolution  
Protocol.  
AppleTalk Transaction Protocol (ATP)  
transport protocol that provides loss-free  
transaction service between sockets. This  
service allows exchanges between two  
socket clients in which one client requests  
the other to perform a particular task and to  
report the results. ATP binds the request and  
response together to ensure the reliable  
exchange of request-response pairs.  
A
Address Resolution Protocol (ARP) The  
Internet protocol that maps an IP address to  
a MAC address.  
Apple Remote Access (ARA) The  
mechanism by which computers running  
Mac OS connect to remote sites.  
AppleTalk Address Resolution Protocol  
(AARP) The protocol that reconciles  
addressing discrepancies in networks that  
support more than one set of protocols. For  
example, by resolving the differences  
between an Ethernet addressing scheme and  
the AppleTalk addressing scheme, AARP  
facilitates the transport of DDP packets over  
a high-speed EtherTalk connection.  
ARA See Apple Remote Access.  
area The highest level of organization in  
the Network Setup database. Areas contain  
entities. See also entity, named area,  
temporary area.  
ASP See AppleTalk Session Protocol.  
ATCP See AppleTalk Control Protocol.  
ATP See AppleTalk Transaction Protocol.  
AppleTalk Control Protocol (ATCP) The  
protocol that establishes and configures  
AppleTalk over PPP.  
Bootstrap Protocol The protocol used by a  
node to obtain the IP address of its Ethernet  
interfaces from another node on the  
network, thereby allowing the first node to  
boot without local storage media.  
AppleTalk Data Stream Protocol  
(ADSP) A connection-oriented protocol  
that provides a reliable, full-duplex, byte  
stream service between any two sockets in  
an AppleTalk network. ADSP ensures  
in-sequence, duplicate-free delivery of data  
over its connections.  
BOOTP See Bootstrap Protocol.  
current area The area in which  
preferences are stored. Another name for the  
default area.  
AppleTalk Session Protocol (ASP)  
A
database reference A value that represents  
the open session with the Network Setup  
database.  
general-purpose protocol that uses ATP to  
provide session establishment, maintenance,  
and teardown, along with request  
sequencing.  
175  
 
 
G L O S S A R Y  
Datagram Delivery Protocol (DDP) The  
network-layer protocol that is responsible  
for the socket-to-socket delivery of  
Internet Control Message Protocol  
(ICMP) A network-layer Internet protocol  
that reports errors and provides other  
information relevant to IP packet  
processing.  
datagrams over an AppleTalk network.  
DDP See Datagram Delivery Protocol.  
Internet Protocol (IP) 1) A set of protocols  
including TCP, UDP, and ICMP. IP provides  
features for addressing, type-of-service  
specification, fragmentation and reassembly,  
and security. 2) An IP network-layer  
protocol offering a connectionless  
default area The preferred name for the  
area in which preferences are stored.  
Another name for the current area.  
DHCP See Dynamic Host Configuration  
Protocol.  
internetwork service.  
DNS See Domain Name System.  
Internetwork Packet Exchange (IPX)  
network-layer protocol used for transferring  
data between clients and servers.  
A
Domain Name System (DNS) The system  
used on the Internet for translating the name  
of a network node to an IP address.  
IP See Internet Protocol.  
Dynamic Host Configuration Protocol  
mechanism for assigning an IP address  
dynamically so that the address can be  
reassigned when the original assignee no  
longer needs it.  
A
IP Control Protocol (IPCP) The protocol  
that establishes and configures IP over PPP.  
IPCP See IP Control Protocol.  
IPX See Internetwork Packet Exchange.  
entity The unit of organization within an  
entity. See also global protocol entity,  
network connection entity, set entity.  
ITU-T See International  
Telecommunication Union  
Telecommunication Standardization Sector.  
global protocol entity An entity that  
contains information shared by all  
connections for a particular protocol.  
LCP See Link Control Protocol.  
Link Control Protocol (LCP) The protocol  
that establishes, configures, and tests  
data-link connections for use by PPP.  
ICMP See Internet Control Message  
Protocol.  
International Telecommunication Union  
Telecommunication Standardization  
Sector An international body that  
develops worldwide standards for  
telecommunications technologies.  
MAC address See media access control  
address.  
MacIP A network-layer protocol that  
encapsulates IP packets in DDP packets for  
transmission over AppleTalk and that also  
provides proxy ARP services.  
maximum transmission unit (MTU) The  
maximum number of bytes in a packet.  
176  
 
G L O S S A R Y  
media access control address The six-byte  
data link layer address that is required for  
every device that connects to a network.  
Other devices in the network use MAC  
addresses to locate devices on the network  
and to create and update routing tables.  
Printer Access Protocol (PAP) The  
AppleTalk protocol that manages interaction  
between computers and print servers; PAP  
handles connection setup, maintenance, and  
termination, as well as data transfer.  
proxy ARP A variation of the ARP  
protocol in which an intermediate device  
(such as a router) sends an ARP response to  
the requesting host on behalf of the node  
whose MAC address was requested.  
MTU See maximum transmission unit.  
Name Binding Protocol (NBP) The  
AppleTalk transport-layer protocol that  
translates a character string name to the  
address of the corresponding socket client;  
NBP enables AppleTalk protocols to  
understand user-defined zones and device  
names by providing and maintaining  
translation tables that map names to  
corresponding socket addresses.  
RARP See Reverse Address Resolution  
Protocol.  
Reverse Address Resolution Protocol  
(RARP) The Internet protocol that maps  
MAC addresses to IP addresses.  
Routing Table Maintenance Protocol  
(RTMP) The AppleTalk protocol used to  
establish and maintain the routing  
information that is required by routers in  
order to route datagrams from any source  
socket to any destination socket on the  
network. Using RTMP, routers dynamically  
maintain routing tables to reflect changes in  
network topology.  
named area An area in which preferences  
are stored.  
NBP See Name Binding Protocol.  
network connection entity An entity that  
contains information for a single instance of  
a network protocol.  
PAP See Printer Access Protocol.  
PPP See Point-to-Point Protocol.  
RTMP See Routing Table Maintenance  
Protocol.  
Point-to-Point Protocol (PPP) A protocol  
that provides host-to-network connections  
over synchronous and asynchronous  
circuits. PPP was designed to work with  
several network-layer protocols, such as IP,  
IPX, and ARA.  
set entity An entity that is used to group  
global and network connection entities for a  
particular purpose. For example, a set entity  
can be used to group AppleTalk and TCP/IP  
configurations for a particular location, such  
as home or work.  
preference The unit of organization  
within an entity. Each preference  
TCP See Transmission Control Protocol/  
corresponds to a structure containing the  
settings for a particular protocol.  
Internet Protocol.  
TCP/IP See Transmission Control  
preference type An OSTypethat identifies a  
Protocol/Internet Protocol.  
particular preference.  
177  
 
G L O S S A R Y  
temporary area An area that is created  
when a named area is modified.  
Transmission Control Protocol/Internet  
Protocol A connection-oriented  
transport-layer Internet protocol that  
provides reliable full-duplex data  
transmission.  
User Datagram Protocol (UDP)  
A
connectionless transport-layer Internet  
protocol that exchanges datagrams without  
acknowledgments or guaranteed delivery,  
requiring that error processing and  
retransmission be handled by other  
protocols.  
UDP See User Datagram Protocol.  
ZIP See Zone Information Protocol.  
X.25 An ITU-T standard that defines how  
connections are maintained for remote  
terminal access and computer  
communications in public data networks.  
Zone Information Protocol (ZIP) The  
AppleTalk session-layer protocol that  
maintains and discovers the network-wide  
mapping of network number ranges to zone  
names. NBP uses ZIP to determine which  
networks contain nodes that belong to a  
zone.  
178  
 
Index  
areas 62, 65  
A
active set entity  
finding 43–48  
number of 17, 43  
ARA constants 163  
architecture, Network Setup 11–14  
area IDs  
committing changes 20  
comparing 65  
set entities, working with 48  
unique 16  
areas  
closing 62, 65  
counting 68  
creating 70  
deleting 72  
duplicating 71  
getting current 60  
getting name 66  
listing 68  
D
modifying 63  
opening 61, 66  
setting current 61  
setting name 67  
writing modifications 64  
database  
opening 25, 27  
C
CfgEntityInfostructure 99  
CfgEntityRefstructure 98, 99, 100  
CfgPrefsHeaderstructure 100, 101  
CfgSetsElementstructure 103  
CfgSetsStructstructure 101  
CfgSetsVectorstructure 103  
changing entity areas 82  
E
class, entity 16  
classes and types 104  
encrypting data 93  
179  
 
 
I N D E X  
entities  
active, finding 34  
active set 17  
changing 82  
classes 16  
classes and types 104  
closing 85  
counting 73  
creating 76  
deleting 43, 78  
duplicating 78  
getting name 79, 80  
global protocol 16  
IDs, getting 82  
listing 30–34, 74  
network connection 16  
references 16  
OTCfgOpenName 61  
references, comparing 76  
set 16  
OTCfgOpenPrefs 84  
OTCfgSetAreaName 67  
setting name 81  
types 16  
user-visibile names of 16  
OTCfgSetCurrentArea 61  
OTCfgSetEntityName 81  
OTCfgSetPrefs 87  
F
G
functions  
OTCfgAbortAreaModifications 65  
OTCfgBeginAreaModifications 63  
OTCfgChangeEntityArea 82  
OTCfgCloseArea 62  
OTCfgCloseDatabase 58  
OTCfgClosePrefs 85  
OTCfgCreateArea 70  
OTCfgCreateEntityArea 76  
OTCfgDecrypt 93  
OTCfgDeleteArea 72, 78  
OTCfgDuplicateArea 71  
OTCfgDuplicateEntity 78  
OTCfgEncrypt 93  
OTCfgGetAreaName 66  
OTCfgGetAreasCount 68  
OTCfgGetAreasList 68  
OTCfgGetCurrentArea 60  
I
icons 17  
infrared constants 173  
iterating preferences 40–41  
180  
 
I N D E X  
OTCfgAbortAreaModificationsfunction 65  
OTCfgATalkGeneralAARPstructure 146  
OTCfgATalkGeneralADSPstructure 147  
OTCfgATalkGeneralASPstructure 149  
OTCfgATalkGeneralATPstructure 150  
OTCfgATalkLocksstructure 156  
OTCfgATalkNetworkArchictecture  
structure 157  
OTCfgATalkPortDeviceTypestructure 158  
OTCfgBeginAreaModificationsfunction 63  
OTCfgChangeEntityAreafunction 82  
OTCfgChgGetEntitiesListfunction 74  
OTCfgChgGetEntityAreafunction 82  
OTCfgCloseDatabasefunction 58  
OTCfgClosePrefsfunction 85  
K
kOTCfgClassNetworkConnectionclass 30  
kOTCfgSetsStructPrefpreference 43  
kOTCfgSetsVectorPrefpreference 43  
L
legacy  
preference files 13  
synchronization 15, 21, 22–23, 43  
library, Network Setup 14–15  
listing entities 30–34, 74  
low-level database 15  
M
OTCfgCreateEntityAreafunction 76  
OTCfgDecryptfunction 93  
mid-level database 15  
modem constants 170  
multihoming 12, 43  
OTCfgDuplicateAreafunction 71  
N
OTCfgGetAreaNamefunction 66  
named areas 16  
network connection entities 16  
Network Setup  
constants 106–109  
library 13, 14–15  
notification routine  
installing 94  
OTCfgGetCloseAreafunction 62  
OTCfgGetCreateAreafunction 70  
OTCfgGetCurrentAreafunction 60  
OTCfgGetDefaultfunction 90  
OTCfgGetDeleteAreafunction 72  
OTCfgGetEntitiesCountfunction 73  
OTCfgGetPrefsSizefunction 85  
OTCfgGetPrefsTOCCountfunction 88  
OTCfgGetPrefsTOCfunction 89  
OTCfgGetSurrentAreafunction 61  
OTCfgGetTemplatefunction 91  
removing 96  
O
opening  
areas 61, 66  
database 25–27, 58  
preferences 84  
OTCfgInstallNotifierfunction 94, 96  
181  
 
I N D E X  
OTCfgIRGeneralstructure 159  
OTCfgIsSameAreaIDfunction 65  
P
OTCfgIsSameEntityReffunction 76  
OTCfgModemApplicationstructure 141, 142  
OTCfgModemLocksstructure 143  
packing TCP/IP interface preferences 50–51  
preferences  
coherency 21  
OTCfgOpenAreafunction 66  
OTCfgOpenDatabasefunction 58  
OTCfgOpenNamefunction 61  
size of 85  
OTCfgOpenPrefsfunction 84  
OTCfgRemoteAlternateAddressstructure 123  
OTCfgRemoteApplicationstructure 123  
OTCfgRemoteARAPstructure 124  
OTCfgRemoteClientLocksstructure 125  
OTCfgRemoteClientMiscstructure 127  
OTCfgRemoteConnectstructure 127  
OTCfgRemoteDialAssiststructure 130  
OTCfgRemoteDialingstructure 131  
OTCfgRemoteIPCPstructure 132  
OTCfgRemoteLCPstructure 133  
OTCfgRemoteLogOptionsstructure 135  
OTCfgRemotePasswordstructure 135  
OTCfgRemoteServerPortstructure 137  
OTCfgRemoteServerstructure 136  
OTCfgRemoteTerminalstructure 138  
OTCfgRemoteUserModestructure 139  
OTCfgRemoteX25structure 140  
OTCfgSetAreaNamefunction 67  
OTCfgSetEntityNamefunction 81  
OTCfgSetPrefsfunction 87  
OTCfgTCPDNSServersListstructure 116  
OTCfgTCPInterfacesPackedPartstructure 114  
OTCfgTCPInterfacesPackedstructure 114  
OTCfgTCPInterfacesUnpackedstructure 112  
OTCfgTCPLocksstructure 116  
OTCfgTCPRoutersListEntrystructure 119  
OTCfgTCPRoutersListstructure 119  
OTCfgTCPSearchDomainsstructure 120  
OTCfgTCPSearchListstructure 120  
OTCfgTCPUnloadAttrstructure 121  
OTCfgWritingAreaModificationsfunction 64  
R
reading  
fixed-size preferences 35–37  
getting 89  
Remote Access preferences 53–54  
resource files 12  
result codes 110  
S
sample database structure 17–19  
scripting 13  
182  
 
I N D E X  
set entities 16  
active, number of 43  
using 42–49  
setting entity names 81  
structures  
CfgEntityInfo 99  
CfgEntityRef 98, 99, 100  
CfgPrefsHeader 100, 101  
CfgSetsElement 103  
CfgSetsStruct 101  
CfgSetsVector 103  
OTCfgATalkGeneral 145  
OTCfgATalkGeneralAARP 146  
OTCfgATalkGeneralADSP 147  
OTCfgATalkGeneralASP 149  
OTCfgATalkGeneralATP 150  
OTCfgATalkGeneralDDP 151  
OTCfgATalkGeneralNBP 153  
OTCfgATalkGeneralPAP 154  
OTCfgATalkGeneralZIP 155  
OTCfgATalkLocks 156  
T
preferences 49–53  
OTCfgATalkNetworkArchictecture 157  
OTCfgATalkPortDeviceType 158  
OTCfgDHCPLeaseInfo 115  
OTCfgIRGeneral 159  
OTCfgModemApplication 141, 142  
OTCfgModemLocks 143  
unpacking TCP/IP interface preferences 52–53  
OTCfgRemoteAlternateAddress 123  
OTCfgRemoteApplication 123  
OTCfgRemoteARAP 124  
OTCfgRemoteClientLocks 125  
OTCfgRemoteClientMisc 127  
OTCfgRemoteConnect 127  
OTCfgRemoteDialAssist 130  
OTCfgRemoteDialing 131  
OTCfgRemoteIPCP 132  
W
OTCfgRemoteLCP 133  
OTCfgRemoteLogOptions 135  
OTCfgRemotePassword 135  
OTCfgRemoteServer 136  
OTCfgRemoteServerPort 137  
OTCfgRemoteTerminal 138  
OTCfgRemoteUserMode 139  
OTCfgRemoteX25 140  
preferences 39–40  
OTCfgTCPDNSServersList 116  
183  
 
I N D E X  
184  
 

Accton Technology Switch VM2524 User Manual
AC International Styling Iron AC8TC User Manual
ADTRAN Network Router 1200263L1 12A User Manual
ADT Security Services Automobile Alarm FOCUS 200 PLUS User Manual
Amana Microwave Oven AMV5164BA BC User Manual
American Standard Indoor Furnishings 0066000 User Manual
Avenview TV Cables C COMPVGA HDM User Manual
Axis Communications Home Theater Server AXIS 240Q User Manual
Barco Network Router 3G HD SD SD User Manual
Beckett Water Gardening Outdoor Fountain BL25LED User Manual