| Framework | Carbon/Carbon.h |
| Declared in | InternetConfig.h |
Internet Config, a Mac OS 8 and 9 API, supports centralized entry and management of Internet preferences for all of a user’s Internet applications. For example, email programs and Web browsers can obtain a user's name, email address, home page, incoming mail server, and similar preferences from one common place that is easily edited by the user via the Internet Config application.
Mac OS X applications should employ Launch Services and System Configuration for managing Internet preferences. In Mac OS X, Internet Config calls through to these newer APIs. Using them directly increases your application’s efficiency.
If you use Internet Config in Mac OS X, perhaps to maintain backward compatibility for your application with Mac OS 8 and 9, here are some ways to optimize performance.
Getting multiple preferences at once.
Your program may access several Internet Config preferences within a single operation. For example, an FTP program on startup might always get the kICFTPHost, kICFTPProxyHost, kICFTPProxyAccount, kICFTPProxyPassword, and kICFTPProxyUser preferences. Bracket such a sequence of ICGetPref calls with an ICBegin and ICEnd function pair for significantly faster performance.
Calling Internet Config less often.
Your application can cache Internet Config preference data and then watch for changes using one of the preference coherency strategies described in the developer’s online documentation:
http://www.quinn.echidna.id.au/Quinn/Config/Prog_Docs.html#PreferenceCoherency
Using preferences from underlying frameworks.
Starting with Mac OS X, Internet Config is no longer the final authority on Internet preferences. For example, Launch Services stores URL helper application settings, and System Configuration stores the various proxy settings. When called by an application, Internet Config must call through to the appropriate underlying framework. Call Launch Services and System Configuration directly to improve performance.
The Mac OS 8 and 9 implementation of Internet Config is in the public domain, and Carbon supports all of its commonly-used functions. Functions that are not compatible with preemptive threads are not supported, and Internet Config no longer supports multiple configuration files. This document contains information on replacement functions.
For more information on Internet Config see its developer’s web site:
http://www.quinn.echidna.id.au/Quinn/Config
These functions let you create, configure, and destroy connections to Internet Config, denoted by the ICInstance type. Although it is usual to create one connection when your program starts and destroy it when it terminates, you can create an arbitrary number of connections at any time.
These routines are not always required because the commonly used reading and writing calls perform this operation automatically. However, even in that case, these routines are useful if you are making repeated calls because they allow those calls to work faster.
You must call ICBegin before calling any of these routines.
We recommend that you do not provide a user interface for editing Internet Config preferences from within your application. In Mac OS X, simply provide a way for the user to open the Internet pane of System Preferences. The ICEditPreferences function provides support for this.
Internet Config’s high-level functions are suitable for applications that want to easily look up a file type and creator based on an extension, or vice versa. These functions are significantly slower than their lower level counterparts, especially if you call them repeatedly.
These functions are useful if you are doing multiple searches because they avoid the overhead of accessing the mappings database each time.
Internet Config’s low-level functions give you access to the primitive operations used to implement the other mapping functions.
ICGetCurrentProfile
ICSetCurrentProfile
ICCountProfiles
ICGetIndProfile
ICGetProfileName
ICSetProfileName
ICAddProfile
ICDeleteProfile
ICCSetPref
ICCAddMapEntry
ICCAddProfile
ICCBegin
ICCChooseConfig
ICCChooseNewConfig
ICCCountMapEntries
ICCCountPref
ICCCountProfiles
ICCCreateGURLEvent
ICCDefaultFileName
ICCDeleteMapEntry
ICCDeletePref
ICCDeleteProfile
ICCEditPreferences
ICCEnd
ICCFindConfigFile
ICCFindPrefHandle
ICCFindUserConfigFile
ICCGeneralFindConfigFile
ICCGetComponentInstance
ICCGetConfigName
ICCGetConfigReference
ICCGetCurrentProfile
ICCGetDefaultPref
ICCGetIndMapEntry
ICCGetIndPref
ICCGetIndProfile
ICCGetMapEntry
ICCGetMappingInterruptSafe
ICCGetPerm
ICCGetPref
ICCGetPrefHandle
ICCGetProfileName
ICCGetSeed
ICCGetSeedInterruptSafe
ICCGetVersion
ICChooseConfig
ICChooseNewConfig
ICCLaunchURL
ICCMapEntriesFilename
ICCMapEntriesTypeCreator
ICCMapFilename
ICCMapTypeCreator
ICCParseURL
ICCRefreshCaches
ICCRequiresInterruptSafe
ICCSendGURLEvent
ICCSetConfigReference
ICCSetCurrentProfile
ICCSetMapEntry
ICCSetPrefHandle
ICCSetProfileName
ICCSpecifyConfigFile
ICCStart
ICCStop
ICDefaultFileName
ICFindConfigFile
ICFindUserConfigFile
ICGeneralFindConfigFile
ICGetComponentInstance
ICGetConfigReference
ICGetMappingInterruptSafe
ICGetSeedInterruptSafe
ICRefreshCaches
ICRequiresInterruptSafe
ICSetConfigReference
ICSpecifyConfigFile
Adds an entry to the mappings database.
OSStatus ICAddMapEntry ( ICInstance inst, Handle entries, const ICMapEntry *entry );
A result code. See “Result Codes.”
InternetConfig.h
Creates a new profile and returns its ID.
OSStatus ICAddProfile ( ICInstance inst, ICProfileID prototypeID, ICProfileID *newID );
A result code. See “Result Codes.”
InternetConfig.h
Prepares Internet Config to read (and, optionally, to write) preferences.
OSStatus ICBegin ( ICInstance inst, ICPerm perm );
A result code. See “Result Codes.”
InternetConfig.h
Unsupported
OSStatus ICCAddMapEntry ( ComponentInstance inst, Handle entries, ICMapEntry *entry );
Use ICAddMapEntry instead.
InternetConfig.h
Unsupported
OSStatus ICCAddProfile ( ComponentInstance inst, ICProfileID prototypeID, ICProfileID *newID );
Use ICAddProfile instead.
InternetConfig.h
Unsupported
OSStatus ICCBegin ( ComponentInstance inst, ICPerm perm );
Use ICBegin instead.
InternetConfig.h
Unsupported
OSStatus ICCChooseConfig ( ComponentInstance inst );
Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICCChooseNewConfig ( ComponentInstance inst );
Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICCCountMapEntries ( ComponentInstance inst, Handle entries, SInt32 *count );
Use ICCountMapEntries instead.
InternetConfig.h
Unsupported
OSStatus ICCCountPref ( ComponentInstance inst, SInt32 *count );
Use ICCountPref instead.
InternetConfig.h
Unsupported
OSStatus ICCCountProfiles ( ComponentInstance inst, SInt32 *count );
Use ICCountProfiles instead.
InternetConfig.h
Unsupported
OSStatus ICCCreateGURLEvent ( ComponentInstance inst, OSType helperCreator, Handle urlH, AppleEvent *theEvent );
Use ICCreateGURLEvent instead.
InternetConfig.h
Unsupported
OSStatus ICCDefaultFileName ( ComponentInstance inst, Str63 name );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICCDeleteMapEntry ( ComponentInstance inst, Handle entries, SInt32 pos );
Use ICDeleteMapEntry instead.
InternetConfig.h
Unsupported
OSStatus ICCDeletePref ( ComponentInstance inst, ConstStr255Param key );
Use ICDeletePref instead.
InternetConfig.h
Unsupported
OSStatus ICCDeleteProfile ( ComponentInstance inst, ICProfileID thisID );
Use ICDeleteProfile instead.
InternetConfig.h
Unsupported
OSStatus ICCEditPreferences ( ComponentInstance inst, ConstStr255Param key );
Use ICEditPreferences instead.
InternetConfig.h
Unsupported
OSStatus ICCEnd ( ComponentInstance inst );
Use ICEnd instead.
InternetConfig.h
Unsupported
OSStatus ICCFindConfigFile ( ComponentInstance inst, SInt16 count, ICDirSpecArrayPtr folders );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICCFindPrefHandle ( ComponentInstance inst, ConstStr255Param key, ICAttr *attr, Handle prefh );
Use ICFindPrefHandle instead.
InternetConfig.h
Unsupported
OSStatus ICCFindUserConfigFile ( ComponentInstance inst, ICDirSpec *where );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICCGeneralFindConfigFile ( ComponentInstance inst, Boolean searchPrefs, Boolean canCreate, SInt16 count, ICDirSpecArrayPtr folders );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICCGetComponentInstance ( ComponentInstance inst, ComponentInstance *componentInst );
Because Internet Config is not component-based under Mac OS X, use ICGetVersion instead.
InternetConfig.h
Unsupported
OSStatus ICCGetConfigName ( ComponentInstance inst, Boolean longname, Str255 name );
Use ICGetConfigName instead.
InternetConfig.h
Unsupported
OSStatus ICCGetConfigReference ( ComponentInstance inst, ICConfigRefHandle ref );
Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICCGetCurrentProfile ( ComponentInstance inst, ICProfileID *currentID );
Use ICGetCurrentProfile instead.
InternetConfig.h
Unsupported
OSStatus ICCGetDefaultPref ( ComponentInstance inst, ConstStr255Param key, Handle prefH );
Use ICGetDefaultPref instead.
InternetConfig.h
Unsupported
OSStatus ICCGetIndMapEntry ( ComponentInstance inst, Handle entries, SInt32 index, SInt32 *pos, ICMapEntry *entry );
Use ICGetIndMapEntry instead.
InternetConfig.h
Unsupported
OSStatus ICCGetIndPref ( ComponentInstance inst, SInt32 index, Str255 key );
Use ICGetIndPref instead.
InternetConfig.h
Unsupported
OSStatus ICCGetIndProfile ( ComponentInstance inst, SInt32 index, ICProfileID *thisID );
Use ICGetIndProfile instead.
InternetConfig.h
Unsupported
OSStatus ICCGetMapEntry ( ComponentInstance inst, Handle entries, SInt32 pos, ICMapEntry *entry );
Use ICGetMapEntry instead.
InternetConfig.h
Unsupported
OSStatus ICCGetMappingInterruptSafe ( ComponentInstance inst, Ptr *mappingPref, SInt32 *mappingPrefSize );
ICCGetMappingInterruptSafe is not compatible with preemptive threads. If your application relies on this API, contact Apple Developer Technical Support.
InternetConfig.h
Unsupported
OSStatus ICCGetPerm ( ComponentInstance inst, ICPerm *perm );
Use ICGetPerm instead.
InternetConfig.h
Unsupported
OSStatus ICCGetPref ( ComponentInstance inst, ConstStr255Param key, ICAttr *attr, Ptr buf, SInt32 *size );
Use ICGetPref instead.
InternetConfig.h
Unsupported
OSStatus ICCGetPrefHandle ( ComponentInstance inst, ConstStr255Param key, ICAttr *attr, Handle *prefh );
Use ICFindPrefHandle instead.
InternetConfig.h
Unsupported
OSStatus ICCGetProfileName ( ComponentInstance inst, ICProfileID thisID, Str255 name );
Use ICGetProfileName instead.
InternetConfig.h
Unsupported
OSStatus ICCGetSeed ( ComponentInstance inst, SInt32 *seed );
Use ICGetSeed instead.
InternetConfig.h
Unsupported
OSStatus ICCGetSeedInterruptSafe ( ComponentInstance inst, SInt32 *seed );
ICCGetSeedInterruptSafe is not compatible with preemptive threads. If your application relies on this API, contact Apple Developer Technical Support.
InternetConfig.h
Unsupported
OSStatus ICCGetVersion ( ComponentInstance inst, SInt32 whichVersion, UInt32 *version );
Use ICGetVersion instead.
InternetConfig.h
Unsupported
OSStatus ICChooseConfig ( ICInstance inst );
Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICChooseNewConfig ( ICInstance inst );
Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICCLaunchURL ( ComponentInstance inst, ConstStr255Param hint, Ptr data, SInt32 len, SInt32 *selStart, SInt32 *selEnd );
Use ICLaunchURL instead.
InternetConfig.h
Unsupported
OSStatus ICCMapEntriesFilename ( ComponentInstance inst, Handle entries, ConstStr255Param filename, ICMapEntry *entry );
Use ICMapEntriesFilename instead.
InternetConfig.h
Unsupported
OSStatus ICCMapEntriesTypeCreator ( ComponentInstance inst, Handle entries, OSType fType, OSType fCreator, ConstStr255Param filename, ICMapEntry *entry );
Use ICMapEntriesTypeCreator instead.
InternetConfig.h
Unsupported
OSStatus ICCMapFilename ( ComponentInstance inst, ConstStr255Param filename, ICMapEntry *entry );
Use ICMapFilename instead.
InternetConfig.h
Unsupported
OSStatus ICCMapTypeCreator ( ComponentInstance inst, OSType fType, OSType fCreator, ConstStr255Param filename, ICMapEntry *entry );
Use ICMapTypeCreator instead.
InternetConfig.h
Counts the number of entries in the mappings database preference provided.
OSStatus ICCountMapEntries ( ICInstance inst, Handle entries, long *count );
A result code. See “Result Codes.”
InternetConfig.h
Returns the total number of preferences available.
OSStatus ICCountPref ( ICInstance inst, long *count );
A result code. See “Result Codes.”
InternetConfig.h
Returns the number of available profiles.
OSStatus ICCountProfiles ( ICInstance inst, long *count );
A result code. See “Result Codes.”
InternetConfig.h
Unsupported
OSStatus ICCParseURL ( ComponentInstance inst, ConstStr255Param hint, Ptr data, SInt32 len, SInt32 *selStart, SInt32 *selEnd, Handle url );
Use ICParseURL instead.
InternetConfig.h
Creates a GURL Apple event, targetted at the application with the specified creator code
OSStatus ICCreateGURLEvent ( ICInstance inst, OSType helperCreator, Handle urlH, AppleEvent *theEvent );
A result code. See “Result Codes.”
InternetConfig.h
Unsupported
OSStatus ICCRefreshCaches ( ComponentInstance inst );
This function is obsolete, because there is no supported way to modify the Internet Config database without going through the Internet Config API. There is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICCRequiresInterruptSafe ( ComponentInstance inst );
This function is not compatible with preemptive threads. There is no replacement.
InternetConfig.h
Unsupported
OSStatus ICCSendGURLEvent ( ComponentInstance inst, AppleEvent *theEvent );
Use ICSendGURLEvent instead.
InternetConfig.h
Unsupported
OSStatus ICCSetConfigReference ( ComponentInstance inst, ICConfigRefHandle ref, SInt32 flags );
Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.
InternetConfig.h
Unsupported
OSStatus ICCSetCurrentProfile ( ComponentInstance inst, ICProfileID newID );
Use ICSetCurrentProfile instead.
InternetConfig.h
Unsupported
OSStatus ICCSetMapEntry ( ComponentInstance inst, Handle entries, SInt32 pos, ICMapEntry *entry );
Use ICSetMapEntryICSetMapEntry instead.
InternetConfig.h
Unsupported
OSStatus ICCSetPref ( ComponentInstance inst, ConstStr255Param key, ICAttr attr, Ptr buf, SInt32 size );
Use ICSetPref instead.
InternetConfig.h
Unsupported
OSStatus ICCSetPrefHandle ( ComponentInstance inst, ConstStr255Param key, ICAttr attr, Handle prefh );
Use ICSetPrefHandle instead.
InternetConfig.h
Unsupported
OSStatus ICCSetProfileName ( ComponentInstance inst, ICProfileID thisID, ConstStr255Param name );
Use ICSetProfileName instead.
InternetConfig.h
Unsupported
OSStatus ICCSpecifyConfigFile ( ComponentInstance inst, FSSpec *config );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICCStart ( ComponentInstance *inst, OSType creator );
Use ICStart instead.
InternetConfig.h
Unsupported
OSStatus ICCStop ( ComponentInstance inst );
Use ICStop instead.
InternetConfig.h
Unsupported
OSStatus ICDefaultFileName ( ICInstance inst, Str63 name );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Deletes an entry in the specified Mapping preference.
OSStatus ICDeleteMapEntry ( ICInstance inst, Handle entries, long pos );
A result code. See “Result Codes.”
InternetConfig.h
Deletes the preference for the specified key.
OSStatus ICDeletePref ( ICInstance inst, ConstStr255Param key );
A result code. See “Result Codes.”
InternetConfig.h
Deletes the profile that has the specified ID.
OSStatus ICDeleteProfile ( ICInstance inst, ICProfileID thisID );
A result code. See “Result Codes.”
InternetConfig.h
Opens the Internet pane of System Preferences.
OSStatus ICEditPreferences ( ICInstance inst, ConstStr255Param key );
A result code. See “Result Codes.”
This function launches the Internet preference control appropriate to the operating system version. In Mac OS X, it opens the Internet pane of System Preferences. In Mac OS 8 and 9 wiith Carbon, it launches the Internet control panel. On earlier systems, it launches Internet Config.
InternetConfig.h
Tells Internet Config that you have finished accessing preference information.
OSStatus ICEnd ( ICInstance inst );
A result code. See “Result Codes.”
InternetConfig.h
Unsupported
OSStatus ICFindConfigFile ( ICInstance inst, SInt16 count, ICDirSpecArrayPtr folders );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Gets a preference’s data, like ICGetPref, but returns the data in a handle.
OSStatus ICFindPrefHandle ( ICInstance inst, ConstStr255Param key, ICAttr *attr, Handle prefh );
A result code. See “Result Codes.”
InternetConfig.h
Unsupported
OSStatus ICFindUserConfigFile ( ICInstance inst, ICDirSpec *where );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICGeneralFindConfigFile ( ICInstance inst, Boolean searchPrefs, Boolean canCreate, SInt16 count, ICDirSpecArrayPtr folders );
Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.
InternetConfig.h
Unsupported
OSStatus ICGetComponentInstance ( ICInstance inst,