Date: Thu, 4 Jan 2007 15:10:01 -0500                                                                
From: Aidan Van Dyk <aidan@ifax.com>                                                                
Subject: [hylafax-devel] Generic hook mechanism                                                     
To: hylafax-devel@hylafax.org                                                                       
Message-ID: <20070104201001.GD13225@yugib.highrise.ca>                                              


Sparked Alessandro's patch for a "submit" hook script, I sat down this                              
morning and tried out a generic hook mechanism.                                                     
                                                                                                    
FaxQueuer already has generic "Trigger" mechanism in it, which allows                               
clients to get notification of any event as it happens in faxq already                              
(See the Trigger classes).                                                                          
                                                                                                    
What this patch does is ties into the trigger calls to add the possible                             
invokation of a program.  This means that you have access to *any* of                               
the events that faxq triggers (see the faxwatch man page, or grep for                               
Trigger::post in faxQueueApp.c++.                                                                   
                                                                                                    
This patch addes a config option for faxq, not yet documented, but                                  
something like:                                                                                     
                                                                                                    
        AuditHook:    <string>        -       specific a faxq hook for events                     
                                                                                                    
        AuditHook:                                                                                
          Syntax is like  "program: spec", where program is the program                             
          to invoke, and spec is the specification, like J*M*S*R* as                                
          described in the faxwatch man page.                                                       
                                                                                                    
                                                                                                    
This means that putting                                                                             
        AuditHook:            "bin/hook: J*S*M*R*"                                                
into your faxq config file will cause it to run bin/hook on *every*                                 
event.                                                                                              
                                                                                                    
The arguments passed to the hook program are:                                 
                                                                                                    
$PROGRAM <class> <mask> <id> [info]                                                                 
                                                                                                    
        <class> = JOB | SEND | MODEM | RECV                                                         
        <mask> = the specific event (see faxwatch man page)                                         
        <id> = id of the job/modem the event is associated with                                     
        [info] = extra info that faxq passes for the event.                                         
                                                                                                    
I use the full names for <class> instead of just th J/S/R/M, but I could                            
use the letters if people think it's more consistent.                                               
                                                                                                    
Also not that if you use an id in your specification in the config file,                            
that id will *not* be honoured.  All masks for the hook are global.  I                              
looked into making them id away (because triggers are id aware), but the                            
mechanism for that is tied heavily to the HylaClient class, and that                                
requries the hfaxd/faxq fifo communication, and wasn't easily usable.                               
But generally, I think hooks want to be global anyways...                                           
                                                                                                    
With a simple hook script:                                                                          
        #!/bin/sh                                                                                   
        logger -p local1.info -t "hook[$$]" "ARGS: $*"                                              
                                                                                                    
You get results like this in syslog:                                                                
        Jan  4 14:14:22 espresso hook[24465]: ARGS: MODEM 0x0008 ttyds01                            
        Jan  4 14:14:30 espresso hook[24477]: ARGS: MODEM 0x0008 ttyds01                            
        Jan  4 14:14:39 espresso hook[24495]: ARGS: MODEM 0x0008 ttyds01                            
        Jan  4 14:14:51 espresso hook[24531]: ARGS: JOB 0x0001 33                                   
        Jan  4 14:14:56 espresso hook[24535]: ARGS: JOB 0x0004 33                                   
        Jan  4 14:14:57 espresso hook[24537]: ARGS: JOB 0x0020 33                                   
        Jan  4 14:18:25 espresso hook[24679]: ARGS: JOB 0x0001 33                                   
        Jan  4 14:18:25 espresso hook[24682]: ARGS: MODEM 0x0008 ttyds01                            
        Jan  4 14:18:30 espresso hook[24685]: ARGS: JOB 0x0004 33                                   
        Jan  4 14:18:31 espresso hook[24687]: ARGS: JOB 0x0020 33                                   
        Jan  4 14:24:30 espresso hook[24840]: ARGS: JOB 0x0001 33                                   
        Jan  4 14:24:30 espresso hook[24843]: ARGS: MODEM 0x0008 ttyds01                            
        Jan  4 14:24:35 espresso hook[24846]: ARGS: JOB 0x0004 33                                   
        Jan  4 14:24:36 espresso hook[24848]: ARGS: JOB 0x0020 33                                   
                                                                                                    
Comments?  Anybody think of ways to make this more usefull, or more                                 
practical?                                                                                          
                                                                                                    
a.                                                                                                  
                                                                                                    
                                                                                                    
--                                                                                                  
Aidan Van Dyk                                             aidan@ifax.com                            
Senior Software Developer                          +1 215 825-8700 x8103                            
iFAX Solutions, Inc.                                http://www.ifax.com/