Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Internet Config Reference

Framework
Carbon/Carbon.h
Declared in
InternetConfig.h

Overview

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.

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

Functions by Task

Starting and Stopping Internet 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.

Getting Information About an Instance

Preparing to Read and Write Preferences

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.

Reading and Writing Preferences

Enumerating All Preferences

You must call ICBegin before calling any of these routines.

Accessing the User Interface

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.

URL Functions

Mapping-Database High-Level Functions

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.

Mapping-Database Mid-Level Functions

These functions are useful if you are doing multiple searches because they avoid the overhead of accessing the mappings database each time.

Mapping-Database Low-Level Functions

Internet Config’s low-level functions give you access to the primitive operations used to implement the other mapping functions.

Profile Functions

Deprecated functions

Unsupported Functions

Functions

ICAddMapEntry

Adds an entry to the mappings database.

OSStatus ICAddMapEntry (
   ICInstance inst,
   Handle entries,
   const ICMapEntry *entry
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICAddProfile

Creates a new profile and returns its ID.

OSStatus ICAddProfile (
   ICInstance inst,
   ICProfileID prototypeID,
   ICProfileID *newID
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICBegin

Prepares Internet Config to read (and, optionally, to write) preferences.

OSStatus ICBegin (
   ICInstance inst,
   ICPerm perm
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICCAddMapEntry

Unsupported

OSStatus ICCAddMapEntry (
   ComponentInstance inst,
   Handle entries,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICAddMapEntry instead.

Declared In
InternetConfig.h

ICCAddProfile

Unsupported

OSStatus ICCAddProfile (
   ComponentInstance inst,
   ICProfileID prototypeID,
   ICProfileID *newID
);

Carbon Porting Notes

Use ICAddProfile instead.

Declared In
InternetConfig.h

ICCBegin

Unsupported

OSStatus ICCBegin (
   ComponentInstance inst,
   ICPerm perm
);

Carbon Porting Notes

Use ICBegin instead.

Declared In
InternetConfig.h

ICCChooseConfig

Unsupported

OSStatus ICCChooseConfig (
   ComponentInstance inst
);

Carbon Porting Notes

Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.

Declared In
InternetConfig.h

ICCChooseNewConfig

Unsupported

OSStatus ICCChooseNewConfig (
   ComponentInstance inst
);

Carbon Porting Notes

Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.

Declared In
InternetConfig.h

ICCCountMapEntries

Unsupported

OSStatus ICCCountMapEntries (
   ComponentInstance inst,
   Handle entries,
   SInt32 *count
);

Carbon Porting Notes

Use ICCountMapEntries instead.

Declared In
InternetConfig.h

ICCCountPref

Unsupported

OSStatus ICCCountPref (
   ComponentInstance inst,
   SInt32 *count
);

Carbon Porting Notes

Use ICCountPref instead.

Declared In
InternetConfig.h

ICCCountProfiles

Unsupported

OSStatus ICCCountProfiles (
   ComponentInstance inst,
   SInt32 *count
);

Carbon Porting Notes

Use ICCountProfiles instead.

Declared In
InternetConfig.h

ICCCreateGURLEvent

Unsupported

OSStatus ICCCreateGURLEvent (
   ComponentInstance inst,
   OSType helperCreator,
   Handle urlH,
   AppleEvent *theEvent
);

Carbon Porting Notes

Use ICCreateGURLEvent instead.

Declared In
InternetConfig.h

ICCDefaultFileName

Unsupported

OSStatus ICCDefaultFileName (
   ComponentInstance inst,
   Str63 name
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICCDeleteMapEntry

Unsupported

OSStatus ICCDeleteMapEntry (
   ComponentInstance inst,
   Handle entries,
   SInt32 pos
);

Carbon Porting Notes

Use ICDeleteMapEntry instead.

Declared In
InternetConfig.h

ICCDeletePref

Unsupported

OSStatus ICCDeletePref (
   ComponentInstance inst,
   ConstStr255Param key
);

Carbon Porting Notes

Use ICDeletePref instead.

Declared In
InternetConfig.h

ICCDeleteProfile

Unsupported

OSStatus ICCDeleteProfile (
   ComponentInstance inst,
   ICProfileID thisID
);

Carbon Porting Notes

Use ICDeleteProfile instead.

Declared In
InternetConfig.h

ICCEditPreferences

Unsupported

OSStatus ICCEditPreferences (
   ComponentInstance inst,
   ConstStr255Param key
);

Carbon Porting Notes

Use ICEditPreferences instead.

Declared In
InternetConfig.h

ICCEnd

Unsupported

OSStatus ICCEnd (
   ComponentInstance inst
);

Carbon Porting Notes

Use ICEnd instead.

Declared In
InternetConfig.h

ICCFindConfigFile

Unsupported

OSStatus ICCFindConfigFile (
   ComponentInstance inst,
   SInt16 count,
   ICDirSpecArrayPtr folders
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICCFindPrefHandle

Unsupported

OSStatus ICCFindPrefHandle (
   ComponentInstance inst,
   ConstStr255Param key,
   ICAttr *attr,
   Handle prefh
);

Carbon Porting Notes

Use ICFindPrefHandle instead.

Declared In
InternetConfig.h

ICCFindUserConfigFile

Unsupported

OSStatus ICCFindUserConfigFile (
   ComponentInstance inst,
   ICDirSpec *where
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICCGeneralFindConfigFile

Unsupported

OSStatus ICCGeneralFindConfigFile (
   ComponentInstance inst,
   Boolean searchPrefs,
   Boolean canCreate,
   SInt16 count,
   ICDirSpecArrayPtr folders
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICCGetComponentInstance

Unsupported

OSStatus ICCGetComponentInstance (
   ComponentInstance inst,
   ComponentInstance *componentInst
);

Carbon Porting Notes

Because Internet Config is not component-based under Mac OS X, use ICGetVersion instead.

Declared In
InternetConfig.h

ICCGetConfigName

Unsupported

OSStatus ICCGetConfigName (
   ComponentInstance inst,
   Boolean longname,
   Str255 name
);

Carbon Porting Notes

Use ICGetConfigName instead.

Declared In
InternetConfig.h

ICCGetConfigReference

Unsupported

OSStatus ICCGetConfigReference (
   ComponentInstance inst,
   ICConfigRefHandle ref
);

Carbon Porting Notes

Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.

Declared In
InternetConfig.h

ICCGetCurrentProfile

Unsupported

OSStatus ICCGetCurrentProfile (
   ComponentInstance inst,
   ICProfileID *currentID
);

Carbon Porting Notes

Use ICGetCurrentProfile instead.

Declared In
InternetConfig.h

ICCGetDefaultPref

Unsupported

OSStatus ICCGetDefaultPref (
   ComponentInstance inst,
   ConstStr255Param key,
   Handle prefH
);

Carbon Porting Notes

Use ICGetDefaultPref instead.

Declared In
InternetConfig.h

ICCGetIndMapEntry

Unsupported

OSStatus ICCGetIndMapEntry (
   ComponentInstance inst,
   Handle entries,
   SInt32 index,
   SInt32 *pos,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICGetIndMapEntry instead.

Declared In
InternetConfig.h

ICCGetIndPref

Unsupported

OSStatus ICCGetIndPref (
   ComponentInstance inst,
   SInt32 index,
   Str255 key
);

Carbon Porting Notes

Use ICGetIndPref instead.

Declared In
InternetConfig.h

ICCGetIndProfile

Unsupported

OSStatus ICCGetIndProfile (
   ComponentInstance inst,
   SInt32 index,
   ICProfileID *thisID
);

Carbon Porting Notes

Use ICGetIndProfile instead.

Declared In
InternetConfig.h

ICCGetMapEntry

Unsupported

OSStatus ICCGetMapEntry (
   ComponentInstance inst,
   Handle entries,
   SInt32 pos,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICGetMapEntry instead.

Declared In
InternetConfig.h

ICCGetMappingInterruptSafe

Unsupported

OSStatus ICCGetMappingInterruptSafe (
   ComponentInstance inst,
   Ptr *mappingPref,
   SInt32 *mappingPrefSize
);

Carbon Porting Notes

ICCGetMappingInterruptSafe is not compatible with preemptive threads. If your application relies on this API, contact Apple Developer Technical Support.

Declared In
InternetConfig.h

ICCGetPerm

Unsupported

OSStatus ICCGetPerm (
   ComponentInstance inst,
   ICPerm *perm
);

Carbon Porting Notes

Use ICGetPerm instead.

Declared In
InternetConfig.h

ICCGetPref

Unsupported

OSStatus ICCGetPref (
   ComponentInstance inst,
   ConstStr255Param key,
   ICAttr *attr,
   Ptr buf,
   SInt32 *size
);

Carbon Porting Notes

Use ICGetPref instead.

Declared In
InternetConfig.h

ICCGetPrefHandle

Unsupported

OSStatus ICCGetPrefHandle (
   ComponentInstance inst,
   ConstStr255Param key,
   ICAttr *attr,
   Handle *prefh
);

Carbon Porting Notes

Use ICFindPrefHandle instead.

Declared In
InternetConfig.h

ICCGetProfileName

Unsupported

OSStatus ICCGetProfileName (
   ComponentInstance inst,
   ICProfileID thisID,
   Str255 name
);

Carbon Porting Notes

Use ICGetProfileName instead.

Declared In
InternetConfig.h

ICCGetSeed

Unsupported

OSStatus ICCGetSeed (
   ComponentInstance inst,
   SInt32 *seed
);

Carbon Porting Notes

Use ICGetSeed instead.

Declared In
InternetConfig.h

ICCGetSeedInterruptSafe

Unsupported

OSStatus ICCGetSeedInterruptSafe (
   ComponentInstance inst,
   SInt32 *seed
);

Carbon Porting Notes

ICCGetSeedInterruptSafe is not compatible with preemptive threads. If your application relies on this API, contact Apple Developer Technical Support.

Declared In
InternetConfig.h

ICCGetVersion

Unsupported

OSStatus ICCGetVersion (
   ComponentInstance inst,
   SInt32 whichVersion,
   UInt32 *version
);

Carbon Porting Notes

Use ICGetVersion instead.

Declared In
InternetConfig.h

ICChooseConfig

Unsupported

OSStatus ICChooseConfig (
   ICInstance inst
);

Carbon Porting Notes

Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.

Declared In
InternetConfig.h

ICChooseNewConfig

Unsupported

OSStatus ICChooseNewConfig (
   ICInstance inst
);

Carbon Porting Notes

Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.

Declared In
InternetConfig.h

ICCLaunchURL

Unsupported

OSStatus ICCLaunchURL (
   ComponentInstance inst,
   ConstStr255Param hint,
   Ptr data,
   SInt32 len,
   SInt32 *selStart,
   SInt32 *selEnd
);

Carbon Porting Notes

Use ICLaunchURL instead.

Declared In
InternetConfig.h

ICCMapEntriesFilename

Unsupported

OSStatus ICCMapEntriesFilename (
   ComponentInstance inst,
   Handle entries,
   ConstStr255Param filename,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICMapEntriesFilename instead.

Declared In
InternetConfig.h

ICCMapEntriesTypeCreator

Unsupported

OSStatus ICCMapEntriesTypeCreator (
   ComponentInstance inst,
   Handle entries,
   OSType fType,
   OSType fCreator,
   ConstStr255Param filename,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICMapEntriesTypeCreator instead.

Declared In
InternetConfig.h

ICCMapFilename

Unsupported

OSStatus ICCMapFilename (
   ComponentInstance inst,
   ConstStr255Param filename,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICMapFilename instead.

Declared In
InternetConfig.h

ICCMapTypeCreator

Unsupported

OSStatus ICCMapTypeCreator (
   ComponentInstance inst,
   OSType fType,
   OSType fCreator,
   ConstStr255Param filename,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICMapTypeCreator instead.

Declared In
InternetConfig.h

ICCountMapEntries

Counts the number of entries in the mappings database preference provided.

OSStatus ICCountMapEntries (
   ICInstance inst,
   Handle entries,
   long *count
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICCountPref

Returns the total number of preferences available.

OSStatus ICCountPref (
   ICInstance inst,
   long *count
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICCountProfiles

Returns the number of available profiles.

OSStatus ICCountProfiles (
   ICInstance inst,
   long *count
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICCParseURL

Unsupported

OSStatus ICCParseURL (
   ComponentInstance inst,
   ConstStr255Param hint,
   Ptr data,
   SInt32 len,
   SInt32 *selStart,
   SInt32 *selEnd,
   Handle url
);

Carbon Porting Notes

Use ICParseURL instead.

Declared In
InternetConfig.h

ICCreateGURLEvent

Creates a GURL Apple event, targetted at the application with the specified creator code

OSStatus ICCreateGURLEvent (
   ICInstance inst,
   OSType helperCreator,
   Handle urlH,
   AppleEvent *theEvent
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICCRefreshCaches

Unsupported

OSStatus ICCRefreshCaches (
   ComponentInstance inst
);

Carbon Porting Notes

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.

Declared In
InternetConfig.h

ICCRequiresInterruptSafe

Unsupported

OSStatus ICCRequiresInterruptSafe (
   ComponentInstance inst
);

Carbon Porting Notes

This function is not compatible with preemptive threads. There is no replacement.

Declared In
InternetConfig.h

ICCSendGURLEvent

Unsupported

OSStatus ICCSendGURLEvent (
   ComponentInstance inst,
   AppleEvent *theEvent
);

Carbon Porting Notes

Use ICSendGURLEvent instead.

Declared In
InternetConfig.h

ICCSetConfigReference

Unsupported

OSStatus ICCSetConfigReference (
   ComponentInstance inst,
   ICConfigRefHandle ref,
   SInt32 flags
);

Carbon Porting Notes

Because Internet Config no longer supports multiple configuration files, this function is obsolete, and there is no replacement function.

Declared In
InternetConfig.h

ICCSetCurrentProfile

Unsupported

OSStatus ICCSetCurrentProfile (
   ComponentInstance inst,
   ICProfileID newID
);

Carbon Porting Notes

Use ICSetCurrentProfile instead.

Declared In
InternetConfig.h

ICCSetMapEntry

Unsupported

OSStatus ICCSetMapEntry (
   ComponentInstance inst,
   Handle entries,
   SInt32 pos,
   ICMapEntry *entry
);

Carbon Porting Notes

Use ICSetMapEntryICSetMapEntry instead.

Declared In
InternetConfig.h

ICCSetPref

Unsupported

OSStatus ICCSetPref (
   ComponentInstance inst,
   ConstStr255Param key,
   ICAttr attr,
   Ptr buf,
   SInt32 size
);

Carbon Porting Notes

Use ICSetPref instead.

Declared In
InternetConfig.h

ICCSetPrefHandle

Unsupported

OSStatus ICCSetPrefHandle (
   ComponentInstance inst,
   ConstStr255Param key,
   ICAttr attr,
   Handle prefh
);

Carbon Porting Notes

Use ICSetPrefHandle instead.

Declared In
InternetConfig.h

ICCSetProfileName

Unsupported

OSStatus ICCSetProfileName (
   ComponentInstance inst,
   ICProfileID thisID,
   ConstStr255Param name
);

Carbon Porting Notes

Use ICSetProfileName instead.

Declared In
InternetConfig.h

ICCSpecifyConfigFile

Unsupported

OSStatus ICCSpecifyConfigFile (
   ComponentInstance inst,
   FSSpec *config
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICCStart

Unsupported

OSStatus ICCStart (
   ComponentInstance *inst,
   OSType creator
);

Carbon Porting Notes

Use ICStart instead.

Declared In
InternetConfig.h

ICCStop

Unsupported

OSStatus ICCStop (
   ComponentInstance inst
);

Carbon Porting Notes

Use ICStop instead.

Declared In
InternetConfig.h

ICDefaultFileName

Unsupported

OSStatus ICDefaultFileName (
   ICInstance inst,
   Str63 name
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICDeleteMapEntry

Deletes an entry in the specified Mapping preference.

OSStatus ICDeleteMapEntry (
   ICInstance inst,
   Handle entries,
   long pos
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICDeletePref

Deletes the preference for the specified key.

OSStatus ICDeletePref (
   ICInstance inst,
   ConstStr255Param key
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICDeleteProfile

Deletes the profile that has the specified ID.

OSStatus ICDeleteProfile (
   ICInstance inst,
   ICProfileID thisID
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICEditPreferences

Opens the Internet pane of System Preferences.

OSStatus ICEditPreferences (
   ICInstance inst,
   ConstStr255Param key
);

Return Value

A result code. See “Result Codes.”

Discussion

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.

Availability
Declared In
InternetConfig.h

ICEnd

Tells Internet Config that you have finished accessing preference information.

OSStatus ICEnd (
   ICInstance inst
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICFindConfigFile

Unsupported

OSStatus ICFindConfigFile (
   ICInstance inst,
   SInt16 count,
   ICDirSpecArrayPtr folders
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICFindPrefHandle

Gets a preference’s data, like ICGetPref, but returns the data in a handle.

OSStatus ICFindPrefHandle (
   ICInstance inst,
   ConstStr255Param key,
   ICAttr *attr,
   Handle prefh
);

Return Value

A result code. See “Result Codes.”

Availability
Declared In
InternetConfig.h

ICFindUserConfigFile

Unsupported

OSStatus ICFindUserConfigFile (
   ICInstance inst,
   ICDirSpec *where
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICGeneralFindConfigFile

Unsupported

OSStatus ICGeneralFindConfigFile (
   ICInstance inst,
   Boolean searchPrefs,
   Boolean canCreate,
   SInt16 count,
   ICDirSpecArrayPtr folders
);

Carbon Porting Notes

Functions related to finding different IC database files are obsolete. You can simply remove these calls from your code—there are no replacement functions.

Declared In
InternetConfig.h

ICGetComponentInstance

Unsupported

OSStatus ICGetComponentInstance (
   ICInstance inst,