OTCfgOpenPrefs | Apple Network Setup guide

C H A P T E R 3

Network Setup Reference

OTCfgOpenPrefs

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).
entityRef	On input, a pointer to a value of type CfgEntityRef (page 99)
	that represents the entity whose preferences are to be read or
	written. If the entity does not exist, OTCfgOpenPrefs returns the
	error kCfgErrEntityNotFound.
writer	On input, a Boolean value. If writer is TRUE, the entity
	represented by entityRef must be in an area that was opened by
	calling OTCfgBeginAreaModifications (page 63); otherwise,
	OTCfgOpenPrefs returns the error kCfgErrLocked. If writer is
	FALSE, the entity represented by entityRef must be in an open
	area [opened by calling OTCfgBeginAreaModifications (page 63)
	or OTCfgOpenArea (page 61)]; otherwise, OTCfgOpenPrefs returns
	the error kCfgErrAreaNotOpen.
accessID	On input, a pointer to a value of type CfgEntityAccessID
	(page 100). On output, use accessID in subsequent calls to get
	and set preferences.
function result	A value of noErr indicates that OTCfgOpenPrefs returned
	successfully. For a list of other possible result codes, see “Result
	Codes” (page 110).

DISCUSSION

The OTCfgOpenPrefs function opens the speciﬁed entity so that your application can get or set the value of the preferences the entity contains.

If the value of the writer parameter is TRUE, you can set preferences as well as get preferences; otherwise, you can only get preferences.

84Network Setup Functions

Image 84

Apple Network Setup manual OTCfgOpenPrefs

Contents

Network Setup Page Contents Network Setup Reference Network Setup Protocol Structures and Data Types Glossary Index111 Page Figures, Tables, and Listings Page About This Manual Conventions Used in This Manual For More Information About Network Setup Network Setup Architecture 1Network configuration prior to Network Setup 2Network Setup in Mac OS 8.5 through the present Inside the Network Setup Library 3Future Network Setup architecture 4Structure of the Network Setup Library Network Setup Database Fundamentals Database Structure Database Structure Example 5Sample organization of the default area Database Operations Shows this process diagrammatically Legacy Issues Preference Coherency Legacy Synchronization Algorithm Network Setup Version History Mac OS Not releasedMac OS About Network Setup Network Setup Version History Opening and Closing the Network Setup Database Opening the Database for Reading Opening the Database for Writing Using Network Setup Closing the Database After Reading Closing the Database After Writing Listing 2-4Closing the database after writing Working with Entities Listing All Entities KCfgClassAnyEntity and kCfgTypeAnyEntity, respectively NoErr HLock Handle entityRefs Listing 2-6Printing the user-visible name for an entity Reading and Writing Preferences Finding an Active Entity Reading Fixed-size Preferences Listing 2-7Reading a ﬁxed-size preference OSStatus err AssertdbRef = nil Assertentity Reading Variable-size Preferences Listing 2-9Reading the user-visible name preference == noErr HLockbuffer Writing Preferences Listing 2-11Writing a preference Listing 2-12Printing an entity’s table of contents Iterating the Preferences in an Entity 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 Protocol-speciﬁc Topics TCP/IP Notes Start the cursor at the beginning of the packed preference PrefDataErr return paramErr AssertpackedPref != nil assertunpackedPref != nil Remote Access Notes Listing 2-17Encrypting the user’s password Modem Notes Using Network Setup Using Network Setup Network Setup Functions Opening and Closing the Network Setup Database OTCfgOpenDatabase OTCfgCloseDatabase Managing Areas Obtains the default area OTCfgGetCurrentAreaOn input, a value of type CfgDatabaseRef page 98 that Represents a database session previously opened by calling OTCfgSetCurrentArea OTCfgOpenArea Closes an area in the Network Setup database OTCfgCloseAreaOn input, a value of type CfgAreaID page 98 that identiﬁes OTCfgBeginAreaModiﬁcations OTCfgCommitAreaModiﬁcations OTCfgAbortAreaModiﬁcations OTCfgIsSameAreaID OTCfgGetAreaName OTCfgSetAreaName OTCfgGetAreasCount OTCfgGetAreasList Be less that expected if areas were deleted between calling Is large enough to hold the number of area IDs speciﬁed byYou don’t want to get area IDs, set areaID to Null On input, an array of elements of type Str255 that is large Creates an area in the Network Setup database OTCfgCreateAreaOutput, areaID contains the ID of the area that was created Value of noErr indicates that OTCfgCreateArea returned Copies the contents of one area to another area OTCfgDuplicateAreaBy areaID does not exist, OTCfgDuplicateArea returns Value of noErr indicates that OTCfgDuplicateArea returned Deletes an area in the Network Setup database Managing EntitiesOTCfgDeleteArea Not exist, OTCfgGetEntitiesCount returns the error OTCfgGetEntitiesCountClasses and Types KCfgTypeAnyEntity. For a list of possible types, see Entity OTCfgGetEntitiesList Obtains information about entities in an area Network Setup Reference OTCfgIsSameEntityRef OTCfgCreateEntityCompares two entity references Creates an entity in an area AreaID is not writable, OTCfgCreateEntity returns the error Already exists, OTCfgCreateEntity returns the errorSpeciﬁes the class, type, user-visible name, and icon for On input, a pointer to a value of type CfgEntityRef OTCfgDeleteEntity OTCfgDuplicateEntity OTCfgGetEntityLogicalName Obtains the user-visible name of an entityReference for an entity, call OTCfgGetEntitiesList User-visible name of the entity represented by entityRef OTCfgGetEntityName Obtains the name of an entity OTCfgSetEntityName OTCfgGetEntityArea OTCfgChangeEntityArea Managing Preferences OTCfgOpenPrefs OTCfgClosePrefs OTCfgGetPrefsSize OTCfgGetPrefs OTCfgSetPrefs OTCfgGetPrefsTOCCount Gets the number of preferences in an entity OTCfgGetPrefsTOC Gets a list of the preferences in an entity OTCfgGetDefault OTCfgDeletePrefsDeletes a preference Gets the default value for a speciﬁc preference OTCfgGetTemplate Returns as much data as possible and returns the error Value but not the default value itself, set data to NullPreference Utilities Value of noErr indicates that OTCfgGetTemplate returned OTCfgEncrypt OTCfgDecrypt Installing and Removing a Notiﬁcation Callback OTCfgInstallNotiﬁer Notiﬁcation callback that is to be installed Notiﬁcation callback when it is calledValue of noErr indicates that OTCfgInstallNotifier returned Values, see the constants described in Entity Classes Was speciﬁed when the notiﬁcation callback was installed Application-Deﬁned RoutinesOTCfgRemoveNotiﬁer Removes a notiﬁcation callback Network Setup Structures and Data Types Notiﬁcation Callback Routine CfgDatabaseRef CfgAreaIDValue of type CfgAreaID identiﬁes an area An unsigned 32-bit value that uniquely identiﬁes an area CfgEntityRef CfgEntityInfoCfgEntityRef structure refers to a speciﬁc entity Area in which the entity resides CfgEntityAccessID CfgPrefsHeader CfgResourceLocator CfgSetsStruct101 For the fFlags ﬁeld that follows An array of time stamps used during legacy importExport indexed by the enumeration for the fTimes ﬁeld that Follows CfgSetsElement CfgSetsVector103 Network Setup Constants Entity Classes and Types Class code for network connection entities 105 Common Preference Types Following enumeration deﬁnes per-connection preference types This preference is not documented Dummy preference type used for free blocks in an entityFollowing enumeration deﬁnes global preference types 107 Set Entity Preference Types Basic user mode Advanced user modeInvalid Area ID Constant kInvalidCfgAreaID represents an invalid area ID Result Codes Protocol Structures TCP/IP Structures111 OTCfgTCPInterfacesUnpacked 113 OTCfgTCPInterfacesPacked OTCfgTCPInterfacesPackedPartContaining port, module, and framing information OTCfgTCPDHCPLeaseInfo 115 OTCfgTCPDNSServersList OTCfgTCPLocksNumber of IP addresses in the list An unbounded array containing the IP addresses of name 117 Set to True to lock the Router address text ﬁeld Set to True to lock the Ending domain name text ﬁeldSet to True to lock the Additional search domains text ﬁeld OTCfgTCPRoutersList OTCfgTCPRoutersListEntry119 OTCfgTCPSearchDomains OTCfgTCPSearchListNumber of domains in the list OTCfgTCPUnloadAttr 121 Apple Remote Access Structures OTCfgRemoteAlternateAddress OTCfgRemoteApplicationMust be zero 123 OTCfgRemoteARAP OTCfgRemoteClientLocks 125 Allow error correction and compression in modem ErrorCheck ﬁeld is set to 1 and unlocked whenErrorCheck ﬁeld is set to zero Control panel is locked when the headerCompress ﬁeld is set OTCfgRemoteClientMisc OTCfgRemoteConnect127 Set to 1 to use the password preference KOTCfgRemotePasswordPref or set to zero to promptUser for a password Is to log on as Guest 129 OTCfgRemoteDialAssist OTCfgRemoteDialing 131 OTCfgRemoteIPCP Milliseconds. Must be OTCfgRemoteLCP 133 Port. Must be ‘Script’ OTCfgRemotePassword OTCfgRemoteLogOptions135 OTCfgRemoteServer OTCfgRemoteServerPort 137 OTCfgRemoteTerminal OTCfgRemoteUserMode 139 Administration password. The format is not OTCfgRemoteX25Documented OTCfgRemoteX25 structure stores X.25 connection information Modem Structures OTCfgModemGeneralMust be zero for standard dial-up connections 141 OTCfgModemApplication OTCfgModemLocks 143 Set dialing to zero to unlock the setting AppleTalk Structures OTCfgATalkGeneral 145 OTCfgATalkGeneralAARP OTCfgATalkGeneralADSP 147 FDefaultSendBlockingBytes, default is Transport Service Data Unit TSDU, which isCarry. The default is Extended Tsdu Etsdu size. The default is OTCfgATalkGeneralASP Size in bytes of this structure149 Can carry. The default is OTCfgATalkGeneralATPMaximum amount of data that packets of this protocol OTCfgATalkGeneralDDP 151 Can carry. Must be 586, which is the basic AppleTalk Datagram sizeWhether AppleTalk is active. See discussion below for Possible values OTCfgATalkGeneralNBP 153 OTCfgATalkGeneralPAP Default open interval in milliseconds. The default value is OTCfgATalkGeneralZIP155 OTCfgATalkLocks OTCfgATalkNetworkArchitecture 157 Infrared Structures OTCfgATalkPortDeviceTypeMust be OTOn Open Transport device type such as Protocol Constants and Other Data Types OTCfgIRGeneralReference to the infrared port 159 TCP/IP Constants and Other Data Types KOTCfgTCPSearchListPref Masks for the kOTCfgProtocolOptionsPref Preference 161 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 Preference type for the OTCfgRemoteIPCP page 132 structure Preference type for the OTCfgRemoteLCP page 133 structurePreference type for the OTCfgRemoteX25 page 140 structure 165 ARA Global Preference Types OTCfgRemotePPPConnectScriptDeﬁned but not used by ARA OTCfgRemoteProtocol 167 OTCfgRemoteLogLevel OTCfgRemoteDialMode OTCfgRemoteAnswerMode OTCfgRemoteNetworkProtocol169 OTCfgRemoteNetAccessMode Modem Constants and Other Data Types Modem Global Preference Types OTCfgModemDialingToneModePreference type for the OTCfgModemLocks page 143 structure 171 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 Aarp See AppleTalk Address Resolution Protocol 175 Icmp See Internet Control Message Protocol IP See Internet Protocol Media access control address The six-byte 177 O S S a R Y Index 179 180 History, version 181 Structure 182 183 184