home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warphead.zip / H / SESSION.H < prev    next >
C/C++ Source or Header  |  1997-02-28  |  12KB  |  260 lines
  1. /* @(#)Z 1.7 com/src/cm/Session.h, odstorage, od96os2, odos29646d 96/11/15 15:27:14 (96/10/29 09:19:12) */
  2. /*====START_GENERATED_PROLOG======================================
  3.  */
  4. /*
  5.  *   COMPONENT_NAME: odstorage
  6.  *
  7.  *   CLASSES: none
  8.  *
  9.  *   ORIGINS: 82,27
  10.  *
  11.  *
  12.  *   (C) COPYRIGHT International Business Machines Corp. 1995,1996
  13.  *   All Rights Reserved
  14.  *   Licensed Materials - Property of IBM
  15.  *   US Government Users Restricted Rights - Use, duplication or
  16.  *   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  17.  *       
  18.  *   IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  19.  *   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20.  *   PURPOSE. IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  21.  *   CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  22.  *   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  23.  *   OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
  24.  *   OR PERFORMANCE OF THIS SOFTWARE.
  25.  */
  26. /*====END_GENERATED_PROLOG========================================
  27.  */
  28.  
  29. /*
  30.     File:             Session.h     
  31.  
  32.     Contains:    Container Manager Session (task) Global Data Definitions
  33.  
  34.     Written by:    Ira L. Ruben
  35.  
  36.     Owned by:    Ed Lai
  37.  
  38.     Copyright:    ⌐ 1992-1994 by Apple Computer, Inc., all rights reserved.
  39.  
  40.     Change History (most recent first):
  41.  
  42.          <2>     8/26/94    EL        #1181622 Ownership update.
  43.          <1>      2/3/94    EL        first checked in
  44.          <2>    11/22/93    EL        Add refcon for alloc and free handers.
  45.  
  46.     To Do:
  47. */
  48.  
  49. /*---------------------------------------------------------------------------*
  50.  |                                                                           |
  51.  |                        <<<      Session.h      >>>                        |
  52.  |                                                                           |
  53.  |         Container Manager Session (task) Global Data Definitions          |
  54.  |                                                                           |
  55.  |                               Ira L. Ruben                                |
  56.  |                                  4/9/92                                   |
  57.  |                                                                           |
  58.  |                    Copyright Apple Computer, Inc. 1992-1994               |
  59.  |                           All rights reserved.                            |
  60.  |                                                                           |
  61.  *---------------------------------------------------------------------------*
  62.  
  63.  Although it is kept to a minimum, the Container Manager needs some global data!  This
  64.  header defines that data.  It is defined in terms of a struct to group all the globals
  65.  in one place.  The space for the struct is dynamically allocated by CMStartSession(). This
  66.  allows the global data to be associated with a particular running session or task.  Using
  67.  static global data is not necessary supported in some configurations of the Container
  68.  Manager.  For example, in some DLL environments, static global data is not supported.
  69.  
  70.  The scheme chosen here is the most painless (unless you're me who had to change all the
  71.  code to use this thing). The SessionGlobalData struct is known only to the Container
  72.  Manager.  It is allocated by CMStartSession() and returned as an anonomous pointer to be
  73.  passed to the container open routines, CMOpen[New]Container().  All routines, except 
  74.  ones global to all containers, access the session data through a container refNum.
  75.  
  76.  There are some routines that are global to all containers.  Specifically, they are the
  77.  handler operations (e.g, CMSetMetaHandler(), CMGetMetaHandler(), etc.).  All of these
  78.  take the session data pointer explicitly as one of their parameters.
  79. */
  80.  
  81. #ifndef __SESSIONDATA__
  82. #define __SESSIONDATA__
  83.  
  84. #include <stdio.h>
  85. #include <setjmp.h>
  86.  
  87. #ifndef __CMTYPES__
  88. #include "CMTypes.h"
  89. #endif
  90. #ifndef __CM_API_TYPES__
  91. #include "CMAPITyp.h"
  92. #endif
  93. #ifndef __LISTMGR__
  94. #include "ListMgr.h"
  95. #endif
  96. #ifndef __TOCENTRIES__
  97. #include "TOCEnts.h"   
  98. #endif
  99. #ifndef __TOCOBJECTS__
  100. #include "TOCObjs.h"   
  101. #endif
  102. #ifndef __HANDLERS__
  103. #include "Handlers.h"
  104. #endif
  105. #ifndef __CONTAINEROPS__
  106. #include "Containr.h"  
  107. #endif
  108.  
  109. struct MetaHandler;
  110.                                                                     CM_CFUNCTIONS
  111.  
  112.  
  113. /*----------------------------*
  114.  | Session Handler Prototypes |
  115.  *----------------------------*
  116.  
  117.  There are curently three session handlers whose addresses are returned through the session
  118.  metahandler passed to CMStartSession().  These handlers have the following prototypes:
  119. */
  120.  
  121. typedef void CM_PTR *(CM_FIXEDARGS *MallocProto)(CMSize size, CMRefCon sessionRefCon);
  122. typedef void (CM_FIXEDARGS *FreeProto)(CMPtr ptr, CMRefCon sessionRefCon);
  123. #ifdef _PLATFORM_OS2_
  124. typedef void (CM_VARARGS * _System ErrorProto)(CMErrorNbr errorNumber, ...);
  125. #else
  126. typedef void (CM_VARARGS *ErrorProto)(CMErrorNbr errorNumber, ...);
  127. #endif
  128.  
  129.  
  130. /*-----------------------------------------------------*
  131.  | SessionGlobalData - all global data is defined here |
  132.  *-----------------------------------------------------*
  133.  
  134.  Note that the Container Manager version number is placed in the session global data as 
  135.  the last item.  It is variable length so it must come at the end to allow for the     
  136.  proper dynamic allocation. This makes it harder to find, but it sould not be a problem.
  137. */
  138.  
  139. struct SessionGlobalData {                            /* Session global data layout:                                    */
  140.     MallocProto cmMalloc;                                    /*         handler's version of malloc()                            */
  141.     FreeProto     cmFree;                                        /*         handler's version of free()                                */
  142.     ErrorProto     cmReportError;                         /*         error reporter                                                        */
  143.     
  144.     jmp_buf cmForEachGlobalNameEnv;                /*         AbortForEachGlobalName() setjmp env.            */
  145.     jmp_buf cmForEachObjectEnv;                        /*         AbortForEachObject() setjmp env.                    */
  146.     
  147.     CM_ULONG cmTocTblSize;                        /*         size of TOC index tables                                    */
  148.     
  149.     FILE *cmDbgFile;                                            /*         debugging trace file                                            */
  150.     
  151.     #if CMDUMPTOC
  152.     CM_ULONG currTOCoffset;                    /*         current input TOC offset for debugging        */
  153.     CMBoolean gotExplicitGen;                                /*        true ==> explicit generation nbr read            */
  154.     #endif
  155.     
  156.     ListHdr openContainers;                                /*         list of open containers                                        */
  157.     struct MetaHandler *metaHandlerTable;    /*         the root of the handler tree                            */
  158.     
  159.     CMRefCon refCon;                                            /*         pointer to additional user supplied data    */
  160.     
  161.     #if CMVALIDATE
  162.     CMBoolean validate;                                            /*         true ==> do refNum validations                         */
  163.     #endif
  164.     
  165.     unsigned char scratchBuffer[256];            /*         ptr to a general short-term scratch buffer*/
  166.     CMBoolean success;                                            /*        special function result status                        */
  167.     CMBoolean    aborting;                                            /*        in "abort" state (abnormal termination)        */
  168.     
  169.     CM_CHAR cmVersion[1];                                        /*         start of CM version nbr (MUST be last)         */
  170. };
  171. typedef struct SessionGlobalData SessionGlobalData, *SessionGlobalDataPtr;
  172.  
  173.  
  174. /* By convention, the variable "container" will always be used to point to the current    */
  175. /* container.  The following macro is used to access the session global data through         */
  176. /* container:                                                                                                                                                        */
  177.  
  178. #define SESSION (((ContainerPtr)container)->sessionData)
  179.  
  180.  
  181. /* Note, some routines must deal directly with the session data instead of accessing it */
  182. /* through the container. By convention, the variable "sessionData" will always be used */
  183. /* as the session pointer.  To make life a little simpler, the following macros are         */
  184. /* defined to access some of the fields in the session data:                                                        */
  185.  
  186. #define SessionRefCon                        (((SessionGlobalDataPtr)sessionData)->refCon)
  187. #define SessionError                         (*(((SessionGlobalDataPtr)sessionData)->cmReportError))
  188. #define SessionMalloc(size)          (*(((SessionGlobalDataPtr)sessionData)->cmMalloc))((CMSize)(size),SessionRefCon)
  189. #define SessionFree(ptr)              (*(((SessionGlobalDataPtr)sessionData)->cmFree))((CMPtr)(ptr),SessionRefCon)
  190.  
  191. #define SessionMetaHandlerTable    (((SessionGlobalDataPtr)sessionData)->metaHandlerTable)
  192.  
  193.  
  194. /* The validate switch in the session data is controlled by CMDebugging() if                         */
  195. /* CMDebugging() itself is allowed to be generated (under its CMDEBUGGING switch macro     */
  196. /* controlled by the header CMTypes.h). It is preset to CMDEFAULT_VALIDATE (also defined*/
  197. /* in CMTypes.h to keep if hidden from the user).                                                                                */
  198.  
  199. /* The validate switch allows for dynamic controlling of the refNum validations and also*/
  200. /* checking for CMStartSession() being called. Thus the code checks can be toggled on or*/
  201. /* off through CMDebugging().                                                                                                                        */
  202.  
  203. /* There is also a static switch to suppress the validation code entirely. It is called */
  204. /* CMVALIDATE, also defined in CMTypes.h.  Of course, if CMVALIDATE is 0, ALL the                */
  205. /* validations are suppressed and the dynamic switch has no effect.                                            */
  206.  
  207. /* Remember, suppressing the validation checks removes what little protection the                */
  208. /* Container Manager has against careless users.  */
  209.  
  210. /* I am getting off the track.  The whole point here is to define a macro to make it        */
  211. /* easier to access the validate switch...                                                                                            */
  212.  
  213. #if CMVALIDATE
  214. #define VALIDATE (SESSION->validate)
  215. #else
  216. #define VALIDATE 0
  217. #endif
  218.  
  219. /* Since this uses the SESSION macro, container is assumed to be the container pointer.    */
  220.  
  221. /* Also, since we usually get at the container via a refNum, and assuming the validation*/
  222. /* code is not suppressed (CMVALIDATE was 1), we must at least always validate that a        */
  223. /* refNum is not NULL before we use it to go after the session data pointer to see if        */
  224. /* all further validation checking is being dynamically suppressed.                                            */
  225.  
  226.  
  227. /* The following allows access to scratchBuffer as a function of the current container     */
  228. /* pointer via the SESSION macro defined above.                                                                                    */
  229.  
  230. #define ScratchBufr (SESSION->scratchBuffer)
  231.  
  232. /* The following serves the same purpose but uses the session data pointer directly. As    */
  233. /* above, it is assued this pointer is in the variable "sessionData".                                        */
  234.  
  235. #define SessionScratchBufr    (((SessionGlobalDataPtr)sessionData)->scratchBuffer)
  236.  
  237.  
  238. /* Some routines, for example, some of the lookup routines like the metahandler lookup,    */
  239. /* need to do "malloc"s to allocate special temporaries to do their work.     There are         */
  240. /* vary few routines like this.  "Malloc"s, of course, are subject to failure.  So we     */
  241. /* need a way for these routines to report such an error status.  It is confusing and     */
  242. /* inconvenient to have an extra explicit parameter for these routines since the return    */
  243. /* value is always used to indicate a found/not found status.  So the session global,        */
  244. /* "success", is provided for this purpose.                                                                                          */
  245.  
  246. /* The preceding is one use for the switch. It can also be used as an "separate channel"*/
  247. /* to report other status as well.  Fo example, indicating success or failure for             */
  248. /* setjmp/longjmp's, since you cannot use the returned int from a setjmp in a pure ANSI */
  249. /* envoironment!                                                                                                                                                */
  250.  
  251. /* The following macro is provided to interrogate the success/failure status.  This         */
  252. /* assumes "container" is the current container pointer.    Note, routines that use this    */
  253. /* switch must always set it both ways as appropriate. Never assume the previous setting*/
  254. /* of this switch.                                                                                                                                            */
  255.  
  256. #define SessionSuccess (SESSION->success)
  257.  
  258.                                                           CM_END_CFUNCTIONS
  259. #endif
  260.