home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / at-inc-bin.lha / os-include / utility / hooks.h < prev    next >
C/C++ Source or Header  |  1993-10-15  |  3KB  |  101 lines
  1. #ifndef UTILITY_HOOKS_H
  2. #define UTILITY_HOOKS_H
  3. /*
  4. **    $VER: hooks.h 39.2 (16.6.93)
  5. **    Includes Release 40.15
  6. **
  7. **    Callback hooks
  8. **
  9. **    (C) Copyright 1989-1993 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. /* Useful definition for casting function pointers:
  37.  * hook.h_SubEntry = (HOOKFUNC)AFunction
  38.  */
  39. typedef unsigned long (*HOOKFUNC)();
  40.  
  41. /* Hook calling conventions.
  42.  *
  43.  * The function pointed to by Hook.h_Entry is called with the following
  44.  * parameters:
  45.  *
  46.  *    A0 - pointer to hook data structure itself
  47.  *    A1 - pointer to parameter structure ("message")
  48.  *    A2 - Hook specific address data ("object")
  49.  *
  50.  * Control will be passed to the routine h_Entry.  For many
  51.  * High-Level Languages (HLL), this will be an assembly language
  52.  * stub which pushes registers on the stack, does other setup,
  53.  * and then calls the function at h_SubEntry.
  54.  *
  55.  * The standard C receiving code is:
  56.  *
  57.  *    HookFunc(struct Hook *hook, APTR object, APTR message)
  58.  *
  59.  * Note that register natural order differs from this convention for C
  60.  * parameter order, which is A0,A2,A1.
  61.  *
  62.  * The assembly language stub for "vanilla" C parameter conventions
  63.  * could be:
  64.  *
  65.  * _hookEntry:
  66.  *    move.l    a1,-(sp)        ; push message packet pointer
  67.  *    move.l    a2,-(sp)        ; push object pointer
  68.  *    move.l    a0,-(sp)        ; push hook pointer
  69.  *    move.l    h_SubEntry(a0),a0    ; fetch C entry point ...
  70.  *    jsr    (a0)            ; ... and call it
  71.  *    lea    12(sp),sp        ; fix stack
  72.  *    rts
  73.  *
  74.  * With this function as your interface stub, you can write a Hook setup
  75.  * function as:
  76.  *
  77.  * InitHook(struct Hook *hook, ULONG (*c_function)(), APTR userdata)
  78.  * {
  79.  * ULONG (*hookEntry)();
  80.  *
  81.  *     hook->h_Entry    = hookEntry;
  82.  *     hook->h_SubEntry = c_function;
  83.  *     hook->h_Data    = userdata;
  84.  * }
  85.  *
  86.  * With a compiler capable of registerized parameters, such as SAS C, you
  87.  * can put the C function in the h_Entry field directly. For example, for
  88.  * SAS C:
  89.  *
  90.  *   ULONG __saveds __asm HookFunc(register __a0 struct Hook *hook,
  91.  *                   register __a2 APTR          object,
  92.  *                   register __a1 APTR          message);
  93.  *
  94.  */
  95.  
  96.  
  97. /*****************************************************************************/
  98.  
  99.  
  100. #endif /* UTILITY_HOOKS_H */
  101.