home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / notify.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  7.1 KB  |  208 lines
  1. dopus5.library/AddNotifyRequest               dopus5.library/AddNotifyRequest
  2.  
  3.     NAME
  4.         AddNotifyRequest - add a request to Opus's notify chain
  5.  
  6.     SYNOPSIS
  7.         AddNotifyRequest(type, userdata, port)
  8.                           D0      D1      A0
  9.  
  10.         APTR AddNotifyRequest(ULONG, ULONG, struct MsgPort *);
  11.  
  12.     FUNCTION
  13.         Opus keeps track of several different system events, and this routine
  14.         allows you to request notification on them.
  15.  
  16.         The events currently available for notification:
  17.  
  18.             DN_WRITE_ICON      - an icon is written to disk
  19.             DN_APP_ICON_LIST   - an AppIcon is added or removed
  20.             DN_APP_MENU_LIST   - an AppMenuItem is added or removed
  21.             DN_CLOSE_WORKBENCH - CloseWorkbench() has been called
  22.             DN_OPEN_WORKBENCH  - OpenWorkbench() has been called
  23.             DN_RESET_WORKBENCH - the workbench screen has been closed and
  24.                                  re-opened
  25.             DN_DISKCHANGE      - a disk has been inserted or removed
  26.             DN_DOS_ACTION      - a DOS event has occurred. In Opus 5.5,
  27.                                  these messages are only available if the
  28.                                  dopus/DOSPatch environment variable is set.
  29.             DN_REXX_UP         - the ARexx process has been started.
  30.             DN_FLUSH_MEM       - low memory handler called, please free memory
  31.             DN_APP_WINDOW_LIST - AppWindow added or removed
  32.  
  33.         Several Opus events are also available for notification:
  34.  
  35.             DN_OPUS_START      - Opus has started
  36.             DN_OPUS_QUIT       - Opus has quit
  37.             DN_OPUS_HIDE       - Opus has been hidden
  38.             DN_OPUS_SHOW       - Opus has been revealed
  39.  
  40.         When an event occurs that you have requested notification for, a
  41.         DOpusNotify message is sent to your message port. The message
  42.         structure is defined as follows:
  43.  
  44.             dn_Msg      - Exec message header
  45.  
  46.             dn_Type     - Event type
  47.  
  48.             dn_UserData - the userdata you supplied to AddNotifyRequest()
  49.  
  50.             dn_Data     - data specific to the type of event
  51.  
  52.             dn_Flags    - flags specific to the type of event
  53.  
  54.             dn_Fib      - a FileInfoBlock for some types of event
  55.  
  56.             dn_Name     - pathname specific to the type of event
  57.  
  58.  
  59.         The event-specific fields are used in the following way:
  60.  
  61.             DN_WRITE_ICON
  62.             -------------
  63.                 dn_Data  - NULL
  64.                 dn_Flags - if DNF_ICON_REMOVED is set, icon was deleted
  65.                 dn_Fib   - NULL
  66.                 dn_Name  - full pathname of icon
  67.  
  68.             DN_APP_ICON_LIST
  69.             ----------------
  70.                 dn_Data  - pointer to the AppIcon added or removed
  71.                 dn_Flags - if DNF_ICON_REMOVED is set, icon was removed
  72.                            if DNF_ICON_CHANGED is set, the icon image
  73.                            was changed
  74.                 dn_Fib   - NULL
  75.                 dn_Name  - NULL
  76.  
  77.             DN_APP_MENU_LIST
  78.             ----------------
  79.                 dn_Data  - pointer to the AppMenuItem added or removed
  80.                 dn_Flags - if DNF_ICON_REMOVED is set, item was removed
  81.                 dn_Fib   - NULL
  82.                 dn_Name  - NULL
  83.  
  84.             DN_DISKCHANGE
  85.             -------------
  86.                 dn_Data  - disk units the change occurred in (bits 0-3
  87.                            represent units 0-3) *
  88.                 dn_Flags - which units have disks in them (bits 0-3
  89.                            represent units 0-3) *
  90.                 dn_Fib   - NULL
  91.                 dn_Name  - device that was changed
  92.  
  93.                 * note that these are only valid for DF0: through to DF3:
  94.  
  95.             DN_DOS_ACTION
  96.             -------------
  97.                 dn_Data  - NULL
  98.                 dn_Flags - which DOS action occurred (see <dopus/notify.h>)
  99.                 dn_Fib   - FileInfoBlock with file information. This is
  100.                            supplied for all actions except Delete.
  101.                 dn_Name  - full pathname of file involved
  102.  
  103.             DN_APP_WINDOW_LIST
  104.             ----------------
  105.                 dn_Data  - pointer to the AppWindow added or removed
  106.                 dn_Flags - if DNF_WINDOW_REMOVED is set, window was removed
  107.                            (in this case the AppWindow in dn_Data is no longer
  108.                            valid)
  109.                 dn_Fib   - NULL
  110.                 dn_Name  - NULL
  111.  
  112.     INPUTS
  113.         type - type of events you want to be notified of. One request can
  114.                ask for multiple events. See <dopus/notify.h> for the full
  115.                list.
  116.  
  117.         userdata - a user-defined data field that is passed in any notify
  118.                    messages.
  119.  
  120.         port - message port to send notification messages to.
  121.  
  122.     NOTES
  123.         Most notification messages are sent "reply free", meaning you must
  124.         use the ReplyFreeMsg() call to reply to them. Otherwise, the
  125.         message memory will be lost.
  126.  
  127.     RESULT
  128.         Returns a notify handle which you use to remove the request.
  129.  
  130.     SEE ALSO
  131.         RemoveNotifyRequest(), SetNotifyRequest()
  132.  
  133. dopus5.library/RemoveNotifyRequest         dopus5.library/RemoveNotifyRequest
  134.  
  135.     NAME
  136.         RemoveNotifyRequest - remove a notification request
  137.  
  138.     SYNOPSIS
  139.         RemoveNotifyRequest(request)
  140.                               A0
  141.  
  142.         void RemoveNotifyRequest(APTR);
  143.  
  144.     FUNCTION
  145.         Removes a notify request that was added with AddNotifyRequest().
  146.  
  147.     INPUTS
  148.         request - request to remove
  149.  
  150.     RESULT
  151.         The request is removed. You will receive no more notifications for
  152.         that request. Once you have removed the request you should check
  153.         your message port for outstanding messages and reply to them.
  154.  
  155.     SEE ALSO
  156.         AddNotifyRequest()
  157.  
  158. dopus5.library/ReplyFreeMsg                       dopus5.library/ReplyFreeMsg
  159.  
  160.     NAME
  161.         ReplyFreeMsg - reply or free a message
  162.  
  163.     SYNOPSIS
  164.         ReplyFreeMsg(msg)
  165.                       A0
  166.  
  167.         void ReplyFreeMsg(struct Message *);
  168.  
  169.     FUNCTION
  170.         If the message has a valid ReplyPort, this function simply passes it
  171.         through to ReplyMsg(). If the message has no reply port set, this
  172.         function calls FreeVec() on the message to free it.
  173.  
  174.     INPUTS
  175.         msg - message to reply or free
  176.  
  177.     NOTES
  178.         Most Opus notification messages are sent "reply free", meaning you
  179.         MUST use this function to reply to them or the memory will be lost.
  180.  
  181.     SEE ALSO
  182.         AddNotifyRequest()
  183.  
  184. dopus5.library/SetNotifyRequest               dopus5.library/SetNotifyRequest
  185.  
  186.     NAME
  187.         SetNotifyRequest - change notification events
  188.  
  189.     SYNOPSIS
  190.         SetNotifyRequest(request, new_type, mask)
  191.                            A0        D0      D1
  192.  
  193.         void SetNotifyRequest(APTR, ULONG, ULONG);
  194.  
  195.     FUNCTION
  196.         This routine changes the type of events that an existing notification
  197.         request is interested in.
  198.  
  199.     INPUTS
  200.         request - notification request to change
  201.         new_type - the new event flags to receive notification about
  202.         mask - mask of event flags to change (any events not specified in the
  203.                mask field will not be modified)
  204.  
  205.     SEE ALSO
  206.         AddNotifyRequest()
  207.  
  208.