Macintosh Development

[Home] [About Us] [People] [Information Systems]
[Kerberos for Macintosh] [Applications] [Miscellaneous Documentation]

Kerberos Preferences library API 1.0

The Kerberos Preferences library provides an easy way to locate and initialize Kerberos Preferences files. It should not be directly used by applications other than administrative applications; all other applications should access Kerberos preferences via the appropriate call in the Kerberos API they are using (krb_get_profile, krb5_get_profile, or KClientGetProfileHandle), or via the Login Library API.

Locating Kerberos Preferences files

OSErr KPGetListOfPreferencesFiles (
    UInt32 inUserSystemFlags,
    FSSpecPtr* thePrefFiles);
    UInt32*    outNumberOfPrefsFiles

The KPGetListOfPreferencesFiles() function returns a list of file system specifiers for the preferences files. The number of preferences files in the list is returned in outNumberOfPrefsFiles.

Each specifier in the list describes a possible location for the preferences files, even if no files exist at some of those locations. For example, if there is no Kerberos Preferences file in the Preferences folder, a file specifier for it will be returned nonetheless.

If the inUserSystemFlags argument is kpUserPreferences, only user preferences files' specifiers are returned; on Mac OS 8 and 9, these files reside in the user's Preferences folder. If the inUserSystemFlags argument is kpSystemPreferences, only system preferences files' specifiers are returned; on Mac OS 8 and 9, these files reside in the Application Support folder. If the inUserSystemFlags argument is kpUserPreferences | kpSystemPreferences, both user and system preferences files' specifiers are returned.

The files are already returned in overridding order; i.e. the first file in the list should be read or written before any other ones.

KPGetListOfPreferencesFiles() may create some of the folders that might contain a preferences files, but exactly which ones are created varies. Do not depend on a particular behavior, and use KPCreatePreferencesFile() to correctly create a preferences file.

The list returned by KPGetListOfPreferencesFiles() should be freed with KPFreeListOfPreferencesFiles().

KPGetListOfPreferencesFiles returns noErr if it succeeds, memFullErr if it can't allocate the file list, fnfErr if it can't locate the preferences files' parent folders, and dupFNErr if the preferences files' folders can't be created because there are already files in their locations.

Inspecting Kerberos Preferences files

OSErr KPPreferencesFileIsReadable (
    const FSSpec* inPrefsFile);
OSErr KPPreferencesFileIsWritable (
    const FSSpec* inPrefsFile);

KPPreferencesFileIsReadable() and KPPreferencesFileIsWritable() return noErr if the preferences file passed in is readable or writable. A readable file exists and its data and resource forks can be opened for reading. A writable file either exists and is not locked nor in a locked folder or on a locked volume, or it does not exist, and the folder in which it would be created is not locked and not on a locked volume.

If the preferences file is not readable or writable, the functions return an appropriate File or Resource manager error, such as fnfErr, dupFnErr, nsvErr, fLckdErr, vLckdErr, opWrErr, afpLockErr, afpAccessDenied, afpVolLocked, afpObjectLocked, and others.

Creating Kerberos Preferences files

OSErr KPCreatePreferencesFile (
    const FSSpec* inPrefsFile);

KPCreatePreferencesFile() creates a preferences file in the given location, with the correct type and creator. It returns noErr on success, or a File, Memory, or Resource manager error on failure. Some of the possible errors are fnfErr, dupFnErr, nsvErr, fLckdErr, vLckdErr, opWrErr, afpLockErr, afpAccessDenied, afpVolLocked, afpObjectLocked.

The data and resource forks of the newly created file exist but are empty.

Initialiazing Kerberos library preferences files

OSErr KPInitializeWithDefaultKerberosLibraryPreferences (
    const FSSpec* prefLocation);

Given the specifier of a preferences file, KPInitializeWithDefaultKerberosLibraryPreferences initializes it with default Kerberos library preferences. On success, noErr is returned. On failure, an appropriate File, Resource, or Memory Manager error is returned.

This function should only be used by Kerberos libraries. Applications should never use this function; a preferences file will be created by the Kerberos library as necessary.

Using Kerberos Preferences library

Initializing a profile handle

To initialize a profile handle with the file list returned from KPGetListOfFiles(), copy the list into an array of FSSpecs, terminating the array as required by the profile library, and pass it to profile_init().

Locating a preferences file to read

To locate a preferences file to read, get the list of user and system preferences files from KPGetListOfFiles() and use the first one for which KPPreferencesFileIsReadable() returns noErr.

Locating a preferences file to write

To locate a preferences file to write, get the list of user preferences files from KPGetListOfFiles(). Then, for every file in the list, do the following:

with (f in listOfFiles) {
    if (f is writable) {
        if (f is not readable) {
            create f
        }
        write preferences to f and return
    } else if (f is readable and f already contains preferences belonging to your program) {
        can't write: return and alert the user;
    }
}

can't write: return and alert the user

The reason why you must abort when you encounter a readable and non-writable file that already contains your preferences is that if you write to any file that follows it in the list, you will never reach those preferences when reading them (they would always be overridden by the readable and non-writable file).

Questions or comments? Send mail to macdev@mit.edu
Last updated on $Date: 2003/11/19 20:42:22 $
Last modified by $Author: smcguire $