Callback Hooks - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:04:47Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:04, 26 January 2025
Line 7:		Line 7:
	An application passes a custom function in the form of a callback Hook (from <utility/hooks.h>):		An application passes a custom function in the form of a callback Hook (from <utility/hooks.h>):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Hook		struct Hook
	{		{
Line 32:		Line 32:
	There is only one function defined in utility library that relates to callback hooks:		There is only one function defined in utility library that relates to callback hooks:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 CallHookPkt(struct Hook *hook, APTR object, APTR paramPkt);		uint32 CallHookPkt(struct Hook *hook, APTR object, APTR paramPkt);
	</syntaxhighlight>		</syntaxhighlight>
Line 48:		Line 48:
	For a callback function written in C, the parameters must appear in this order:		For a callback function written in C, the parameters must appear in this order:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	myCallbackFunction(Pointer to Hook, // A0 in 68000		myCallbackFunction(Pointer to Hook, // A0 in 68000
	Pointer to Object, // A2 in 68000		Pointer to Object, // A2 in 68000
Line 58:		Line 58:
	The following is a simple function that can be used in a callback hook which indicates which context it is running on.		The following is a simple function that can be used in a callback hook which indicates which context it is running on.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 MyFunction (struct Hook h, VOID o, VOID *msg)		uint32 MyFunction (struct Hook h, VOID o, VOID *msg)
	{		{
Line 75:		Line 75:
	The following example shows how to allocate a Hook structure dynamically:		The following example shows how to allocate a Hook structure dynamically:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Hook *hook = IExec->AllocSysObjectTags(ASOT_HOOK,		struct Hook *hook = IExec->AllocSysObjectTags(ASOT_HOOK,
	ASOHOOK_Entry, func,		ASOHOOK_Entry, func,
Line 84:		Line 84:
	The following simple function initializes a static Hook structure.		The following simple function initializes a static Hook structure.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* This simple function is used to initialize a Hook */		/* This simple function is used to initialize a Hook */
	VOID InitHook (struct Hook h, uint32 (func)(), VOID *data)		VOID InitHook (struct Hook h, uint32 (func)(), VOID *data)
Line 101:		Line 101:
	The following is a simple example of a callback hook function.		The following is a simple example of a callback hook function.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// hooks1.c		// hooks1.c

Steven Solie at 21:21, 26 March 2014

2014-03-26T21:21:46Z

← Older revision		Revision as of 21:21, 26 March 2014
Line 1:		Line 1:
	== Callback Hooks ==		= Callback Hooks =

	The callback feature provides a standard means for applications to extend the functionality of libraries, devices, and applications. This standard makes it easy for the operating system to use custom modules from different high level programming languages as part of the operating system. For example, the layers library, which takes care of treating a display as a series of layered regions, allows an application to attach a pattern function to a display layer. Instead of filling in the background of a layer with the background color, the layers library calls the custom pattern function which fills in the layer display with a custom background pattern.		The callback feature provides a standard means for applications to extend the functionality of libraries, devices, and applications. This standard makes it easy for the operating system to use custom modules from different high level programming languages as part of the operating system. For example, the layers library, which takes care of treating a display as a series of layered regions, allows an application to attach a pattern function to a display layer. Instead of filling in the background of a layer with the background color, the layers library calls the custom pattern function which fills in the layer display with a custom background pattern.

	=== Callback Hook Structure and ~~Function~~ ===		= Callback Hook Structure and Functions =

	An application passes a custom function in the form of a callback Hook (from <utility/hooks.h>):		An application passes a custom function in the form of a callback Hook (from <utility/hooks.h>):
Line 21:		Line 21:

	; h_Entry		; h_Entry
			: This is the address of the callback function.
	: ~~This is the address of the callback function.~~ Since AmigaOS 4.0, all callbacks adhere to the PowerPC SysV ABI which is stack based and therefore the order of the parameters is important. When AmigaOS ran only on 68000 based CPUs, this entry would point to a hook stub which would take the arguments from 68000 registers A0, A1, and A2, push them on the stack and finally call h_SubEntry.		: Since AmigaOS 4.0, all callbacks adhere to the PowerPC SysV ABI which is stack based and therefore the order of the parameters is important. When AmigaOS ran only on 68000 based CPUs, this entry would point to a hook stub which would take the arguments from 68000 registers A0, A1, and A2, push them on the stack and finally call h_SubEntry.

	; h_SubEntry		; h_SubEntry
Line 37:		Line 38:
	CallHookPkt will always ensure the correct procedure is used to invoke a callback. If the callback points to PowerPC code, it will be called directly. If the callback points to 68000 code, it will invoke the emulator and take the appropriate action.		CallHookPkt will always ensure the correct procedure is used to invoke a callback. If the callback points to PowerPC code, it will be called directly. If the callback points to 68000 code, it will invoke the emulator and take the appropriate action.

	=== Simple Callback Hook Usage ===		= Simple Callback Hook Usage =

	A Hook function accepts the following three parameters in the order specified:		A Hook function accepts the following three parameters in the order specified:
Line 138:		Line 139:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

			= Function Reference =

			The following are brief descriptions of the utility library functions which pertain to callback hooks. See the SDK for details on each function call.

			{\| class="wikitable"
			! Function
			! Description
			\|-
			\| CallHookPkt()
			\| Call a standard callback Hook function.
			\|}

Steven Solie: Created page with "== Callback Hooks == The callback feature provides a standard means for applications to extend the functionality of libraries, devices, and applications. This standard makes ..."

2014-03-26T21:09:39Z

Created page with "== Callback Hooks == The callback feature provides a standard means for applications to extend the functionality of libraries, devices, and applications. This standard makes ..."

New page

== Callback Hooks ==

The callback feature provides a standard means for applications to extend the functionality of libraries, devices, and applications. This standard makes it easy for the operating system to use custom modules from different high level programming languages as part of the operating system. For example, the layers library, which takes care of treating a display as a series of layered regions, allows an application to attach a pattern function to a display layer. Instead of filling in the background of a layer with the background color, the layers library calls the custom pattern function which fills in the layer display with a custom background pattern.

=== Callback Hook Structure and Function ===

An application passes a custom function in the form of a callback Hook (from <utility/hooks.h>):

<syntaxhighlight>
struct Hook
{
struct MinNode h_MinNode;
ULONG (*h_Entry)(); /* function entry point */
ULONG (*h_SubEntry)(); /* secondary function entry point (not usually used) */
VOID *h_Data; /* owner specific */
};
</syntaxhighlight>

; h_MinNode
: This field is reserved for use by the module that will call the Hook.

; h_Entry
: This is the address of the callback function. Since AmigaOS 4.0, all callbacks adhere to the PowerPC SysV ABI which is stack based and therefore the order of the parameters is important. When AmigaOS ran only on 68000 based CPUs, this entry would point to a hook stub which would take the arguments from 68000 registers A0, A1, and A2, push them on the stack and finally call h_SubEntry.

; h_SubEntry
: This is the address of the secondary function entry point. It should only used when emulating 68000 code.

; h_Data
: This field is for the application to use. It could point to a global storage structure that the callback function utilizes.

There is only one function defined in utility library that relates to callback hooks:

<syntaxhighlight>
uint32 CallHookPkt(struct Hook *hook, APTR object, APTR paramPkt);
</syntaxhighlight>

CallHookPkt will always ensure the correct procedure is used to invoke a callback. If the callback points to PowerPC code, it will be called directly. If the callback points to 68000 code, it will invoke the emulator and take the appropriate action.

=== Simple Callback Hook Usage ===

A Hook function accepts the following three parameters in the order specified:

# Pointer to the Hook structure.
# Pointer to an object to manipulate. The object is context specific.
# Pointer to a message packet. This is also context specific.

For a callback function written in C, the parameters must appear in this order:

<syntaxhighlight>
myCallbackFunction(Pointer to Hook, // A0 in 68000
Pointer to Object, // A2 in 68000
Pointer to message); // A1 in 68000
</syntaxhighlight>

A callback function is executed on the context of the module that invoked it. This usually means that callback functions cannot call functions that need to look at environment specific data. For example, Printf() needs to look at the current process's input and output stream. Entities like Intuition have no input and output stream. To find out which context your callback is running on use the FindTask() function from Exec.

The following is a simple function that can be used in a callback hook which indicates which context it is running on.

<syntaxhighlight>
uint32 MyFunction (struct Hook *h, VOID *o, VOID *msg)
{
struct Task *task = IExec->FindTask(0);

/* Debugging function to send a string to the serial port */
IExec->DebugPrintF("MyFunction() running on Task %s\n",
(task->tc_Node.ln_Name == NULL) ? "NoName" : task->tc_Node.ln_Name);

return 1;
}
</syntaxhighlight>

The next step is to initialize the Hook for use. This basically means that the fields of the Hook structure must be filled with appropriate values. There are two ways to accomplish this. Either use the AllocSysObject() function with an object type of ASOT_HOOK or declare the hook statically and manually initialize the fields.

The following example shows how to allocate a Hook structure dynamically:

<syntaxhighlight>
struct Hook *hook = IExec->AllocSysObjectTags(ASOT_HOOK,
ASOHOOK_Entry, func,
ASOHOOK_Data, data,
TAG_END);
</syntaxhighlight>

The following simple function initializes a static Hook structure.

<syntaxhighlight>
/* This simple function is used to initialize a Hook */
VOID InitHook (struct Hook *h, uint32 (*func)(), VOID *data)
{
/* Make sure a pointer was passed */
if (h != NULL)
{
/* Fill in the hook fields */
h->h_Entry = func;
h->h_SubEntry = NULL;
h->h_Data = data;
}
}
</syntaxhighlight>

The following is a simple example of a callback hook function.

<syntaxhighlight>
// hooks1.c

#include <exec/types.h>
#include <exec/libraries.h>
#include <utility/hooks.h>
#include <dos.h>

// Note the newlib startup code opens these libraries.
#include <proto/exec.h>
#include <proto/utility.h>

/* This function only prints out a message indicating that we are
* inside the callback function.
*/
uint32 MyFunction (struct Hook *h, VOID *o, VOID *msg)
{
/* Debugging function to send a string to the serial port */
IExec->DebugPrintF("Inside MyFunction()\n");

return (1);
}

int main()
{
struct Hook *h = IExec->AllocSysObjectTags(ASOT_HOOK,
ASOHOOK_Entry, MyFunction,
TAG_END);

if (h != NULL)
{
/* Use the utility library function to invoke the Hook */
IUtility->CallHookPkt (h, NULL, NULL);

IExec->FreeSysObject(ASOT_HOOK, h);
}
}
</syntaxhighlight>