OTCfgGetEntitiesList | Apple Network Setup guide

C H A P T E R 3

Network Setup Reference

itemCount On input, a pointer to a value of type ItemCount. On output, itemCount contains the number of entities that matched the speciﬁed class and type.

function result A value of noErr indicates that OTCfgGetEntitiesCount returned successfully. For a list of other possible result codes, see “Result Codes” (page 110).

DISCUSSION

The OTCfgGetEntitiesCount function obtains the number of entities of the speciﬁed class and type in the speciﬁed area. With the number of entities, you can call OTCfgGetEntitiesList (page 74) to get the list of entities in the area.

OTCfgGetEntitiesList

Obtains information about entities in an area.

OSStatus OTCfgGetEntitiesList (CfgDatabaseRef dbRef,

CfgAreaID areaID,

CfgEntityClass entityClass,

CfgEntityType entityType,

ItemCount* itemCount,

CfgEntityRef entityRef[],

CfgEntityInfo entityInfo[]);

dbRef	On input, a value of type CfgDatabaseRef (page 98) that
	represents a database session previously opened by calling
	OTCfgOpenDatabase (page 58).
areaID	On input, a value of type CfgAreaID (page 98) that identiﬁes the
	area that is to be searched. If the area speciﬁed by areaID does
	not exist, OTCfgGetEntitiesCount returns the error
	kCfgErrAreaNotFound.
entityClass	On input, a value of type CfgEntityClass that speciﬁes the class
	that is to be matched. To specify all classes, set entityClass to
	kCfgClassAnyEntity. For a list of possible classes, see “Entity
	Classes and Types” (page 104).

74Network Setup Functions

Image 74

Apple Network Setup manual OTCfgGetEntitiesList, Obtains information about entities in an area

Contents

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