INSIDE MACINTOSH Network Setup © Apple Computer, Inc.
Apple Computer, Inc. © 2000 Apple Computer, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc., except to make a backup copy of any documentation provided on CD-ROM. The Apple logo is a trademark of Apple Computer, Inc.
Contents Figures, Tables, and Listings Preface About This Manual 7 9 Conventions Used in This Manual For More Information 10 Chapter 1 About Network Setup 9 11 Network Setup Architecture 11 Inside the Network Setup Library 14 Network Setup Database Fundamentals 16 Database Structure 16 Database Structure Example 17 Database Operations 19 Preference Coherency 21 Legacy Issues 21 Legacy Synchronization Algorithm 22 Network Setup Version History 23 Chapter 2 Using Network Setup 25 Opening and Clos
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 Network Setup and Third-party Protocol Stacks Chapter 3 Network Setup Reference 55 55 57 Network Setup Functions 57 Opening and Closing the Network Setup Database 57 Managing Areas 59 Managing Entities 72 Managi
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 Modem Constants and Other Data Types 170 AppleTalk Constants and Other Data Types 172 Infrared Constants and Other Data Types 173 Glossary Index 111 163 175 1
Figures, Tables, and Listings Chapter 1 Chapter 2 About Network Setup 11 Figure 1-1 Figure 1-2 Figure 1-3 Figure 1-4 Figure 1-5 Figure 1-6 Network configuration prior to Network Setup 12 Network Setup in Mac OS 8.
P R E F A C E About This Manual This manual describes Network Setup, which is a programming interface that allows you to manipulate the contents of the Network Setup database. The Network Setup database contains settings for all of the network protocols installed on the system. Using Network Setup, you can programmatically modify any network setting that the user can see in the various networking control panels.
P R E F A C E For More Information 0 The following sources provide additional information that may be of interest to developers who use the Network Setup programming interface: ■ 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.
C H A P T E R Figure 1-0 Listing 1-0 Table 1-0 1 About Network Setup 1 Network Setup is a system service that allows you to manipulate network configurations. You can use Network Setup to read, create, modify, and delete network configurations. Any option that is accessible to the user through the network control panels provided by Apple is also available to you through the Network Setup programming interface.
C H A P T E R 1 About Network Setup Figure 1-1 Network configuration prior to Network Setup Control panels TCP/IP Private interface AppleTalk TCP/IP protocol stack AppleTalk protocol stack Remote Access, Modem, Dial Assist, 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.
C H A P T E R 1 About Network Setup Figure 1-2 Network Setup in Mac OS 8.
C H A P T E R 1 About Network Setup remove support for legacy preferences files as soon as possible. Figure 1-3 shows the future Network Setup architecture.
C H A P T E R 1 About Network Setup Figure 1-4 Structure of the Network Setup Library Network Setup aware applications High-level framework Mid-level database (OTCfg) Network Setup extension Legacy Synchronization module 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 manipulation engine.
C H A P T E R 1 About Network Setup Network Setup Database Fundamentals 1 This section describes the fundamental structure of and operations on the Network Setup database. Database Structure 1 The Network Setup database consists of multiple areas. There are two types of areas: named areas store preferences, while temporary areas are used as part of the preference modification process.
C H A P T E R 1 About Network Setup one active set entity. The entities referenced by the active set entity comprise the active network preferences. All set entities have the same type. ■ 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).
C H A P T E R 1 About Network Setup Figure 1-5 Sample organization of the default area Default area AppleTalk global protocol entity 'opts' 'opts' preference preference ... ... TCP/IP global protocol entity 'opts' 'opts' preference preference ... ... "LocalTalk for Printer" AppleTalk network protocol entity 'atfp' general AppleTalk preference 'atfp' preference preference 'port' user-visible name of this port 'port' preference preference ... ...
C H A P T E R 1 About Network Setup For simplicity, this example assumes a computer with two places of operation, home and work, and two protocol stacks, TCP/IP and AppleTalk. Thus, there are four network connection entities: ■ “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.
C H A P T E R 1 About Network Setup reading, it reads the area directly. Network Setup simply notes that the area is open for synchronization purposes (see the section “Preference Coherency” (page 21)). For writing, the process is somewhat different. When an application opens an area for writing, Network Setup creates a temporary area that is an exact duplicate of the default area. It then returns the temporary area ID to the application.
C H A P T E R 1 About Network Setup Preference Coherency 1 When an application commits changes to the default area, it is important that applications that are reading the database be informed of those changes. For example, an application might be displaying the DHCP client ID preference. If another application changes this preference in the database, it is important that the original application update its display. Prior to Network Setup 1.0.
C H A P T E R 1 About Network Setup Given that legacy synchronization is slow and that legacy preferences files do not support multihoming, future system software will not support legacy synchronization. Legacy Synchronization Algorithm 1 Network Setup synchronizes the database and the legacy preferences files at the following times: ■ When the database is opened. Network Setup checks the modification dates of each legacy preferences file against modification dates stored in the database.
C H A P T E R 1 About Network Setup entity, it creates a resource containing the preference data with the resource type matching the preference type and the resource ID the same as the 'cnam' resource. Network Setup uses a number of private preferences to ensure a reliable round trip conversion between legacy preferences files and the database.
C H A P T E R 1 About Network Setup 24 Network Setup Version History
C H A P T E R Figure 2-0 Listing 2-0 Table 2-0 2 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.
C H A P T E R 2 Using Network Setup Listing 2-1 Opening the database for reading static OSStatus MyOpenDatabaseForReading(CfgDatabaseRef *dbRef, CfgAreaID *readArea) { OSStatus err; assert(dbRef != nil); assert(readArea != nil); err = OTCfgOpenDatabase(dbRef); if (err == noErr) { err = OTCfgGetCurrentArea(*dbRef, readArea); if (err == noErr) { err = OTCfgOpenArea(*dbRef, *readArea); } if (err != noErr) { (void) OTCfgCloseDatabase(dbRef); } } if (err != noErr) { *dbRef = nil; *readArea = kInvalidCfgArea
C H A P T E R 2 Using Network Setup area, but you can read from both the original area and the writable area to access, respectively, the currently active network settings and your proposed changes to the network settings.
C H A P T E R 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.
C H A P T E R 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.
C H A P T E R 2 Using Network Setup Working with Entities 2 Once you have a reference to the database and an area identifier for the default area, the next step is to look for appropriate entities within that area. Regardless of what you want to do to an entity, you must first obtain a reference to it. An entity reference is an opaque data structure that Network Setup uses to uniquely identify each entity within an area.
C H A P T E R 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.
C H A P T E R 2 Using Network Setup SetHandleSize( (Handle) entityRefs, entityCount * sizeof(CfgEntityRef) ); err = MemError(); } if ((err == noErr) && (entityInfos != nil)) { SetHandleSize( (Handle) entityInfos, entityCount * sizeof(CfgEntityInfo) ); err = MemError(); } if (err == noErr) { if (entityRefs == nil) { paramRefs = nil; } else { sRefs = HGetState( (Handle) entityRefs ); noErr); HLock( (Handle) entityRefs ); noErr); paramRefs = *entityRefs; } if (entityInfos == nil) { paramInfos = nil; } else
C H A P T E R 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).
C H A P T E R 2 Using Network Setup entityCount = GetHandleSize( (Handle) entityRefs ) / sizeof(CfgEntityRef); for (entityIndex = 0; entityIndex < entityCount; entityIndex++) { err = MyGetEntityUserVisibleName(dbRef, &(*entityRefs)[entityIndex], userVisibleName); if (err == noErr) { printf("%ld) "%#s"\n", entityIndex, userVisibleName); } } } MyCloseDatabaseAfterReading(dbRef, readArea); } if (entityRefs != nil) { DisposeHandle( (Handle) entityRefs ); noErr); } assert(MemError() == if (err != noErr) { p
C H A P T E R 2 Using Network Setup write the desired preferences, and close the entity. This section describes this process for reading variable-length and fixed-size preferences and for writing preferences. Reading Fixed-size Preferences 2 Many Network Setup preferences are of a fixed size. Reading a fixed size preference is easy because you simply read it into the C structure that corresponds to the preference.
C H A P T E R 2 Using Network Setup Note The sample shown in Listing 2-7, which opens and closes the entity before reading each preference, is implemented in an inefficient manner for the sake of clarity. If you are reading multiple preferences, it is more efficient to open the entity once. Then read the preferences by calling OTCfgGetPrefs or OTCfgSetPrefs multiple times and close the entity when you’re done.
C H A P T E R 2 Using Network Setup IMPORTANT You can derive the C structure for a specific 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-defined preferences are provided in Chapter 4, “Network Setup Protocol Structures and Data Types.
C H A P T E R 2 Using Network Setup by calling OTCfgGetPrefsSize before you read the preference, as shown in Listing 2-10.
C H A P T E R 2 Using Network Setup } return err; } Writing Preferences 2 Listing 2-11 shows the routine MyWritePref, which demonstrates the basic mechanism for writing preferences. Writing a preference is similar to reading a preference, with the following exceptions: ■ 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.
C H A P T E R 2 Using Network Setup err2 = OTCfgClosePrefs(accessID); if (err == noErr) { err = err2; } } return err; } Note The sample shown in Listing 2-11, which opens and closes the entity for each preference written, is implemented in an inefficient manner for the sake of clarity. If you are writing multiple preferences, it is more efficient to open the entity, write your preferences by calling OTCfgSetPrefs multiple times, and close the entity when you’re done.
C H A P T E R 2 Using Network Setup assert(dbRef != nil); assert(entity != nil); prefsTOC = nil; err = OTCfgOpenPrefs(dbRef, entity, false, &accessID); if (err == noErr) { err = OTCfgGetPrefsTOCCount(accessID, &prefsTOCCount); if (err == noErr) { prefsTOC = (CfgPrefsHeader *) NewPtr(prefsTOCCount * sizeof(CfgPrefsHeader)); err = MemError(); } if (err == noErr) { err = OTCfgGetPrefsTOC(accessID, &prefsTOCCount, prefsTOC); } if (err == noErr) { for (prefsTOCIndex = 0; prefsTOCIndex < prefsTOCCount; prefsTO
C H A P T E R 2 Using Network Setup Working with Sets 2 The Network Setup database uses set entities to store collections of other entity references. When network entities are grouped into sets, they can be activated and deactivated as a group. All of the network entities in all of the sets reside in a single area, so there are no limits on the way entities can be grouped. For example, a single network connection entity can be referenced by multiple sets.
C H A P T E R 2 Using Network Setup There are a few basic rules for set entities: ■ Each set entity contains a preference, kOTCfgSetsStructPref, that has a flag 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.
C H A P T E R 2 Using Network Setup The MyFindActiveSet routine in Listing 2-13 implements the first two steps. It starts by getting a list of all of the set entities by calling the MyGetEntitiesList routine (Listing 2-5). Then 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.
C H A P T E R 2 Using Network Setup kOTCfgSetsStructPref, &thisStruct, sizeof(thisStruct)); if ((err == noErr) && ((thisStruct.
C H A P T E R 2 Using Network Setup Listing 2-14 Finding the active entity of a given class and type static OSStatus MyFindFirstActiveEntity(CfgDatabaseRef dbRef, CfgAreaID area, OSType entityClass, OSType entityType, CfgEntityRef *activeEntity) { OSStatus err; CfgEntityRef activeSet; CfgSetsVector **entitiesInSet; ItemCount entityIndex; Boolean found; CfgEntityInfo thisEntityInfo; entitiesInSet = (CfgSetsVector **) NewHandle(0); err = MemError(); if (err == noErr) { err = MyFindActiveSet(dbRef, area,
C H A P T E R 2 Using Network Setup *activeEntity = (**entitiesInSet).fElements[entityIndex].fEntityRef; OTCfgChangeEntityArea(activeEntity, area); } if (entitiesInSet != nil) { DisposeHandle( (Handle) entitiesInSet ); noErr); } return err; } assert(MemError() == The code in Listing 2-15 pulls together the process of finding an active set entity by finding the active TCP/IP set entity.
C H A P T E R 2 Using Network Setup printf("User-visible name of active TCP/IP entity = "%#s"\n", userVisibleName); } MyCloseDatabaseAfterReading(dbRef, readArea); } if (err != noErr) { printf("Failed with error %ld.\n", err); } } Areas and Sets 2 When working with sets you need to be very careful about area identifiers. There are three key points to remember: ■ The area identifier is embedded in the entity reference. ■ All modifications to the database are done in a temporary area.
C H A P T E R 2 Using Network Setup The solution to this problem is very simple: assume that all entity references in a set refer to entities that are in the same area as the set. This has two practical consequences. ■ 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.
C H A P T E R 2 Using Network Setup ■ kOTCfgTCPDNSServersListPref, which contains the list of configured 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 specifies how TCP/IP loads and unloads. For details, see OTCfgTCPUnloadAttr (page 121).
C H A P T E R 2 Using Network Setup cursor = (UInt8 *) packedPref; // For each field in the unpacked pref, copy the field to the // packed preference cursor and advance the cursor appropriately.
C H A P T E R 2 Using Network Setup static OSStatus MyUnpackTCPInterfacesPref(const OTCfgTCPInterfacesPacked *packedPref, ByteCount packedPrefSize, OTCfgTCPInterfacesUnpacked *unpackedPref) { UInt8 *cursor; assert(packedPref != nil); assert(unpackedPref != nil); // Put the cursor at the beginning of the packed preference data. cursor = (UInt8 *) packedPref; // Walk through the packed preference data and extract the fields.
C H A P T E R 2 Using Network Setup // If the cursor doesn’t stop at the end of the packed preference data, a data format error occurs.
C H A P T E R 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.
C H A P T E R 2 Using Network Setup DTS Technote 1119 Serial Port Apocrypha available at http://developer.apple.com/technotes/tn/tn1119.html. Notes for Third Parties 2 This section contains miscellaneous hints and tips for third-party developers who want to use Network Setup to store their own preferences. Storing Third-party Preferences in Apple Entities 2 It is reasonable for third-party developers to store custom preferences inside Apple Computer’s protocol entities.
C H A P T E R 2 Using Network Setup 56 Notes for Third Parties
C H A P T E R Figure 3-0 Listing 3-0 Table 3-0 3 Network Setup Reference 3 This chapter describes the functions, structures, and data types for calling Network Setup. For protocol-specific preferences, see Chapter 4, “Network Setup Protocol Structures and Data Types.
C H A P T E R 3 Network Setup Reference OTCfgOpenDatabase 3 Opens a session with the Network Setup database. OSStatus OTCfgOpenDatabase (CfgDatabaseRef* dbRef); dbRef On input, a pointer to a value of type CfgDatabaseRef (page 98). On output, 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).
C H A P T E R 3 Network Setup Reference Note Closing a database session automatically removes any notification callback that has been installed for the session represented by dbRef. ◆ 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.
C H A P T E R 3 Network Setup Reference IMPORTANT Areas other than the default area (also known as the current area) do not affect any network setting, so many of the area manipulation functions described in this section are not commonly used. You rarely need to call OTCfgGetAreaName, OTCfgSetAreaName, OTCfgGetAreasCount, OTCfgGetAreasList, OTCfgCreateArea, OTCfgDuplicateArea, or OTCfgDeleteArea. ▲ OTCfgGetCurrentArea 3 Obtains the default area.
C H A P T E R 3 Network Setup Reference OTCfgSetCurrentArea 3 Sets the default area. OSStatus OTCfgSetCurrentArea (CfgDatabaseRef dbRef, CfgAreaID areaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). areaID On input, a value of type CfgAreaID (page 98) containing the areaID that identifies the area that is to be made active.
C H A P T E R 3 Network Setup Reference dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). areaID On input, a value of type CfgAreaID (page 98) that identifies the area that is to be opened. If the area specified by areaID does not exist, OTCfgOpenArea returns kCfgErrAreaNotFound. function result A value of noErr indicates that OTCfgOpenArea returned successfully.
C H A P T E R 3 Network Setup Reference OTCfgBeginAreaModifications 3 Creates a temporary area for modifying an area. OSStatus OTCfgBeginAreaModifications (CfgDatabaseRef dbRef, CfgAreaID readAreaID, CfgAreaID* writeAreaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). readAreaID On input, a value of type CfgAreaID (page 98) obtained by calling OTCfgGetCurrentArea (page 60).
C H A P T E R 3 Network Setup Reference Call OTCfgCommitAreaModifications (page 64) to write the temporary area to the area identified by writeAreaID, dispose of the temporary area, and close the area represented by writeAreaID, or call OTCfgAbortAreaModifications (page 65) to close the area represented by readAreaID and discard the temporary area. OTCfgCommitAreaModifications 3 Closes an area for writing and commits modifications.
C H A P T E R 3 Network Setup Reference OTCfgAbortAreaModifications 3 Closes an area for writing without committing modifications. OSStatus OTCfgAbortAreaModifications (CfgDatabaseRef dbRef, CfgAreaID readAreaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). readAreaID On input, a value of type CfgAreaID (page 98) that identifies an area that has been opened for writing.
C H A P T E R 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.
C H A P T E R 3 Network Setup Reference OTCfgSetAreaName 3 Sets the user-visible name of an area. OSStatus OTCfgSetAreaName (CfgDatabaseRef dbRef, CfgAreaID areaID, ConstStr255Param areaName, CfgAreaID* newAreaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). areaID On input, a value of type CfgAreaID (page 98) that identifies the area whose name is to be set.
C H A P T E R 3 Network Setup Reference OTCfgGetAreasCount 3 Obtains the number of areas in the Network Setup database. OSStatus OTCfgGetAreasCount (CfgDatabaseRef dbRef, ItemCount* itemCount); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). itemCount On input, a pointer to value of type ItemCount. On output, itemCount points to the number of areas in the database.
C H A P T E R 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 specified by itemCount. On output, each array element contains an area ID.
C H A P T E R 3 Network Setup Reference OTCfgCreateArea 3 Creates an area in the Network Setup database. OSStatus OTCfgCreateArea (CfgDatabaseRef dbRef, ConstStr255Param areaName, CfgAreaID* areaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). areaName On input, a value of type ConstStr255Param that specifies the user-visible name of the area to create.
C H A P T E R 3 Network Setup Reference OTCfgDuplicateArea 3 Copies the contents of one area to another area. OSStatus OTCfgDuplicateArea (CfgDatabaseRef dbRef, CfgAreaID sourceAreaID, CfgAreaID destAreaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). sourceAreaID On input, a value of type CfgAreaID (page 98) that identifies the area that is to be duplicated.
C H A P T E R 3 Network Setup Reference OTCfgDeleteArea 3 Deletes an area in the Network Setup database. OSStatus OTCfgDeleteArea (CfgDatabaseRef dbRef, CfgAreaID areaID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). areaID On input, a value of type CfgAreaID (page 98) that identifies the area that is to be deleted.
C H A P T E R 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.
C H A P T E R 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 specified 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 specified class and type in the specified area.
C H A P T E R 3 Network Setup Reference entityType On input, a value of type CfgEntityType that specifies 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 specifies the number of entities to list. Call OTCfgGetEntitiesCount (page 73) to get the current number of entities in the area represented by areaID.
C H A P T E R 3 Network Setup Reference OTCfgIsSameEntityRef 3 Compares two entity references. Boolean OTCfgIsSameEntityRef (const CfgEntityRef* entityRef1, const CfgEntityRef* entityRef2, Boolean ignoreArea); entityRef1 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.
C H A P T E R 3 Network Setup Reference dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). areaID On input, a value of type CfgAreaID (page 98) that identifies the area in which the entity is to be created. If the area specified by areaID is not writable, OTCfgCreateEntity returns the error kCfgErrLocked.
C H A P T E R 3 Network Setup Reference OTCfgDeleteEntity 3 Deletes the specified entity. OSStatus OTCfgDeleteEntity (CfgDatabaseRef dbRef, const CfgEntityRef* entityRef); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). entityRef On input, a pointer to a value of type CfgEntityRef (page 99) representing the entity that is to be deleted.
C H A P T E R 3 Network Setup Reference entityRef On input, a pointer to a value of type CfgEntityRef (page 99) that identifies the entity reference that is to be duplicated. If the entity represented by entityRef does not exist, OTCfgDuplicateEntry returns the error kCfgErrEntityNotFound. newEntityRef On input, a pointer to a value of type CfgEntityRef (page 99) that identifies the entity that is to be overwritten by the contents of entityRef.
C H A P T E R 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.
C H A P T E R 3 Network Setup Reference ▲ W AR N I N G 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.
C H A P T E R 3 Network Setup Reference DISCUSSION The OTCfgSetEntityName function sets the user-visible name of the specified entity and returns a new entity reference for the renamed entity. OTCfgGetEntityArea 3 Obtains the area ID of an entity. void OTCfgGetEntityArea (const CfgEntityRef *entityRef, CfgAreaID *areaID); entityRef On input, a pointer to a value of type CfgEntityRef (page 99) that identifies the entity reference whose area is to be obtained.
C H A P T E R 3 Network Setup Reference entityRef On input, a pointer to a value of type CfgEntityRef (page 99) that represents the entity reference whose area is to be changed. To obtain the entity reference for an entity, call OTCfgGetEntitiesList (page 74) or use the entity reference returned by a Network Setup function that creates an entity. newAreaID On input, a value of type CfgAreaID (page 98) that specifies the new area ID for the specified entity. function result None.
C H A P T E R 3 Network Setup Reference OTCfgOpenPrefs 3 Opens an entity so that its preferences can be accessed. OSStatus OTCCfgOpenPrefs (CfgDatabaseRef dbRef, const CfgEntityRef* entityRef, Boolean writer, CfgEntityAccessID* accessID); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58).
C H A P T E R 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 identifies 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).
C H A P T E R 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 specified by prefsType in the entity represented by accessID.
C H A P T E R 3 Network Setup Reference DISCUSSION The OTCfgGetPrefs function gets the value of the preference specified 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.
C H A P T E R 3 Network Setup Reference DISCUSSION The OTCfgSetPrefs function sets the preference represented by prefsType to the value specified 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.
C H A P T E R 3 Network Setup Reference OTCfgGetPrefsTOC 3 Gets a list of the preferences in an entity. OSStatus OTCfgGetPrefsTOC (CfgEntityAccessID accessID. ItemCount* itemCount, CfgPrefsHeader prefsTOC[]); accessID On input, a value of type CfgEntityAccessID (page 100), obtained by previously calling OTCfgOpenPrefs (page 84) that identifies the entity whose preferences are to be obtained.
C H A P T E R 3 Network Setup Reference OTCfgGetDefault 3 Returns a handle containing the default value for a preference. Handle OTCfgGetDefault (OSType entityType, OSType entityClass, OSType prefsType); entityType On input, a value of type OSType that identifies the entity type of the default preference that is to be obtained. For possible values, see “Entity Classes and Types” (page 104).
C H A P T E R 3 Network Setup Reference accessID On input, a value of type CfgEntityAccessID (page 100), obtained by previously calling OTCfgOpenPrefs (page 84) that identifies the entity from which a preference is to be deleted. prefsType On input, a value of type OSType that identifies the preference type of the preference that is to be deleted. function result A value of noErr indicates that OTCfgDeletePrefs returned successfully.
C H A P T E R 3 Network Setup Reference data On input, a pointer to the buffer into which the default value is to be placed. On output, 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.
C H A P T E R 3 Network Setup Reference OTCfgEncrypt 3 Encrypts data. SInt16 OTCCfgEncrypt (const UInt8 *key. UInt8 *data, SInt16 dataLen); key On input, a pointer to a Pascal string containing the encryption key. For Remote Access password, the encryption key is a user name. data On input, a pointer to an array of bytes that contains data that is to be encrypted. Usually, the data is a password. On output, data contains the encrypted password.
C H A P T E R 3 Network Setup Reference key On input, a pointer to a Pascal string containing the encryption key. Usually the encryption key is a user name. data On input, a pointer to an array of bytes containing data that was previously encrypted by OTCfgEncrypt (page 93). On output, data contains the decrypted data. dataLen On input, a value of type SInt16 that specifies the length of data. function result The length in bytes of the decrypted data.
C H A P T E R 3 Network Setup Reference dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). theClass On input, a value of type CfgEntityClass that specifies the class for which the notification callback is to be called. For possible values, see the constants described in “Entity Classes and Types” (page 104). Constants that define wildcards are valid.
C H A P T E R 3 Network Setup Reference OTCfgRemoveNotifier 3 Removes a notification callback. OSStatus OTCfgRemoveNotifier (CfgDatabaseRef dbRef. CfgEntityClass theClass, CfgEntityType theType); dbRef On input, a value of type CfgDatabaseRef (page 98) that represents a database session previously opened by calling OTCfgOpenDatabase (page 58). theClass On input, a value of type CfgEntityClass specifying the class that was specified when the notification callback was installed.
C H A P T E R 3 Network Setup Reference Notification Callback Routine 3 Receives notifications of changes to the Network Setup database. typedef CALLBACK_API_C( void, OTNotifyProcPtr ) ( void *contextPtr, OTEventCode code, OSStatus result, void *cookie); contextPtr A pointer to the untyped value that was specified when you called OTCfgInstallNotifier (page 94) to install the notification callback routine. code A value of type OTEventCode.
C H A P T E R 3 Network Setup Reference ■ CfgEntityInfo (page 99), which contains information about the entities in an area. ■ CfgEntityAccessID (page 100), which identifies an open preference within an entity. (page 100), which is used to return information about the preferences within an entity. ■ CfgPrefsHeader ■ CfgSetsStruct (page 101), which stores information about a set entity. (page 103), which represents an element in a CfgSetsVector (page 103) structure.
C H A P T E R 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 specific entity.
C H A P T E R 3 Network Setup Reference Field descriptions 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 definition of CfgResourceLocator (page 101). CfgEntityInfo structures are used when calling OTCfgCreateEntity (page 76) and when calling OTCfgGetEntitiesList (page 74).
C H A P T E R 3 Network Setup Reference OSType fType; }; typedef struct CfgPrefsHeader CfgPrefsHeader; Field descriptions fSize The size in bytes of the preference, not including the CfgPrefsHeader structure itself. Always zero in the version of Network Setup described by this document. fType An OS type that uniquely identifies the preference within the entity. To get the CfgPrefsHeader structures for an entity, call OTCfgGetPrefsTOC (page 89).
C H A P T E R 3 Network Setup Reference struct CfgSetsStruct { UInt32 fFlags; UInt32 fTimes[ kOTCfgIndexSetsLimit ]; }; typedef struct CfgSetsStruct CfgSetsStruct; Field descriptions Flags for this set. For possible values, see the enumeration for the fFlags field that follows. fTimes An array of time stamps used during legacy import and export indexed by the enumeration for the fTimes field that follows.
C H A P T E R 3 Network Setup Reference The preference type for the CfgSetsStruct structure is kOTCfgSetsStructPref, which is defined as 'stru'. CfgSetsElement 3 The CfgSetsElement structure represents an element in a CfgSetsVector structure. struct CfgSetsElement { CfgEntityRef fEntityRef; CfgEntityInfo fEntityInfo; }; typedef struct CfgSetsElement CfgSetsElement; Field descriptions An entity reference for the entity to be included in this set.
C H A P T E R 3 Network Setup Reference An unbounded array consisting of the number of CfgSetsElement (page 103) structures specified by fCount. All of the entities in this array are considered to be part of the set. The preference type for the CfgSetsVector structure is kOTCfgSetsVectorPref, which is defined as 'vect'.
C H A P T E R 3 Network Setup Reference kOTCfgClassSetOfSettings kOTCfgTypeSetOfSettings = 'otsc', = 'otst', }; Constant descriptions kOTCfgClassNetworkConnection The class code for network connection entities. kOTCfgClassGlobalSettings The class code global protocol entities. kOTCfgClassServer The class code for server setting entities. kOTCfgTypeGeneric The type code for non-specific entities. kOTCfgTypeAppleTalkThe type code for AppleTalk entities.
C H A P T E R 3 Network Setup Reference Constant descriptions Matches the class type for any entity. This constant is typically used when calling OTCfgGetEntitiesCount (page 73) and OTCfgGetEntitiesList (page 74). kCfgClassUnknownEntityDoes not match the class type for any entity. Use this constant as a “NULL” equivalent. kCfgTypeAnyEntity Matches the type for any entity. This constant is typically used when calling OTCfgGetEntitiesCount (page 73) and OTCfgGetEntitiesList (page 74).
C H A P T E R 3 Network Setup Reference kOTCfgVersionPref Some protocols store the version of the protocol in this preference. Typically, this preference is a UInt16 whose value is 1. kOTCfgPortUserVisibleNamePref Some protocols use this preference to store the user-visible name of the port over which the protocol is running as a Pascal string. kOTCfgProtocoltUserVisibleNamePref Some protocols store a user-visible description of the protocol in this preference as a C string.
C H A P T E R 3 Network Setup Reference Set Entity Preference Types 3 The following enumeration defines preference types for set entities: enum { kOTCfgSetsStructPref= 'stru', kOTCfgSetsVectorPref= 'vect', }; Constant descriptions kOTCfgSetsStructPrefPreference type for the CfgSetsStruct (page 101) structure. kOTCfgSetsVectorPrefPreference type for the CfgSetsVector (page 103) structure.
C H A P T E R 3 Network Setup Reference These preferences are used by the Network Setup backward compatibility mechanism to ensure an accurate conversion between legacy preference files and the Network Setup database. OTCfgUserMode Preference 3 For most control panels that support a concept of “user mode,” the OTCfgUserMode preference holds (or is used as a field in another preference to hold) the current user mode as a UInt16.
C H A P T E R 3 Network Setup Reference Result Codes 3 The result codes specific to Network Setup are listed here. Network Setup functions can also return system error codes, which do not appear in this list.
C H A P T E R Figure 4-0 Listing 4-0 Table 4-0 4 Network Setup Protocol Structures and Data Types 4 This chapter describes the structures and data types for protocols provided by Apple Computer. Protocol Structures 4 This section describes the structures that organize the information in the Network Setup database. ■ The section “TCP/IP Structures” (page 111) describes the structures used by TCP/IP preferences.
C H A P T E R 4 Network Setup Protocol Structures and Data Types (page 114) stores information about the configured TCP/IP interfaces in packed format. ■ OTCfgTCPInterfacesPacked (page 114) is a member of the (page 114) structure that stores port, module, and framing information for TCP/IP interfaces in packed format. ■ OTCfgTCPInterfacesPackedPart OTCfgTCPInterfacesPacked ■ OTCfgTCPDHCPLeaseInfo (page 115) stores information about a DHCP lease.
C H A P T E R 4 Network Setup Protocol Structures and Data Types InetHost InetHost Str32 UInt8 UInt8 UInt8 UInt32 fIPAddress; fSubnetMask; fAppleTalkZone; pad2; path[kMaxPortNameSize]; module[kMaxModuleNameSize]; framing; }; Field descriptions A value that is always 1 in the current versions of Open Transport. pad1 A pad byte. Remove this pad byte when you pack this structure. fConfigMethod The configuration method. For possible values, see the section OTCfgTCPConfigMethod (page 162).
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgTCPInterfacesPacked 4 The OTCfgTCPInterfacesPacked structure stores information about the configured TCP/IP interfaces in packed format. See Listing 2-16 in Chapter 2, “Using Network Setup,” for sample code that packs and unpacks this structure. IMPORTANT You must pack this structure before you write it to the database and you must unpack this structure after you reading it from the database.
C H A P T E R 4 Network Setup Protocol Structures and Data Types struct OTCfgTCPInterfacesPackedPart { UInt8 path[kMaxPortNameSize]; UInt8 module[kMaxModuleNameSize]; UInt32 framing; }; Field descriptions path module framing The name of the port over which this interface communicates. The name of the module that controls the port over which this interface communicates. Ethernet framing options. Constants are defined in the file “OpenTransportProviders.h,” an Open Transport header file.
C H A P T E R 4 Network Setup Protocol Structures and Data Types The preference type for OTCfgTCPLeaseDHCPInfo is kOTCfgTCPDHCPLeaseInfoPref, which is defined as 'dclt'. OTCfgTCPDNSServersList 4 The OTCfgTCPDNSServersList structure stores the list of name servers that have been configured for an interface. struct OTCfgTCPDNSServersList { UInt16 fCount; InetHost fAddressesList[1]; }; Field descriptions The number of IP addresses in the list.
C H A P T E R 4 Network Setup Protocol Structures and Data Types UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 UInt8 pad5; lockLocalDomainName; pad6; lockSubnetMask; pad7; lockRoutersList; pad8; lockDNSServersList; pad9; lockAdminDomainName; pad10; lockSearchDomains; pad11; lockUnknown; pad12; lock8023; pad13; lockDHCPClientID; pad14; }; Field descriptions pad1 Always zero.
C H A P T E R 4 Network Setup Protocol Structures and Data Types lockRoutersList pad8 lockDNSServersList pad9 Set to TRUE to lock the “Router address” text field. Always zero. Set to TRUE to lock the “Name server addr.” text field. Always zero. lockAdminDomainName Set to TRUE to lock the “Ending domain name” text field. pad10 Always zero. lockSearchDomains Set to TRUE to lock the “Additional search domains” text field. pad11 Always zero. lockUnknown Reserved. pad12 Always zero.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgTCPRoutersList 4 The OTCfgTCPRoutersList structure holds an array of OTCfgTCPRoutersListEntry (page 119) structures. struct OTCfgTCPRoutersList { UInt16 OTCfgTCPRoutersListEntry }; fCount; fList[1]; Field descriptions The number of elements in the fList array. An unbounded array consisting of a OTCfgTCPRoutersListEntry (page 119) structures.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgTCPSearchDomains 4 The OTCfgTCPSearchDomains structure stores the list of domains that are searched after the implicit search domains. IMPORTANT You must pack this structure before you write it to the database and you must unpack this structure after you reading it from the database.
C H A P T E R 4 Network Setup Protocol Structures and Data Types struct OTCfgTCPSearchList { UInt8 fPrimaryInterfaceIndex; Str255 fLocalDomainName[256]; Str255 fAdmindomain[256]; }; Field descriptions fPrimaryInterfaceIndex A value that must be 1 in the current versions of Open Transport. fLocalDomainName The local domain name in Pascal string format. You must unpack this field when you read this structure from the database and pack this file when you write this structure to the database.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOTCfgTCPActiveAlwaysLoaded TCP/IP is always loaded. kOTCfgTCPInactive TCP/IP is never loaded. The preference type for this preference is kOTCfgTCPDHCPUnloadAttrPref, which is defined as 'unld'. Apple Remote Access Structures 4 This section describes structures that store Apple Remote Access (ARA) preferences. The structures are ■ OTCfgRemoteAlternateAddress (page 123) stores an alternate number to dial.
C H A P T E R 4 Network Setup Protocol Structures and Data Types ■ OTCfgRemoteServerPort (page 137) stores core configuration information for the personal server. ■ OTCfgRemoteTerminal (page 138) stores information used by the PPP terminal window. (page 139) stores the current user mode and the administration password for the control panel. ■ OTCfgRemoteUserMode ■ OTCfgRemoteX25 (page 140) stores X.25 connection information.
C H A P T E R 4 Network Setup Protocol Structures and Data Types UInt32 tabChoice; OTCfgUserMode32 fUserMode; UInt32 fSetupVisible; }; version fWindowPosition tabChoice Must be 1 for Open Transport/PPP or 3 for ARA. Global coordinates for the application’s window position. Currently active tab in the Options dialog box. Use 1 for the Redialing tab, 2 for the Connection tab, or 3 for the Protocol tab. The current user mode. See the OTCfgUserMode preference (page 109) enumeration for possible values.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteClientLocks 4 The OTCfgRemoteClientLocks structure stores information about preferences that have been locked by the administration mode of the control panel.
C H A P T E R 4 Network Setup Protocol Structures and Data Types errorCheck headerCompress termWindow reminder autoConn redial useProtocolLock useVerboseLogLock regUserOrGuestLock dialAssistLock savePasswordLock reserved 126 Protocol Structures The “Allow error correction and compression in modem” checkbox in the control panel is locked when the errorCheck field is set to 1 and unlocked when the errorCheck field is set to zero.
C H A P T E R 4 Network Setup Protocol Structures and Data Types The preference type for this preference is OTCfgRemoteClientLocks, which is defined as 'clks'. OTCfgRemoteClientMisc 4 The OTCfgRemoteClientMisc structure stores automatic connection information. struct OTCfgRemoteClientMisc { UInt32 version; UInt32 connectAutomatically; }; Field descriptions version Depending how the preference was constructed, version may be kOTCfgRemoteDefaultVersion or kOTCfgRemoteAcceptedVersion.
C H A P T E R 4 Network Setup Protocol Structures and Data Types UInt32 UInt32 UInt32 UInt32 SInt32 UInt32 UInt32 OTCfgRemotePPPConnectScript OTCfgRemoteProtocol UInt32 UInt32 UInt32 UInt32 * Str63 UInt32 UInt32 UInt32 UInt32 OSType UInt32 UInt32 showStatus; passwordSaved; flashConnectedIcon; issueConnectedReminders; reminderMinutes; connectManually; allowModemDataCompression; chatMode; serialProtocolMode; passwordPtr; userNamePtr; addressLength; addressPtr; chatScriptName; chatScriptLength; chatScriptP
C H A P T E R 4 Network Setup Protocol Structures and Data Types flashConnectedIcon Set to zero if the menu bar flashes when a disconnection occurs; set to 1 if the menu bar does not flash when a disconnection occurs. issueConnectedReminders reminderMinutes connectManually Set to 1 to flash an icon in the menu bar to remind the user that the connection is active; set to zero to not flash an icon.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Must be zero. securityData Must be zero. The preference type for OTCfgRemoteConnect is kOTCfgRemoteConnectPref, which is defined as 'conn'. securityDataLength OTCfgRemoteDialAssist 4 The OTCfgRemoteDialAssist structure stores area and country code information used by the Dial Assist facility.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteDialing 4 The OTCfgRemoteDialing structure stores settings for outgoing ARA connections. struct OTCfgRemoteDialing { UInt32 version; UInt32 fType; UInt32 additionalPtr; OTCfgRemoteRedialMode dialMode; UInt32 redialTries; UInt32 redialDelay; UInt32 pad; }; Field descriptions Depending how the preference was constructed, version may be kOTCfgRemoteDefaultVersion or kOTCfgRemoteAcceptedVersion.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteIPCP 4 The OTCfgRemoteIPCP structure stores information for configuring the Internet Protocol Control Protocol (IPCP) layer of PPP. This information is also used as part of a Remote Access server configuration. This structure is not used for ARAP connections.
C H A P T E R 4 Network Setup Protocol Structures and Data Types allowAddressNegotiation idleTimerEnabled compressTCPHeaders Must be 1. Set idleTimerEnabled to 1 to cause a connection that has been idle for the number of milliseconds specified by the idletTimerMilliseconds field to be disconnected. Set idleTimerEnabled to zero to disable the idle timer. Set compressTCPHeaders to 1 to allow Van Jacobsen header compression. Set compressTCPHeaders to zero to disallow header compression.
C H A P T E R 4 Network Setup Protocol Structures and Data Types UInt32 UInt32 UInt32 txACCMap; rcACCMap; isNoLAPB; }; typedef struct OTCfgRemoteLCP OTCfgRemoteLCP; Field descriptions Depending how the preference was constructed, version may be kOTCfgRemoteDefaultVersion or kOTCfgRemoteAcceptedVersion. When reading the version field, accept either value. When writing the version field, set it to kOTCfgRemoteDefaultVersion. reserved Must be zero.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteLogOptions 4 The OTCfgRemoteLogOptions structure controls the level of logging performed by ARA. struct OTCfgRemoteLogOptions { UInt32 version; UInt32 fType; UInt32 additionalPtr; OTCfgRemoteLogLevel logLevel; UInt32 reserved[4]; }; typedef struct OTCfgRemoteLogOptions OTCfgRemoteLogOptions; Depending how the preference was constructed, version may be kOTCfgRemoteDefaultVersion or kOTCfgRemoteAcceptedVersion.
C H A P T E R 4 Network Setup Protocol Structures and Data Types struct OTCfgRemotePassword { UInt8 data[256]; }; typedef struct OTCfgRemotePassword OTCfgRemotePassword; The encrypted password. Call OTCfgEncrypt (page 93) to encrypt the password. The preference type for this preference is kOTCfgRemotePasswordPref, which is defined as 'pass'. data OTCfgRemoteServer 4 The OTCfgRemoteServer structure stores an array of port configuration IDs used to locate the configuration for a particular port.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteServerPort 4 The OTCfgRemoteServerPort structure stores core configuration information for the personal server.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Serial protocol flags. For possible values, see the OTCfgRemoteProtocol (page 167). networkProtoFlags Network protocol flags. For possible values, see the OTCfgRemoteNetworkProtocol (page 169) enumeration. netAccessMode Access mode flags. For possible values, see the OTCfgRemoteNetAccessMode (page 170) enumeration. requiresCCL Must be TRUE. portName C string containing the name of the underlying port.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Str255 fFontName; }; typedef struct OTCfgRemoteTerminal OTCfgRemoteTerminal; Must be 1. fLocalEcho Set to TRUE for the terminal window to echo typed characters; otherwise, set to FALSE. The default is FALSE. fNonModal Must be FALSE. fPowerUser Must be FALSE. fQuitWhenPPPStarts Set to TRUE to cause the terminal window to quit when the PPP connection is made. The default is TRUE. fDontAskVarStr The default is FALSE.
C H A P T E R 4 Network Setup Protocol Structures and Data Types struct OTCfgRemoteUserMode { UInt32 version; OTCfgUserMode32 userMode; Str255 adminPassword; }; typedef struct OTCfgRemoteUserMode OTCfgRemoteUserMode; Depending how the preference was constructed, version may be kOTCfgRemoteDefaultVersion or kOTCfgRemoteAcceptedVersion. When reading the version field, accept either value. When writing the version field, set it to kOTCfgRemoteDefaultVersion. userMode Current user mode.
C H A P T E R 4 Network Setup Protocol Structures and Data Types field, accept either value. When writing the version field, set it to kOTCfgRemoteDefaultVersion. fType Must be zero for standard dial-up connections. additionalPtr Must be zero for standard dial-up connections. script Must be zero for standard dial-up connections. address Must be zero for standard dial-up connections. userName Must be zero for standard dial-up connections. closedUserGroup Must be zero for standard dial-up connections.
C H A P T E R 4 Network Setup Protocol Structures and Data Types UInt8 FSSpec Boolean Boolean OTCfgModemDialogToneMode char pad; modemScript; modemSpeakerOn; modemPulseDial; modemDialToneMode; lowerLayerName[kMaxProviderNameSize]; }; Field descriptions Depending how the preference was constructed, version may be kOTCfgRemoteDefaultVersion or kOTCfgRemoteAcceptedVersion. When reading the version field, accept either value. When writing the version field, set it to kOTCfgRemoteDefaultVersion.
C H A P T E R 4 Network Setup Protocol Structures and Data Types struct OTCfgModemApplication { UInt32 version; Point windowPos; OTCfgUserMode32 userMode; }; Field descriptions Must be 1. windowPos Window position in global coordinates of the modem control panel. userMode Must be kOTCfgBasicUserModeUser mode because the Modem control panel does not support any other mode. The preference type for the OTCfgModemApplication structure is kOTCfgModemApplicationPref, which is defined as 'mapt'.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Set dialing to lock the setting for pulse or tone dialing, or set dialing to zero to unlock the setting. The preference type for the OTCfgModemLocks structure is kOTCfgModemLocksPref, which is defined as 'lkmd'. dialing AppleTalk Structures 4 This section describes the structures that store AppleTalk preferences. The structures are (page 145) is a general structure holds the combined preferences for each AppleTalk protocol.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgATalkGeneral 4 The OTCfgATalkGeneral structure consists of structures for each AppleTalk protocol.
C H A P T E R 4 Network Setup Protocol Structures and Data Types The preference type for the OTCfgATalkGeneral structure is kOTCfgATalkGeneralPref, which is defined as 'atpf'. OTCfgATalkGeneralAARP 4 The OTCfgATalkGeneralAARP structure defines parameters for the AppleTalk Address Resolution Protocol (AARP) component of the AppleTalk protocol stack and is a sub-structure of the OTCfgATalkGeneral structure.
C H A P T E R 4 Network Setup Protocol Structures and Data Types The number of times to retry a probe. The default is 10. fRequestInterval The request interval in milliseconds. The default request interval is 200 milliseconds. fRequestRetryCount The number of times to retry a request. The default is 8. For a detailed descriptions of AARP, see Inside AppleTalk, Second edition. No preference type is defined for this structure.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Must be the size in bytes of this structure. fDefaultSendBlockingBytes, default is 16. fTSDUSize The Transport Service Data Unit (TSDU), which is the maximum amount of data that packets of this protocol can carry. The default is 572. fETSDUSize The extended TSDU (ETSDU) size. The default is 572. fSize fDefaultOpenInterval The default open interval in milliseconds. The default is 3000.
C H A P T E R 4 Network Setup Protocol Structures and Data Types No preference type is defined for this structure. Instead, access this structure through the OTCfgATalkGeneral (page 145) structure, which has a preference type of kOTCfgATalkGeneralPref. OTCfgATalkGeneralASP 4 The OTCfgATalkGeneralASP structure defines parameters for the AppleTalk Session Protocol (ASP) component of the AppleTalk protocol stack and is a sub-structure of the OTCfgATalkGeneral structure.
C H A P T E R 4 Network Setup Protocol Structures and Data Types For a detailed description of ASP, see Inside AppleTalk, Second Edition. No preference type is defined for this structure. Instead, access this structure through the OTCfgATalkGeneral (page 145) structure, which has a preference type of kOTCfgATalkGeneralPref.
C H A P T E R 4 Network Setup Protocol Structures and Data Types The default “at least once” (ALO) setting. The default value is FALSE. For a detailed descriptions ATP, see Inside Macintosh: Networking with Open Transport and Inside AppleTalk, Second edition. fDefaultALOSetting No preference type is defined for this structure. Instead, access this structure through the OTCfgATalkGeneral (page 145) structure, which has a preference type of kOTCfgATalkGeneralPref.
C H A P T E R 4 Network Setup Protocol Structures and Data Types fTSDUSize fLoadType fNode fNetwork fRTMPRequestLimit The maximum amount of data that packets of this protocol can carry. Must be 586, which is the basic AppleTalk datagram size. Whether AppleTalk is active. See discussion below for possible values. Most recently acquired node number or the fixed node number to use. Most recently acquired network number or the fixed network number. Must be 3.
C H A P T E R 4 Network Setup Protocol Structures and Data Types redefined as a flag, with zero meaning inactive and non-zero meaning active. However, the default preferences were not updated to reflect this change.
C H A P T E R 4 Network Setup Protocol Structures and Data Types fSize fTSDUSize The size in bytes of this structure. The maximum amount of data that packets of this protocol can carry. The default is 584. fDefaultRetryInterval fDefaultRetryCount The default retry interval in milliseconds. By default, this value is 800. The default retry count. By default, this value is 3. fCaseSensitiveCompare Whether comparisons are case sensitive. The default value is FALSE.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Field descriptions fVersion fSize Must be 1. The size in bytes of this structure. fDefaultOpenInterval The default open interval in milliseconds. The default value is 2000. fDefaultTickleInterval The default tickle interval in milliseconds. The default value is 15000. fDefaultOpenRetries The default number of times to retry an opening. The default value is 0.
C H A P T E R 4 Network Setup Protocol Structures and Data Types UInt32 UInt16 UInt8 UInt8 Boolean UInt8 fZoneListInterval; fDDPInfoTimeout; fGetZoneRetries; fZoneListRetries; fChecksumFlag; fPad; }; Field descriptions Must be 1. The size in bytes of this structure. fGetZoneInterval The “get zone” interval in milliseconds. The default is 2000. fZoneListInterval The “zone list” interval in milliseconds. The default is 2000. fDDPInfoTimeout The “DDP info” timeout in milliseconds. The default is 4000.
C H A P T E R 4 Network Setup Protocol Structures and Data Types The following enumeration defines mask values for the fLocks field: enum { kOTCfgATalkPortLockMask = kOTCfgATalkZoneLockMask = kOTCfgATalkAddressLockMask = kOTCfgATalkConnectionLockMask= kOTCfgATalkSharingLockMask = }; 0x01, 0x02, 0x04, 0x08, 0x10 Constant descriptions kOTCfgATalkPortLockMask The bit set by this mask indicates that the port used by AppleTalk is locked.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OSType fNetworkArchitecture; }; typedef struct OTCfgATalkNetworkArchitecture OTCfgATalkNetworkArchitecture; Field descriptions fVersion Must be zero. fNetworkArchitecture Must be 'OTOn'. The preference type for the OTCfgATalkNetworkArchitecture structure is kOTCfgATalkNetworkArchitecturePref, which is defined as 'neta'.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgIRGeneral 4 The OTCfgIRGeneral structure stores per-connection infrared settings. struct OTCfgIRGeneral { UInt32 fVersion; OTPortRef fPortRef; OTCfgIRPortSettingfPortSetting; Boolean fNotifyOnDisconnect; Boolean fDisplayIRControlStrip; }; Field descriptions fVersion fPortRef OTCfgIRPortSetting Must be zero. Reference to the infrared port. A value that specifies the infrared protocol.
C H A P T E R 4 Network Setup Protocol Structures and Data Types ■ “AppleTalk Constants and Other Data Types” (page 172) ■ “Infrared Constants and Other Data Types” (page 173) TCP/IP Constants and Other Data Types 4 The following enumeration defines type codes for the TCP/IP preferences.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOTCfgTCPDNSServersListPref Preference type for the OTCfgTCPDNSServersList (page 116) structure. kOTCfgTCPSearchDomainsPref Preference type for the OTCfgTCPSearchDomains (page 120) structure. kOTCfgTCPDNSServersListPref Preference type for the OTCfgTCPDNSServersList (page 116) structure. kOTCfgTCPDHCPLeaseInfoPref Preference type for the OTCfgTCPDHCPLeaseInfo (page 115) structure.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOversizeOffNetPacketsMask kDHCPDontPreserveLeaseMask = 0x0008, = 0x0010, }; Constant descriptions kDontDoPMTUDiscoveryMask If set, this bit turns off path MTU discovery. kDontShutDownOnARPCollisionMask kDHCPInformMask If set, this bit disables ARP collision shutdown. If set, this bit enables DHCPINFORM instead of DHCPREQUEST.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOTCfgBOOTPConfig kOTCfgDHCPConfig kOTCfgMacIPConfig Obtain an address from a BOOTP server. Obtain an address from a DHCP server. Configure TCP/IP to use MacIP. Note The TCP/IP control panel’s “PPP Server” address acquisition method is actually implemented by setting fConfigMethod to kOTCfgManualConfig and setting fIPAddress to zero.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOTCfgRemoteAlternateAddressPref= kOTCfgRemoteClientLocksPref = kOTCfgRemoteClientMiscPref = kOTCfgRemoteConnectPref = kOTCfgRemoteUserPref = kOTCfgRemoteDialAssistPref = kOTCfgRemoteIPCPPref = kOTCfgRemoteLCPPref = kOTCfgRemoteLogOptionsPref = kOTCfgRemotePasswordPref = kOTCfgRemoteTerminalPref = kOTCfgRemoteUserModePref = kOTCfgRemoteSecurityDataPref = kOTCfgRemoteX25Pref = 'cead', 'clks', 'cmsc', 'conn', 'cusr', 'dass', 'ipcp', 'lcp ',
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOTCfgRemoteConnectPref The preference type for the OTCfgRemoteConnect (page 127) structure. kOTCfgRemoteConnectPref The preference type for the OTCfgRemoteConnect (page 127) structure. kOTCfgRemoteUserPref The preference type that stores the user name as a Pascal string. kOTCfgRemoteDialAssistPref The preference type for OTCfgRemoteDialAssist (page 130) structure.
C H A P T E R 4 Network Setup Protocol Structures and Data Types ARA Global Preference Types 4 The following enumeration defines global preference types for Apple Remote Access (ARA) enum { kOTCfgRemoteServerLocksPref kOTCfgRemoteServerPortPref kOTCfgRemoteServerPref kOTCfgRemoteApplicationPref }; = = = = 'slks', 'port', 'srvr', 'capt' Constant descriptions kOTCfgRemoteServerLocksPref Defined but not used by ARA.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Constant descriptions OTCfgRemotePPPConnectScriptNone No connect script is configured. OTCfgRemotePPPConnectScriptTerminalWindow A terminal window is used to make the connection. OTCfgRemotePPPConnectScriptScript A chat script is used to make the connection.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteLogLevel 4 The OTCfgRemoteLogLevel structure defines values for use in the logLevel field of the OTCfgRemoteLogOptions (page 135) structure: typedef UInt32 OTCfgRemoteLogLevel; enum { kOTCfgRemoteLogLevelNormal = 0, kOTCfgRemoteLogLevelVerbose = 1 }; Constant descriptions kOTCfgRemoteLogLevelNormal Normal ARA logging. kOTCfgRemoteLogLevelVerbose Verbose ARA logging.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgRemoteAnswerMode 4 The OTCfgRemoteAnswerMode enumeration defines constants for the answerMode field of the OTCfgRemoteServerPort (page 137) structure: typedef UInt32 OTCfgRemoteAnswerMode; enum { kAnswerModeOff = 0, kAnswerModeNormal = 1, kAnswerModeTransfer = 2, kAnswerModeCallback = 3 }; Constant descriptions Answering is disabled. Answering is enabled. kAnswerModeTransferAnswering as a callback server.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kOTCfgNetProtoAT kOTCfgNetProtoAny Allow AppleTalk connections (ATCP and ARAP). Allow IPCP and AppleTalk connections.
C H A P T E R 4 Network Setup Protocol Structures and Data Types Constant descriptions kOTCfgModemGeneralPrefs The preference type for the OTCfgModemGeneral (page 141) structure. kOTCfgModemLocksPref The preference type for the OTCfgModemLocks (page 143) structure. kOTCfgModemAdminPasswordPref Preference type for the preference that contains the administration password.
C H A P T E R 4 Network Setup Protocol Structures and Data Types kModemDialToneIgnore, kModemDialToneManual }; Constant descriptions kModemDialToneNormalWait for dial tone. kModemDialToneIgnoreDo not wait for dial tone. kModemDialToneManualManual dialing.
C H A P T E R 4 Network Setup Protocol Structures and Data Types enum { kOTCfgATalkGeneralPref = 'atpf', kOTCfgATalkLocksPref = 'lcks', kOTCfgATalkPortDeviceTypePref= 'ptfm', }; Global AppleTalk Preference Types 4 The following enumeration defines constants for global AppleTalk preference types: enum { kOTCfgATalkNetworkArchitecturePref = 'neta' }; Infrared Constants and Other Data Types 4 The following enumeration defines type codes for infrared preferences.
C H A P T E R 4 Network Setup Protocol Structures and Data Types OTCfgIRPortSetting 4 The OTCfgIRPortSetting enumeration defines constants for use in the OTCfgIRPortSetting field of the OTCfgIRGeneral (page 159) structure: typedef UInt16 OTCfgIRPortSetting; enum { kOTCfgIRIrDA = 0, kOTCfgIRIRTalk = 1 }; Constant descriptions kOTCfgIRIrDA kOTCfgIRIRTalk 174 Specifies the Infrared Data Association (IrDA) protocol.
Glossary AARP See AppleTalk Address Resolution Protocol. Address Resolution Protocol (ARP) The Internet protocol that maps an IP address to a MAC address. Apple Remote Access (ARA) The mechanism by which computers running Mac OS connect to remote sites. AppleTalk Address Resolution Protocol (AARP) The protocol that reconciles addressing discrepancies in networks that support more than one set of protocols.
G L O S S A RY Datagram Delivery Protocol (DDP) The network-layer protocol that is responsible for the socket-to-socket delivery of datagrams over an AppleTalk network. DDP See Datagram Delivery Protocol. default area The preferred name for the area in which preferences are stored. Another name for the current area. DHCP See Dynamic Host Configuration Protocol. DNS See Domain Name System. Domain Name System (DNS) The system used on the Internet for translating the name of a network node to an IP address.
G L O S S A RY media access control address The six-byte data link layer address that is required for every device that connects to a network. Other devices in the network use MAC addresses to locate devices on the network and to create and update routing tables. MTU See maximum transmission unit.
G L O S S A RY temporary area An area that is created when a named area is modified. Transmission Control Protocol/Internet Protocol A connection-oriented transport-layer Internet protocol that provides reliable full-duplex data transmission. User Datagram Protocol (UDP) A connectionless transport-layer Internet protocol that exchanges datagrams without acknowledgments or guaranteed delivery, requiring that error processing and retransmission be handled by other protocols. UDP See User Datagram Protocol.
Index A active set entity finding 43–48 number of 17, 43 ARA constants 163 architecture, Network Setup 11–14 area IDs comparing 65 set entities, working with 48 unique 16 areas closing 62, 65 counting 68 creating 70 deleting 72 duplicating 71 getting current 60 getting name 66 listing 68 modifying 63 opening 61, 66 setting current 61 setting name 67 writing modifications 64 C CfgEntityInfo structure 99 CfgEntityRef structure 98, 99, 100 CfgPrefsHeaderstructure 100, 101 CfgSetsElement structure 103 CfgSetsS
I N D E X entities active, finding 34 active set 17 changing 82 classes 16 classes and types 104 closing 85 counting 73 creating 76 deleting 43, 78 duplicating 78 getting name 79, 80 global protocol 16 IDs, getting 82 listing 30–34, 74 network connection 16 references 16 references, comparing 76 set 16 setting name 81 types 16 user-visibile names of 16 F functions OTCfgAbortAreaModifications 65 OTCfgBeginAreaModifications 63 OTCfgChangeEntityArea 82 OTCfgCloseArea 62 OTCfgCloseDatabase 58 OTCfgClosePrefs
I N D E X K kOTCfgClassNetworkConnection class 30 kOTCfgSetsStructPref preference 43 kOTCfgSetsVectorPref preference 43 L legacy preference files 13 synchronization 15, 21, 22–23, 43 library, Network Setup 14–15 listing entities 30–34, 74 low-level database 15 M mid-level database 15 modem constants 170 multihoming 12, 43 N named areas 16 network connection entities 16 Network Setup constants 106–109 library 13, 14–15 notification routine installing 94 removing 96 O opening areas 61, 66 database 25–27,
I N D E X OTCfgIRGeneral structure 159 OTCfgIsSameAreaID function 65 OTCfgIsSameEntityRef function 76 OTCfgModemApplication structure 141, 142 OTCfgModemLocks structure 143 OTCfgOpenArea function 66 OTCfgOpenDatabase function 58 OTCfgOpenName function 61 OTCfgOpenPrefs function 84 OTCfgRemoteAlternateAddress structure 123 OTCfgRemoteApplication structure 123 OTCfgRemoteARAP structure 124 OTCfgRemoteClientLocks structure 125 OTCfgRemoteClientMisc structure 127 OTCfgRemoteConnect structure 127 OTCfgRemoteDia
I N D E X set entities 16 active, number of 43 using 42–49 setting entity names 81 structures CfgEntityInfo 99 CfgEntityRef 98, 99, 100 CfgPrefsHeader 100, 101 CfgSetsElement 103 CfgSetsStruct 101 CfgSetsVector 103 OTCfgATalkGeneral 145 OTCfgATalkGeneralAARP 146 OTCfgATalkGeneralADSP 147 OTCfgATalkGeneralASP 149 OTCfgATalkGeneralATP 150 OTCfgATalkGeneralDDP 151 OTCfgATalkGeneralNBP 153 OTCfgATalkGeneralPAP 154 OTCfgATalkGeneralZIP 155 OTCfgATalkLocks 156 OTCfgATalkNetworkArchictecture 157 OTCfgATalkPortDev
I N D E X 184
