Created by ic@stairways.com

IC Programmer's Release Notes

This document describes recent changes in the Internet Config Programmer's Kit. It is divided up by release, starting at IC 2.0.

Changes in IC 2.0

This section describes the important changes in IC 2.0 that you should be aware of.

System 7 and Component Manager Required

Internet Config now requires at least System 7.0 and Component Manager to function. This is a direct result of the following change.

No Link-In Implementation

IC 2.0 no longer supports the link-in implementation, ie any application built with the IC 2.0 SDK will require that the IC Extension be installed for it to function properly.

This decision was made because IC is now much more likely to be installed on user systems. Also, the size of the link-in implementation was becoming prohibitive. Finally, the link-in implementation was never available to CFM based clients, so the change helps to make the model a bit simpler.

As a consequence of this, the distinction between the IC* and ICC* routines has disappeared. Both variants continue to be available, so this should not cause you any troubles. If you're writing new code, you should write it to the IC* routines, because these are smaller and faster.

If the lack of a link-in implementation is a problem for your product, you should continue to develop using the IC 1.4 SDK. Products developed with the old SDK work just fine on systems running IC 2.0, but don't have access to the new APIs.

Interface Files

All of the Internet Config interfaces have been combined into a single file, "InternetConfig.[ph]". Where your program would previously uses "ICTypes.[ph]", "ICKeys.[ph]", and "ICAPI.[ph]", it can now just use "InternetConfig.[ph]".

For the sake of minimising clutter, there are no compatibility interfaces which include the new interface. If you feel the need for these, it's very easy to write you own, ie you would write "ICTypes.h", "ICAPI.h", "ICCAPI.h", and "ICKeys.h" each to have the following three lines of text:

#ifndef __INTERNETCONFIG__
#include <InternetConfig.h>
#endif
 

API Additions, Changes and Removals

IC 2.0 has added 11 new API routines, divided into two groups:

• Profile API -- IC uses the term profile to denote an independent set of preferences for use by a specific user on the same machine, or for use by the same user in different locations. The profile API allows you to get and set the current profile, get and set the name of the a profile, iterate through all the profiles, and add and remove profiles. The existing IC API routines (eg ICGetPref and ICSetPref) always modify the current profile.
• Interrupt Safe File Mapping -- The interrupt safe file mapping API allows you to register yourself as an interrupt safe instance and then make a special interrupt safe call to do file type to extension mapping. This routine was designed for low-level system software, such as File System Manager plug-ins, that want to use IC's file mapping database but require an interrupt safe API.

See the IC Programming Documentation for details.

IC 2.0 renders some routines obsolete, even though these routines continue to exist and operate successfully. Because IC 2.0 now supports multiple users through profiles, there is no need to mess around with searching directories for preferences. So the API routines ICFindUserConfigFile and ICGeneralFindConfigFile should now be considered obsolete. Similarly, passing a list of directories to ICFindConfigFile is no longer recommended, ie you should always call it in the following way:

    err := ICFindConfigFile (inst, 0, nil)

Let me reiterate that all of these operations are still fully supported, they just don't make a lot of sense under IC 2.0.

Some API features are now considered obsolete. Specifically:

• constants beginning with internetConfigurationComponent* have been renamed to begin with kICComponent*.
• the type internetConfigurationComponent (previously only defined in the C header file) is now obsolete. Clients should use the system type ComponentInstance instead.
• the type ICFileInfo was originally used to define the format of a key. That key was removed, but we forgot to remove ICFileInfo.

You can still get at the original definitions by setting the compile time variable OLDROUTINENAMES to true.

Finally, the type of the parameter to ICGetComponentInstance has changed from univ Ptr to ComponentInstance. The original rationale for the weird type was that Think Pascal did not, by default, include "Components.p", so we tried to avoid requiring any declarations from that file in "ICAPI.p". Now that I've merged all the interface files, requiring "Components.p" is unavoidable. Fortunately, Think Pascal is much less relevant these days, so this is not really a drawback.

Libraries

IC 2.0 now provides real CFM libraries for PowerPC and CFM-68K clients. Instead of linking with statically linked linked glue that makes direct component calls, you can now link CFM clients with "InternetConfigLib". This is a stub library that is linked, at runtime, with the Internet Config Extension itself.

While everyone agrees that this is a big improvement, it does pose some issues for you as a developer:

• If your product optionally uses Internet Config, you should be sure to weak link against InternetConfigLib. After you've launched, you can test whether the weak link succeeded by checking that ICStart is not kUnresolvedCFragSymbolAddress.
• Old versions of IC do not provide a shared library interface, so if you link against the InternetConfigLib stub library, you will only execute if IC 2.0 or higher is present. If this is a serious issue for you, you should either:
  • continue to use the IC 1.4 SDK, or
  • if you need the new API routines provided by IC 2.0, you can add "ICGlueCFM.c" source file to your project.

Note that the fragment name for InternetConfigLib is actually "ICAp;InternetConfigLib", which is in compliance with Apple's standard for naming third party shared libraries. Some development environments (specifically, very old versions of CodeWarrior) generate bad links when the fragment name and the file name do not match. If you have troubles running after linking against InternetConfigLib, you might try renaming the stub library to "ICAp;InternetConfigLib".

Classic 68K runtime applications should continue to link with "ICGlue.o" (for near model clients) or "ICGlueFar.o" (for far model clients). Because IC no longer support the concept of a link-in implementation, these object files are now radically smaller.

IC 2.0 and Override Components

IC allows you to write override components that intercept and modify the IC component's behaviour. Because some parts of IC are now interrupt safe, it is important that the dispatcher for override components also be interrupt safe.

If you have an override component, you should ensure that its dispatcher is interrupt safe. Specifically, your override component's globals should not be stored in an unlocked handle which you lock on entry and unlock on exit. Doing so will cause your component to call the Memory Manager at interrupt time, even if you do not override one of the interrupt safe routines.

Note that, if you're based on the 'generic override component architecture' that shipped with earlier versions of IC, you automatically inherit this misfeature.

Debug Versions

The IC Programmer's Kit now comes with debug versions of the Internet Config Extension and the various other Internet Config Goodies. These debug versions are very useful for the developers of Internet Config, and somewhat useful for developers of programs that use Internet Config.

Comments: ic@stairways.com