KerberosWrappers.html [plain text]
<!-- #bbinclude "header.template"
#PAGETITLE#="KerberosWrappersLib API"
#BASEHREF#=""
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<BASE HREF="http://web.mit.edu/macdev/KfM/KerberosFramework/KerberosWrappers/Documentation/KerberosWrappers.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>KerberosWrappersLib API</TITLE>
<STYLE TYPE="text/css">
@import url(../../../Common/Documentation/templates/site.css);
</STYLE>
</HEAD>
<BODY>
<DIV ID="menu">
<IMG SRC="../../../Common/Documentation/graphics/Kerberos.jpg" ALT="Kerberos for Macintosh Logo">
<HR>
<P><A HREF="../../../Common/Documentation/index.html">Home</A></P>
<P><A HREF="http://web.mit.edu/kerberos/">MIT Kerberos</A></P>
<P><A HREF="http://web.mit.edu/ist/">MIT IS&T</A></P>
<HR>
<P><A HREF="../../../Common/Documentation/news.html">News</A></P>
<P><A HREF="../../../Common/Documentation/documentation.html">Documentation</A></P>
<P><A HREF="../../../Common/Documentation/developer.html">Developer Resources</A></P>
<P><A HREF="../../../Common/Documentation/license.html">License</A></P>
<HR>
<P><A HREF="../../../Common/Documentation/download.html">Download</A></P>
<P><A HREF="../../../Common/Documentation/support.html">Support</A></P>
<P><A HREF="../../../Common/Documentation/contact.html">Contact Us</A></P>
</DIV>
<DIV ID="body">
<!-- end bbinclude -->
<TABLE BORDER=0 CELLSPACING=4>
<TR>
<TD><IMG SRC="../../Common/Documentation/graphics/MITKerberosLib.gif"></TD>
<TD><B><FONT SIZE="+3">KerberosWrappersLib API</FONT></B></TD>
</TR>
</TABLE>
<BLOCKQUOTE>
<p>All of the classes in WrappersLib except for UKerberos4Principal behave like the std::auto_ptr class from the Standard Template Library. That means that:</p>
<ol>
<li>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.
<li>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.
<li>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.
</ol>
<p>Because of this you should follow a few rules about the way that you use the objects:</p>
<ol>
<li>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.
<li>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.
</ol>
<p>The classes are:</p>
<ul>
<li>UCCacheContext -- represents a CCache context. Calls cc_initialize in the default constructor.
<li>UCCache -- represents a CCache
<li>UCredentials -- represents CCache credentials
<li>UCCacheString -- represents CCache strings
<li>UCredentialsIterator -- represents CCache credentials iterators
<li>UCCacheIterator -- represents CCache iterators
<li>UProfile -- represents a Kerberos Profile handle. Calls krb_get_profile in the default constructor.
<li>UProfileInputString -- represents strings passed into the Kerberos Profile API
<li>UProfileOutputString -- represents strings returned from the Kerberos Profile API
<li>UProfileInputList -- represents string lists passed into the Kerberos Profile API
<li>UProfileOutputList -- represents string lists returned from the Kerberos Profile API
<li>UProfileIterator -- represent Kerberos Profile iterators
<li>UPrincipal -- represents a generic Kerberos v4 or v5 principal
<li>UKerberos4Principal -- represents a Kerberos v4 principal (less expensive than UPrincipal)
<li>UKerberos5Context -- represents a Kerberos v5 context. Calls krb5_init_context in the default constructor.
</ul>
<p>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.</p>
<p>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. </p>
<p>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.</p>
<p>Other than a memory failure, the following conditions cause a runtime error to be thrown:</p>
<ul>
<li>Any CCache wrappers when credentials are asked for that don't exist
<li>UProfile::UProfile when krb_get_profile fails, or when the profile is invalid
<li>Any other Kerberos Profile wrappers, when the profile is valid but the needed information is missing
<li>Any UPrincipal and UKerberos4Principal functions, when an invalid principal is passed in as an argument
</ul>
</BLOCKQUOTE>
<!-- #bbinclude "footer.template" -->
</DIV>
<DIV ID="footer">
<P>
Copyright 2005 Massachusetts Institute of Technology.<BR>
Last updated on $Date: 2005-10-05 17:41:09 -0400 (Wed, 05 Oct 2005) $ <BR>
Last modified by $Author: lxs $
</P>
</DIV>
<!-- Begin MIT-use only web reporting counter -->
<IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT="">
<!-- End MIT-use only web reporting counter -->
</BODY></HTML>
<!-- end bbinclude -->