Apple INSIDE MACIN TOSH User Manual

Download



INSIDE MACINTOSH

Network Setup



Apple Computer, Inc.



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 Inﬁnite 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 modiﬁcation, 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 speciﬁc legal rights, and you may also have other rights which vary from state to state.

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

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-speciﬁc 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 Notiﬁcation Callback 94

Application-Deﬁned 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

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

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 conﬁguration 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 ﬁxed-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

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.

◆

▲

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

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 conﬁgurations. You can use Network Setup to read, create, modify, and delete network conﬁgurations. 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 conﬁgurations window used to select, duplicate, and rename network conﬁgurations.

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 ﬁles in the Preferences folder. Figure 1-1 shows the overall network conﬁguration architecture prior to the introduction of Network Setup.

Network Setup Architecture

CHAPTER 1

About Network Setup

Figure 1-1

Control panels

Private interface

Private preferences files

Network configuration prior to Network Setup

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 ﬁle format. After changing the ﬁles “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 ﬁle format

■

and private interfaces to the protocol stack made it difﬁcult for Apple to ship modern network features, such as TCP/IP multihoming, and to support the multiple users feature in Mac OS 9.

■

Resource ﬁles 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

Protocol

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 conﬁgurations stored in the Network Setup database. The database is designed to store network preferences reliably even if the system crashes while preferences are being modiﬁed.

■

The Network Setup library provides automatic synchronization between the database and legacy preference ﬁles. Synchronization allows existing software with dependencies on the format of those ﬁles (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 ﬁeld will not break.

Network Setup scripting is a bridge between the Network Setup

■

programming interface and AppleScript. It allows script developers to manipulate network conﬁgurations through a standard AppleScript object model interface.

The primary disadvantage of the current Network Setup architecture is that the synchronization between the legacy preferences ﬁles and the Network Setup database is a time consuming operation. Consequently, Apple intends to

Network Setup Architecture

CHAPTER 1

About Network Setup

remove support for legacy preferences ﬁles 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

Protocol

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 ﬁles 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.

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 ﬁle. 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 preﬁx (“Cfg”) is used by some Network Setup identiﬁers.

■

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 ﬁles. This module will be removed in a future version of Network Setup. See “Legacy Synchronization Algorithm” (page 22) for more information about legacy ﬁle 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

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 modiﬁcation 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 identiﬁed 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 identiﬁes an entity. The entity

entities

having the following properties:

reference contains an area ID, which identiﬁes 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 conﬁguration 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 conﬁguration 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

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 ﬁles. If you are familiar with the legacy ﬁle 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 ﬁles.

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

CHAPTER 1

About Network Setup

Figure 1-5

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

...

"Company Ethernet" AppleTalk network protocol entity

'aftp' preference

'port' preference

...

"AirPort" TCP/IP network protocol entity

'idns' preference

'port' preference

...

"Work/DHCP" TCP/IP network protocol entity

'idns' preference

'port' preference

...

"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

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

Active

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 conﬁgures 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

■

conﬁgures 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 conﬁgures a

■

TCP/IP interface to use DHCP over the Ethernet port.

“Company Ethernet,” an AppleTalk network connection entity that

■

conﬁgures 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 conﬁguration will switch accordingly.

Database Operations 1

Before reading or writing preferences, an application must open the database. The ﬁrst 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 identiﬁes the

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 reconﬁgure themselves for the new conﬁguration.

Alternatively, the writing application can choose to abort the modiﬁcations, in response to which Network Setup discards the temporary area and the system continues to use the conﬁguration in the default area.

Figure 1-6 shows this process diagrammatically.

Figure 1-6

Reading

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 notiﬁes each application that has opened the database for reading that a change has occurred, as explained in the next section, “Preference Coherency.”

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, notiﬁer-based mechanism for learning about preference changes. The reading application attaches a notiﬁer to the database reference. When changes are committed to the database, Network Setup calls each installed notiﬁer 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 ﬁles 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 ﬁles directly.

■ Legacy preferences ﬁles do not support multihoming.

Legacy Issues

CHAPTER 1

About Network Setup

Given that legacy synchronization is slow and that legacy preferences ﬁles 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 ﬁles at the following times:

■ When the database is opened. Network Setup checks the modiﬁcation dates

of each legacy preferences ﬁle against modiﬁcation dates stored in the database. If the dates are different, Network Setup assumes that some application has changed one or more legacy preferences ﬁles and imports preferences from the modiﬁed ﬁles.

■ When changes are committed to the database. Network Setup determines

whether the committed changes affect a legacy preferences ﬁle. If they do, Network Setup exports the database to the legacy preferences ﬁle and records the modiﬁcation date of the legacy preferences ﬁle in the database.

The legacy import mechanism makes good use of the structure of the legacy preferences ﬁles. Most preferences ﬁles are resource ﬁles 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

conﬁguration. The contents of these resources are the preferences for that conﬁguration.

■ There is one ﬁxed resource whose type is 'ccfg' and whose ID is 1 that

contains the resource ID of the active conﬁguration.

■ Any resources with IDs other than those used for conﬁgurations are global

preferences.

When importing a legacy preferences ﬁle, 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 conﬁguration 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 ﬁle. 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 ﬁles 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 ﬁles.

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 speciﬁc 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 modiﬁcations.

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 identiﬁes your application’s connection to the database. It

then calls OTCfgGetCurrentArea, which returns an area identiﬁer (of type

CfgAreaID) that identiﬁes 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 identiﬁer (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 identiﬁer that references a writable temporary area. The MyOpenDatabaseForWriting routine returns both the original default area identiﬁer and the writable temporary area identiﬁer. You must keep both of these area identiﬁers 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 ﬁnished making changes. The ﬁrst three routine parameters (the database reference, the read area identiﬁer, and the write area identiﬁer) 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 notiﬁes the network protocol stacks that their preferences have changed so that they can reconﬁgure 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 identiﬁer 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 ﬁrst 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 ﬁnd 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 identiﬁer 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 speciﬁc class and type. Set the entityClass and

entityType parameters to that class and type. For example, to ﬁnd 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 deﬁned classes and types.

30 Working with Entities

CHAPTER 2

Using Network Setup

■ Getting all entities. Set entityClass and entityType to the wildcard values

kCfgClassAnyEntity and kCfgTypeAnyEntity, respectively.

The entityRefs and entityInfos parameters are handles containing an array of elements of type CfgEntityRef and CfgEntityInfo, respectively. You must create these handles before calling MyGetEntitiesList. You can set entityInfos to NULL if you’re not interested in the information returned in that handle. The

MyGetEntitiesList routine resizes the handles appropriately to hold

information about each of the entities that it ﬁnds.

The MyGetEntitiesList routine calls two key Network Setup functions:

OTCfgGetEntitiesCount to count the number of entities of the speciﬁed class and

type and OTCfgGetEntitiesList to get the actual entity information. The rest of the MyGetEntitiesList routine 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

CHAPTER 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 ); assert(MemError() ==

noErr);

HLock( (Handle) entityRefs ); assert(MemError() ==

noErr);

paramRefs = *entityRefs; } if (entityInfos == nil) {

paramInfos = nil; } else {

sInfos = HGetState( (Handle) entityInfos ); assert(MemError() ==

noErr);

HLock( (Handle) entityInfos ); assert(MemError() ==

noErr);

paramInfos = *entityInfos; }

err = OTCfgGetEntitiesList(dbRef, area,

if (entityRefs != nil) {

HSetState( (Handle) entityRefs, sRefs ); assert(MemError() ==

noErr);

}

if (entityInfos != nil) {

HSetState( (Handle) entityInfos, sInfos ); assert(MemError() ==

noErr);

32 Working with Entities

entityClass, entityType, &entityCount, paramRefs, paramInfos);

CHAPTER 2

Using Network Setup

}

return err;

}

The next routine, shown in Listing 2-6, opens the database for reading, gets the entity references for all of the TCP/IP network connection entities in the default area (using the

MyGetEntitiesList routine 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 entityCount; ItemCount entityIndex; Str255 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

CHAPTER 2

Using Network Setup

entityCount = GetHandleSize( (Handle) entityRefs ) / sizeof(CfgEntityRef); for (entityIndex = 0; entityIndex < entityCount; entityIndex++) {

err = MyGetEntityUserVisibleName(dbRef,

if (err == noErr) {

}

} } MyCloseDatabaseAfterReading(dbRef, readArea);

} if (entityRefs != nil) {

DisposeHandle( (Handle) entityRefs ); assert(MemError() ==

noErr);

}

if (err != noErr) {

printf("Failed with error %ld.\n", err);

}

&(*entityRefs)[entityIndex], userVisibleName);

printf("%ld) "%#s"\n", entityIndex, userVisibleName);

Finding an Active Entity 2

Currently, only one entity can be active for any given network connection type. This is not a restriction of Network Setup itself, but a limitation in the network 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 ﬁnding 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

CHAPTER 2

Using Network Setup

write the desired preferences, and close the entity. This section describes this process for reading variable-length and ﬁxed-size preferences and for writing preferences.

Reading Fixed-size Preferences 2

Many Network Setup preferences are of a ﬁxed size. Reading a ﬁxed 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 ﬁxed size preference from an entity within the database. The prefType parameter controls the preference that is read. The preference data is put in the buffer described by buffer and bufferSize.

Listing 2-7 Reading a ﬁxed-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

CHAPTER 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 inefﬁcient manner for the sake of clarity. If you are reading multiple preferences, it is more efﬁcient to open the entity once. Then read the preferences by calling

OTCfgGetPrefs or OTCfgSetPrefs multiple times and close

the entity when you’re done. ◆

A noteworthy point about reading preferences is that the OTCfgOpenPrefs function does not take an area parameter. This is because the CfgEntityRef itself implicitly includes the area. The signiﬁcant of this point is demonstrated in the section “Working with Sets” (page 42).

You can use the MyReadFixedSizePref routine shown in Listing 2-7 to read speciﬁc 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,

{

OSStatus err;

assert(dbRef != nil); assert(entity != nil); assert(dhcpInfo != nil);

err = MyReadFixedSizePref(dbRef, entity, kOTCfgTCPDHCPLeaseInfoPref,

return err;

}

36 Reading and Writing Preferences

const CfgEntityRef *entity, OTCfgTCPDHCPLeaseInfo *dhcpInfo)

dhcpInfo, sizeof(*dhcpInfo));

CHAPTER 2

Using Network Setup

IMPORTANT

You can derive the C structure for a speciﬁc preference type by removing the “k” from the front of the name and the “Pref” from the end. For example, the C structure for

kOTCfgTCPDHCPLeaseInfoPref is OTCfgTCPDHCPLeaseInfo. The

preference type constants and preference structures for all of the Apple-deﬁned preferences are provided in Chapter 4, “Network Setup Protocol Structures and Data Types.” ▲

Reading Variable-size Preferences 2

The MyReadFixedSizePref routine shown in Listing 2-7 also works with variable 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 ﬁrst byte denotes the length of the actual string data. Listing 2-9 shows how to use

MyReadFixedSizePref to 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

Reading and Writing Preferences 37

OTCfgGetPrefs. You can get this information

CHAPTER 2

Using Network Setup

by calling OTCfgGetPrefsSize before 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()

== noErr);

HLock(buffer); assert(MemError()

== noErr);

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

CHAPTER 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:

■ When you open the entity, open the entity for writing by passing true in the

writer parameter of OTCfgOpenPrefs.

■ 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 identiﬁer when you call

OTCfgOpenPrefs because an entity “knows” the area to

which it belongs. ◆

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 != nil); assert(entity != nil); assert(buffer != nil);

err = OTCfgOpenPrefs(dbRef, entity, true, &accessID); if (err == noErr) {

err = OTCfgSetPrefs(accessID, prefType, buffer, bufferSize);

Reading and Writing Preferences 39

CHAPTER 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 inefﬁcient manner for the sake of clarity. If you are writing multiple preferences, it is more efﬁcient to open the entity, write your preferences by calling OTCfgSetPrefs multiple times, and close the entity when you’re done. ◆

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 ﬁrst calls OTCfgGetPrefsTOCCount (TOC stands for “Table of Contents”) to get a count of the number of preferences in the entity and then calls OTCfgGetPrefsTOC to get an array of CfgPrefsHeader structures. Each structure represents a preference in the entity, with ﬁelds 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

CHAPTER 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

CHAPTER 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. ▲

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

Work

class 'otsc' type 'otst'

Work/DHCP

class 'otnc' type 'tcp4'

Network Connection Entities Global Protocol Entities

42 Working with Sets

Set Entities

Company Ethernet

class 'otnc' type 'atlk'

Home

class 'otsc' type 'otst'

AirPort

class 'otnc' type 'tcp4'

LocalTalk for Printer

class 'otnc' type 'atlk'

TCP/IP Globals

class 'otgl' type 'tcp4'

AppleTalk Globals

class 'otgl' type 'atlk'

CHAPTER 2

Using Network Setup

There are a few basic rules for set entities:

■ Each set entity contains a preference, kOTCfgSetsStructPref, that has a ﬂag

that determines whether the set is active.

■ At all times, there must be one and only one active set.

■ Each set entity contains a preference, kOTCfgSetsVectorPref, that includes, as

elements of an unbounded array, the entity references of all entities in the set.

■ 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:

■ If you mark a set as active, you must deactivate the previously active set.

■ When you add an entity to a set entity, you must remove the ﬁrst 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.

■ When you delete an entity, you must delete its reference from all set entities,

whether they are active or not.

■ You must not delete the last remaining entity of a particular class and type

from a set entity.

■ 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 ﬁnding 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

CHAPTER 2

Using Network Setup

The MyFindActiveSet routine in Listing 2-13 implements the ﬁrst two steps. It starts by getting a list of all of the set entities by calling the MyGetEntitiesList routine (Listing 2-5). Then MyFindActiveSet iterates through all of the set entities, reading the kOTCfgSetsStructPref preference of each set entity. That preference maps to the CfgSetsStruct structure, which contains an fFlags member. One bit of the fFlags member, 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 entityCount; ItemCount entityIndex; Boolean 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

CHAPTER 2

Using Network Setup

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);

}

kOTCfgSetsStructPref, &thisStruct, sizeof(thisStruct));

return err;

}

The remaining two steps for ﬁnding the set entity of a particular class and type are implemented by the MyFindFirstActiveEntity routine, shown in Listing 2-14. It calls MyFindActiveSet (Listing 2-13) to ﬁnd the entity reference of the active set entity. The MyFindFirstActiveEntity routine then reads the

kOTCfgSetsVectorPref preference out of the active set entity. This preference is a

count ﬁeld followed by an unbounded array of CfgSetsElement structures, each of which represents an entity in the set. Because of its variable size,

MyFindFirstActiveEntity reads the preference by calling MyReadVariableSizePref (Listing 2-10). Once it has the array of information

about entities contained in the set, MyFindFirstActiveEntity iterates over that array looking for the ﬁrst element whose class and type matches the required class and type speciﬁed by the caller. When it ﬁnds the correct entity in the set,

MyFindFirstActiveEntity breaks out of the loop and returns the found entity

reference to the caller.

Working with Sets 45

CHAPTER 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 entityIndex; Boolean 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

CHAPTER 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 ﬁnding an active set entity by ﬁnding the active TCP/IP set entity. It opens the database, calls

MyFindFirstActiveEntity (Listing 2-14) with kOTCfgClassNetworkConnection and kOTCfgTypeTCPv4 as 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 readArea; CfgEntityRef activeTCPEntity; Str255 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

CHAPTER 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 identiﬁers. There are three key points to remember:

■ The area identiﬁer is embedded in the entity reference.

■ All modiﬁcations to the database are done in a temporary area.

■ The temporary area is destroyed when changes are committed to the

database.

So, the area identiﬁer that is embedded in the entity reference in a set is an area identiﬁer 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 identiﬁer is 1370.

2. A program opens the database for writing, which creates a temporary area whose identiﬁer 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 identiﬁer 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 identiﬁer 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 identiﬁer is 6288, not 1370.

48 Working with Sets

CHAPTER 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.

■ When comparing two entity references that might have come from a set

entity, always pass kOTCfgIgnoreArea when calling OTCfgIsSameEntityRef. The

OTCfgIsSameEntityRef function will then compare the entities as if they were

in the same area.

■ When opening an entity whose reference you have obtained from a set,

always call OTCfgChangeEntityArea to reset its area identiﬁer to that of the area in which you are working.

Listing 2-14 demonstrates this technique.

Protocol-speciﬁc 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

A TCP/IP network connection entity has a class of

kOTCfgClassNetworkConnection and a type of kOTCfgTypeTCPv4. The entity must

contain the following preferences:

■ kOTCfgTCPInterfacesPref, which contains the core TCP/IP conﬁguration

information. For details, see the discussion below and

OTCfgTCPInterfacesUnpacked (page 112), OTCfgTCPInterfacesPacked

(page 114), and OTCfgTCPInterfacesPackedPart (page 114).

■ kOTCfgTCPDeviceTypePref, which contains data needed by the current TCP/IP

control panel. For details, see OTCfgTCPDeviceTypePref in the section “TCP/IP Constants and Other Data Types” (page 160).

■ kOTCfgTCPRoutersListPref, which contains the list of conﬁgured routers. For

details, see OTCfgTCPRoutersList (page 119).

■ kOTCfgTCPSearchListPref, which contains the strings which make up the

implicit search path for DNS. For details, see OTCfgTCPSearchList (page 120).

Protocol-speciﬁc Topics 49

CHAPTER 2

Using Network Setup

■ kOTCfgTCPDNSServersListPref, which contains the list of conﬁgured DNS

servers. For details, see OTCfgTCPDNSServersList (page 116).

■ kOTCfgTCPSearchDomainsPref, which contains the list of additional domains to

be searched. For details, see OTCfgTCPSearchDomains (page 120).

■ kOTCfgTCPUnloadAttrPref, which speciﬁes how TCP/IP loads and unloads.

For details, see OTCfgTCPUnloadAttr (page 121).

■ 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

kOTCfgTCPInterfacesPref preference. 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.

■ OTCfgTCPInterfacesPacked and OTCfgTCPInterfacesPackedPart help you

access the preference in its packed format.

■ OTCfgTCPInterfacesUnpacked is 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

kOTCfgTCPInterfacesPref preference.

Listing 2-16 Packing and unpacking the kOTCfgTCPInterfacesPref preference

static OSStatus MyPackTCPInterfacesPref(const OTCfgTCPInterfacesUnpacked *unpackedPref,

OTCfgTCPInterfacesPacked *packedPref, ByteCount *packedPrefSize)

{

UInt8 *cursor;

assert(unpackedPref != nil); assert(packedPref != nil); assert(packedPrefSize != nil);

// Start the cursor at the beginning of the packed preference.

50 Protocol-speciﬁc Topics

CHAPTER 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-speciﬁc Topics 51

CHAPTER 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-speciﬁc Topics

CHAPTER 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

kOTCfgClassNetworkConnection and a type of kOTCfgTypeRemote and typically

contains the following preferences:

■ kOTCfgRemoteConnectPref, which contains core connection preferences. For

details, see OTCfgRemoteConnect (page 127).

■ kOTCfgRemoteUserPref, which contains the user name. For details, see

OTCfgRemoteUserPref in the section “Apple Remote Access Constants and

Other Data Types” (page 163).

■ kOTCfgRemotePasswordPref, which contains the user’s encrypted password.

For details, see the sample code below and OTCfgRemotePassword (page 135).

■ kOTCfgRemoteAddressPref, which contains the phone number to dial. For

details, see OTCfgRemoteAddressPref in the section “Apple Remote Access Constants and Other Data Types” (page 163).

■ kOTCfgRemoteDialingPref, which contains redial preferences. For details, see

OTCfgRemoteDialing (page 131).

■ kOTCfgRemoteClientMiscPref, which controls the “dial on demand” feature of

IPCP. For details, see OTCfgRemoteClientMisc (page 127).

■ kOTCfgRemoteIPCPPref, which contains low-level preferences for IPCP. You

typically set this preference to a default value obtained by calling

OTCfgGetDefault (page 90). For details, see OTCfgRemoteIPCP (page 132).

■ 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-speciﬁc Topics 53

CHAPTER 2

Using Network Setup

■ kOTCfgRemoteLogOptionsPref, which contains the “verbose logging” option.

For details, see OTCfgRemoteLogOptions (page 135).

■ 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,

}

Modem Notes 2

A Remote Access network connection entity has a class of

kOTCfgClassNetworkConnection and a type of kOTCfgTypeModem. The entity

typically contains the following preferences:

■ kOTCfgModemGeneralPrefs, which contains the core modem preferences. For

details, see OTCfgModemGeneral (page 141).

■ kOTCfgModemLocksPref, which is used by the Modem control panel to

remember which preferences are locked. For details, see OTCfgModemLocks (page 143).

When creating the kOTCfgModemGeneralPrefs preference, 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-speciﬁc Topics

encodedPassword, sizeof(Str255));

CHAPTER 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 types will prevent two different developers from using the same preference type for conﬂicting preferences.

http://developer.apple.com/dev/cftype. Registering preference

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.

■ It is recommended that you use the existing classes,

kOTCfgClassNetworkConnection and kOTCfgClassGlobalSettings, for your

global protocol and network connection entities.

■ You should register a unique creator code with DTS at

http://developer.apple.com/dev/cftype and use it as the type for your

entities. This will ensure that your work does not conﬂict with Apple Computer or other developers.

Your protocol stack conﬁgurator should call OTCfgInstallNotifier (page 94) to install a Network Setup notiﬁer to watch for changes to its preferences by your control panel or by third-party software.

Notes for Third Parties 55

CHAPTER 2

Using Network Setup

56 Notes for Third Parties

CHAPTER 3

Figure 3-0 Listing 3-0 Table 3-0

Network Setup Reference 3

This chapter describes the functions, structures, and data types for calling Network Setup. For protocol-speciﬁc preferences, see Chapter 4, “Network Setup Protocol Structures and Data Types.”

Network Setup Functions 3

The Network Setup functions are described in these sections:

■ “Opening and Closing the Network Setup Database” (page 57)

■ “Managing Areas” (page 59)

■ “Managing Entities” (page 72)

■ “Managing Preferences” (page 83)

■ “Preference Utilities” (page 92)

■ “Installing and Removing a Notiﬁcation Callback” (page 94)

Opening and Closing the Network Setup Database 3

Before attempting to call the Network Setup functions, you must open the Network Setup database. Be sure to close the database when you are done. The functions are:

■ OTCfgOpenDatabase (page 58) opens the Network Setup database.

■ OTCfgCloseDatabase (page 58) closes the Network Setup database.

Network Setup Functions 57

CHAPTER 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, dbRef is a reference to the opened database that is passed as a parameter to other Network Setup functions.

function result A value of noErr if the database was opened. For a list of other

possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgOpenDatabase function opens a session with the Network Setup database. Your application must call OTCfgOpenDatabase successfully before it can call any other Network Setup function.

OTCfgCloseDatabase 3

Closes the Network Setup database.

OSStatus OTCfgCloseDatabase (OTCfgDatabaseRef* dbRef);

dbRef

function result A value of noErr if the database was closed. For a list of other

A pointer to value of type CfgDatabaseRef (page 98) that represents the database session you want to close.

possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgCloseDatabase function closes the database session represented by

dbRef.

58 Network Setup Functions

CHAPTER 3

Network Setup Reference

Note

Closing a database session automatically removes any notiﬁcation callback that has been installed for the session represented by dbRef. ◆

Managing Areas 3

The following functions manage areas in the Network Setup database:

■ OTCfgGetCurrentArea (page 60) obtains the default area in the database.

■ OTCfgSetCurrentArea (page 61) sets the default area in the database.

■ OTCfgOpenArea (page 61) opens an area in the database.

■ OTCfgCloseArea (page 62) closes an area in the database.

■ OTCfgBeginAreaModifications (page 63) creates a temporary area for

modifying the database.

■ OTCfgCommitAreaModifications (page 64) commits changes made in a

temporary area to the database.

■ OTCfgAbortAreaModifications (page 65) discards a temporary area and all

modiﬁcations made to it.

■ OTCfgIsSameAreaID (page 65) determines whether two area IDs are the same.

■ OTCfgGetAreaName (page 66) gets the name of an area in the database.

■ OTCfgSetAreaName (page 67) sets the name of an area in the database.

■ OTCfgGetAreasCount (page 68) obtains the number of areas in the database.

■ OTCfgGetAreasList (page 68) obtains the area IDs and area names in the

database.

■ OTCfgCreateArea (page 70) creates a new area in the database.

■ OTCfgDuplicateArea (page 71) copies the contents of an area to another area.

■ OTCfgDeleteArea (page 72) deletes an area in the database.

Network Setup Functions 59

CHAPTER 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. ▲

OTCfgGetCurrentArea 3

Obtains the default area.

OSStatus OTCfgGetCurrentArea (CfgDatabaseRef dbRef,

CfgAreaID* areaID);

DISCUSSION

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, areaID points to the area ID of the current area.

function result A value of noErr indicates that OTCfgGetCurrentArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgGetCurrentArea function obtains the area ID of the default area. The default area is sometimes referred to as the current area.

60 Network Setup Functions

CHAPTER 3

▲

Network Setup Reference

OTCfgSetCurrentArea 3

Sets the default area.

OSStatus OTCfgSetCurrentArea (CfgDatabaseRef dbRef,

CfgAreaID areaID);

DISCUSSION

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

areaID that identiﬁes the area that is to be made active. If the

area does not exist, OTCfgSetCurrentArea returns

kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgSetCurrentArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgSetCurrentArea function makes the area ID speciﬁed by the areaID parameter the default area. The default area is sometimes referred to as the current area.

WARNING

Do not change the default area. If you want to modify settings, make changes to the entities within the default area. ▲

OTCfgOpenArea 3

Opens an area in the Network Setup database for reading.

OSStatus OTCfgOpenArea (CfgDatabaseRef dbRef,

CfgAreaID areaID);

Network Setup Functions 61

CHAPTER 3

Network Setup Reference

dbRef On input, a value of type CfgDatabaseRef (page 98) that

represents a database session previously opened by calling

OTCfgOpenDatabase (page 58).

areaID On input, a value of type CfgAreaID (page 98) that identiﬁes the

area that is to be opened. If the area speciﬁed by areaID does not exist, OTCfgOpenArea returns kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgOpenArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgOpenArea function opens the speciﬁed area in the Network Setup database for reading.

OTCfgCloseArea 3

Closes an area in the Network Setup database.

OSStatus OTCfgCloseArea (CfgDatabaseRef dbRef,

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 identiﬁes the

area that is to be closed. If the area speciﬁed by areaID does not exist, OTCfgCloseArea returns kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgCloseArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgCloseArea function closes an area in the database that was previously opened for reading by calling OTCfgOpenArea (page 61).

62 Network Setup Functions

CfgAreaID areaID);

CHAPTER 3

Network Setup Reference

OTCfgBeginAreaModiﬁcations 3

Creates a temporary area for modifying an area.

OSStatus OTCfgBeginAreaModifications (CfgDatabaseRef dbRef,

CfgAreaID readAreaID, CfgAreaID* writeAreaID);

DISCUSSION

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 speciﬁed by

readAreaID does not exist, OTCfgBeginAreaModifications returns kCfgErrAreaNotFound.

writeAreaID On input, a pointer to a value of type CfgAreaID (page 98). On

output, writeAreaID points to a new area ID that your application should use to modify, delete, enumerate, or read data in the area.

function result A value of noErr indicates that OTCfgBeginAreaModifications

returned successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgBeginAreaModifications function creates a temporary area and returns in the writeAreaID parameter 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, unmodiﬁed data, you can continue using

readAreaID to 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, OTCfgBeginAreaModifications returns

kCfgErrConfigLocked. ▲

Network Setup Functions 63

CHAPTER 3

Network Setup Reference

Call OTCfgCommitAreaModifications (page 64) to write the temporary area to the area identiﬁed 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 readAreaID and discard the temporary area.

OTCfgCommitAreaModiﬁcations 3

Closes an area for writing and commits modiﬁcations.

OSStatus OTCfgCommitAreaModifications (CfgDatabaseRef dbRef,

CfgAreaID readAreaID, CfgAreaID writeAreaID);

DISCUSSION

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). If readAreaID does

not exist or does not match the writeAreaID referred to by

OTCfgBeginAreaModifications (page 63), OTCfgCommitAreaModifications returns kCfgErrAreaNotFound.

writeAreaID On input, a value of type CfgAreaID (page 98) previously

obtained by calling OTCfgBeginAreaModifications (page 63). If

writeAreaID does not exist or does not match the readAreaID

passed to OTCfgBeginAreaModifications (page 63),

OTCfgCommitAreaModifications returns kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgCommitAreaModifications

returned successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgCommitAreaModifications function writes the temporary area represented by writeAreaID to the area represented by readAreaID and closes the write area.

Readers of the area represented by readAreaID are informed that the database has been modiﬁed.

64 Network Setup Functions

CHAPTER 3

Network Setup Reference

OTCfgAbortAreaModiﬁcations 3

Closes an area for writing without committing modiﬁcations.

OSStatus OTCfgAbortAreaModifications (CfgDatabaseRef dbRef,

CfgAreaID readAreaID);

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) that identiﬁes an

area that has been opened for writing. If readAreaID does not exist or you have not called OTCfgBeginAreaModifications (page 63) for the area represented by readAreaID,

OTCfgAbortAreaModifications returns kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgAbortAreaModifications

returned successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgAbortAreaModifications function closes an area that was opened for writing without writing the modiﬁcations to the area presented by readAreaID.

OTCfgIsSameAreaID 3

Compares two area IDs.

Boolean OTCfgIsSameAreaID (CfgAreaID areaID1,

CfgAreaID areaID2);

areaID1

On input, a value of type CfgAreaID (page 98) representing one of the area IDs that is to be compared.

areaID2 On input, a value of type CfgAreaID (page 98) representing the

other area ID that is to be compared.

Network Setup Functions 65

CHAPTER 3

Network Setup Reference

function result A Boolean value that is TRUE if the area IDs are the same and

FALSE if the area IDs are different.

DISCUSSION

The OTCfgIsSameAreaID function 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);

DISCUSSION

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 identiﬁes the

area whose name is to be obtained. If the area speciﬁed by

areaID does not exist, OTCfgGetAreaName returns kCfgErrAreaNotFound.

areaName On input, a value of type Str255. On output, areaName contains

the user-visible name of the area speciﬁed by areaID.

function result A value of noErr indicates that OTCfgGetAreaName returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgGetAreaName function gets the user-visible name of the speciﬁed area.

Note

The OTCfgGetAreaName function is available in Network Setup version 1.0.1 and later. ◆

66 Network Setup Functions

CHAPTER 3

▲

Network Setup Reference

OTCfgSetAreaName 3

Sets the user-visible name of an area.

OSStatus OTCfgSetAreaName (CfgDatabaseRef dbRef,

CfgAreaID areaID, ConstStr255Param areaName, CfgAreaID* newAreaID);

DISCUSSION

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 identiﬁes the

area whose name is to be set. If the area speciﬁed by areaID does not exist, OTCfgSetAreaName returns kCfgErrAreaNotFound.

areaName On input, a value of type ConstStr255Param that speciﬁes the

name to set. If an area of the name speciﬁed by areaName already exists, OTCfgSetAreaName returns kCfgErrAreaAlreadyExists.

newAreaID On input, a pointer to value of type CfgAreaID (page 98). On

output, newAreaID points to a new area ID that your application should use for any subsequent calls for the area.

function result A value of noErr indicates that OTCfgSetAreaName returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgSetAreaName function changes the user-visible name of the speciﬁed area and returns a new area ID for that area.

WARNING

Do not change the name of the default area. ▲

Network Setup Functions 67

CHAPTER 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,

itemCount points to the number of areas in the database.

function result A value of noErr indicates that OTCfgGetAreasCount returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgGetAreasCount function obtains the number of areas that are currently deﬁned 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

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 a value of type ItemCount that speciﬁes

the number of areas for which information is requested. Call

OTCfgGetAreasCount (page 68) to determine the number of areas

68 Network Setup Functions

CHAPTER 3

Network Setup Reference

that are available. On output, itemCount points 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 speciﬁed by

itemCount. On output, each array element contains an area ID. If

you don’t want to get area IDs, set areaID to NULL.

areaName On input, an array of elements of type Str255 that is large

enough to hold the number of area names speciﬁed by

itemCount. On output, each array element contains an area

name. The area name in the ﬁrst element corresponds to the area ID in the ﬁrst element of the array speciﬁed by areaID, and so on. If you don’t want to get area names, set areaName to NULL.

function result A value of noErr indicates that OTCfgGetAreasList returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgGetAreasList function obtains the IDs and names of areas in the database and stores this information in two arrays: one containing area IDs and the other containing area names. Each area ID and area name pair identiﬁes an area in the database.

When you allocate the arrays for the areaID and areaName parameters, 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

CHAPTER 3

Network Setup Reference

OTCfgCreateArea 3

Creates an area in the Network Setup database.

OSStatus OTCfgCreateArea (CfgDatabaseRef dbRef,

ConstStr255Param areaName, CfgAreaID* areaID);

DISCUSSION

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 ConstStr255Param that speciﬁes the

user-visible name of the area to create. If an area of the name speciﬁed by areaName already exists, OTCfgCreateArea returns

kCfgErrAreaAlreadyExists.

areaID On input, a pointer to a value of type CfgAreaID (page 98). On

output, areaID contains the ID of the area that was created.

function result A value of noErr indicates that OTCfgCreateArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgCreateArea function creates an area of the speciﬁed name in the database.

IMPORTANT

The OTCfgCreateArea function has almost no purpose in the version of Network Setup described by this document. ◆

70 Network Setup Functions

CHAPTER 3

Network Setup Reference

OTCfgDuplicateArea 3

Copies the contents of one area to another area.

OSStatus OTCfgDuplicateArea (CfgDatabaseRef dbRef,

CfgAreaID sourceAreaID, CfgAreaID destAreaID);

DISCUSSION

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 identiﬁes the

area that is to be duplicated. If the area speciﬁed by areaID does not exist, OTCfgDuplicateArea returns kCfgErrAreaNotFound.

destAreaID On input, a value of type CfgAreaID (page 98) that identiﬁes the

area that is to contain the duplicated area. If the area speciﬁed by areaID does not exist, OTCfgDuplicateArea returns

kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgDuplicateArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgDuplicateArea function copies the contents of the area speciﬁed by

sourceAreaID into the area speciﬁed by destAreaID. Both areas must exist before

you call OTCfgDuplicateArea. To create an area, call OTCfgCreateArea (page 70).

IMPORTANT

The OTCfgDuplicateArea function has almost no purpose in the version of Network Setup described by this document. ◆

Network Setup Functions 71

CHAPTER 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 On input, a value of type CfgAreaID (page 98) that identiﬁes the

area that is to be deleted. If the area speciﬁed by areaID does not exist, OTCfgDeleteArea returns kCfgErrAreaNotFound.

function result A value of noErr indicates that OTCfgDeleteArea returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgDeleteArea function removes the speciﬁed area from the database.

IMPORTANT

The OTCfgDeleteArea function has almost no purpose in the version of Network Setup described by this document. ◆

Managing Entities 3

Use the following functions to create, modify, and delete entities within an area:

■ OTCfgGetEntitiesCount (page 73) obtains the number of entities in an area.

■ OTCfgGetEntitiesList (page 74) obtains a list of entities in an area.

■ OTCfgIsSameEntityRef (page 76) determines whether two entity references are

the same.

■ OTCfgCreateEntity (page 76) creates an entity in an area.

■ OTCfgDeleteEntity (page 78) deletes an entity from an area.

72 Network Setup Functions

CHAPTER 3

Network Setup Reference

■ OTCfgDuplicateEntity (page 78) copies the contents of one entity to another

entity.

■ OTCfgGetEntityLogicalName (page 79) gets the name of an entity.

■ OTCfgGetEntityName (page 80) gets the name of an entity.

■ OTCfgSetEntityName (page 81) sets the name of an entity in an area.

■ OTCfgGetEntityArea (page 82) gets the area ID of an entity.

■ OTCfgChangeEntityArea (page 82) changes an entity’s area.

OTCfgGetEntitiesCount 3

Obtains the number of entities of a speciﬁed 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 identiﬁes the

area that is to be searched. If the area speciﬁed by areaID does not exist, OTCfgGetEntitiesCount returns the error

kCfgErrAreaNotFound.

entityClass On input, a value of type CfgEntityClass that speciﬁes the class

that is to be matched. To specify all classes, set entityClass to

kCfgClassAnyEntity. For a list of possible classes, see “Entity

Classes and Types” (page 104).

entityType On input, a value of type CfgEntityType that speciﬁes the type

that is to be matched. To specify all types, set entityType to

kCfgTypeAnyEntity. For a list of possible types, see “Entity

Classes and Types” (page 104).

Network Setup Functions 73

CHAPTER 3

Network Setup Reference

itemCount On input, a pointer to a value of type ItemCount. On output,

itemCount contains the number of entities that matched the

speciﬁed class and type.

function result A value of noErr indicates that OTCfgGetEntitiesCount returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgGetEntitiesCount function obtains the number of entities of the speciﬁed class and type in the speciﬁed 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,

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 identiﬁes the

area that is to be searched. If the area speciﬁed by areaID does not exist, OTCfgGetEntitiesCount returns the error

kCfgErrAreaNotFound.

entityClass On input, a value of type CfgEntityClass that speciﬁes the class

that is to be matched. To specify all classes, set entityClass to

kCfgClassAnyEntity. For a list of possible classes, see “Entity

Classes and Types” (page 104).

74 Network Setup Functions

CfgAreaID areaID, CfgEntityClass entityClass, CfgEntityType entityType, ItemCount* itemCount, CfgEntityRef entityRef[], CfgEntityInfo entityInfo[]);

CHAPTER 3

Network Setup Reference

entityType On input, a value of type CfgEntityType that speciﬁes the type

that is to be matched. To specify all types, set entityType to

kCfgTypeAnyEntity. For a list of possible types, see “Entity

Classes and Types” (page 104).

itemCount On input, a pointer to a value of type ItemCount that speciﬁes

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, itemCount points 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 speciﬁed by itemCount, or NULL if you do not want to receive entity references. If not NULL on input, each element of the

entityRef array corresponds to an element of the entityInfo

array on output.

entityInfo On input, an array of CfgEntityInfo (page 99) structures that is

large enough to hold the number of CfgEntityInfo structures speciﬁed by itemCount, or NULL if you do not want to receive

CfgEntityInfo structures.

DISCUSSION

function result A value of noErr indicates that OTCfgGetEntitiesList returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgGetEntitiesList function obtains an array of entity references, each of which represents an entity in the speciﬁed area, and an array of entity 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

CHAPTER 3

Network Setup Reference

OTCfgIsSameEntityRef 3

Compares two entity references.

Boolean OTCfgIsSameEntityRef (const CfgEntityRef* entityRef1,

const CfgEntityRef* entityRef2, Boolean ignoreArea);

entityRef1

On input, a pointer to a value of type CfgEntityRef (page 99) for one of the entity references that is to be compared.

entityRef2 On input, a pointer to a value of type CfgEntityRef (page 99) for

the second entity reference that is to be compared.

ignoreArea On input, a Boolean value. If ignoreArea is kCfgIgnoreArea,

OTCfgIsSameEntityRef ignores the area ID when comparing entityRef1 and entityRef2. If ignoreArea is kCfgDontIgnoreArea, OTCfgIsSameEntityRef does not ignore the area ID when

comparing entityRef1 and entityRef2.

function result TRUE if the entity references represent the same entity; FALSE if

the entity references represent different entities.

DISCUSSION

The OTCfgIsSameEntityRef function determines whether two entity references represent the same area. For a discussion of the circumstances in which calling

OTCfgIsSameEntityRef is particularly useful, see “Areas and Sets” (page 48).

OTCfgCreateEntity 3

Creates an entity in an area.

OSStatus OTCfgCreateEntity (CfgDatabaseRef dbRef,

76 Network Setup Functions

CfgAreaID areaID, CfgEntityInfo* entityInfo, CfgEntityRef* entityRef);

CHAPTER 3

Network Setup Reference

dbRef On input, a value of type CfgDatabaseRef (page 98) that

represents a database session previously opened by calling

OTCfgOpenDatabase (page 58).

areaID On input, a value of type CfgAreaID (page 98) that identiﬁes the

area in which the entity is to be created. If the area speciﬁed by

areaID is not writable, OTCfgCreateEntity returns the error kCfgErrLocked. If the area speciﬁed by areaID does not exist, OTCfgCreateEntity returns the error kCfgErrAreaNotFound.

entityInfo On input, a pointer to a CfgEntityInfo (page 99) structure that

speciﬁes the class, type, user-visible name, and icon for the entity that is to be created. If an entity of the speciﬁed name already exists, OTCfgCreateEntity returns the error

kCfgErrEntityAlreadyExists.

entityRef On input, a pointer to a value of type CfgEntityRef (page 99).

On output, entityRef points to an entity reference for the created reference.

function result A value of noErr indicates that OTCfgCreateEntity returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgCreateEntity function creates an entity in the area speciﬁed by areaID with the class, type, user-visible name, and icon speciﬁed by the entityInfo parameter.

The area represented by areaID must have been opened by calling

OTCfgBeginAreaModifications (page 63).

The OTCfgCreateEntity function 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

CHAPTER 3

Network Setup Reference

OTCfgDeleteEntity 3

Deletes the speciﬁed 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, OTCfgDeleteEntity returns the error

kCfgErrAreaNotOpen or kCfgErrLocked. If the entity represented

by entityRef does not exist, OTCfgDeleteEntry returns the error

kCfgErrEntityNotFound.

function result A value of noErr indicates that OTCfgDeleteEntity returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgDeleteEntity function deletes the speciﬁed entity.

OTCfgDuplicateEntity 3

Copies the contents of one entity to another entity.

OSStatus OTCfgDuplicateEntity (CfgDatabaseRef dbRef,

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

const CfgEntityRef* entityRef, const CfgEntityRef* newEntityRef);

DISCUSSION

CHAPTER 3

Network Setup Reference

entityRef On input, a pointer to a value of type CfgEntityRef (page 99)

that identiﬁes the entity reference that is to be duplicated. If the entity represented by entityRef does not exist,

OTCfgDuplicateEntry returns the error kCfgErrEntityNotFound.

newEntityRef On input, a pointer to a value of type CfgEntityRef (page 99)

that identiﬁes the entity that is to be overwritten by the contents of entityRef. If entityRef represents an entity that does not reside in an area that is open for writing, OTCfgDuplicateEntity returns the error kCfgErrAreaNotOpen or kCfgErrLocked.

function result A value of noErr indicates that OTCfgDuplicateEntity returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgDuplicateEntity function copies the contents of the entity speciﬁed by

entityRef to the entity speciﬁed by newEntityRef. Any data stored in newEntityRef before OTCfgDuplicateEntity is called is overwritten by the

contents of entityRef when OTCfgDuplicateEntity returns.

OTCfgGetEntityLogicalName 3

Obtains the user-visible name of an entity.

OSStatus OTCfgGetEntityLogicalName( CfgDatabaseRef dbRef,

const CfgEntityRef *entityRef, Str255 entityName );

dbRef

entityRef On input, a pointer to a value of type CfgEntityRef (page 99)

entityName On input, a value of type Str255. On output, entityName contains

Network Setup Functions 79

On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling

OTCfgOpenDatabase (page 58).

that identiﬁes the entity whose name is to be obtained. To obtain the reference for an entity, call OTCfgGetEntitiesList (page 74).

the user-visible name of the entity represented by entityRef.

CHAPTER 3

Network Setup Reference

function result A value of noErr indicates that OTCfgGetEntityLogicalName

returned successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgGetEntityLogicalName function obtains the user-visible name of the entity represented by entityRef.

Note

The OTCfgGetEntityLogicalName function 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 kOTCfgUserVisibleNamePref as the preference to get. ◆

OTCfgGetEntityName 3

Obtains the name of an entity.

void OTCfgGetEntityName (const CfgEntityRef *entityRef,

entityRef

On input, a pointer to a value of type CfgEntityRef (page 99) that identiﬁes 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, entityName contains

the name of the entity represented by entityRef.

function result None.

DISCUSSION

The OTCfgGetEntityName function obtains the name of the entity represented by

entityRef.

80 Network Setup Functions

Str255 entityName);

CHAPTER 3

▲

Network Setup Reference

WARNING

The OTCfgGetEntityName function does not return the user-visible name of the entity. Instead, OTCfgGetEntityName returns an internal name in entityName. To get the user-visible name, call OTCfgGetPrefs (page 86) passing

kOTCfgUserVisibleNamePref in the prefsType parameter or

call OTCfgGetEntityLogicalName (page 79) if that function is available. ▲

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 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 name is to be set. To obtain the entity reference for an entity, call OTCfgGetEntitiesList (page 74). If entityRef does not refer to a valid entity,

OTCfgSetEntityName returns the error kCfgEntityNotFoundErr.

entityName On input, a value of type ConstStr255Param that speciﬁes the

new user-visible name for the entity.

newEntityRef On input, a pointer to a value of type CfgEntityRef (page 99).

On output, newEntityRef points to a new entity reference that represents the renamed entity. Your application should use

newEntityRef for future references to the renamed entity.

function result A value of noErr indicates that OTCfgSetEntityName returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

Network Setup Functions 81

CHAPTER 3

Network Setup Reference

DISCUSSION

The OTCfgSetEntityName function sets the user-visible name of the speciﬁed 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

On input, a pointer to a value of type CfgEntityRef (page 99) that identiﬁes the entity reference whose area is to be obtained. To obtain the entity reference for an entity, call

OTCfgGetEntitiesList (page 74).

areaID On input, a pointer to a value of type CfgAreaID (page 98). On

output, areaID points to the area ID of the entity represented by

entityRef.

function result None.

DISCUSSION

The OTCfgGetEntityArea function 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

CHAPTER 3

Network Setup Reference

entityRef On input, a pointer to a value of type CfgEntityRef (page 99)

that represents the entity reference whose area is to be changed. To obtain the entity reference for an entity, call

OTCfgGetEntitiesList (page 74) or use the entity reference

returned by a Network Setup function that creates an entity.

newAreaID On input, a value of type CfgAreaID (page 98) that speciﬁes the

new area ID for the speciﬁed entity.

function result None.

DISCUSSION

The OTCfgChangeEntityArea function changes the area ID of the speciﬁed entity. This function does not actually move the entity. Instead, it changes the entity reference to point to the same entity in the area speciﬁed by newAreaID.

Managing Preferences 3

Use the following functions to manage preferences, which are stored in an entity:

■ OTCfgOpenPrefs (page 84) opens an entity so that its preferences can be

accessed.

■ OTCfgClosePrefs (page 85) closes an entity.

■ OTCfgGetPrefsSize (page 85) gets the size of a preference.

■ OTCfgGetPrefs (page 86) gets the value of a preference.

■ OTCfgSetPrefs (page 87) sets the value of a preference.

■ OTCfgGetPrefsTOCCount (page 88) gets the number of preferences in an entity.

■ OTCfgGetPrefsTOC (page 89) gets a list of a preferences in an entity.

■ OTCfgGetDefault (page 90) gets the default value for a preference.

■ OTCfgDeletePrefs (page 90) deletes a preference from an entity.

■ OTCfgGetTemplate (page 91) gets a preference’s template.

Network Setup Functions 83

CHAPTER 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, OTCfgOpenPrefs returns the error kCfgErrEntityNotFound.

writer On input, a Boolean value. If writer is TRUE, the entity

represented by entityRef must be in an area that was opened by calling OTCfgBeginAreaModifications (page 63); otherwise,

OTCfgOpenPrefs returns the error kCfgErrLocked. If writer is FALSE, the entity represented by entityRef must be in an open

area [opened by calling OTCfgBeginAreaModifications (page 63) or OTCfgOpenArea (page 61)]; otherwise, OTCfgOpenPrefs returns the error kCfgErrAreaNotOpen.

accessID On input, a pointer to a value of type CfgEntityAccessID

(page 100). On output, use accessID in subsequent calls to get and set preferences.

function result A value of noErr indicates that OTCfgOpenPrefs returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgOpenPrefs function opens the speciﬁed entity so that your application can get or set the value of the preferences the entity contains.

If the value of the writer parameter is TRUE, you can set preferences as well as get preferences; otherwise, you can only get preferences.

84 Network Setup Functions

CHAPTER 3

Network Setup Reference

OTCfgClosePrefs 3

Closes an entity.

OSStatus OTCCfgClosePrefs (CfgEntityAccessID accessID);

accessID

On input, a value of type CfgEntityAccessID (page 100), obtained by previously calling OTCfgOpenPrefs (page 84), that identiﬁes the entity that is to be closed.

function result A value of noErr indicates that OTCfgClosePrefs returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgClosePrefs function closes the speciﬁed 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 identiﬁes the entity containing the preference whose size is to be obtained.

prefsType On input, a value of type prefsType that identiﬁes the type of

the preference whose size is to be obtained.

length On input, a pointer to a value of type ByteCount. On output,

length contains the size in bytes of the preference speciﬁed by prefsType.

Network Setup Functions 85

CHAPTER 3

Network Setup Reference

function result A value of noErr indicates that OTCfgGetPrefsSize returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgGetPrefsSize function gets the size in bytes of the preference speciﬁed by prefsType in the entity represented by accessID.

For variable-length preferences, you should call OTCfgGetPrefsSize to 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), obtained by previously calling OTCfgOpenPrefs (page 84), that identiﬁes the entity containing the preference whose value is to be obtained.

prefsType On input, a value of type OSType that identiﬁes the preference

whose value is to be obtained. See“Protocol Constants and Other Data Types” (page 159) for protocol-speciﬁc preferences.

data On input, a pointer to the buffer into which the value of the

preference is to be placed. On output, data contains the value of the preference speciﬁed by prefsType.

length On input, a value of type ByteCount that is the size in bytes of

the buffer pointed to by data.

function result A value of noErr indicates that OTCfgGetPrefs returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

86 Network Setup Functions

CHAPTER 3

Network Setup Reference

DISCUSSION

The OTCfgGetPrefs function gets the value of the preference speciﬁed by

prefsType in 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 data parameter of the appropriate size.

If the data parameter is too small to hold the value, OTCfgGetPrefs stores as much of the value in data as 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 accessID resides 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 identiﬁes the preference to

set. If a preference of the type speciﬁed by prefsType already exists OTCfgSetPrefs overwrites the value of the preference. Otherwise, OTCfgSetPrefs creates the new preference.

data On input, a pointer to the data that is to be set.

length On input, a value of type ByteCount that contains the length in

bytes of the data in data.

function result A value of noErr indicates that OTCfgSetPrefs returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

Network Setup Functions 87

CHAPTER 3

Network Setup Reference

DISCUSSION

The OTCfgSetPrefs function sets the preference represented by prefsType to the value speciﬁed by data.

The accessID parameter must have been created by calling OTCfgOpenPrefs (page 84) with the writer parameter 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);

DISCUSSION

accessID

On input, a value of type CfgEntityAccessID (page 100), obtained by previously calling OTCfgOpenPrefs (page 84) that identiﬁes the entity whose preferences are to be counted.

itemCount On input, a pointer to a value of type ItemCount. On output,

itemCount contains the number of preferences in the entity

represented by accessID.

function result A value of noErr indicates that OTCfgGetPrefsTOCCount returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgGetPrefsTOCCount function gets the number of preferences in the entity represented by accessID.

You should call OTCfgPrefsTOCCount to ﬁnd out how many preferences are present before calling OTCfgGetPrefsTOC (page 89).

88 Network Setup Functions

CHAPTER 3

▲

Network Setup Reference

OTCfgGetPrefsTOC 3

Gets a list of the preferences in an entity.

OSStatus OTCfgGetPrefsTOC (CfgEntityAccessID accessID.

ItemCount* itemCount, CfgPrefsHeader prefsTOC[]);

DISCUSSION

accessID

On input, a value of type CfgEntityAccessID (page 100), obtained by previously calling OTCfgOpenPrefs (page 84) that identiﬁes the entity whose preferences are to be obtained.

itemCount On input, a pointer to a value of type ItemCount that speciﬁes

the requested number of preferences. On output, itemCount contains the number of preferences that were obtained.

prefsTOC On input, an array of CfgPrefsHeader (page 100) structures. The

prefsTOC parameter must have enough CfgPrefsHeader

structures to store all of the preferences in the entity.

function result A value of noErr indicates that OTCfgGetPrefsTOC returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgGetPrefsTOC function obtains information about the speciﬁed number preferences in the entity represented by accessID and stores them in the

prefsTOC array.

Before you call OTCfgPrefsTOC, you must should ﬁnd out how many preferences are available by calling OTCfgGetPrefsTOCCount (page 88).

WARNING

Early versions of Network Setup do not determine whether there is enough space in prefsTOC (as speciﬁed on input by

itemCount) and can write beyond the end of the array. You

should always call OTCfgGetPrefsTOCCount before calling

OTCfgGetPrefsTOC. When you call OTCfgGetPrefsTOC, set itemCount to the value returned by OTCfgGetPrefsTOCCount

in the

itemCount parameter. ▲

Network Setup Functions 89

CHAPTER 3

Network Setup Reference

OTCfgGetDefault 3

Returns a handle containing the default value for a preference.

Handle OTCfgGetDefault (OSType entityType,

OSType entityClass, OSType prefsType);

DISCUSSION

entityType

On input, a value of type OSType that identiﬁes the entity type of the default preference that is to be obtained. For possible values, see “Entity Classes and Types” (page 104).

entityClass On input, a value of type OSType that identiﬁes the entity class of

the default preference that is to be obtained. For possible values, see “Entity Classes and Types” (page 104).

prefsType On input, a value of type OSType that identiﬁes the preference

whose default value is to be obtained.

function result A handle or NULL if no preference of the speciﬁed entity type,

class, and preference type exists, or if there is not enough memory to obtain the handle.

The OTCfgGetDefault function returns a handle containing the default value for a preference of the speciﬁed entity, class, and preference type.

Note

You are responsible for disposing of the handle that

OTCfgGetDefault obtains by calling the Memory Manager

function DisposeHandle. ◆

OTCfgDeletePrefs 3

Deletes a preference.

OSStatus OTCfgDeletePrefs (CfgEntityAccessID accessID,

OSType prefsType);

90 Network Setup Functions

DISCUSSION

CHAPTER 3

Network Setup Reference

accessID On input, a value of type CfgEntityAccessID (page 100),

obtained by previously calling OTCfgOpenPrefs (page 84) that identiﬁes the entity from which a preference is to be deleted.

prefsType On input, a value of type OSType that identiﬁes the preference

type of the preference that is to be deleted.

function result A value of noErr indicates that OTCfgDeletePrefs returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgDeletePrefs function deletes the preference of the type speciﬁed by

prefsType from the entity speciﬁed by accessID.

Note

The OTCfgDeletePrefs function is available in Network Setup version 1.2 and later.

OTCfgGetTemplate 3

Gets the default value for a speciﬁc preference.

OSStatus OTCfgGetTemplate(CfgEntityClass entityClass,

CfgEntityType entityType, OSType prefsType, void *data, ByteCount *dataSize);

entityClass

entityType On input, a value of type CfgEntityType that speciﬁes the type of

prefsType On input, a value of type OSType that speciﬁes the preference

Network Setup Functions 91

On input, a value of type CfgEntityClass that speciﬁes the class of the preference whose default value is to be obtained.

the preference whose default value is to be obtained.

type of the preference whose default value is to be obtained.

DISCUSSION

CHAPTER 3

Network Setup Reference

data On input, a pointer to the buffer into which the default value is

to be placed. On output, data points 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,

dataSize points to the number of bytes in the buffer pointed to

by data. On input, if data is NULL, on output, dataSize points to the size in bytes of the default value for the specified preference.

function result A value of noErr indicates that OTCfgGetTemplate returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgGetTemplate function gets the default value for the preference identiﬁed by the entityClass, entityType, and prefsType parameters and stores it in the buffer described by data and dataSize.

IMPORTANT

The OTCfgGetTemplate function 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. ▲

Preference Utilities 3

Use the following functions to encrypt and decrypt preferences:

■ OTCfgDecrypt (page 93) decrypts data.

■ OTCfgEncrypt (page 93) encrypts data.

92 Network Setup Functions

CHAPTER 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,

data contains the encrypted password.

dataLen On input, a value of type SInt16 that speciﬁes the number of

bytes in the data array.

function result The length of the encrypted data.

DISCUSSION

The OTCfgEncrypt function encrypts the contents of the data parameter using the key speciﬁed by the key parameter. For sample code, see Listing 2-17 in Chapter 2, “Using Network Setup.”

Note

The OTCCfgEncrypt function is available in Network Setup version 1.1 and later. ◆

OTCfgDecrypt 3

Decrypts data.

SInt16 OTCCfgDecrypt (const UInt8 *key.

UInt8 *data, SInt16 dataLen);

Network Setup Functions 93

DISCUSSION

CHAPTER 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,

data contains the decrypted data.

dataLen On input, a value of type SInt16 that speciﬁes the length of data.

function result The length in bytes of the decrypted data.

The OTCfgDecrypt function decrypts the contents of the data parameter using the key speciﬁed by the key parameter.

Note

The OTCCfgDecrypt function is available in Network Setup version 1.1 and later. ◆

Installing and Removing a Notiﬁcation Callback 3

You can use the following functions to install and remove a notiﬁcation callback:

■ OTCfgInstallNotifier (page 94) installs a notiﬁcation callback.

■ OTCfgRemoveNotifier (page 96) removes a notiﬁcation callback.

OTCfgInstallNotiﬁer 3

Installs a notiﬁcation callback.

OSStatus OTCfgInstallNotifier (CfgDatabaseRef dbRef.

CfgEntityClass theClass, CfgEntityType theType, OTNotifyProcPtr notifier, void* contextPtr);

94 Network Setup Functions

CHAPTER 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).

theClass On input, a value of type CfgEntityClass that speciﬁes the class

for which the notiﬁcation callback is to be called. For possible values, see the constants described in “Entity Classes and Types” (page 104). Constants that deﬁne wildcards are valid.

theType On input, a value of type CfgEntityType that speciﬁes the type

for which the notiﬁcation callback is to be called. For possible values, see the constants described in “Entity Classes and Types” (page 104). Constants that deﬁne wildcards are valid.

notifier On input, a value of type OTNotifyProcPtr that points to the

notiﬁcation callback that is to be installed.

contextPtr On input, a pointer to an arbitrary data type that is passed to the

notiﬁcation callback when it is called.

function result A value of noErr indicates that OTCfgInstallNotifier returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110)

DISCUSSION

The OTCfgInstallNotifier function installs a notiﬁcation callback that is called when changes to preferences of the speciﬁed class and type occur. Calling

OTCfgInstallNotifier when you have already installed a notiﬁcation callback

causes the current notiﬁcation callback to be replaced by the new notiﬁcation callback.

Note

The OTCfgInstallNotifier function is available in Network Setup version 1.0.2 and later. ◆

To remove an installed notiﬁcation callback, call OTCfgRemoveNotifier (page 96). Notiﬁcation callbacks are removed automatically when the database session represented by dbRef is closed.

Network Setup Functions 95

CHAPTER 3

Network Setup Reference

OTCfgRemoveNotiﬁer 3

Removes a notiﬁcation callback.

OSStatus OTCfgRemoveNotifier (CfgDatabaseRef dbRef.

CfgEntityClass theClass, CfgEntityType theType);

DISCUSSION

dbRef

On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling

OTCfgOpenDatabase (page 58).

theClass On input, a value of type CfgEntityClass specifying the class

that was speciﬁed when the notiﬁcation callback was installed.

theType On input, a value of type CfgEntityType specifying the type that

was speciﬁed when the notiﬁcation callback was installed.

function result A value of noErr indicates that OTCfgRemoveNotifier returned

successfully. For a list of other possible result codes, see “Result Codes” (page 110).

The OTCfgRemoveNotifier function removes the speciﬁed notiﬁcation callback that was previously installed by OTCfgInstallNotifier (page 94).

Note

The OTCfgRemoveNotifier function is available in Network Setup version 1.0.2 and later. ◆

Notiﬁcation callbacks are removed automatically when the database session represented by dbRef is closed.

Application-Deﬁned Routines 3

This section describes the application-deﬁned routine that you can provide:

■ A notiﬁcation callback routine, which is called when changes occur in the

Network Setup database.

96 Network Setup Functions

CHAPTER 3

Network Setup Reference

Notiﬁcation Callback Routine 3

Receives notiﬁcations of changes to the Network Setup database.

typedef CALLBACK_API_C( void, OTNotifyProcPtr ) (

void *contextPtr, OTEventCode code, OSStatus result, void *cookie);

contextPtr

A pointer to the untyped value that was speciﬁed when you called OTCfgInstallNotifier (page 94) to install the notiﬁcation callback routine.

code A value of type OTEventCode.Your notiﬁcation callback routine

should ignore callbacks when this is any value other than

kCfgDatabaseChanged.

result A notiﬁcation-dependent value of type OSStatus. When the

value of code is kCfgDatabaseChanged, the value of result is

kCfgErrDatabaseChanged.

cookie Reserved.

DISCUSSION

Your notiﬁcation 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 notiﬁcation 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

■ CfgDatabaseRef (page 98), which refers to an open database session.

■ CfgAreaID (page 98), which identiﬁes an area.

■ CfgEntityRef (page 99), which refers to an open entity.

Network Setup Structures and Data Types 97

CHAPTER 3

Network Setup Reference

■ CfgEntityInfo (page 99), which contains information about the entities in an

area.

■ CfgEntityAccessID (page 100), which identiﬁes an open preference within an

entity.

■ CfgPrefsHeader (page 100), which is used to return information about the

preferences within an entity.

■ CfgSetsStruct (page 101), which stores information about a set entity.

■ CfgSetsElement (page 103), which represents an element in a CfgSetsVector

(page 103) structure.

■ 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 identiﬁes 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 CfgDatabaseRef to open an area, make changes in an area, list and create entities in an area, and to open an entity.

A CfgDatabaseRef whose value is NULL is never a valid database reference.

CfgAreaID 3

A value of type CfgAreaID identiﬁes an area.

typedef UInt32 CfgAreaID;

CfgAreaID

98 Network Setup Structures and Data Types

An unsigned 32-bit value that uniquely identiﬁes an area.

CHAPTER 3

Network Setup Reference

Network Setup uses a value of type CfgAreaID to identify the area in which an entity resides. For example, a value of type CfgAreaID is 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 CfgEntityRef structure refers to a speciﬁc entity.

struct CfgEntityRef {

CfgAreaID fLoc; UInt32 fReserved;

Str255 fID; }; typedef struct CfgEntityRef CfgEntityRef;

Field descriptions

fLoc The area in which the entity resides.

fReserved Reserved.

fID The entity ID.

For example, OTCfgCreateEntity (page 76) returns a CfgEntityRef structure to refer to the newly created entity, and OTCfgGetEntitiesList (page 74) returns a

CfgEntityRef for each entity in an area.

CfgEntityInfo 3

The CfgEntityInfo structure 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

CHAPTER 3

Network Setup Reference

Field descriptions

fClass The entity’s class. See “Entity Classes and Types”

(page 104) for possible values.

fType The entity’s type. See “Entity Classes and Types” (page 104)

for possible values.

fName The entity’s user-visible name.

fIcon The entity’s custom icon. For details, see the deﬁnition of

CfgResourceLocator (page 101).

CfgEntityInfo structures are used when calling OTCfgCreateEntity (page 76)

and when calling OTCfgGetEntitiesList (page 74).

CfgEntityAccessID 3

A CfgEntityAccessID refers to an open preference.

typedef void *CfgEntityAccessID;

CfgEntityAccessID

A pointer to an arbitrary data type whose value represents an open entity

Call OTCfgOpenPrefs (page 84) to open an entity and received a value of type

CfgEntityAccessID. Pass CfgEntityAccessID as 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 CfgEntityAccessID whose value is NULL is never a valid entity access ID.

CfgPrefsHeader 3

The CfgPrefsHeader structure is used to return information about preferences in an entity.

struct CfgPrefsHeader {

UInt16 fSize; UInt16 fVersion;

100 Network Setup Structures and Data Types

Apple INSIDE MACIN TOSH User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Figures, Tables, and Listings

About This Manual

Conventions Used in This Manual 0

For More Information 0

About Network Setup 1

Network Setup Architecture

Inside the Network Setup Library

Database Structure 1

Network Setup Database Fundamentals

Database Structure Example 1

Database Operations 1

Preference Coherency 1

Legacy Issues

Legacy Synchronization Algorithm 1

Network Setup Version History 1

Using Network Setup 2

Opening and Closing the Network Setup Database 2

Opening the Database for Reading 2

Opening the Database for Writing 2

Closing the Database After Reading 2

Closing the Database After Writing 2

Working with Entities 2

Listing All Entities 2

Finding an Active Entity 2

Reading and Writing Preferences 2

Reading Fixed-size Preferences 2

Reading Variable-size Preferences 2

Writing Preferences 2

Iterating the Preferences in an Entity 2

Working with Sets 2

Finding the Active Set Entity 2

Areas and Sets 2

TCP/IP Notes 2

Remote Access Notes 2

Modem Notes 2

Notes for Third Parties 2

Storing Third-party Preferences in Apple Entities 2

Network Setup and Third-party Protocol Stacks 2

Network Setup Reference 3

Network Setup Functions 3

Opening and Closing the Network Setup Database 3

OTCfgOpenDatabase 3

OTCfgCloseDatabase 3

Managing Areas 3

OTCfgGetCurrentArea 3

OTCfgSetCurrentArea 3

OTCfgOpenArea 3

OTCfgCloseArea 3

Only one program can open an area of writing at any one time. If another program has already opened the area for writing, OTCfgBeginAreaModifications returns

OTCfgCommitAreaModifications returns kCfgErrAreaNotFound.

OTCfgAbortAreaModifications returns kCfgErrAreaNotFound.

OTCfgIsSameAreaID 3

OTCfgGetAreaName 3

OTCfgSetAreaName 3

OTCfgGetAreasList (page 68) to get the ID and name of each area.

OTCfgGetAreasCount (page 68) to determine the number of areas

OTCfgCreateArea 3

OTCfgDuplicateArea 3

OTCfgDeleteArea 3

Managing Entities 3

OTCfgGetEntitiesCount 3

OTCfgGetEntitiesList 3

OTCfgIsSameEntityRef is particularly useful, see “Areas and Sets” (page 48).

OTCfgCreateEntity 3

OTCfgDeleteEntity 3

OTCfgDuplicateEntity 3

OTCfgGetEntityLogicalName 3

OTCfgGetEntityName 3

OTCfgSetEntityName 3

OTCfgGetEntityArea 3

OTCfgChangeEntityArea 3

Managing Preferences 3

OTCfgOpenPrefs 3

OTCfgClosePrefs 3

OTCfgGetPrefsSize 3