I N S I D E M A C I N T O S H
Network Setup
© Apple Computer, Inc. 2000
Contents
Figures, Tables, and Listings
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
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
Writing Preferences
Finding the Active Set Entity
TCP/IP Notes 49
Remote Access Notes
Modem Notes 54
Notes for Third Parties
53
55
Storing Third-party Preferences in Apple Entities
55
57
Preference Utilities
Wildcard Classes and Types
Common Preference Types
Global Preference Types
Backward Compatibility Preference Types
OTCfgUserMode Preference 109
Invalid Area ID 109
Result Codes 110
108
4
6
Figures, Tables, and Listings
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 Setup in Mac OS 8.5 through the present
12
13
Future Network Setup architecture
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
Reading the DHCP lease info preference in a TCP/IP network
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
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),
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
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
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
example, a single network connection entity can be referenced by multiple sets.
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
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
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.
modifying the database.
temporary area to the database.
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
not exist or does not match the writeAreaIDreferred to by
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
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
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
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:
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
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
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.
entity.
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
Network Setup Reference
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;
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.
TCP/IP preferences.
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
I OTCfgTCPInterfacesPacked(page 114) stores information about the configured
TCP/IP interfaces in packed format.
framing information for TCP/IP interfaces in packed format.
locked.
(page 119) structures.
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
the personal server.
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
This section describes the structures that store AppleTalk preferences. The
structures are
preferences for each AppleTalk protocol.
Address Resolution protocol (AARP).
Stream Protocol (ADSP).
Session Protocol (ASP).
Transaction Protocol (ATP).
Delivery Protocol (DDP).
Protocol (NBP).
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 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
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
fDefaultALOSetting The default “at least once” (ALO) setting. The default value
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
OTCfgInstallNotifier 94, 96
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
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
OTCfgOpenPrefsfunction 84
OTCfgRemoteAlternateAddressstructure 123
OTCfgRemoteApplicationstructure 123
OTCfgRemoteARAPstructure 124
OTCfgRemoteClientLocksstructure 125
OTCfgRemoteClientMiscstructure 127
OTCfgRemoteConnectstructure 127
OTCfgRemoteDialAssiststructure 130
OTCfgRemoteDialingstructure 131
OTCfgRemoteIPCPstructure 132
record headers
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
record headers
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
|