home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 2 / FFMCD02.bin / useful / os-include / utility / hooks.h < prev    next >
C/C++ Source or Header  |  1992-09-24  |  3KB  |  96 lines
  1. #ifndef UTILITY_HOOKS_H
  2. #define UTILITY_HOOKS_H
  3. /*
  4. **    $VER: hooks.h 39.1 (20.01.92)
  5. **    Includes Release 39.108
  6. **
  7. **    Callback hooks
  8. **
  9. **    (C) Copyright 1989-1992 Commodore-Amiga Inc.
  10. **    All Rights Reserved
  11. */
  12.  
  13. /*****************************************************************************/
  14.  
  15.  
  16. #ifndef EXEC_TYPES_H
  17. #include <exec/types.h>
  18. #endif
  19.  
  20. #ifndef EXEC_NODES_H
  21. #include <exec/nodes.h>
  22. #endif
  23.  
  24.  
  25. /*****************************************************************************/
  26.  
  27.  
  28. struct Hook
  29. {
  30.     struct MinNode h_MinNode;
  31.     ULONG       (*h_Entry)();    /* assembler entry point */
  32.     ULONG       (*h_SubEntry)();    /* often HLL entry point */
  33.     APTR       h_Data;        /* owner specific     */
  34. };
  35.  
  36. /* Hook calling conventions.
  37.  *
  38.  * The function pointed to by Hook.h_Entry is called with the following
  39.  * parameters:
  40.  *
  41.  *    A0 - pointer to hook data structure itself
  42.  *    A1 - pointer to parameter structure ("message")
  43.  *    A2 - Hook specific address data ("object")
  44.  *
  45.  * Control will be passed to the routine h_Entry.  For many
  46.  * High-Level Languages (HLL), this will be an assembly language
  47.  * stub which pushes registers on the stack, does other setup,
  48.  * and then calls the function at h_SubEntry.
  49.  *
  50.  * The standard C receiving code is:
  51.  *
  52.  *    HookFunc(struct Hook *hook, APTR object, APTR message)
  53.  *
  54.  * Note that register natural order differs from this convention for C
  55.  * parameter order, which is A0,A2,A1.
  56.  *
  57.  * The assembly language stub for "vanilla" C parameter conventions
  58.  * could be:
  59.  *
  60.  * _hookEntry:
  61.  *    move.l    a1,-(sp)        ; push message packet pointer
  62.  *    move.l    a2,-(sp)        ; push object pointer
  63.  *    move.l    a0,-(sp)        ; push hook pointer
  64.  *    move.l    h_SubEntry(a0),a0    ; fetch C entry point ...
  65.  *    jsr    (a0)            ; ... and call it
  66.  *    lea    12(sp),sp        ; fix stack
  67.  *    rts
  68.  *
  69.  * With this function as your interface stub, you can write a Hook setup
  70.  * function as:
  71.  *
  72.  * InitHook(struct Hook *hook, ULONG (*c_function)(), APTR userdata)
  73.  * {
  74.  * ULONG (*hookEntry)();
  75.  *
  76.  *     hook->h_Entry    = hookEntry;
  77.  *     hook->h_SubEntry = c_function;
  78.  *     hook->h_Data    = userdata;
  79.  * }
  80.  *
  81.  * With a compiler capable of registerized parameters, such as SAS C, you
  82.  * can put the C function in the h_Entry field directly. For example, for
  83.  * SAS C:
  84.  *
  85.  *   ULONG __saveds __asm HookFunc(register __a0 struct Hook *hook,
  86.  *                   register __a2 APTR          object,
  87.  *                   register __a1 APTR          message);
  88.  *
  89.  */
  90.  
  91.  
  92. /*****************************************************************************/
  93.  
  94.  
  95. #endif /* UTILITY_HOOKS_H */
  96.