workbench/libs/reqtools/rtreqhandlera.c

   1 /*
   2     Copyright © 1995-2010, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc:
   6     Lang: English
   7 */
   8
   9 #include <exec/types.h>
  10 #include <proto/exec.h>
  11 #include <proto/reqtools.h>
  12 #include <proto/intuition.h>
  13 #include <exec/libraries.h>
  14 #include <exec/memory.h>
  15 #include <aros/libcall.h>
  16
  17 #include "general.h"
  18 #include "reqtools_intern.h"
  19 #include "rtfuncs.h"
  20
  21 /*****************************************************************************
  22
  23     NAME */
  24
  25     AROS_LH3(IPTR, rtReqHandlerA,
  26
  27 /*  SYNOPSIS */
  28
  29         AROS_LHA(struct rtHandlerInfo *, handlerinfo, A1),
  30         AROS_LHA(ULONG, sigs, D0),
  31         AROS_LHA(struct TagItem *, taglist, A0),
  32
  33 /*  LOCATION */
  34
  35         struct ReqToolsBase *, ReqToolsBase, 18, ReqTools)
  36
  37 /*  FUNCTION
  38         This function should be called if you used the RT_ReqHandler tag
  39         with a requester function.
  40
  41         The requester you used the tag with will have returned immediately
  42         after its initialization and will have initialized a pointer to a
  43         rtHandlerInfo structure for you. You should now do the following:
  44
  45         Check the DoNotWait field. If it is FALSE you have to wait for the
  46         signals in the WaitMask field (plus your own signals if you like).
  47         If any of the signals in WaitMask are received or DoNotWait was not
  48         FALSE you have to call rtReqHandlerA() and check its return value
  49         for one of the following values:
  50
  51         CALL_HANDLER - Check DoNotWait again, Wait() if you have to and
  52             call rtReqHandlerA() again. In other words, loop.
  53         everything else - normal return value, requester has finished. This
  54             return value will be the same as if the requester had run
  55             normally.
  56
  57         You must pass the signals you received to rtReqHandlerA().
  58
  59         NOTE: if you want to wait for your own signals do not do so if
  60             DoNotWait is TRUE. Call rtReqHandlerA() and if you must know if
  61             one of your signals arrived use SetSignal() to find this out.
  62             If you are waiting for a message to arrive at a message port
  63             you can simple call GetMsg() and check if it is non-null.
  64             DoNotWait will naturally only be TRUE when it absolutely,
  65             positively has to be. A multitasking machine as the Amiga
  66             should use Wait() as much as possible.
  67
  68         This is an example of a "requester loop":
  69
  70         ...
  71         struct rtHandlerInfo *hinfo;
  72         ULONG ret, mymask, sigs;
  73
  74         ...
  75         // calculate our mask
  76         mymask = 1 << win->UserPort->mp_SigBit;
  77
  78         // We use the RT_ReqHandler tag to cause the requester to return
  79         // after initializing.
  80         // Check the return value to see if this setup went ok.
  81         if( rtFontRequest( req, "Font", RT_ReqHandler, &hinfo, TAG_END )
  82                                                        == CALL_HANDLER )
  83         {
  84             do
  85             {
  86                 // Wait() if we can
  87                 if( !hinfo->DoNotWait )
  88                 {
  89                     sigs = Wait( hinfo->WaitMask | mymask );
  90                 }
  91
  92                 // check our own message port
  93                 while( msg = GetMsg( win->UserPort ) )
  94                 {
  95                     ...
  96                     // here we handle messages received at our windows
  97                     // IDCMP port
  98                     ...
  99                 }
 100
 101                 // let the requester do its thing (remember to pass 'sigs')
 102                 ret = rtReqHandler( hinfo, sigs, TAG_END );
 103
 104                 // continue this loop as long as the requester is up
 105             } while( ret == CALL_HANDLER )
 106
 107             // when we get here we know the requester has finished, 'ret'
 108             // is the return code.
 109             ...
 110         }
 111         else
 112         {
 113             notify( "Error opening requester!" );
 114         }
 115         ...
 116
 117     INPUTS
 118         handlerinfo - pointer to handler info structure initialized by
 119             using the RT_ReqHandler tag when calling a requester function.
 120         sigs - the signals received by previous wait, will be ignored if
 121             handlerinfo->DoNotWait was TRUE.
 122         taglist - pointer to a TagItem array.
 123
 124     TAGS
 125         RTRH_EndRequest - supplying this tag will end the requester. The
 126             return code from rtReqHandlerA() will _not_ be CALL_HANDLER,
 127             but the requester return code. If the tagdata of this tag is
 128             REQ_CANCEL the requester will be canceled, if it is REQ_OK the
 129             requester will be ok-ed. In case of an EZRequest tagdata should
 130             be the return code of the requester (TRUE, FALSE or 2,3,4,...).
 131
 132     RESULT
 133         ret - CALL_HANDLER if you have to call rtReqHandlerA() again, or
 134             the normal return value from the requester.
 135
 136     NOTES
 137
 138     EXAMPLE
 139
 140     BUGS
 141         none known
 142
 143     SEE ALSO
 144         rtEZRequestA(), (RT_ReqHandler explanation)
 145
 146     INTERNALS
 147
 148     HISTORY
 149
 150 ******************************************************************************/
 151 {
 152     AROS_LIBFUNC_INIT
 153
 154     return RTFuncs_rtReqHandlerA(handlerinfo, sigs, taglist);
 155
 156     AROS_LIBFUNC_EXIT
 157
 158 } /* rtReqHandlerA */