MIT Information Systems

Macintosh Development

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

KerberosWrappersLib API

All of the classes in WrappersLib except for UKerberos4Principal behave like the std::auto_ptr class from the Standard Template Library. That means that:

  1. Class instances own the pointer they represent, and destroy it appropriately when they are destroyed. For example, if you have a UCCache object, the cc_ccache_t which that object owns will be released when the object is destroyed.
  2. Assignment between class instances signifies transfer of ownership. If you have two UCCache objects, and assign one to the other, then the one that is assigned to releases its existing cc_ccache_t, and takes the ownership of the cc_ccache_t of the UCCache assigned to it. The assigned UCCache loses ownership of the cc_ccache_t and no longer represents it after the asignment.
  3. There is no transparent way to convert class objects to their corresponding raw pointers; you need to call the Get() member function to accomplish that. The reasons for this have to do with potential problems with ownership transfer. However, you in general won't need to do this, as the objects have many member functions implemented, and therefore you won't need to convert them to raw pointers most of the time.

Because of this you should follow a few rules about the way that you use the objects:

  1. Don't pass them around, unless you intend to relinquish the ownership. Almost the only case when you want to do that is when a function returns a new object of a wrapper class. Otherwise, if you need to pass them around, pass them around as references. This will keep the ownership in the original object, and references will have access to it without stealing the ownership.
  2. Use the Get() function as little as possible. Calling Get() puts you in a position where you can release the pointer without the object knowing about it, which will cause it to try to release it again when it's destroyed. Call the Release() member function if you want to take over the raw pointer. The object will no longer do anything with it after the call.

The classes are:

The classes UCCacheContext, UProfile, and UKerberos5Context initialize themselves by creating a new context/handle when they are constructed with no arguments; other classes initialize themselves to invalid pointers when they are created with no arguments.

All classes throw exceptions when they encounter errors. The exceptions are descended from std::exception, and therefore catching std::exception& will catch all exceptions thrown by wrapper classes.

When a wrapper class fails because of a memory error, std::bad_alloc is thrown. When a wrapper class fails because of a logic error, a subclass of std::logic_error is thrown. When a wrapper class fails because of a runtime error, a subclass of std::runtime_error is thrown. You should be able to handle all runtime errors by catching std::bad_alloc& and std::runtime_error&; if you catch a std::logic_error&, you probably have a bug that's causing the Wrappers library to fail.

Other than a memory failure, the following conditions cause a runtime error to be thrown:

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