home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / notify.doc < prev    next >
Encoding:
Text File  |  1997-02-27  |  6.7 KB  |  198 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.  
  32.         Several Opus events are also available for notification:
  33.  
  34.             DN_OPUS_START      - Opus has started
  35.             DN_OPUS_QUIT       - Opus has quit
  36.             DN_OPUS_HIDE       - Opus has been hidden
  37.             DN_OPUS_SHOW       - Opus has been revealed
  38.  
  39.         When an event occurs that you have requested notification for, a
  40.         DOpusNotify message is sent to your message port. The message
  41.         structure is defined as follows:
  42.  
  43.             dn_Msg      - Exec message header
  44.  
  45.             dn_Type     - Event type
  46.  
  47.             dn_UserData - the userdata you supplied to AddNotifyRequest()
  48.  
  49.             dn_Data     - data specific to the type of event
  50.  
  51.             dn_Flags    - flags specific to the type of event
  52.  
  53.             dn_Fib      - a FileInfoBlock for some types of event
  54.  
  55.             dn_Name     - pathname specific to the type of event
  56.  
  57.  
  58.         The event-specific fields are used in the following way:
  59.  
  60.             DN_WRITE_ICON
  61.             -------------
  62.                 dn_Data  - NULL
  63.                 dn_Flags - if DNF_ICON_REMOVED is set, icon was deleted
  64.                 dn_Fib   - NULL
  65.                 dn_Name  - full pathname of icon
  66.  
  67.             DN_APP_ICON_LIST
  68.             ----------------
  69.                 dn_Data  - pointer to the AppIcon added or removed
  70.                 dn_Flags - if DNF_ICON_REMOVED is set, icon was removed
  71.                            if DNF_ICON_CHANGED is set, the icon image
  72.                            was changed
  73.                 dn_Fib   - NULL
  74.                 dn_Name  - NULL
  75.  
  76.             DN_APP_MENU_LIST
  77.             ----------------
  78.                 dn_Data  - pointer to the AppMenuItem added or removed
  79.                 dn_Flags - if DNF_ICON_REMOVED is set, item was removed
  80.                 dn_Fib   - NULL
  81.                 dn_Name  - NULL
  82.  
  83.             DN_DISKCHANGE
  84.             -------------
  85.                 dn_Data  - disk units the change occurred in (bits 0-3
  86.                            represent units 0-3) *
  87.                 dn_Flags - which units have disks in them (bits 0-3
  88.                            represent units 0-3) *
  89.                 dn_Fib   - NULL
  90.                 dn_Name  - device that was changed
  91.  
  92.                 * note that these are only valid for DF0: through to DF3:
  93.  
  94.             DN_DOS_ACTION
  95.             -------------
  96.                 dn_Data  - NULL
  97.                 dn_Flags - which DOS action occurred (see <dopus/notify.h>)
  98.                 dn_Fib   - FileInfoBlock with file information. This is
  99.                            supplied for all actions except Delete.
  100.                 dn_Name  - full pathname of file involved
  101.  
  102.     INPUTS
  103.         type - type of events you want to be notified of. One request can
  104.                ask for multiple events. See <dopus/notify.h> for the full
  105.                list.
  106.  
  107.         userdata - a user-defined data field that is passed in any notify
  108.                    messages.
  109.  
  110.         port - message port to send notification messages to.
  111.  
  112.     NOTES
  113.         Most notification messages are sent "reply free", meaning you must
  114.         use the ReplyFreeMsg() call to reply to them. Otherwise, the
  115.         message memory will be lost.
  116.  
  117.     RESULT
  118.         Returns a notify handle which you use to remove the request.
  119.  
  120.     SEE ALSO
  121.         RemoveNotifyRequest(), SetNotifyRequest()
  122.  
  123. dopus5.library/RemoveNotifyRequest         dopus5.library/RemoveNotifyRequest
  124.  
  125.     NAME
  126.         RemoveNotifyRequest - remove a notification request
  127.  
  128.     SYNOPSIS
  129.         RemoveNotifyRequest(request)
  130.                               A0
  131.  
  132.         void RemoveNotifyRequest(APTR);
  133.  
  134.     FUNCTION
  135.         Removes a notify request that was added with AddNotifyRequest().
  136.  
  137.     INPUTS
  138.         request - request to remove
  139.  
  140.     RESULT
  141.         The request is removed. You will receive no more notifications for
  142.         that request. Once you have removed the request you should check
  143.         your message port for outstanding messages and reply to them.
  144.  
  145.     SEE ALSO
  146.         AddNotifyRequest()
  147.  
  148. dopus5.library/ReplyFreeMsg                       dopus5.library/ReplyFreeMsg
  149.  
  150.     NAME
  151.         ReplyFreeMsg - reply or free a message
  152.  
  153.     SYNOPSIS
  154.         ReplyFreeMsg(msg)
  155.                       A0
  156.  
  157.         void ReplyFreeMsg(struct Message *);
  158.  
  159.     FUNCTION
  160.         If the message has a valid ReplyPort, this function simply passes it
  161.         through to ReplyMsg(). If the message has no reply port set, this
  162.         function calls FreeVec() on the message to free it.
  163.  
  164.     INPUTS
  165.         msg - message to reply or free
  166.  
  167.     NOTES
  168.         Most Opus notification messages are sent "reply free", meaning you
  169.         MUST use this function to reply to them or the memory will be lost.
  170.  
  171.     SEE ALSO
  172.         AddNotifyRequest()
  173.  
  174. dopus5.library/SetNotifyRequest               dopus5.library/SetNotifyRequest
  175.  
  176.     NAME
  177.         SetNotifyRequest - change notification events
  178.  
  179.     SYNOPSIS
  180.         SetNotifyRequest(request, new_type, mask)
  181.                            A0        D0      D1
  182.  
  183.         void SetNotifyRequest(APTR, ULONG, ULONG);
  184.  
  185.     FUNCTION
  186.         This routine changes the type of events that an existing notification
  187.         request is interested in.
  188.  
  189.     INPUTS
  190.         request - notification request to change
  191.         new_type - the new event flags to receive notification about
  192.         mask - mask of event flags to change (any events not specified in the
  193.                mask field will not be modified)
  194.  
  195.     SEE ALSO
  196.         AddNotifyRequest()
  197.  
  198.