workbench/libs/workbench/registerworkbench.c

   1 /*
   2     Copyright © 1995-2003, The AROS Development Team. All rights reserved.
   3     $Id$
   4 */
   5
   6 #include "workbench_intern.h"
   7 #include <workbench/workbench.h>
   8
   9 /*****************************************************************************
  10
  11     NAME */
  12
  13         #include <proto/workbench.h>
  14
  15         AROS_LH1(BOOL, RegisterWorkbench,
  16
  17 /*  SYNOPSIS */
  18         AROS_LHA(struct MsgPort *, messageport, A0),
  19
  20 /*  LOCATION */
  21         struct WorkbenchBase *, WorkbenchBase, 23, Workbench)
  22
  23 /*  FUNCTION
  24         The workbench application uses this function to register itself with
  25         the library. When it has done this, the library sends messages to the
  26         specified port about actions the application is supposed to carry out.
  27
  28         All messages sent to the message port are of struct WBHandlerMessage,
  29         which is specified in <workbench/handler.h>. The wbhm_Type field
  30         identifies the type of message and which part of the wbhm_Data union
  31         is relevant. The following types are currently defined:
  32
  33         WBHM_TYPE_SHOW
  34             Intuition has (re)opened the Workbench Screen, and request that
  35             you open all your windows. When the message is replied, Intuition
  36             assumes that the windows have been opened.
  37
  38         WBHM_TYPE_HIDE
  39             Intuition is about to close the Workbench Screen, and request that
  40             you close all your windows. When the message is replied, Intuition
  41             assumes that the windows have been closed and will try to close the
  42             screen.
  43
  44         WBHM_TYPE_OPEN
  45             Request to open the specified drawer.
  46
  47         WBHM_TYPE_UPDATE
  48             The state of the specified disk object has changed, and this
  49             message serves as a notification and suggestion that you should
  50             update its visual representation to the user. For example, it
  51             might have been deleted or renamed.
  52
  53     INPUTS
  54         messageport - The message port to send the to.
  55
  56     RESULT
  57         TRUE if the message port was successfully registered, FALSE otherwise.
  58         The registration will fail if an other message port has already been
  59         registered earlier or if a NULL pointer was passed in.
  60
  61     NOTES
  62         As you can read above, only one workbench application can be registered
  63         at a time. This is intentional. Note that "workbench application" in
  64         this context means the program that is the file manager and handles
  65         the GUI, not a program that is started using OpenWorkbenchObjectA()!
  66
  67     EXAMPLE
  68
  69     BUGS
  70
  71     SEE ALSO
  72         UnregisterWorkbench()
  73
  74     INTERNALS
  75
  76 ******************************************************************************/
  77 {
  78     AROS_LIBFUNC_INIT
  79
  80     BOOL success = FALSE;
  81
  82     if (messageport != NULL)
  83     {
  84         ObtainSemaphore(&(WorkbenchBase->wb_WorkbenchPortSemaphore));
  85
  86         if (WorkbenchBase->wb_WorkbenchPort == NULL)
  87         {
  88             WorkbenchBase->wb_WorkbenchPort = messageport;
  89             success = TRUE;
  90         }
  91
  92         ReleaseSemaphore(&(WorkbenchBase->wb_WorkbenchPortSemaphore));
  93     }
  94
  95     return success;
  96
  97     AROS_LIBFUNC_EXIT
  98 } /* RegisterWorkbench() */