Macintosh Development

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

ErrorLib API Functions

OSStatus	GetMITLibError (	void );
void	SetMITLibError (	OSStatus theError );
void	ClearMITLibError (	void );

GetMITLibError() gets the current Kerberos Support Library error code. Clients should call this after calling MIT Support Library functions to check what error occurred. Some Kerberos Support Library functions do not set the error unless they report failure (for instance, you only need to call GetMITLibError() if socket() returns -1.

SetMITLibError() sets the current Kerberos Support Library error code. Only libraries needing to return errors back to client applications should call this function.

ClearMITLibError() sets the current Kerberos Support Library error code back to noErr. Libraries using ErrorLib to return errors to callers should call this at the beginning of every API function.

OSStatus	RegisterErrorTable (	const FSSpec* inResFile, SInt16 inResID );
OSStatus	RegisterErrorTableForBundle (	CFStringRef inBundleID, SInt16 inResID );

RegisterErrorTable() (Mac OS 8 and 9) and RegisterErrorTableForBundle() (Mac OS X) add new error to description string mappings to ErrorLib's error tables. When calling RegisterErrorTable(), inResFile is the resource file to get the error tables from. When calling RegisterErrorTableForBundle(), inBundleID is the bundle identifier for the framework whose resource fork contains the error tables (usually the caller's bundle identifier). inResID is the resource ID of the error table resource.

Error tables are of resource type 'ErrT'. The resource template is defined in ErrorList.r. The short string is the name of the error (eg: ENOMEM) and the long string is a description of the error (eg: "Out of memory").

The ErrorLib implementations of RegisterErrorTable() and RegisterErrorTableForBundle() only save inResFile and inResID or inBundleID. The error tables will not actually get loaded until one of the error string functions described below is called. This is because if ErrorLib loaded all the Str255 error strings all the time, Kerberos Support Library would have a massive memory footprint and could not be called by code resources or applications short on memory. However, ErrorLib does keep the error strings for Resource Manager and Memory Manager errors loaded so that if the error table loading code fails it can generate an appropriate "Out of memory" error.

OSStatus	GetErrorString (	OSStatus error, char *message, long messageLength, ErrorFormat format );
OSStatus	GetErrorLongFormat (	OSStatus error, char *message, long messageLength );
OSStatus	GetErrorShortFormat (	OSStatus error, char *message, long messageLength );
OSStatus	GetErrorManager (	OSStatus error, char *message, long messageLength );
OSStatus	GetErrorLongString (	OSStatus error, char *message, long messageLength );
OSStatus	GetErrorShortString (	OSStatus error, char *message, long messageLength );

GetErrorString() loads the error string for the error specified by error and places the string in message. messageLength is the size of the buffer allocated for message (GetErrorString() will not overrun the buffer). format is the format type you want the error string to be in. Possible values for format are:

kErrorLongFormat:	Returns a string of the form "[Manager Name] returned [Short String] ([Error Code]: [Long string]." (eg: "Open Transport returned kOTNoDataErr (-3162): No data available for reading.")
kErrorShortFormat:	Returns a string of the form "[Manager Name]: [Short String] ([Error Code])" (eg: "Open Transport: kOTNoDataErr (-3162)")
kErrorManager:	Returns the Manager Name
kErrorLongString:	Returns the Short String for the error.
kErrorShortString:	Returns the Long String for the error.

GetErrorLongFormat() is equivalent to GetErrorString() called with kErrorLongFormat as the format.

GetErrorShortFormat() is equivalent to GetErrorString() called with kErrorShortFormat as the format.

GetErrorManager() is equivalent to GetErrorString() called with kErrorManager as the format.

GetErrorLongString() is equivalent to GetErrorString() called with kErrorLongString as the format.

GetErrorShortString() is equivalent to GetErrorString() called with kErrorShortString as the format.

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