How it Works
Apple
Loading...
I
Loading...
Loading...
INSIDE MACIN TOSH
User Manual
184 pgs988.73 Kb0
Table of contents
Loading...

Apple INSIDE MACIN TOSH User Manual

INSIDE MACINTOSH
Network Setup
© Apple Computer, Inc. 2000
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.

Contents

Figures, Tables, and Listings 7
Preface
Chapter 1
Chapter 2
About This Manual
Conventions Used in This Manual 9 For More Information 10
About Network Setup
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
Using Network Setup
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
9
11
25
3
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
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
57
4
Chapter 4
Network Setup Protocol Structures and Data Types
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
111
Glossary
Index
175
179
5
6

Figures, Tables, and Listings

Chapter 1
Chapter 2
About Network Setup
Figure 1-1 Figure 1-2 Figure 1-3 Figure 1-4 Figure 1-5 Figure 1-6
Table 1-1
Network configuration prior to Network Setup 12 Network Setup in Mac OS 8.5 through the present 13 Future Network Setup architecture 14 Structure of the Network Setup Library 15 Sample organization of the default area 18 Reading and writing the default area 20
Network Setup versions 23
Using Network Setup
Figure 2-1
Listing 2-1 Listing 2-2 Listing 2-3 Listing 2-4 Listing 2-5 Listing 2-6 Listing 2-7 Listing 2-8
Listing 2-9 Listing 2-10 Listing 2-11 Listing 2-12 Listing 2-13 Listing 2-14 Listing 2-15 Listing 2-16
Listing 2-17
Set entities reference other entities 42
Opening the database for reading 26 Opening the database for writing 27 Closing the database after reading 28 Closing the database after writing 29 Finding all entities of a particular class and type 31 Printing the user-visible name for an entity 33 Reading a fixed-size preference 35 Reading the DHCP lease info preference in a TCP/IP network
connection entity 36 Reading the user-visible name preference 37 Calling OTCfgGetPrefsSize to read a variable-size preference 38 Writing a preference 39 Printing an entity’s table of contents 40 Finding the active set entity 44 Finding the active entity of a given class and type 46 Finding the active TCP/IP entity 47 Packing and unpacking the kOTCfgTCPInterfacesPref
preference 50 Encrypting the user’s password 54
11
25
7
8
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.
◆
▲
▲
9
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,
■
Inside Macintosh: Networking with Open Transport.
■
■
Open Transport Advanced Client Programming,
http://developer.apple.com/macos/opentransport/OTAdvancedClientProg/ OTAdvancedClientProg.html
Second Edition.
available at
10
CHAPTER 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
CHAPTER 1
About Network Setup
Figure 1-1
Control panels
Private interface
Private preferences files
Network configuration prior to Network Setup
TCP/IP
TCP/IP
protocol
stack
TCP/IP preferences
AppleTalk
AppleTalk preferences
AppleTalk
protocol
stack
Remote Access, Modem, Dial Assist, Infrared, ...
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.
12
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.
Network Setup Architecture
CHAPTER 1
About Network Setup
Figure 1-2
Legacy control panels
Legacy protocol stacks
Legacy preferences files
Network Setup in Mac OS 8.5 through the present
Network
Setup
scripting
TCP/IP
TCP/IP
TCP/IP
TCP/IP
TCP/IP
TCP/IP
Protocol
Protocol
Protocol
Stack
Stack
Stack
Network Setup library
Network Setup database
Third-party application
Network Setup aware applications
Public interface
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 Architecture
13
CHAPTER 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
Updated protocol stacks
Future Network Setup architecture
Network
control
panel
TCP/IP
TCP/IP
TCP/IP
Protocol
Protocol
Protocol
Stack
Stack
Stack
Network Setup library
Network Setup database
Network
Setup
scripting
Third-party
application
Network Setup aware applications
Public interface
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

CHAPTER 1
About Network Setup
Figure 1-4
Network Setup aware applications
Network Setup extension
Structure of the Network Setup Library
High-level framework
Mid-level database (OTCfg)
Low-level database (Cfg)
Synchronization
Legacy
module
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.
Inside the Network Setup Library
15
CHAPTER 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
the preference modification process. The system currently uses a single named area, known as the 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
store preferences, while temporary areas are used as part of
default area
(sometimes referred to as the
area ID
current area
) to
Each area contains a number of
entity reference.
■
An entity reference uniquely identifies an entity. The entity
entities
having the following properties:
reference contains an area ID, which identifies the area in which the entity resides.
entity name.
■
■
entity class
A user-visible name for the entity that need not be unique.
and
type.
These values, both of type
, determine the type
OSType
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
16

Network Setup Database Fundamentals

CHAPTER 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.
■
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
preference type
(an
). A preference is the atomic unit of data in the
OSType
preferences
, distinguished by a
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
CHAPTER 1
About Network Setup
Figure 1-5
Default area
AppleTalk global protocol entity
'opts' preference
'opts' preference
...
...
TCP/IP global protocol entity
'opts' preference
'opts' preference
...
...
"LocalTalk for Printer" AppleTalk network protocol entity
'atfp' preference
'atfp' preference
'port' preference
'port' preference
...
...
"Company Ethernet" AppleTalk network protocol entity
'aftp' preference
'aftp' preference
'port' preference
'port' preference
...
...
"AirPort" TCP/IP network protocol entity
'idns' preference
'idns' preference
'port' preference
'port' preference
...
...
"Work/DHCP" TCP/IP network protocol entity
'idns' preference
'idns' preference
'port' preference
'port' preference
...
...
"Home" set entity
AppleTalk global protocol entity
AppleTalk global protocol entity
TCP/IP global protocol entity
TCP/IP global protocol entity
"LocalTalk for Printer" AppleTalk network protocol entity
"LocalTalk for Printer" AppleTalk network protocol entity
"AirPort" TCP/IP network protocol entity
"AirPort" TCP/IP network protocol entity
"Work" set entity
AppleTalk global protocol entity
AppleTalk global protocol entity
TCP/IP global protocol entity
TCP/IP global protocol entity
"Company Ethernet" AppleTalk network protocol entity
"Company Ethernet" AppleTalk network protocol entity
"Work/DHCP" TCP/IP network protocol entity
"Work/DHCP" TCP/IP network protocol entity
Sample organization of the default area
general AppleTalk preference user-visible name of this port
general AppleTalk preference
user-visible name of this port
DNS configuration user-visible name of this port
DNS configuration user-visible name of this port
Active
Active
18
Network Setup Database Fundamentals
CHAPTER 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:
■
“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 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
database reference
. This reference identifies the
19
CHAPTER 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 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
Default area
Default area
being read
Default area
Reading and writing the default area
Open for reading
Close for reading
Writing
Default area
Open for write
abort
Temporary area
being written
Commit
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
CHAPTER 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:
■ 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.

Legacy Issues

21
CHAPTER 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:
■ 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 resource with a unique ID in the legacy file. Then, for each preference in the
22 Legacy Issues
'cnam'
CHAPTER 1
About Network Setup
entity, it creates a resource containing the preference data with the resource type matching the preference type and the resource ID the same as the 'cnam' resource.
Network Setup uses a number of private preferences to ensure a reliable round trip conversion between legacy preferences files and the database. The preference types are described in “Common Preference Types” (page 106), but your application should not depend on their presence, their content, or their semantics.
If you find undocumented preferences (such as a preference of type 'vers') in a global protocol entity, do not be concerned. Network Setup itself does not actually look at the data as it imports from and exports to legacy preferences files.

Network Setup Version History 1

Table 1-1 summarizes the different versions of Network Setup, their features, and their release vehicles.
Table 1-1 Network Setup versions
Version Mac OS version 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
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
CHAPTER 1
About Network Setup
24 Network Setup Version History
CHAPTER 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 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.
Opening and Closing the Network Setup Database 25
CHAPTER 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 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
26 Opening and Closing the Network Setup Database
CHAPTER 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
CHAPTER 2
Using Network Setup

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.
28 Opening and Closing the Network Setup Database
CHAPTER 2
Using Network Setup
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;
}
Opening and Closing the Network Setup Database 29
CHAPTER 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.
■ 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.
30 Working with Entities
Loading...
+ 154 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use