Manuals / Apple / Computer Equipment / Network Card

Apple Network Setup manual OTCfgGetEntityLogicalName

Models: Network Setup

1 184

Download 184 pages 5.56 Kb

Page 79

C H A P T E R 3

Network Setup Reference

entityRef On input, a pointer to a value of type CfgEntityRef (page 99) that identiﬁes the entity reference that is to be duplicated. If the entity represented by entityRef does not exist, OTCfgDuplicateEntry returns the error kCfgErrEntityNotFound.

newEntityRef On input, a pointer to a value of type CfgEntityRef (page 99) that identiﬁes the entity that is to be overwritten by the contents of entityRef. If entityRef represents an entity that does not reside in an area that is open for writing, OTCfgDuplicateEntity returns the error kCfgErrAreaNotOpen or kCfgErrLocked.

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

DISCUSSION

The OTCfgDuplicateEntity function copies the contents of the entity speciﬁed by entityRef to the entity speciﬁed by newEntityRef. Any data stored in newEntityRef before OTCfgDuplicateEntity is called is overwritten by the contents of entityRef when OTCfgDuplicateEntity returns.

OTCfgGetEntityLogicalName

Obtains the user-visible name of an entity.

OSStatus OTCfgGetEntityLogicalName( CfgDatabaseRef dbRef, const CfgEntityRef *entityRef, Str255 entityName );

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 identiﬁes the entity whose name is to be obtained. To obtain
	the reference for an entity, call OTCfgGetEntitiesList (page 74).
entityName	On input, a value of type Str255. On output, entityName contains
	the user-visible name of the entity represented by entityRef.

Network Setup Functions

79

Image 79

Apple Network Setup manual OTCfgGetEntityLogicalName

Contents

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 This Manual ContentsAbout Network Setup Using Network SetupChapter Network Setup ReferenceGlossary Index Chapter 4 Network Setup Protocol Structures and Data TypesPage Chapter About Network SetupUsing Network Setup Figures, Tables, and ListingsPage Conventions Used in This Manual About This ManualOpen Transport Advanced Client Programming, available at For More InformationInside AppleTalk, Second Edition Inside Macintosh Networking with Open TransportNetwork Setup Architecture About Network SetupThe 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 Mid-level database OTCfg About Network Setup Figure 1-4 Structure of the Network Setup LibraryInside the Network Setup Library High-level frameworkDatabase Structure Network Setup Database FundamentalsDatabase Structure Example LocalTalk for Printer AppleTalk networkork protocol entity About Network SetupFigure 1-5 Sample organization of the default area 18 Network Setup Database FundamentalsDatabase Operations Figure 1-6 shows this process diagrammatically Preference Coherency Legacy IssuesLegacy Synchronization Algorithm Version Network Setup Version HistoryMac OS version 24 Network Setup Version History About Network SetupC H A P T E R Opening and Closing the Network Setup Database Using Network SetupOpening the Database for Reading Using Network Setup Listing 2-1 Opening the database for reading Opening the Database for Writing26 Opening and Closing the Network Setup Database Opening and Closing the Network Setup Database Using Network SetupListing 2-2 Opening the database for writing Closing the Database After Writing Closing the Database After Readingerr = OTCfgCommitAreaModificationsdbRef, readArea, writeArea Using Network SetupOpening and Closing the Network Setup Database Listing 2-4 Closing the database after writingListing All Entities Working with EntitiesCfgEntityInfo **entityInfos kCfgClassAnyEntity and kCfgTypeAnyEntity, respectivelystatic OSStatus MyGetEntitiesListCfgDatabaseRef dbRef, CfgAreaID area OSType entityClass OSType entityType CfgEntityRef **entityRefs32 Working with Entities Using Network SetupThe 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 PreferencesReading and Writing Preferences Reading Fixed-size PreferencesUsing Network Setup Listing 2-7 Reading a ﬁxed-size preferenceThe sample shown in Listing 2-7, which opens and closes the entity before reading each preference, is implemented in an inefﬁcient manner for the sake of clarity. If you are reading multiple preferences, it is more efﬁcient 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 Preferences38 Reading and Writing Preferences Using Network SetupWriting Preferences Iterating the Preferences in an Entity Reading and Writing Preferences Using Network SetupWorking with Sets Finding the Active Set Entity The MyFindActiveSet routine in Listing 2-13 implements the ﬁrst 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 Setup46 Working with Sets Listing 2-15 Finding the active TCP/IP entity Using Network SetupWorking with Sets Areas and Sets TCP/IP Notes Protocol-speciﬁc Topicsaccess the preference in its packed format Protocol-speciﬁc Topics Using Network Setupcursor = UInt8 * packedPref 52 Protocol-speciﬁc Topics Using Network SetupUInt8 *cursor Remote Access Notes OTCfgRemoteClientLocks page Modem NotesNotes for Third Parties Network Setup and Third-party Protocol StacksStoring Third-party Preferences in Apple Entities 56 Notes for Third Parties Using Network SetupC H A P T E R Network Setup Functions Network Setup ReferenceOpening and Closing the Network Setup Database OTCfgCloseDatabase OTCfgOpenDatabaseManaging Areas OTCfgGetCurrentArea OTCfgOpenArea OTCfgSetCurrentAreaOTCfgCloseArea function result OTCfgBeginAreaModiﬁcationsfunction result OTCfgCommitAreaModiﬁcationsOTCfgAbortAreaModifications returns kCfgErrAreaNotFound OTCfgAbortAreaModiﬁcationsOTCfgIsSameAreaID function resultfunction result OTCfgGetAreaNamefunction result OTCfgSetAreaNameOTCfgGetAreasList OTCfgGetAreasCountfunction result function result that are available. On output, itemCount points to the number offunction result OTCfgCreateAreafunction result OTCfgDuplicateAreaOTCfgDeleteArea Managing EntitiesOTCfgGetEntitiesCount OTCfgGetEntitiesList entityType On input, a value of type CfgEntityType that speciﬁes 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 OTCfgIsSameEntityReffunction result On input, a value of type CfgDatabaseRef page 98 thatconst CfgEntityRef* entityRef, const CfgEntityRef* newEntityRef OTCfgDeleteEntityOTCfgDuplicateEntity function resultOTCfgGetEntityLogicalName function result None OTCfgGetEntityNamefunction result OTCfgSetEntityNameOTCfgChangeEntityArea OTCfgGetEntityAreafunction result function result None Managing Preferencesfunction result OTCfgOpenPrefsOTCfgGetPrefsSize OTCfgClosePrefsfunction result OTCfgGetPrefsvoid* data, ByteCount length function result OTCfgSetPrefsconst void* data, ByteCount length OTCfgGetPrefsTOCCount OTCfgGetPrefsTOC OTCfgDeletePrefs OTCfgGetDefaultOTCfgGetTemplate function result Preference UtilitiesOTCfgDecrypt OTCfgEncryptOTCfgInstallNotiﬁer Installing and Removing a Notiﬁcation Callbackfunction result On input, a value of type CfgDatabaseRef page 98 thatOTCfgRemoveNotiﬁer Application-Deﬁned Routinesfunction result Notiﬁcation Callback Routine Network Setup Structures and Data TypesCfgAreaID CfgDatabaseRefCfgEntityInfo CfgEntityRefField descriptions CfgPrefsHeader CfgEntityAccessIDCfgSetsStruct CfgResourceLocatorFlags for this set. For possible values, see the enumeration CfgSetsVector CfgSetsElementEntity Classes and Types Network Setup ConstantsWildcard Classes and Types Per-connection Preference Types Common Preference TypesGlobal Preference Types Backward Compatibility Preference Types Set Entity Preference TypesGlobal Backward Compatibility Preference Types OTCfgUserMode Preference Invalid Area IDResult Codes Protocol Structures Network Setup Protocol Structures and Data TypesTCP/IP Structures OTCfgTCPInterfacesUnpacked modulekMaxModuleNameSize OTCfgTCPInterfacesPackedPart OTCfgTCPInterfacesPackedpartsizeofOTCfgTCPInterfacesPackedPart OTCfgTCPDHCPLeaseInfo OTCfgTCPLocks OTCfgTCPDNSServersListlockLocalDomainName lockAdminDomainNamelockDNSServersList Set to TRUE to lock the “Router address” text ﬁeld OTCfgTCPRoutersListEntry OTCfgTCPRoutersListOTCfgTCPRoutersListEntry page 119 structures OTCfgTCPSearchList OTCfgTCPSearchDomainsOTCfgTCPUnloadAttr Apple Remote Access Structures OTCfgRemoteApplication OTCfgRemoteAlternateAddressOTCfgRemoteARAP useVerboseLogLock OTCfgRemoteClientLocksregUserOrGuestLock The “Allow error correction and compression in modem” canInteract OTCfgRemoteClientMiscOTCfgRemoteConnect connectAutomaticallyallowModemDataCompression issueConnectedRemindersOTCfgRemotePPPConnectScript If Notification Manager reminders are enabled, the number isAssisted to 1 to use Dial Assist. When isAssisted is set to OTCfgRemoteDialAssistadditionalPtr OTCfgRemoteDialingmade. Only valid if dialMode is not kOTCfgRemoteRedialNone OTCfgRemoteIPCP lowerLayerName36 OTCfgRemoteLCPkOTCfgRemoteAcceptedVersion. When reading the version OTCfgRemoteLogOptions OTCfgRemotePasswordconfigCount OTCfgRemoteServerconfigIDs1 serialLayerNamekMaxProviderNameSize OTCfgRemoteServerPortstruct OTCfgRemoteServerPort OTCfgRemoteNetworkProtocolMust be TRUE OTCfgRemoteTerminalAccess mode flags. For possible values, see the Network Setup Protocol Structures and Data TypesOTCfgRemoteUserMode OTCfgRemoteX25 OTCfgModemGeneral Modem StructuresOTCfgModemApplication OTCfgModemLocks AppleTalk Structures OTCfgATalkGeneral OTCfgATalkGeneralAARP fMaxConsecutiveDataPackets OTCfgATalkGeneralADSPPage OTCfgATalkGeneralASP fDefaultRetryInterval OTCfgATalkGeneralATPfDefaultReleaseTimer fMyZonekZIPMaxZoneLength+1 OTCfgATalkGeneralDDPNetwork Setup Protocol Structures and Data Types Protocol StructuresThe maximum amount of data that packets of this protocol OTCfgATalkGeneralNBP fDefaultPAPEOMEnabled OTCfgATalkGeneralPAPfDefaultTickleInterval fDefaultTickleRetriesOTCfgATalkGeneralZIP OTCfgATalkLocks Constant descriptions kOTCfgATalkPortLockMask OTCfgATalkNetworkArchitectureOTCfgATalkPortDeviceType Infrared StructuresOTCfgIRGeneral Protocol Constants and Other Data Types“Infrared Constants and Other Data Types” page TCP/IP Constants and Other Data TypesNetwork Setup Protocol Structures and Data Types “AppleTalk Constants and Other Data Types” page0x0004 Masks for the kOTCfgProtocolOptionsPref PreferencekDontShutDownOnARPCollisionMask = 0x0002OTCfgTCPConﬁgMethod ARA Per-Connection Preferences Types Apple Remote Access Constants and Other Data TypesThe preference type for the OTCfgRemoteClientLocks page 125 structure Network Setup Protocol Structures and Data TypesThe preference type for the OTCfgRemoteARAP page 124 structure The preference type for the OTCfgRemoteDialing page 131 structureThe preference type for the OTCfgRemoteConnect page 127 structure OTCfgRemotePPPConnectScript ARA Global Preference TypesOTCfgRemoteProtocol OTCfgRemoteDialMode OTCfgRemoteLogLevelOTCfgRemoteNetworkProtocol OTCfgRemoteAnswerModeModem Constants and Other Data Types OTCfgRemoteNetAccessModeOTCfgModemDialingToneMode Modem Global Preference TypesPer-connection AppleTalk Preference Types AppleTalk Constants and Other Data TypesGlobal AppleTalk Preference Types Infrared Constants and Other Data TypesOTCfgIRPortSetting 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 mid-level database 15 modem constants 170 multihoming 12 named areas network connection entities 16 Network Setupnotiﬁcation routine installing 94 removing legacy preference ﬁlesPage temporary area 20 third-party developers 55 type, entity set entities 16 active, number of 43 usingsetting entity names 81 structures TCP/IP constants 160 preferencesI N D E