Manuals / Apple / Computer Equipment / Network Card

Apple Network Setup manual OTCfgGetPrefsTOC

Models: Network Setup

1 184

Download 184 pages 5.56 Kb

Page 89

C H A P T E R 3

Network Setup Reference

OTCfgGetPrefsTOC

Gets a list of the preferences in an entity.

OSStatus OTCfgGetPrefsTOC (CfgEntityAccessID accessID.

ItemCount* itemCount,

CfgPrefsHeader prefsTOC[]);

accessID On input, a value of type CfgEntityAccessID (page 100), obtained by previously calling OTCfgOpenPrefs (page 84) that identiﬁes the entity whose preferences are to be obtained.

itemCount On input, a pointer to a value of type ItemCount that speciﬁes the requested number of preferences. On output, itemCount contains the number of preferences that were obtained.

prefsTOC On input, an array of CfgPrefsHeader (page 100) structures. The prefsTOC parameter must have enough CfgPrefsHeader structures to store all of the preferences in the entity.

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

DISCUSSION

The OTCfgGetPrefsTOC function obtains information about the speciﬁed number preferences in the entity represented by accessID and stores them in the prefsTOC array.

Before you call OTCfgPrefsTOC, you must should ﬁnd out how many preferences are available by calling OTCfgGetPrefsTOCCount (page 88).

▲W AR N I N G

Early versions of Network Setup do not determine whether there is enough space in prefsTOC (as speciﬁed on input by itemCount) and can write beyond the end of the array. You should always call OTCfgGetPrefsTOCCount before calling OTCfgGetPrefsTOC. When you call OTCfgGetPrefsTOC, set itemCount to the value returned by OTCfgGetPrefsTOCCount in the itemCount parameter. ▲

Network Setup Functions

89

Image 89

Apple Network Setup manual OTCfgGetPrefsTOC

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 Network Setup ContentsUsing Network Setup About This ManualChapter Network Setup ReferenceGlossary Index Chapter 4 Network Setup Protocol Structures and Data TypesPage Using Network Setup About Network SetupFigures, Tables, and Listings ChapterPage Conventions Used in This Manual About This ManualInside AppleTalk, Second Edition For More InformationInside Macintosh Networking with Open Transport Open Transport Advanced Client Programming, available atNetwork 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 Inside the Network Setup Library About Network Setup Figure 1-4 Structure of the Network Setup LibraryHigh-level framework Mid-level database OTCfgDatabase Structure Network Setup Database FundamentalsDatabase Structure Example Figure 1-5 Sample organization of the default area About Network Setup18 Network Setup Database Fundamentals LocalTalk for Printer AppleTalk networkork protocol entityDatabase Operations Figure 1-6 shows this process diagrammatically Preference Coherency Legacy IssuesLegacy Synchronization Algorithm Mac OS version Network Setup Version HistoryVersion C H A P T E R About Network Setup24 Network Setup Version History Opening the Database for Reading Using Network SetupOpening and Closing the Network Setup Database 26 Opening and Closing the Network Setup Database Opening the Database for WritingUsing Network Setup Listing 2-1 Opening the database for reading Listing 2-2 Opening the database for writing Using Network SetupOpening and Closing the Network Setup Database Closing the Database After Writing Closing the Database After ReadingOpening and Closing the Network Setup Database Using Network SetupListing 2-4 Closing the database after writing err = OTCfgCommitAreaModificationsdbRef, readArea, writeAreaListing All Entities Working with Entitiesstatic OSStatus MyGetEntitiesListCfgDatabaseRef dbRef, CfgAreaID area kCfgClassAnyEntity and kCfgTypeAnyEntity, respectivelyOSType entityClass OSType entityType CfgEntityRef **entityRefs CfgEntityInfo **entityInfos32 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 PreferencesUsing Network Setup Reading Fixed-size PreferencesListing 2-7 Reading a ﬁxed-size preference Reading and Writing PreferencesThe 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 46 Working with Sets Using Network SetupListing 2-14 Finding the active entity of a given class and type Working with Sets Using Network SetupListing 2-15 Finding the active TCP/IP entity Areas and Sets TCP/IP Notes Protocol-speciﬁc Topicsaccess the preference in its packed format cursor = UInt8 * packedPref Using Network SetupProtocol-speciﬁc Topics UInt8 *cursor Using Network Setup52 Protocol-speciﬁc Topics Remote Access Notes OTCfgRemoteClientLocks page Modem NotesStoring Third-party Preferences in Apple Entities Network Setup and Third-party Protocol StacksNotes for Third Parties C H A P T E R Using Network Setup56 Notes for Third Parties Opening and Closing the Network Setup Database Network Setup ReferenceNetwork Setup Functions OTCfgCloseDatabase OTCfgOpenDatabaseManaging Areas OTCfgGetCurrentArea OTCfgOpenArea OTCfgSetCurrentAreaOTCfgCloseArea function result OTCfgBeginAreaModiﬁcationsfunction result OTCfgCommitAreaModiﬁcationsOTCfgIsSameAreaID OTCfgAbortAreaModiﬁcationsfunction result OTCfgAbortAreaModifications returns kCfgErrAreaNotFoundfunction result OTCfgGetAreaNamefunction result OTCfgSetAreaNamefunction result OTCfgGetAreasCountOTCfgGetAreasList 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 thatOTCfgDuplicateEntity OTCfgDeleteEntityfunction result const CfgEntityRef* entityRef, const CfgEntityRef* newEntityRefOTCfgGetEntityLogicalName function result None OTCfgGetEntityNamefunction result OTCfgSetEntityNamefunction result OTCfgGetEntityAreaOTCfgChangeEntityArea function result None Managing Preferencesfunction result OTCfgOpenPrefsOTCfgGetPrefsSize OTCfgClosePrefsvoid* data, ByteCount length OTCfgGetPrefsfunction result const void* data, ByteCount length OTCfgSetPrefsfunction result 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 thatfunction result Application-Deﬁned RoutinesOTCfgRemoveNotiﬁer Notiﬁcation Callback Routine Network Setup Structures and Data TypesCfgAreaID CfgDatabaseRefField descriptions CfgEntityRefCfgEntityInfo 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 Global Backward Compatibility Preference Types Set Entity Preference TypesBackward Compatibility Preference Types OTCfgUserMode Preference Invalid Area IDResult Codes TCP/IP Structures Network Setup Protocol Structures and Data TypesProtocol Structures OTCfgTCPInterfacesUnpacked modulekMaxModuleNameSize partsizeofOTCfgTCPInterfacesPackedPart OTCfgTCPInterfacesPackedOTCfgTCPInterfacesPackedPart OTCfgTCPDHCPLeaseInfo OTCfgTCPLocks OTCfgTCPDNSServersListlockDNSServersList lockAdminDomainNamelockLocalDomainName Set to TRUE to lock the “Router address” text ﬁeld OTCfgTCPRoutersListEntry page 119 structures OTCfgTCPRoutersListOTCfgTCPRoutersListEntry OTCfgTCPSearchList OTCfgTCPSearchDomainsOTCfgTCPUnloadAttr Apple Remote Access Structures OTCfgRemoteApplication OTCfgRemoteAlternateAddressOTCfgRemoteARAP regUserOrGuestLock OTCfgRemoteClientLocksuseVerboseLogLock The “Allow error correction and compression in modem” OTCfgRemoteConnect OTCfgRemoteClientMiscconnectAutomatically canInteractOTCfgRemotePPPConnectScript issueConnectedRemindersallowModemDataCompression If Notification Manager reminders are enabled, the number isAssisted to 1 to use Dial Assist. When isAssisted is set to OTCfgRemoteDialAssistmade. Only valid if dialMode is not kOTCfgRemoteRedialNone OTCfgRemoteDialingadditionalPtr OTCfgRemoteIPCP lowerLayerName36 OTCfgRemoteLCPkOTCfgRemoteAcceptedVersion. When reading the version OTCfgRemoteLogOptions OTCfgRemotePasswordconfigIDs1 OTCfgRemoteServerconfigCount struct OTCfgRemoteServerPort OTCfgRemoteServerPortOTCfgRemoteNetworkProtocol serialLayerNamekMaxProviderNameSizeAccess mode flags. For possible values, see the OTCfgRemoteTerminalNetwork Setup Protocol Structures and Data Types Must be TRUEOTCfgRemoteUserMode OTCfgRemoteX25 OTCfgModemGeneral Modem StructuresOTCfgModemApplication OTCfgModemLocks AppleTalk Structures OTCfgATalkGeneral OTCfgATalkGeneralAARP fMaxConsecutiveDataPackets OTCfgATalkGeneralADSPPage OTCfgATalkGeneralASP fDefaultReleaseTimer OTCfgATalkGeneralATPfDefaultRetryInterval Network Setup Protocol Structures and Data Types OTCfgATalkGeneralDDPProtocol Structures fMyZonekZIPMaxZoneLength+1The maximum amount of data that packets of this protocol OTCfgATalkGeneralNBP fDefaultTickleInterval OTCfgATalkGeneralPAPfDefaultTickleRetries fDefaultPAPEOMEnabledOTCfgATalkGeneralZIP OTCfgATalkLocks Constant descriptions kOTCfgATalkPortLockMask OTCfgATalkNetworkArchitectureOTCfgATalkPortDeviceType Infrared StructuresOTCfgIRGeneral Protocol Constants and Other Data TypesNetwork Setup Protocol Structures and Data Types TCP/IP Constants and Other Data Types“AppleTalk Constants and Other Data Types” page “Infrared Constants and Other Data Types” pagekDontShutDownOnARPCollisionMask = Masks for the kOTCfgProtocolOptionsPref Preference0x0002 0x0004OTCfgTCPConﬁgMethod ARA Per-Connection Preferences Types Apple Remote Access Constants and Other Data TypesThe preference type for the OTCfgRemoteARAP page 124 structure Network Setup Protocol Structures and Data TypesThe preference type for the OTCfgRemoteDialing page 131 structure The preference type for the OTCfgRemoteClientLocks page 125 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 notiﬁcation routine installing 94 removing named areas network connection entities 16 Network Setuplegacy preference ﬁles mid-level database 15 modem constants 170 multihoming 12Page setting entity names 81 structures set entities 16 active, number of 43 usingTCP/IP constants 160 preferences temporary area 20 third-party developers 55 type, entityI N D E