I N S I D E M A C I N T O S H
Network Setup
Apple Computer, Inc 2000 Apple Computer, Inc. All rights reserved
Contents
About Network Setup
Using Network Setup
About This Manual
Network Setup Reference
Chapter
Chapter 4 Network Setup Protocol Structures and Data Types
Glossary Index
Page
About Network Setup
Using Network Setup
Figures, Tables, and Listings
Chapter
Page
About This Manual
Conventions Used in This Manual
For More Information
Inside AppleTalk, Second Edition
Inside Macintosh Networking with Open Transport
Open Transport Advanced Client Programming, available at
About Network Setup
Network Setup Architecture
The architecture shown in Figure 1-1 had a number of drawbacks
The following key points are to be taken from Figure
Inside the Network Setup Library
About Network Setup Figure 1-4 Structure of the Network Setup Library
Inside the Network Setup Library
High-level framework
Mid-level database OTCfg
Network Setup Database Fundamentals
Database Structure
Database Structure Example
About Network Setup
Figure 1-5 Sample organization of the default area
18 Network Setup Database Fundamentals
LocalTalk for Printer AppleTalk networkork protocol entity
Database Operations
Figure 1-6 shows this process diagrammatically
Legacy Issues
Preference Coherency
Legacy Synchronization Algorithm
Mac OS version
Network Setup Version History
Version
C H A P T E R
About Network Setup
24 Network Setup Version History
Opening the Database for Reading
Using Network Setup
Opening and Closing the Network Setup Database
26 Opening and Closing the Network Setup Database
Opening the Database for Writing
Using Network Setup Listing 2-1 Opening the database for reading
Listing 2-2 Opening the database for writing
Using Network Setup
Opening and Closing the Network Setup Database
Closing the Database After Reading
Closing the Database After Writing
Using Network Setup
Opening and Closing the Network Setup Database
Listing 2-4 Closing the database after writing
err = OTCfgCommitAreaModificationsdbRef, readArea, writeArea
Working with Entities
Listing All Entities
kCfgClassAnyEntity and kCfgTypeAnyEntity, respectively
static OSStatus MyGetEntitiesListCfgDatabaseRef dbRef, CfgAreaID area
OSType entityClass OSType entityType CfgEntityRef **entityRefs
CfgEntityInfo **entityInfos
Using Network Setup
32 Working with Entities
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
Reading and Writing Preferences
Finding an Active Entity
Reading Fixed-size Preferences
Using Network Setup
Listing 2-7 Reading a fixed-size preference
Reading and Writing Preferences
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
Reading Variable-size Preferences
assertdbRef != nil assertentity != nil assertname != nil
Using Network Setup
38 Reading and Writing Preferences
Writing Preferences
Iterating the Preferences in an Entity
Using Network Setup
Reading and Writing Preferences
Working with Sets
Finding the Active Set Entity
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. 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
breaks out of the loop and returns the found entity
46 Working with Sets
Using Network Setup
Listing 2-14 Finding the active entity of a given class and type
Working with Sets
Using Network Setup
Listing 2-15 Finding the active TCP/IP entity
Areas and Sets
Protocol-specific Topics
TCP/IP Notes
access the preference in its packed format
cursor = UInt8 * packedPref
Using Network Setup
Protocol-specific Topics
UInt8 *cursor
Using Network Setup
52 Protocol-specific Topics
Remote Access Notes
Modem Notes
OTCfgRemoteClientLocks page
Storing Third-party Preferences in Apple Entities
Network Setup and Third-party Protocol Stacks
Notes for Third Parties
C H A P T E R
Using Network Setup
56 Notes for Third Parties
Opening and Closing the Network Setup Database
Network Setup Reference
Network Setup Functions
OTCfgOpenDatabase
OTCfgCloseDatabase
Managing Areas
OTCfgGetCurrentArea
OTCfgSetCurrentArea
OTCfgOpenArea
OTCfgCloseArea
OTCfgBeginAreaModifications
function result
OTCfgCommitAreaModifications
function result
OTCfgAbortAreaModifications
OTCfgIsSameAreaID
function result
OTCfgAbortAreaModifications returns kCfgErrAreaNotFound
OTCfgGetAreaName
function result
OTCfgSetAreaName
function result
function result
OTCfgGetAreasCount
OTCfgGetAreasList
that are available. On output, itemCount points to the number of
function result
OTCfgCreateArea
function result
OTCfgDuplicateArea
function result
Managing Entities
OTCfgDeleteArea
OTCfgGetEntitiesCount
OTCfgGetEntitiesList
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
OTCfgIsSameEntityRef
OTCfgCreateEntity
On input, a value of type CfgDatabaseRef page 98 that
function result
OTCfgDeleteEntity
OTCfgDuplicateEntity
function result
const CfgEntityRef* entityRef, const CfgEntityRef* newEntityRef
OTCfgGetEntityLogicalName
OTCfgGetEntityName
function result None
OTCfgSetEntityName
function result
function result
OTCfgGetEntityArea
OTCfgChangeEntityArea
Managing Preferences
function result None
OTCfgOpenPrefs
function result
OTCfgClosePrefs
OTCfgGetPrefsSize
void* data, ByteCount length
OTCfgGetPrefs
function result
const void* data, ByteCount length
OTCfgSetPrefs
function result
OTCfgGetPrefsTOCCount
OTCfgGetPrefsTOC
OTCfgGetDefault
OTCfgDeletePrefs
OTCfgGetTemplate
Preference Utilities
function result
OTCfgEncrypt
OTCfgDecrypt
Installing and Removing a Notification Callback
OTCfgInstallNotifier
On input, a value of type CfgDatabaseRef page 98 that
function result
function result
Application-Defined Routines
OTCfgRemoveNotifier
Network Setup Structures and Data Types
Notification Callback Routine
CfgDatabaseRef
CfgAreaID
Field descriptions
CfgEntityRef
CfgEntityInfo
CfgEntityAccessID
CfgPrefsHeader
CfgResourceLocator
CfgSetsStruct
Flags for this set. For possible values, see the enumeration
CfgSetsElement
CfgSetsVector
Network Setup Constants
Entity Classes and Types
Wildcard Classes and Types
Common Preference Types
Per-connection Preference Types
Global Preference Types
Global Backward Compatibility Preference Types
Set Entity Preference Types
Backward Compatibility Preference Types
Invalid Area ID
OTCfgUserMode Preference
Result Codes
TCP/IP Structures
Network Setup Protocol Structures and Data Types
Protocol Structures
OTCfgTCPInterfacesUnpacked
modulekMaxModuleNameSize
partsizeofOTCfgTCPInterfacesPackedPart
OTCfgTCPInterfacesPacked
OTCfgTCPInterfacesPackedPart
OTCfgTCPDHCPLeaseInfo
OTCfgTCPDNSServersList
OTCfgTCPLocks
lockDNSServersList
lockAdminDomainName
lockLocalDomainName
Set to TRUE to lock the “Router address” text field
OTCfgTCPRoutersListEntry page 119 structures
OTCfgTCPRoutersList
OTCfgTCPRoutersListEntry
OTCfgTCPSearchDomains
OTCfgTCPSearchList
OTCfgTCPUnloadAttr
Apple Remote Access Structures
OTCfgRemoteAlternateAddress
OTCfgRemoteApplication
OTCfgRemoteARAP
regUserOrGuestLock
OTCfgRemoteClientLocks
useVerboseLogLock
The “Allow error correction and compression in modem”
OTCfgRemoteClientMisc
OTCfgRemoteConnect
connectAutomatically
canInteract
OTCfgRemotePPPConnectScript
issueConnectedReminders
allowModemDataCompression
If Notification Manager reminders are enabled, the number
OTCfgRemoteDialAssist
isAssisted to 1 to use Dial Assist. When isAssisted is set to
made. Only valid if dialMode is not kOTCfgRemoteRedialNone
OTCfgRemoteDialing
additionalPtr
OTCfgRemoteIPCP
OTCfgRemoteLCP
lowerLayerName36
kOTCfgRemoteAcceptedVersion. When reading the version
OTCfgRemotePassword
OTCfgRemoteLogOptions
configIDs1
OTCfgRemoteServer
configCount
OTCfgRemoteServerPort
struct OTCfgRemoteServerPort
OTCfgRemoteNetworkProtocol
serialLayerNamekMaxProviderNameSize
OTCfgRemoteTerminal
Access mode flags. For possible values, see the
Network Setup Protocol Structures and Data Types
Must be TRUE
OTCfgRemoteUserMode
OTCfgRemoteX25
Modem Structures
OTCfgModemGeneral
OTCfgModemApplication
OTCfgModemLocks
AppleTalk Structures
OTCfgATalkGeneral
OTCfgATalkGeneralAARP
OTCfgATalkGeneralADSP
fMaxConsecutiveDataPackets
Page
OTCfgATalkGeneralASP
fDefaultReleaseTimer
OTCfgATalkGeneralATP
fDefaultRetryInterval
OTCfgATalkGeneralDDP
Network Setup Protocol Structures and Data Types
Protocol Structures
fMyZonekZIPMaxZoneLength+1
The maximum amount of data that packets of this protocol
OTCfgATalkGeneralNBP
OTCfgATalkGeneralPAP
fDefaultTickleInterval
fDefaultTickleRetries
fDefaultPAPEOMEnabled
OTCfgATalkGeneralZIP
OTCfgATalkLocks
OTCfgATalkNetworkArchitecture
Constant descriptions kOTCfgATalkPortLockMask
Infrared Structures
OTCfgATalkPortDeviceType
Protocol Constants and Other Data Types
OTCfgIRGeneral
TCP/IP Constants and Other Data Types
Network Setup Protocol Structures and Data Types
“AppleTalk Constants and Other Data Types” page
“Infrared Constants and Other Data Types” page
Masks for the kOTCfgProtocolOptionsPref Preference
kDontShutDownOnARPCollisionMask =
0x0002
0x0004
OTCfgTCPConfigMethod
Apple Remote Access Constants and Other Data Types
ARA Per-Connection Preferences Types
Network Setup Protocol Structures and Data Types
The preference type for the OTCfgRemoteARAP page 124 structure
The preference type for the OTCfgRemoteDialing page 131 structure
The preference type for the OTCfgRemoteClientLocks page 125 structure
The preference type for the OTCfgRemoteConnect page 127 structure
ARA Global Preference Types
OTCfgRemotePPPConnectScript
OTCfgRemoteProtocol
OTCfgRemoteLogLevel
OTCfgRemoteDialMode
OTCfgRemoteAnswerMode
OTCfgRemoteNetworkProtocol
OTCfgRemoteNetAccessMode
Modem Constants and Other Data Types
Modem Global Preference Types
OTCfgModemDialingToneMode
AppleTalk Constants and Other Data Types
Per-connection AppleTalk Preference Types
Infrared Constants and Other Data Types
Global AppleTalk Preference Types
OTCfgIRPortSetting
Glossary
maximum transmission unit MTU The maximum number of bytes in a packet
media access control address The six-byte
Transmission Control Protocol/Internet Protocol A connection-oriented transport-layer Internet protocol that provides reliable full-duplex data transmission
Index
Page
named areas network connection entities 16 Network Setup
notification routine installing 94 removing
legacy preference files
mid-level database 15 modem constants 170 multihoming 12
Page
set entities 16 active, number of 43 using
setting entity names 81 structures
TCP/IP constants 160 preferences
temporary area 20 third-party developers 55 type, entity
I N D E