The ASL_HookFunc tag passes an ASL requester a pointer to a custom function. The requester can use this function for two purposes. The first is to determine if the requester should display a particular file or font name. The other purpose is to process messages that the requester receives at its IDCMP port that are not meant for the requester. Some ASL_FuncFlags flags toggle these options: FILF_DOWILDFUNC FONF_DOWILDFUNC FILF_DOMSGFUNC FONF_DOMSGFUNC The FILF_DOWILDFUNC and FONF_DOWILDFUNC flags cause a requester to call the hook function for every file or font entry. The requester displays the file or font name only if the hook function tells it to. For a file requester, if the hook function returns a zero, the file requester will display the file name. For a font requester, if the hook function returns anything but zero, the font requester will display the font name and size. Note that if the DOWILDFUNC function changes the current directory, it must restort the current directory before it exits. Neglecting to restore the current directory can confuse DOS. The FILF_DOMSGFUNC and FONF_DOMSGFUNC flags cause a requester to call the hook function when it receives certain IntuiMessages at the IDCMP port it shares with a window (see the ASL_Window tag). The requester passes on IntuiMessages not meant for the requester. The hook function is responsible for returning a pointer to the IntuiMessage. The requester will take care of replying to the message. A requester passes three parameters to the hook function: ULONG MyHookFunc(ULONG type, CPTR object, CPTR AslRequester) If MyHookFunc() is called from a file requester doing DOWILDFUNC: type = FILF_DOWILDFUNC object is a pointer to an AnchorPath structure (from <dos/dosasl.h>) AslRequester is a pointer to the FileRequester that called the hook function (Return a zero to display this file) Note that the AnchorPath structure is a dos.library structure used in pattern matching. See dos.library documentation for more details. Referencing the specific file or directory from within the DOWILDFUNC hook function is a little tricky. For a file requester, the rf_Dir field is not guaranteed to contain the name of the directory being scanned. The correct way to find the file and directory name is from the AnchorPath structure passed to the DOWILDFUNC. The structure contains a FileInfoBlock structure called ap_Info that contains the file name (fib_FileName). The AnchorPath structure's ap_Current field contains a pointer to an AChain structure (from <dos/dosasl.h>) which contains a field called an_Lock. This is a lock on the directory being scanned. If MyHookFunc() is called from a font requester doing DOWILDFUNC: type = FONF_DOWILDFUNC object is a pointer to a TextAttr structure (from <graphics/text.h>) AslRequester is a pointer to the FontRequester that called the hook function (Return non-zero to display this particular font size) If MyHookFunc() is called from a file or font requester doing DOMSGFUNC: type = FILF_DOMSGFUNC object is a pointer to the IntuiMessage for the function to process AslRequester is a pointer to the FileRequester or FontRequester that called the hook function (Return the pointer to the IntuiMessage) Notice that it is possible for a requester to use both DOWILDFUNC and DOMSGFUNC at the same time. The hook function has to differentiate between the two cases by testing the type passed to it. It is not possible for font and file requester to share a hook function for a DOWILDFUNC, because FILF_DOWILDFUNC is defined to be the same value as FONF_DOWILDFUNC, so the hook function cannot tell if object (from the prototype above) is a pointer to an AnchorPath structure or a pointer to a TextAttr structure. It is possible for font and file requesters to share one hook function for DOMSGFUNC (even though FILF_DOMSGFUNC and FONF_DOMSGFUNC are equal) because, in this case, font and file requesters both call the hook function in the same manner. The example FileHook.c illustrates the use of a hook function for both DOWILDFUNC and DOMSGFUNC.
[Back to Amiga Developer Docs]