Protocol-speciﬁc Topics, TCP/IP Notes | Apple Network Setup guide

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.

■When opening an entity whose reference you have obtained from a set, always call OTCfgChangeEntityArea to reset its area identiﬁer to that of the area in which you are working.

Listing 2-14 demonstrates this technique.

Protocol-speciﬁc Topics

This section contains hints and tips for working with the Network Setup preferences of certain protocol stacks provided by Apple.

TCP/IP Notes

A TCP/IP network connection entity has a class of kOTCfgClassNetworkConnection and a type of kOTCfgTypeTCPv4. The entity must contain the following preferences:

■kOTCfgTCPInterfacesPref, which contains the core TCP/IP conﬁguration information. For details, see the discussion below and

OTCfgTCPInterfacesUnpacked (page 112), OTCfgTCPInterfacesPacked (page 114), and OTCfgTCPInterfacesPackedPart (page 114).

■kOTCfgTCPDeviceTypePref, which contains data needed by the current TCP/IP control panel. For details, see OTCfgTCPDeviceTypePref in the section “TCP/IP Constants and Other Data Types” (page 160).

■kOTCfgTCPRoutersListPref, which contains the list of conﬁgured routers. For details, see OTCfgTCPRoutersList (page 119).

■kOTCfgTCPSearchListPref, which contains the strings which make up the implicit search path for DNS. For details, see OTCfgTCPSearchList (page 120).

Protocol-speciﬁc Topics

49

Image 49

Apple Network Setup manual Protocol-speciﬁc Topics, TCP/IP Notes

Contents

Network Setup Page Contents Network Setup Reference Glossary Index Network Setup Protocol Structures and Data Types111 Page Figures, Tables, and Listings Page Conventions Used in This Manual About This Manual For More Information Network Setup Architecture About Network Setup 1Network configuration prior to Network Setup 2Network Setup in Mac OS 8.5 through the present 3Future Network Setup architecture Inside the Network Setup Library 4Structure of the Network Setup Library Database Structure Network Setup Database Fundamentals Database Structure Example 5Sample organization of the default area Database Operations Shows this process diagrammatically Preference Coherency Legacy Issues Legacy Synchronization Algorithm Mac OS Not released Network Setup Version HistoryMac OS About Network Setup Network Setup Version History Opening the Database for Reading Opening and Closing the Network Setup Database Opening the Database for Writing Using Network Setup Closing the Database After Writing Closing the Database After Reading Listing 2-4Closing the database after writing Listing All Entities Working with Entities KCfgClassAnyEntity and kCfgTypeAnyEntity, respectively NoErr HLock Handle entityRefs Listing 2-6Printing the user-visible name for an entity Finding an Active Entity Reading and Writing Preferences Listing 2-7Reading a ﬁxed-size preference Reading Fixed-size Preferences OSStatus err AssertdbRef = nil Assertentity Listing 2-9Reading the user-visible name preference Reading Variable-size Preferences == noErr HLockbuffer Listing 2-11Writing a preference Writing Preferences Iterating the Preferences in an Entity Listing 2-12Printing an entity’s table of contents If err != noErr PrintfFailed with error %ld.\n, err Working with Sets Finding the Active Set Entity Listing 2-13Finding the active set entity NoErr Return err Working with Sets Listing 2-15Finding the active TCP/IP entity Areas and Sets TCP/IP Notes Protocol-speciﬁc Topics Start the cursor at the beginning of the packed preference PrefDataErr return paramErr AssertpackedPref != nil assertunpackedPref != nil Remote Access Notes Modem Notes Listing 2-17Encrypting the user’s password Using Network Setup Using Network Setup Opening and Closing the Network Setup Database Network Setup Functions OTCfgCloseDatabase OTCfgOpenDatabase Managing Areas OTCfgGetCurrentArea Obtains the default areaOn input, a value of type CfgDatabaseRef page 98 that Represents a database session previously opened by calling OTCfgOpenArea OTCfgSetCurrentArea OTCfgCloseArea Closes an area in the Network Setup databaseOn input, a value of type CfgAreaID page 98 that identiﬁes OTCfgBeginAreaModiﬁcations OTCfgCommitAreaModiﬁcations OTCfgIsSameAreaID OTCfgAbortAreaModiﬁcations OTCfgGetAreaName OTCfgSetAreaName OTCfgGetAreasList OTCfgGetAreasCount Is large enough to hold the number of area IDs speciﬁed by Be less that expected if areas were deleted between callingYou don’t want to get area IDs, set areaID to Null On input, an array of elements of type Str255 that is large OTCfgCreateArea Creates an area in the Network Setup databaseOutput, areaID contains the ID of the area that was created Value of noErr indicates that OTCfgCreateArea returned OTCfgDuplicateArea Copies the contents of one area to another areaBy areaID does not exist, OTCfgDuplicateArea returns Value of noErr indicates that OTCfgDuplicateArea returned Managing Entities Deletes an area in the Network Setup databaseOTCfgDeleteArea OTCfgGetEntitiesCount Not exist, OTCfgGetEntitiesCount returns the errorClasses and Types KCfgTypeAnyEntity. For a list of possible types, see Entity Obtains information about entities in an area OTCfgGetEntitiesList Network Setup Reference OTCfgCreateEntity OTCfgIsSameEntityRefCompares two entity references Creates an entity in an area Already exists, OTCfgCreateEntity returns the error AreaID is not writable, OTCfgCreateEntity returns the errorSpeciﬁes the class, type, user-visible name, and icon for On input, a pointer to a value of type CfgEntityRef OTCfgDuplicateEntity OTCfgDeleteEntity Obtains the user-visible name of an entity OTCfgGetEntityLogicalNameReference for an entity, call OTCfgGetEntitiesList User-visible name of the entity represented by entityRef Obtains the name of an entity OTCfgGetEntityName OTCfgSetEntityName OTCfgChangeEntityArea OTCfgGetEntityArea Managing Preferences OTCfgOpenPrefs OTCfgGetPrefsSize OTCfgClosePrefs OTCfgGetPrefs OTCfgSetPrefs Gets the number of preferences in an entity OTCfgGetPrefsTOCCount Gets a list of the preferences in an entity OTCfgGetPrefsTOC OTCfgDeletePrefs OTCfgGetDefaultDeletes a preference OTCfgGetTemplate Gets the default value for a speciﬁc preference Value but not the default value itself, set data to Null Returns as much data as possible and returns the errorPreference Utilities Value of noErr indicates that OTCfgGetTemplate returned OTCfgDecrypt OTCfgEncrypt OTCfgInstallNotiﬁer Installing and Removing a Notiﬁcation Callback Notiﬁcation callback when it is called Notiﬁcation callback that is to be installedValue of noErr indicates that OTCfgInstallNotifier returned Values, see the constants described in Entity Classes Application-Deﬁned Routines Was speciﬁed when the notiﬁcation callback was installedOTCfgRemoveNotiﬁer Removes a notiﬁcation callback Notiﬁcation Callback Routine Network Setup Structures and Data Types CfgAreaID CfgDatabaseRefValue of type CfgAreaID identiﬁes an area An unsigned 32-bit value that uniquely identiﬁes an area CfgEntityInfo CfgEntityRefCfgEntityRef structure refers to a speciﬁc entity Area in which the entity resides CfgPrefsHeader CfgEntityAccessID CfgSetsStruct CfgResourceLocator101 An array of time stamps used during legacy import For the fFlags ﬁeld that followsExport indexed by the enumeration for the fTimes ﬁeld that Follows CfgSetsVector CfgSetsElement103 Entity Classes and Types Network Setup Constants 105 Class code for network connection entities Following enumeration deﬁnes per-connection preference types Common Preference Types Dummy preference type used for free blocks in an entity This preference is not documentedFollowing enumeration deﬁnes global preference types 107 Set Entity Preference Types Advanced user mode Basic user modeInvalid Area ID Constant kInvalidCfgAreaID represents an invalid area ID Result Codes TCP/IP Structures Protocol Structures111 OTCfgTCPInterfacesUnpacked 113 OTCfgTCPInterfacesPackedPart OTCfgTCPInterfacesPackedContaining port, module, and framing information 115 OTCfgTCPDHCPLeaseInfo OTCfgTCPLocks OTCfgTCPDNSServersListNumber of IP addresses in the list An unbounded array containing the IP addresses of name 117 Set to True to lock the Ending domain name text ﬁeld Set to True to lock the Router address text ﬁeldSet to True to lock the Additional search domains text ﬁeld OTCfgTCPRoutersListEntry OTCfgTCPRoutersList119 OTCfgTCPSearchList OTCfgTCPSearchDomainsNumber of domains in the list 121 OTCfgTCPUnloadAttr Apple Remote Access Structures OTCfgRemoteApplication OTCfgRemoteAlternateAddressMust be zero 123 OTCfgRemoteARAP 125 OTCfgRemoteClientLocks ErrorCheck ﬁeld is set to 1 and unlocked when Allow error correction and compression in modemErrorCheck ﬁeld is set to zero Control panel is locked when the headerCompress ﬁeld is set OTCfgRemoteConnect OTCfgRemoteClientMisc127 KOTCfgRemotePasswordPref or set to zero to prompt Set to 1 to use the password preferenceUser for a password Is to log on as Guest 129 OTCfgRemoteDialAssist 131 OTCfgRemoteDialing Milliseconds. Must be OTCfgRemoteIPCP 133 OTCfgRemoteLCP Port. Must be ‘Script’ OTCfgRemoteLogOptions OTCfgRemotePassword135 OTCfgRemoteServer 137 OTCfgRemoteServerPort OTCfgRemoteTerminal 139 OTCfgRemoteUserMode OTCfgRemoteX25 Administration password. The format is notDocumented OTCfgRemoteX25 structure stores X.25 connection information OTCfgModemGeneral Modem StructuresMust be zero for standard dial-up connections 141 OTCfgModemApplication 143 OTCfgModemLocks AppleTalk Structures Set dialing to zero to unlock the setting 145 OTCfgATalkGeneral OTCfgATalkGeneralAARP 147 OTCfgATalkGeneralADSP Transport Service Data Unit TSDU, which is FDefaultSendBlockingBytes, default isCarry. The default is Extended Tsdu Etsdu size. The default is Size in bytes of this structure OTCfgATalkGeneralASP149 OTCfgATalkGeneralATP Can carry. The default isMaximum amount of data that packets of this protocol 151 OTCfgATalkGeneralDDP Datagram size Can carry. Must be 586, which is the basic AppleTalkWhether AppleTalk is active. See discussion below for Possible values 153 OTCfgATalkGeneralNBP OTCfgATalkGeneralPAP OTCfgATalkGeneralZIP Default open interval in milliseconds. The default value is155 OTCfgATalkLocks 157 OTCfgATalkNetworkArchitecture OTCfgATalkPortDeviceType Infrared StructuresMust be OTOn Open Transport device type such as OTCfgIRGeneral Protocol Constants and Other Data TypesReference to the infrared port 159 KOTCfgTCPSearchListPref TCP/IP Constants and Other Data Types 161 Masks for the kOTCfgProtocolOptionsPref Preference OTCfgTCPConﬁgMethod If set, this bit disables Dhcp INIT-REBOOT capabilityIf set, this bit turns off path MTU discovery ARA Per-Connection Preferences Types Apple Remote Access Constants and Other Data Types163 Preference type for the OTCfgRemoteARAP page 124 structure Preference type for the OTCfgRemoteLCP page 133 structure Preference type for the OTCfgRemoteIPCP page 132 structurePreference type for the OTCfgRemoteX25 page 140 structure 165 OTCfgRemotePPPConnectScript ARA Global Preference TypesDeﬁned but not used by ARA 167 OTCfgRemoteProtocol OTCfgRemoteDialMode OTCfgRemoteLogLevel OTCfgRemoteNetworkProtocol OTCfgRemoteAnswerMode169 Modem Constants and Other Data Types OTCfgRemoteNetAccessMode OTCfgModemDialingToneMode Modem Global Preference TypesPreference type for the OTCfgModemLocks page 143 structure 171 Per-connection AppleTalk Preference Types AppleTalk Constants and Other Data TypesKModemDialToneIgnoreDo not wait for dial tone Global AppleTalk Preference Types Infrared Constants and Other Data Types173 OTCfgIRPortSetting enumeration deﬁnes constants for use OTCfgIRPortSettingSpeciﬁes the Infrared Data Association IrDA protocol 175 Aarp See AppleTalk Address Resolution Protocol IP See Internet Protocol Icmp See Internet Control Message Protocol 177 Media access control address The six-byte O S S a R Y 179 Index History, version 180 Structure 181 182 183 184