home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODFDev / ODF / Found / ODUtils / ODUtils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-17  |  6.2 KB  |  187 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        ODUtils.h
  3.  
  4.     Contains:    Object utility functions
  5.  
  6.     Owned by:    Jens Alfke
  7.  
  8.     Copyright:    © 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <2>     5/24/96    jpa        1292388: Added special-case ODGetDraft &
  13.                                     ODGetSession for nonpersistent frames.
  14.                                     1.1MRD: Added pragma internal.
  15.  
  16.     Theory Of Operation:
  17.     
  18.         These are useful utilities for use with objects, particularly ref-
  19.         counted objects. Some are functions rather than macros, to reduce
  20.         code size, and can be made inline later if necessary.
  21.         
  22.         ODDeleteObject deletes an object (which doesn't need to
  23.             be a SOM object) and sets the variable pointing to it to NULL.
  24.             If the pointer was already NULL, nothing happens.
  25.             
  26.         ODReleaseObject is similar, but releases the object instead of deleting
  27.             it. Use this one for ref-counted objects.
  28.         
  29.         ODFinalReleaseObject is similar to ODReleaseObject, except that it is 
  30.             meant to be used in code which is releasing the last reference
  31.             to that object.  I.E. it does an ASSERT(refcount == 1) before calling release.
  32.         
  33.         ODRelease just releases an object (if it's not NULL.) Unlike ODReleaseObject
  34.             it does not set your pointer to the object to NULL. There are a few
  35.             occasions where you'll want to use this instead, but not many.
  36.         
  37.         ODFinalRelease is analogous to ODRelease; it is like ODFInalReleaseObject
  38.             but does not reset your pointer to NULL.
  39.             
  40.         ODAcquireObject bumps the ref-count of an object, unless it's NULL.
  41.         
  42.         ODSafeReleaseObject also releases an object, but requires no Environment
  43.             parameter and can't throw an exception. It's for use _only_ in
  44.             somUninit methods, where no Environment is available.
  45.         
  46.         ODTransferReference lowers one object's refCount while incrementing
  47.             another's. It's useful in things like setters where you want to
  48.             forget about one object and remember another. It does the right
  49.             thing if either pointer is NULL or if they point to the same object.
  50.             ** This function may throw an exception in the unlikely case that
  51.                 the Acquire or Release call fails.
  52.         
  53.         ODCopyAndRelease returns a copy of an object while releasing the object.
  54.             This is useful when transferring control of an object to the caller,
  55.             but the caller has permission to modify the object. It's optimized
  56.             for the case where the ref-count of the object is 1, in which case
  57.             it just returns the original object since no copying is needed.
  58.             (This function works only on ODShapes and ODTransforms, which are the
  59.             only classes that provide a Copy method.)
  60.             ** This function may throw an exception in the unlikely case that
  61.                 the GetRefCount or Release call fails.
  62.         
  63.         ODObjectsAreEqual returns kODTrue if two pointers point to the same object.
  64.             In OpenDoc 1.0 this is the same thing as comparing the pointers;
  65.             however, in the future when we use DSOM and objects may reside in
  66.             different address spaces, it will be possible to have two different
  67.             pointers to the same object! For future compatibility, use this function.
  68.         
  69.         ODAcquirePart, ODGetDraft and ODGetSession are convenience accessors.
  70.             There's nothing magic about them, but they do save code size since they
  71.             encapsulate several SOM calls. They also simplify the appearance of code.
  72.     
  73.     
  74.         The "do...while(0)" blocks wrapped around the macros are there to prevent
  75.         syntactic problems if a macro call is immediately followed by an "else"
  76.         statement, to keep the "else" from binding to the "if" in the macro body.
  77.         The "while" loop is optimized out by the compiler and has no effect on the
  78.         flow of control or code quality.
  79.  
  80.     To Do:
  81.     In Progress:
  82.         
  83. */
  84.  
  85. #ifndef _ODUTILS_
  86. #define _ODUTILS_
  87.  
  88. #ifndef _ODTYPES_
  89. #include "ODTypes.h"
  90. #endif
  91.  
  92. #ifdef __cplusplus
  93.     struct Environment;
  94.     class ODObject;
  95.     class ODShape;
  96.     class ODTransform;
  97.     class ODRefCntObject;
  98.     class ODPart;
  99.     class ODPersistentObject;
  100.     class ODStorageUnit;
  101.     class ODDraft;
  102.     class ODSession;
  103.     class ODWindow;
  104.     class ODDocument;
  105.     extern "C" {
  106. #else
  107.     #ifndef SOM_ODStorageUnit_h
  108.     #include <StorageU.h>
  109.     #endif
  110.     #ifndef SOM_ODTransform_h
  111.     #include <Shape.h>
  112.     #endif
  113.     #ifndef SOM_ODTransform_h
  114.     #include <Trnsform.h>
  115.     #endif
  116. #endif
  117.  
  118. #ifdef PRAGMA_INTERNAL_SUPPORTED
  119. #pragma internal on
  120. #endif
  121.  
  122. void ODRelease( Environment*, ODRefCntObject* );    // Just releases, does not set ptr to NULL
  123.  
  124. void ODFinalRelease(Environment*, ODRefCntObject* );
  125.  
  126. #define ODReleaseObject(EV,OBJ)                     \
  127.             do{ ODRefCntObject *temp = (OBJ);        \
  128.                 (OBJ) = kODNULL;                    \
  129.                 ODRelease((EV),temp); } while(0)
  130.  
  131. #define ODFinalReleaseObject(EV,OBJ)                 \
  132.             do{ ODRefCntObject *temp = (OBJ);        \
  133.                 (OBJ) = kODNULL;                    \
  134.                 ODFinalRelease((EV),temp); } while(0)
  135.  
  136. #define ODDeleteObject(OBJ) \
  137.             if( !(OBJ) ) ; else { delete (OBJ); (OBJ)=kODNULL; }
  138.             
  139. void ODSafeReleaseObject( ODRefCntObject* );    // Needs no ev, throws no exceptions
  140.  
  141. void ODTransferReference( Environment*, ODRefCntObject *oldObj,
  142.                                                ODRefCntObject *newObj );
  143.  
  144. void ODAcquireObject(Environment* ev, ODRefCntObject* object);
  145.  
  146.  
  147. #if ODDebug || !defined(_OD_IMPL_)
  148.     ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b);
  149. #elif defined(__cplusplus)
  150.     // Optimization for OD implementation since DSOM is not in the picture yet:
  151.     inline ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b)
  152.                         {return a==b;}
  153. #else
  154.     #define ODObjectsAreEqual(a,b)    ((a)==(b))
  155. #endif
  156.  
  157.  
  158. #ifdef __cplusplus
  159. }
  160.  
  161. // Overloaded functions can only be used in C++:
  162.  
  163. ODShape*     ODCopyAndRelease( Environment*, ODShape* );
  164. ODTransform* ODCopyAndRelease( Environment*, ODTransform* );
  165.  
  166. // All of these safely return NULL if the input object is NULL:
  167.  
  168. ODPart* ODAcquirePart( Environment*, ODFrame* );
  169. ODPart* ODAcquirePart( Environment*, ODFacet* );
  170.  
  171. ODDraft* ODGetDraft( Environment*, ODStorageUnit* );
  172. ODDraft* ODGetDraft( Environment*, ODPersistentObject* );
  173. ODDraft* ODGetDraft( Environment*, ODFrame* );            // special case
  174.  
  175. ODSession* ODGetSession( Environment*, ODStorageUnit* );
  176. ODSession* ODGetSession( Environment*, ODPersistentObject* );
  177. ODSession* ODGetSession( Environment*, ODFrame* );        // special case
  178. ODSession* ODGetSession( Environment*, ODDocument* );
  179. ODSession* ODGetSession( Environment*, ODDraft* );
  180. #endif
  181.  
  182. #ifdef PRAGMA_INTERNAL_SUPPORTED
  183. #pragma internal reset
  184. #endif
  185.  
  186. #endif //_ODUTILS_
  187.