Summary of the content on the page No. 1
INSIDE MA C I N T O S H
Network Setup
© Apple Computer, Inc. 2000
Summary of the content on the page No. 2
Apple Computer, Inc. Helvetica and Palatino are registered trademarks of Linotype-Hell AG © 2000 Apple Computer, Inc. and/or its subsidiaries. All rights reserved. ITC Zapf Dingbats is a registered No part of this publication may be trademark of International Typeface reproduced, stored in a retrieval Corporation. system, or transmitted, in any form or by any means, mechanical, Simultaneously published in the electronic, photocopying, recording, United States and Canada. or othe
Summary of the content on the page No. 3
Contents Figures, Tables, and Listings 7 Preface About This Manual 9 Conventions Used in This Manual 9 For More Information 10 Chapter 1 About Network Setup 11 Network Setup Architecture 11 Inside the Network Setup Library 14 Network Setup Database Fundamentals 16 Database Structure 16 Database Structure Example 17 Database Operations 19 Preference Coherency 21 Legacy Issues 21 Legacy Synchronization Algorithm 22 Network Setup Version History 23 Chapter 2 Using Network Setup 25 Open
Summary of the content on the page No. 4
Writing Preferences 39 Iterating the Preferences in an Entity 40 Working with Sets 42 Finding the Active Set Entity 43 Areas and Sets 48 Protocol-specific Topics 49 TCP/IP Notes 49 Remote Access Notes 53 Modem Notes 54 Notes for Third Parties 55 Storing Third-party Preferences in Apple Entities 55 Network Setup and Third-party Protocol Stacks 55 Chapter 3 Network Setup Reference 57 Network Setup Functions 57 Opening and Closing the Network Setup Database 57 Managing Areas 59 Managing Entiti
Summary of the content on the page No. 5
Chapter 4 Network Setup Protocol Structures and Data Types 111 Protocol Structures 111 TCP/IP Structures 111 Apple Remote Access Structures 122 Modem Structures 141 AppleTalk Structures 144 Infrared Structures 158 Protocol Constants and Other Data Types 159 TCP/IP Constants and Other Data Types 160 Apple Remote Access Constants and Other Data Types 163 Modem Constants and Other Data Types 170 AppleTalk Constants and Other Data Types 172 Infrared Constants and Other Data Types 173 Glossa
Summary of the content on the page No. 6
6
Summary of the content on the page No. 7
Figures, Tables, and Listings Chapter 1 About Network Setup 11 Figure 1-1 Network configuration prior to Network Setup 12 Figure 1-2 Network Setup in Mac OS 8.5 through the present 13 Figure 1-3 Future Network Setup architecture 14 Figure 1-4 Structure of the Network Setup Library 15 Figure 1-5 Sample organization of the default area 18 Figure 1-6 Reading and writing the default area 20 Table 1-1 Network Setup versions 23 Chapter 2 Using
Summary of the content on the page No. 8
8
Summary of the content on the page No. 9
PREF ACE 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
Summary of the content on the page No. 10
PREF ACE For More Information 0 The following sources provide additional information that may be of interest to developers who use the Network Setup programming interface: Inside AppleTalk, Second Edition. Inside Macintosh: Networking with Open Transport. Open Transport Advanced Client Programming, available at http://developer.apple.com/macos/opentransport/OTAdvancedClientProg/ OTAdvancedClientProg.html 10
Summary of the content on the page No. 11
CHAPTER 1 Figure 1-0 About Network Setup 1 Listing 1-0 Table 1-0 Network Setup is a system service that allows you to manipulate network configurations. You can use Network Setup to read, create, modify, and delete network configurations. Any option that is accessible to the user through the network control panels provided by Apple is also available to you through the Network Setup programming interface. This chapter describes the overall Network Setup architecture and introduces the
Summary of the content on the page No. 12
CHAPTER 1 About Network Setup Figure 1-1 Network configuration prior to Network Setup Control panels TCP/IP AppleTalk Remote Access, Private interface TCP/IP AppleTalk Modem, protocol protocol Dial Assist, stack stack Infrared, ... Private preferences files TCP/IP preferences AppleTalk preferences 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
Summary of the content on the page No. 13
CHAPTER 1 About Network Setup Figure 1-2 Network Setup in Mac OS 8.5 through the present Network Network Setup Third-party Setup aware applications application scripting Legacy TCP/IP TCP/IP TCP/IP control Public interface panels TCP/IP TCP/IP TCP/IP Legacy Protocol Protocol Network Setup library Protocol protocol Stack Stack Stack stacks Legacy preferences files Network Setup database The following key points are to be taken from Figure 1-2: The Network Setup library provid
Summary of the content on the page No. 14
CHAPTER 1 About Network Setup remove support for legacy preferences files as soon as possible. Figure 1-3 shows the future Network Setup architecture. Figure 1-3 Future Network Setup architecture Network Network Third-party Network Setup control Setup application aware applications panel scripting TCP/IP TCP/IP TCP/IP Protocol Updated Protocol Protocol Public interface Stack protocol Stack Stack stacks Network Setup library Network Setup database In the future Network Setup archi
Summary of the content on the page No. 15
CHAPTER 1 About Network Setup Figure 1-4 Structure of the Network Setup Library Network Setup High-level framework aware applications Legacy Mid-level database (OTCfg) Synchronization Network Setup module extension Low-level database (Cfg) As shown in Figure 1-4, the Network Setup library is divided into four key components: The low-level database, which is an internal component of the Network Setup Extension file. The low-level database contains the core database manipulatio
Summary of the content on the page No. 16
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 store preferences, while temporary areas are used as part of the preference modification process. The system currently uses a single named area, known as the default area
Summary of the content on the page No. 17
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 preferences, distinguished by a preference type (an OSType). A
Summary of the content on the page No. 18
CHAPTER 1 About Network Setup Figure 1-5 Sample organization of the default area Default area AppleTalk global protocol entity 'opts' preference 'opts' preference ... ... TCP/IP global protocol entity 'opts' preference 'opts' preference ... ... "LocalTalk for Printer" AppleTalk network protocol entity 'atfp' preference 'atfp' preference general AppleTalk preference 'port' preference user-visible name of this port 'port' preference ... ... "Company Ethernet" AppleTalk network protocol ent
Summary of the content on the page No. 19
CHAPTER 1 About Network Setup For simplicity, this example assumes a computer with two places of operation, home and work, and two protocol stacks, TCP/IP and AppleTalk. Thus, there are four network connection entities: “AirPort,” a TCP/IP network connection entity that configures a TCP/IP interface to use an AirPort card to access an AirPort Base Station at home. “LocalTalk for Printer,” an AppleTalk network connection entity that configures an AppleTalk interface to
Summary of the content on the page No. 20
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 are
