home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / opendc12.zip / od124os2.exe / od12osp1.exe / src / utils / ODUtils.h < prev    next >
C/C++ Source or Header  |  1997-04-02  |  7KB  |  204 lines
  1. //====START_GENERATED_PROLOG======================================
  2. //
  3. //
  4. //   COMPONENT_NAME: odutils
  5. //
  6. //   CLASSES: none
  7. //
  8. //   ORIGINS: 82,27
  9. //
  10. //
  11. //   (C) COPYRIGHT International Business Machines Corp. 1995,1996
  12. //   All Rights Reserved
  13. //   Licensed Materials - Property of IBM
  14. //   US Government Users Restricted Rights - Use, duplication or
  15. //   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  16. //       
  17. //   IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  18. //   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19. //   PURPOSE. IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  20. //   CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  21. //   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  22. //   OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
  23. //   OR PERFORMANCE OF THIS SOFTWARE.
  24. //
  25. //====END_GENERATED_PROLOG========================================
  26. //
  27. // @(#) 1.5 com/src/utils/include/ODUtils.h, odutils, od96os2, odos29712d 3/14/97 16:52:28 [ 3/21/97 17:21:08 ]
  28. /*
  29.     File:        ODUtils.h
  30.  
  31.     Contains:    Object utility functions
  32.  
  33.     Owned by:    Jens Alfke
  34.  
  35.     Copyright:    (C) 1993 - 1995 by Apple Computer, Inc., all rights reserved.
  36.  
  37.     Theory Of Operation:
  38.     
  39.         These are useful utilities for use with objects, particularly ref-
  40.         counted objects. Some are functions rather than macros, to reduce
  41.         code size, and can be made inline later if necessary.
  42.         
  43.         ODDeleteObject deletes an object (which doesn't need to
  44.             be a SOM object) and sets the variable pointing to it to NULL.
  45.             If the pointer was already NULL, nothing happens.
  46.             
  47.         ODReleaseObject is similar, but releases the object instead of deleting
  48.             it. Use this one for ref-counted objects.
  49.         
  50.         ODFinalReleaseObject is similar to ODReleaseObject, except that it is 
  51.             meant to be used in code which is releasing the last reference
  52.             to that object.  I.E. it does an ASSERT(refcount == 1) before calling release.
  53.         
  54.         ODRelease just releases an object (if it's not NULL.) Unlike ODReleaseObject
  55.             it does not set your pointer to the object to NULL. There are a few
  56.             occasions where you'll want to use this instead, but not many.
  57.         
  58.         ODFinalRelease is analogous to ODRelease; it is like ODFInalReleaseObject
  59.             but does not reset your pointer to NULL.
  60.             
  61.         ODAcquireObject bumps the ref-count of an object, unless it's NULL.
  62.         
  63.         ODSafeReleaseObject also releases an object, but requires no Environment
  64.             parameter and can't throw an exception. It's for use _only_ in
  65.             somUninit methods, where no Environment is available.
  66.         
  67.         ODTransferReference lowers one object's refCount while incrementing
  68.             another's. It's useful in things like setters where you want to
  69.             forget about one object and remember another. It does the right
  70.             thing if either pointer is NULL or if they point to the same object.
  71.             ** This function may throw an exception in the unlikely case that
  72.                 the Acquire or Release call fails.
  73.         
  74.         ODCopyAndRelease returns a copy of an object while releasing the object.
  75.             This is useful when transferring control of an object to the caller,
  76.             but the caller has permission to modify the object. It's optimized
  77.             for the case where the ref-count of the object is 1, in which case
  78.             it just returns the original object since no copying is needed.
  79.             (This function works only on ODShapes and ODTransforms, which are the
  80.             only classes that provide a Copy method.)
  81.             ** This function may throw an exception in the unlikely case that
  82.                 the GetRefCount or Release call fails.
  83.         
  84.         ODObjectsAreEqual returns kODTrue if two pointers point to the same object.
  85.             In OpenDoc 1.0 this is the same thing as comparing the pointers;
  86.             however, in the future when we use DSOM and objects may reside in
  87.             different address spaces, it will be possible to have two different
  88.             pointers to the same object! For future compatibility, use this function.
  89.         
  90.         ODAcquirePart, ODGetDraft and ODGetSession are convenience accessors.
  91.             There's nothing magic about them, but they do save code size since they
  92.             encapsulate several SOM calls. They also simplify the appearance of code.
  93.     
  94.     
  95.         The "do...while(0)" blocks wrapped around the macros are there to prevent
  96.         syntactic problems if a macro call is immediately followed by an "else"
  97.         statement, to keep the "else" from binding to the "if" in the macro body.
  98.         The "while" loop is optimized out by the compiler and has no effect on the
  99.         flow of control or code quality.
  100.  
  101.     To Do:
  102.     In Progress:
  103.         
  104. */
  105.  
  106. #ifndef _ODUTILS_
  107. #define _ODUTILS_
  108.  
  109. #ifndef _ODTYPES_
  110. #include "ODTypes.h"
  111. #endif
  112.  
  113. #ifndef _ODMVCLNK_
  114. #include <ODMvcLnk.h>
  115. #endif
  116.  
  117.  
  118. #ifdef __cplusplus
  119.     struct Environment;
  120.     class ODObject;
  121.     class ODShape;
  122.     class ODTransform;
  123.     class ODRefCntObject;
  124.     class ODPart;
  125.     class ODPersistentObject;
  126.     class ODStorageUnit;
  127.     class ODDraft;
  128.     class ODSession;
  129.     class ODWindow;
  130.     class ODDocument;
  131.     extern "C" {
  132. #else
  133.     #ifndef SOM_ODStorageUnit_h
  134.     #include <StorageU.h>
  135.     #endif
  136.     #ifndef SOM_ODTransform_h
  137.     #include <Shape.h>
  138.     #endif
  139.     #ifndef SOM_ODTransform_h
  140.     #include <Trnsform.h>
  141.     #endif
  142. #endif
  143.  
  144. _DLLIMPORTEXPORT_ void ODRelease( Environment*, ODRefCntObject* );    // Just releases, does not set ptr to NULL
  145.  
  146. _DLLIMPORTEXPORT_ void ODFinalRelease(Environment*, ODRefCntObject* );
  147.  
  148. #define ODReleaseObject(EV,OBJ)                     \
  149.             do{ ODRefCntObject *temp = (OBJ);        \
  150.                 (OBJ) = kODNULL;                    \
  151.                 ODRelease((EV),temp); } while(0)
  152.  
  153. #define ODFinalReleaseObject(EV,OBJ)                 \
  154.             do{ ODRefCntObject *temp = (OBJ);        \
  155.                 (OBJ) = kODNULL;                    \
  156.                 ODFinalRelease((EV),temp); } while(0)
  157.  
  158. #define ODDeleteObject(OBJ) \
  159.             if( !(OBJ) ) ; else { delete (OBJ); (OBJ)=kODNULL; }
  160.             
  161. _DLLIMPORTEXPORT_ void ODSafeReleaseObject( ODRefCntObject* );    // Needs no ev, throws no exceptions
  162.  
  163. _DLLIMPORTEXPORT_ void ODTransferReference( Environment*, ODRefCntObject *oldObj,
  164.                                                ODRefCntObject *newObj );
  165.  
  166. _DLLIMPORTEXPORT_ void ODAcquireObject(Environment* ev, ODRefCntObject* object);
  167.  
  168.  
  169. #if ODDebug || !defined(_OD_IMPL_)
  170.     ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b);
  171. #elif defined(__cplusplus)
  172.     // Optimization for OD implementation since DSOM is not in the picture yet:
  173.     inline ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b)
  174.                         {return a==b;}
  175. #else
  176.     #define ODObjectsAreEqual(a,b)    ((a)==(b))
  177. #endif
  178.  
  179.  
  180. #ifdef __cplusplus
  181. }
  182.  
  183. // Overloaded functions can only be used in C++:
  184.  
  185. _DLLIMPORTEXPORT_ ODShape*     ODCopyAndRelease( Environment*, ODShape* );
  186. _DLLIMPORTEXPORT_ ODTransform* ODCopyAndRelease( Environment*, ODTransform* );
  187.  
  188. // All of these safely return NULL if the input object is NULL:
  189.  
  190. _DLLIMPORTEXPORT_ ODPart* ODAcquirePart( Environment*, ODFrame* );
  191. _DLLIMPORTEXPORT_ ODPart* ODAcquirePart( Environment*, ODFacet* );
  192.  
  193. _DLLIMPORTEXPORT_ ODDraft* ODGetDraft( Environment*, ODStorageUnit* );
  194. _DLLIMPORTEXPORT_ ODDraft* ODGetDraft( Environment*, ODPersistentObject* );
  195.  
  196. _DLLIMPORTEXPORT_ ODSession* ODGetSession( Environment*, ODStorageUnit* );
  197. _DLLIMPORTEXPORT_ ODSession* ODGetSession( Environment*, ODPersistentObject* );
  198. _DLLIMPORTEXPORT_ ODSession* ODGetSession( Environment*, ODDocument* );
  199. _DLLIMPORTEXPORT_ ODSession* ODGetSession( Environment*, ODDraft* );
  200. #endif
  201.  
  202.  
  203. #endif //_ODUTILS_
  204.