Apple INSIDE MACIN TOSH User Manual

0 (0)
© Apple Computer, Inc. 2000
INSIDE MACINTOSH
Network Setup
Apple Computer, Inc.
© 2000 Apple Computer, Inc.
All rights reserved.
No part of this publication may be
reproduced, stored in a retrieval
system, or transmitted, in any form
or by any means, mechanical,
electronic, photocopying, recording,
or otherwise, without prior written
permission of Apple Computer, Inc.,
except to make a backup copy of any
documentation provided on
CD-ROM.
The Apple logo is a trademark of
Apple Computer, Inc.
Use of the “keyboard” Apple logo
(Option-Shift-K) for commercial
purposes without the prior written
consent of Apple may constitute
trademark infringement and unfair
competition in violation of federal
and state laws.
No licenses, express or implied, are
granted with respect to any of the
technology described in this book.
Apple retains all intellectual
property rights associated with the
technology described in this book.
This book is intended to assist
application developers to develop
applications only for Apple-labeled
or Apple-licensed computers.
Every effort has been made to ensure
that the information in this manual is
accurate. Apple is not responsible for
typographical errors.
Apple Computer, Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, and
Macintosh are trademarks of Apple
Computer, Inc., registered in the
United States and other countries.
Adobe, Acrobat, and PostScript are
trademarks of Adobe Systems
Incorporated or its subsidiaries and
may be registered in certain
jurisdictions.
Helvetica and Palatino are registered
trademarks of Linotype-Hell AG
and/or its subsidiaries.
ITC Zapf Dingbats is a registered
trademark of International Typeface
Corporation.
Simultaneously published in the
United States and Canada.
Even though Apple has reviewed this
manual, APPLE MAKES NO
WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH
RESPECT TO THIS MANUAL, ITS
QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. AS A
RESULT, THIS MANUAL IS SOLD “AS
IS,” AND YOU, THE PURCHASER, ARE
ASSUMING THE ENTIRE RISK AS TO
ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE
FOR DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL
DAMAGES RESULTING FROM ANY
DEFECT OR INACCURACY IN THIS
MANUAL, even if advised of the
possibility of such damages.
THE WARRANTY AND REMEDIES
SET FORTH ABOVE ARE EXCLUSIVE
AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED.
No Apple dealer, agent, or employee is
authorized to make any modification,
extension, or addition to this warranty.
Some states do not allow the exclusion or
limitation of implied warranties or
liability for incidental or consequential
damages, so the above limitation or
exclusion may not apply to you. This
warranty gives you specific legal rights,
and you may also have other rights
which vary from state to state.
3

Contents

Figures, Tables, and Listings 7
Preface
About This Manual
9
Conventions Used in This Manual 9
For More Information 10
Chapter 1
About Network Setup
11
Network Setup Architecture 11
Inside the Network Setup Library 14
Network Setup Database Fundamentals 16
Database Structure 16
Database Structure Example 17
Database Operations 19
Preference Coherency 21
Legacy Issues 21
Legacy Synchronization Algorithm 22
Network Setup Version History 23
Chapter 2
Using Network Setup
25
Opening and Closing the Network Setup Database 25
Opening the Database for Reading 25
Opening the Database for Writing 26
Closing the Database After Reading 28
Closing the Database After Writing 28
Working with Entities 30
Listing All Entities 30
Finding an Active Entity 34
Reading and Writing Preferences 34
Reading Fixed-size Preferences 35
Reading Variable-size Preferences 37
4
Writing Preferences 39
Iterating the Preferences in an Entity 40
Working with Sets 42
Finding the Active Set Entity 43
Areas and Sets 48
Protocol-specific Topics 49
TCP/IP Notes 49
Remote Access Notes 53
Modem Notes 54
Notes for Third Parties 55
Storing Third-party Preferences in Apple Entities 55
Network Setup and Third-party Protocol Stacks 55
Chapter 3
Network Setup Reference
57
Network Setup Functions 57
Opening and Closing the Network Setup Database 57
Managing Areas 59
Managing Entities 72
Managing Preferences 83
Preference Utilities 92
Installing and Removing a Notification Callback 94
Application-Defined Routines 96
Network Setup Structures and Data Types 97
Network Setup Constants 104
Entity Classes and Types 104
Wildcard Classes and Types 105
Common Preference Types 106
Per-connection Preference Types 106
Global Preference Types 107
Set Entity Preference Types 108
Backward Compatibility Preference Types 108
Global Backward Compatibility Preference Types 108
OTCfgUserMode Preference 109
Invalid Area ID 109
Result Codes 110
5
Chapter 4
Network Setup Protocol Structures and Data Types
111
Protocol Structures 111
TCP/IP Structures 111
Apple Remote Access Structures 122
Modem Structures 141
AppleTalk Structures 144
Infrared Structures 158
Protocol Constants and Other Data Types 159
TCP/IP Constants and Other Data Types 160
Apple Remote Access Constants and Other Data Types 163
Modem Constants and Other Data Types 170
AppleTalk Constants and Other Data Types 172
Infrared Constants and Other Data Types 173
Glossary
175
Index
179
6
7

Figures, Tables, and Listings

Chapter 1
About Network Setup
11
Figure 1-1
Network configuration prior to Network Setup 12
Figure 1-2
Network Setup in Mac OS 8.5 through the present 13
Figure 1-3
Future Network Setup architecture 14
Figure 1-4
Structure of the Network Setup Library 15
Figure 1-5
Sample organization of the default area 18
Figure 1-6
Reading and writing the default area 20
Table 1-1
Network Setup versions 23
Chapter 2
Using Network Setup
25
Figure 2-1
Set entities reference other entities 42
Listing 2-1
Opening the database for reading 26
Listing 2-2
Opening the database for writing 27
Listing 2-3
Closing the database after reading 28
Listing 2-4
Closing the database after writing 29
Listing 2-5
Finding all entities of a particular class and type 31
Listing 2-6
Printing the user-visible name for an entity 33
Listing 2-7
Reading a fixed-size preference 35
Listing 2-8
Reading the DHCP lease info preference in a TCP/IP network
connection entity 36
Listing 2-9
Reading the user-visible name preference 37
Listing 2-10
Calling OTCfgGetPrefsSize to read a variable-size preference 38
Listing 2-11
Writing a preference 39
Listing 2-12
Printing an entity’s table of contents 40
Listing 2-13
Finding the active set entity 44
Listing 2-14
Finding the active entity of a given class and type 46
Listing 2-15
Finding the active TCP/IP entity 47
Listing 2-16
Packing and unpacking the kOTCfgTCPInterfacesPref
preference 50
Listing 2-17
Encrypting the user’s password 54
8
9
PREFACE

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.
IMPORTANT
Text set off in this manner—with the word Important—
presents important information or instructions.
WARNING
Text set off in this manner—with the word Warning—
indicates potentially serious problems.
10
PREFACE

For More Information 0

The following sources provide additional information that may be of interest to
developers who use the Network Setup programming interface:
Inside AppleTalk,
Second Edition.
Inside Macintosh: Networking with Open Transport.
Open Transport Advanced Client Programming,
available at
http://developer.apple.com/macos/opentransport/OTAdvancedClientProg/
OTAdvancedClientProg.html

Network Setup Architecture

11
CHAPTER 1

About Network Setup 1

Figure 1-0
Listing 1-0
Table 1-0
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.
CHAPTER 1
About Network Setup
12
Network Setup Architecture
Figure 1-1
Network configuration prior to Network Setup
The architecture shown in Figure 1-1 had a number of drawbacks:
There was a control panel for each protocol type, leading to an unnecessary
proliferation of control panels.
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.
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.
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.
TCP/IP
TCP/IP
protocol
stack
TCP/IP preferences
Control panels
Private interface
Private
preferences files
AppleTalk
AppleTalk
protocol
stack
AppleTalk preferences
Remote Access,
Modem,
Dial Assist,
Infrared, ...
CHAPTER 1
About Network Setup
Network Setup Architecture
13
Figure 1-2
Network Setup in Mac OS 8.5 through the present
The following key points are to be taken from Figure 1-2:
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.
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.
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.
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
scripting
Legacy
control
panels
Legacy
protocol
stacks
Legacy
preferences
files
Network Setup library
Third-party
application
TCP/IP
TCP/IP
TCP/IP
TCP/IP
Protocol
Stack
TCP/IP
Protocol
Stack
TCP/IP
Protocol
Stack
Public interface
Network Setup database
Network Setup
aware applications
CHAPTER 1
About Network Setup
14

Inside the Network Setup Library

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
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.
Updated
protocol
stacks
Network Setup library
TCP/IP
Protocol
Stack
TCP/IP
Protocol
Stack
TCP/IP
Protocol
Stack
Public interface
Network Setup database
Network Setup
aware applications
Network
control
panel
Network
Setup
scripting
Third-party
application
CHAPTER 1
About Network Setup
Inside the Network Setup Library
15
Figure 1-4
Structure of the Network Setup Library
As shown in Figure 1-4, the Network Setup library is divided into four key
components:
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.
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
executes the request and manipulates the database. The mid-level database
also interfaces with the legacy synchronization module.
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.
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.
Network Setup
extension
Network Setup
aware applications
High-level framework
Mid-level database (OTCfg)
Low-level database (Cfg)
Legacy
Synchronization
module
CHAPTER 1
About Network Setup
16

Network Setup Database Fundamentals

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:
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.
entity name.
A user-visible name for the entity that need not be unique.
entity class
and
type.
These values, both of type
OSType
, determine the type
of data contained within an entity. There are three entity classes:
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.
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.
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
CHAPTER 1
About Network Setup
Network Setup Database Fundamentals
17
one
active set entity
. The entities referenced by the active set entity
comprise the active network preferences. All set entities have the same
type.
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.
CHAPTER 1
About Network Setup
18
Network Setup Database Fundamentals
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
...
'port' preference
general AppleTalk preference
user-visible name of this port
"Company Ethernet" AppleTalk network protocol entity
'aftp' preference
...
'port' preference
general AppleTalk preference
user-visible name of this port
"AirPort" TCP/IP network protocol entity
'idns' preference
...
'port' preference
"Home" set entity
AppleTalk global protocol entity
"AirPort" TCP/IP network protocol entity
DNS configuration
user-visible name of this port
"LocalTalk for Printer" AppleTalk network protocol entity
TCP/IP global protocol entity
"Work" set entity
AppleTalk global protocol entity
"Work/DHCP" TCP/IP network protocol entity
"Company Ethernet" AppleTalk network protocol entity
TCP/IP global protocol entity
Active
Active
'opts' preference
...
'opts' preference
...
'atfp' preference
...
'port' preference
'aftp' preference
...
'port' preference
'idns' preference
...
'port' preference
AppleTalk global protocol entity
"AirPort" TCP/IP network protocol entity
"LocalTalk for Printer" AppleTalk network protocol entity
TCP/IP global protocol entity
AppleTalk global protocol entity
"Work/DHCP" TCP/IP network protocol entity
"Company Ethernet" AppleTalk network protocol entity
TCP/IP global protocol entity
"Work/DHCP" TCP/IP network protocol entity
'idns' preference
...
'port' preference
DNS configuration
user-visible name of this port
'idns' preference
...
'port' preference
CHAPTER 1
About Network Setup
Network Setup Database Fundamentals
19
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:
“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.
“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.
“Work/DHCP,” a TCP/IP network connection entity which configures a
TCP/IP interface to use DHCP over the Ethernet port.
“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:
“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.
“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
CHAPTER 1
About Network Setup
20
Network Setup Database Fundamentals
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
themselves for the new configuration.
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
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.”
Reading
Open for reading
Close for reading
Default area
Default area
being read
Default area
Open for write
Commit
Writing
Default area
Temporary area
being written
Updated default area
abort
CHAPTER 1
About Network Setup

Legacy Issues

21

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:
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.
Legacy preferences files do not support multihoming.
CHAPTER 1
About Network Setup
22 Legacy Issues
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:
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.
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:
A resource having a well known resource type ('cnam').
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.
There is one fixed resource whose type is 'ccfg' and whose ID is 1 that
contains the resource ID of the active configuration.
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
CHAPTER 1
About Network Setup
Network Setup Version History 23
entity, it creates a resource containing the preference data with the resource type
matching the preference type and the resource ID the same as the 'cnam'
resource.
Network Setup uses a number of private preferences to ensure a reliable round
trip conversion between legacy preferences files and the database. The
preference types are described in “Common Preference Types” (page 106), but
your application should not depend on their presence, their content, or their
semantics.
If you find undocumented preferences (such as a preference of type 'vers') in a
global protocol entity, do not be concerned. Network Setup itself does not
actually look at the data as it imports from and exports to legacy preferences
files.
Network Setup Version History 1
Table 1-1 summarizes the different versions of Network Setup, their features,
and their release vehicles.
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.”
Table 1-1 Network Setup versions
Version Mac OS version New features
1.0 Mac OS 8.5
1.0.1 Not released
OTCfgGetAreaName
1.0.2 Mac OS 8.6 OTCfgInstallNotifier,
OTCfgRemoveNotifier
1.1 Not released OTCfgEncrypt,
OTCfgDecrypt
1.1.1 Mac OS 9.0
CHAPTER 1
About Network Setup
24 Network Setup Version History

Opening and Closing the Network Setup Database 25

CHAPTER 2

Using Network Setup 2

Figure 2-0
Listing 2-0
Table 2-0
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 MyOpenDatabaseForReading routine 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 MyOpenDatabaseForReading routine 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.
CHAPTER 2
Using Network Setup
26 Opening and Closing the Network Setup Database
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 MyOpenDatabaseForWriting routine 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 OTCfgOpenArea to open the area for reading, the routine calls
OTCfgBeginAreaModifications to open the area for writing.
The OTCfgBeginAreaModifications function returns another area identifier that
references a writable temporary area. The MyOpenDatabaseForWriting routine
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
CHAPTER 2
Using Network Setup
Opening and Closing the Network Setup Database 27
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;
}
CHAPTER 2
Using Network Setup
28 Opening and Closing the Network Setup Database

Closing the Database After Reading 2

The MyCloseDatabaseAfterReading routine shown in Listing 2-3 shows how to
close the database after you are done reading from it. The routine simply calls
OTCfgCloseArea to close the read area and then calls OTCfgCloseDatabase to 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 assert macro
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 MyCloseDatabaseAfterWriting routine 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 commit is 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.
CHAPTER 2
Using Network Setup
Opening and Closing the Network Setup Database 29
If commit is false, the routine calls OTCfgAbortAreaModifications to 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 MyCloseDatabaseAfterReading shown in Listing 2-3,
MyCloseDatabaseAfterWriting does not always throw away error results. If
OTCfgCommitAreaModifications returns an error, the
MyCloseDatabaseAfterWriting routine aborts. Your application may respond to
this by calling the same routine again, this time with commit set 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;
}
CHAPTER 2
Using Network Setup

30 Working with Entities

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.
You can list all of the entities of a particular class and type and display that
list to the user. For example, you might want to list all of the TCP/IP
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 find the currently active entity of a particular class and type. This is
useful when you want to read the current network settings. The section
“Finding an Active Entity” (page 34) explains how to do this.
You can also create, duplicate, rename, and delete entities. These tasks are easy
to do and are not explained in detail in this chapter. See “Network Setup
Reference” (page 57) for information about OTCfgCreateEntity (page 76),
OTCfgDuplicateEntity (page 78), OTCfgSetEntityName (page 81), and
OTCfgDeleteEntity (page 78).

Listing All Entities 2

Listing 2-5 shows the routine MyGetEntitiesList, which generates a list of all of
the entities within an area of the database. The routine’s database reference and
area identifier parameters are obtained by opening the database, as explained in
“Opening the Database for Reading” (page 25). The entityClass and entityType
parameters specify the entities to list. Some common scenarios include:
Getting all entities of a specific class and type. Set the entityClass and
entityType parameters 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.
Loading...
+ 154 hidden pages