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