Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
The ODUtils utility is a grab-bag of functions and macros, most of which will simplify your life when working with reference counted objects.
ODDeleteObject deletes an object (which doesn't need to be a SOM object, just anything that was allocated with the C++ “new” operator) and sets the variable pointing to it to NULL. If the pointer was already NULL, nothing happens. For example:
ODFrameFacetIterator *iter;
....
ODDeleteObject(ev,iter);
After ODDeleteObject, the object iter was pointing to, if any, will be deleted and the variable 'iter' will have the value kODNULL.
ODReleaseObject is similar, but releases the object instead of deleting it. Use this one for ref-counted objects.
ODFinalReleaseObject is similar to ODReleaseObject, except that it is meant to be used in code which is releasing the last reference to that object. I.E. it does an ASSERT(refcount == 1) before calling release. This makes no difference in a non-debug build of your part, but in a debug build it can alert you to situations where there is a ref-count leak.
ODSafeReleaseObject releases an object, but requires no Environment parameter and can't throw an exception. It's for use in somUninit methods, where no Environment is available. NOTE that, unlike ODReleaseObject, it does not change the pointer passed in to point to NULL!
ODAcquireObject bumps the ref-count of an object, unless it's NULL.
ODTransferReference lowers one object's ref-count while incrementing another's. It's useful in things like setters where you want to forget about one object and remember another. It does the right thing if either pointer is NULL or if they point to the same object.
ODCopyAndRelease returns a copy of an object while releasing the original object. This is useful when you need your own modifiable copy of a non-modifiable ref-counted object like a frameshape. It's optimized for the case where the ref-count of the object is 1, in which case it just returns the original object since no copying is needed. (This function works only on ODShapes and ODTransforms, which are the only classes that provide a Copy method.)
ODObjectsAreEqual returns kODTrue if two pointers point to the same object. In OpenDoc 1.0 this is the same thing as comparing the pointers; however, in the future when we use DSOM and objects may reside in different address spaces, it will be possible to have two different pointers to the same object! For future compatibility, use this function. (The definition of the function is hacked so that in the implementation of OpenDoc itself we use the faster pointer comparison. In OpenDoc parts, it will always call the utility since parts don't know which version of OpenDoc they're running with.)
ODAcquirePart, ODGetDraft and ODGetSession are convenience accessors. There's nothing magic about them, but they do save code size since they encapsulate several SOM calls. They also simplify the appearance of code.
