OTCfgBeginAreaModiﬁcations | Apple Network Setup specs

C H A P T E R 3

Network Setup Reference

OTCfgBeginAreaModiﬁcations

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). If the area speciﬁed by
	readAreaID does not exist, OTCfgBeginAreaModifications returns
	kCfgErrAreaNotFound.
writeAreaID	On input, a pointer to a value of type CfgAreaID (page 98). On
	output, writeAreaID points to a new area ID that your
	application should use to modify, delete, enumerate, or read
	data in the area.
function result	A value of noErr indicates that OTCfgBeginAreaModifications
	returned successfully. For a list of other possible result codes,
	see “Result Codes” (page 110).

DISCUSSION

The OTCfgBeginAreaModifications function creates a temporary area and returns in the writeAreaID parameter an area ID for it. The area ID for the temporary area can be passed as a parameter to subsequent calls for creating or modifying entities in the temporary area.

If you need to read the area’s original, unmodiﬁed data, you can continue using readAreaID to do so.

IMPORTANT

Only one program can open an area of writing at any one time. If another program has already opened the area for writing, OTCfgBeginAreaModifications returns kCfgErrConfigLocked. ▲

Network Setup Functions

63

Image 63

Apple Network Setup manual OTCfgBeginAreaModiﬁcations

Contents

Network Setup Page Contents Network Setup Reference Network Setup Protocol Structures and Data Types Glossary Index111 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 Network Setup Version History Mac OS Not releasedMac 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 Represents a database session previously opened by calling Obtains the default areaOTCfgGetCurrentArea On input, a value of type CfgDatabaseRef page 98 that OTCfgOpenArea OTCfgSetCurrentArea Closes an area in the Network Setup database OTCfgCloseAreaOn input, a value of type CfgAreaID page 98 that identiﬁes OTCfgBeginAreaModiﬁcations OTCfgCommitAreaModiﬁcations OTCfgIsSameAreaID OTCfgAbortAreaModiﬁcations OTCfgGetAreaName OTCfgSetAreaName OTCfgGetAreasList OTCfgGetAreasCount On input, an array of elements of type Str255 that is large Be less that expected if areas were deleted between callingIs large enough to hold the number of area IDs speciﬁed by You don’t want to get area IDs, set areaID to Null Value of noErr indicates that OTCfgCreateArea returned Creates an area in the Network Setup databaseOTCfgCreateArea Output, areaID contains the ID of the area that was created Value of noErr indicates that OTCfgDuplicateArea returned Copies the contents of one area to another areaOTCfgDuplicateArea By areaID does not exist, OTCfgDuplicateArea returns Deletes an area in the Network Setup database Managing EntitiesOTCfgDeleteArea KCfgTypeAnyEntity. For a list of possible types, see Entity Not exist, OTCfgGetEntitiesCount returns the errorOTCfgGetEntitiesCount Classes and Types Obtains information about entities in an area OTCfgGetEntitiesList Network Setup Reference Creates an entity in an area OTCfgIsSameEntityRefOTCfgCreateEntity Compares two entity references On input, a pointer to a value of type CfgEntityRef AreaID is not writable, OTCfgCreateEntity returns the errorAlready exists, OTCfgCreateEntity returns the error Speciﬁes the class, type, user-visible name, and icon for OTCfgDuplicateEntity OTCfgDeleteEntity User-visible name of the entity represented by entityRef OTCfgGetEntityLogicalNameObtains the user-visible name of an entity Reference for an entity, call OTCfgGetEntitiesList 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 OTCfgGetDefault OTCfgDeletePrefsDeletes a preference OTCfgGetTemplate Gets the default value for a speciﬁc preference Value of noErr indicates that OTCfgGetTemplate returned Returns as much data as possible and returns the errorValue but not the default value itself, set data to Null Preference Utilities OTCfgDecrypt OTCfgEncrypt OTCfgInstallNotiﬁer Installing and Removing a Notiﬁcation Callback Values, see the constants described in Entity Classes Notiﬁcation callback that is to be installedNotiﬁcation callback when it is called Value of noErr indicates that OTCfgInstallNotifier returned Removes a notiﬁcation callback Was speciﬁed when the notiﬁcation callback was installedApplication-Deﬁned Routines OTCfgRemoveNotiﬁer Notiﬁcation Callback Routine Network Setup Structures and Data Types An unsigned 32-bit value that uniquely identiﬁes an area CfgDatabaseRefCfgAreaID Value of type CfgAreaID identiﬁes an area Area in which the entity resides CfgEntityRefCfgEntityInfo CfgEntityRef structure refers to a speciﬁc entity CfgPrefsHeader CfgEntityAccessID CfgResourceLocator CfgSetsStruct101 Follows For the fFlags ﬁeld that followsAn array of time stamps used during legacy import Export indexed by the enumeration for the fTimes ﬁeld that CfgSetsElement CfgSetsVector103 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 107 This preference is not documentedDummy preference type used for free blocks in an entity Following enumeration deﬁnes global preference types Set Entity Preference Types Constant kInvalidCfgAreaID represents an invalid area ID Basic user modeAdvanced user mode Invalid Area ID Result Codes Protocol Structures TCP/IP Structures111 OTCfgTCPInterfacesUnpacked 113 OTCfgTCPInterfacesPacked OTCfgTCPInterfacesPackedPartContaining port, module, and framing information 115 OTCfgTCPDHCPLeaseInfo An unbounded array containing the IP addresses of name OTCfgTCPDNSServersListOTCfgTCPLocks Number of IP addresses in the list 117 ﬁeld Set to True to lock the Router address text ﬁeldSet to True to lock the Ending domain name text ﬁeld Set to True to lock the Additional search domains text OTCfgTCPRoutersList OTCfgTCPRoutersListEntry119 OTCfgTCPSearchDomains OTCfgTCPSearchListNumber of domains in the list 121 OTCfgTCPUnloadAttr Apple Remote Access Structures 123 OTCfgRemoteAlternateAddressOTCfgRemoteApplication Must be zero OTCfgRemoteARAP 125 OTCfgRemoteClientLocks Control panel is locked when the headerCompress ﬁeld is set Allow error correction and compression in modemErrorCheck ﬁeld is set to 1 and unlocked when ErrorCheck ﬁeld is set to zero OTCfgRemoteClientMisc OTCfgRemoteConnect127 Is to log on as Guest Set to 1 to use the password preferenceKOTCfgRemotePasswordPref or set to zero to prompt User for a password 129 OTCfgRemoteDialAssist 131 OTCfgRemoteDialing Milliseconds. Must be OTCfgRemoteIPCP 133 OTCfgRemoteLCP Port. Must be ‘Script’ OTCfgRemotePassword OTCfgRemoteLogOptions135 OTCfgRemoteServer 137 OTCfgRemoteServerPort OTCfgRemoteTerminal 139 OTCfgRemoteUserMode OTCfgRemoteX25 structure stores X.25 connection information Administration password. The format is notOTCfgRemoteX25 Documented 141 Modem StructuresOTCfgModemGeneral Must be zero for standard dial-up connections OTCfgModemApplication 143 OTCfgModemLocks AppleTalk Structures Set dialing to zero to unlock the setting 145 OTCfgATalkGeneral OTCfgATalkGeneralAARP 147 OTCfgATalkGeneralADSP Extended Tsdu Etsdu size. The default is FDefaultSendBlockingBytes, default isTransport Service Data Unit TSDU, which is Carry. The default is OTCfgATalkGeneralASP Size in bytes of this structure149 Can carry. The default is OTCfgATalkGeneralATPMaximum amount of data that packets of this protocol 151 OTCfgATalkGeneralDDP Possible values Can carry. Must be 586, which is the basic AppleTalkDatagram size Whether AppleTalk is active. See discussion below for 153 OTCfgATalkGeneralNBP OTCfgATalkGeneralPAP Default open interval in milliseconds. The default value is OTCfgATalkGeneralZIP155 OTCfgATalkLocks 157 OTCfgATalkNetworkArchitecture Open Transport device type such as Infrared StructuresOTCfgATalkPortDeviceType Must be OTOn 159 Protocol Constants and Other Data TypesOTCfgIRGeneral Reference to the infrared port KOTCfgTCPSearchListPref TCP/IP Constants and Other Data Types 161 Masks for the kOTCfgProtocolOptionsPref Preference If set, this bit disables Dhcp INIT-REBOOT capability OTCfgTCPConﬁgMethodIf set, this bit turns off path MTU discovery Apple Remote Access Constants and Other Data Types ARA Per-Connection Preferences Types163 Preference type for the OTCfgRemoteARAP page 124 structure 165 Preference type for the OTCfgRemoteIPCP page 132 structurePreference type for the OTCfgRemoteLCP page 133 structure Preference type for the OTCfgRemoteX25 page 140 structure ARA Global Preference Types OTCfgRemotePPPConnectScriptDeﬁned but not used by ARA 167 OTCfgRemoteProtocol OTCfgRemoteDialMode OTCfgRemoteLogLevel OTCfgRemoteAnswerMode OTCfgRemoteNetworkProtocol169 Modem Constants and Other Data Types OTCfgRemoteNetAccessMode 171 Modem Global Preference TypesOTCfgModemDialingToneMode Preference type for the OTCfgModemLocks page 143 structure AppleTalk Constants and Other Data Types Per-connection AppleTalk Preference TypesKModemDialToneIgnoreDo not wait for dial tone Infrared Constants and Other Data Types Global AppleTalk Preference Types173 OTCfgIRPortSetting OTCfgIRPortSetting enumeration deﬁnes constants for useSpeciﬁ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