| 1 |
.. _imap-developer-thoughts-prot-events: |
| 2 |
|
| 3 |
.. Note: This document was converted from the original by Nic Bernstein |
| 4 |
(Onlight). Any formatting mistakes are my fault and not the |
| 5 |
original author's. Converted via the pandoc tool from HTML. |
| 6 |
|
| 7 |
Cyrus IMAP Server: Prot Events |
| 8 |
============================== |
| 9 |
|
| 10 |
From an email exchange between Ken Murchison and Lawrence Greenfield, |
| 11 |
dated 03 Feb 2002 (slightly redacted and formatted for your viewing |
| 12 |
pleasure): |
| 13 |
|
| 14 |
| From: Ken Murchison |
| 15 |
| To: Lawrence Greenfield |
| 16 |
| Subject: Re: prot events |
| 17 |
| |
| 18 |
|
| 19 |
Lawrence Greenfield wrote: |
| 20 |
|
| 21 |
Can you give me some details on how the event API in the prot |
| 22 |
layer works? I'm a little unclear about the memory management, |
| 23 |
what should be returned from the event callback, |
| 24 |
|
| 25 |
Either the event pointer (if the event is still active), or NULL |
| 26 |
(if the event has been removed by the callback). |
| 27 |
|
| 28 |
and how to reschedule an event. |
| 29 |
|
| 30 |
Simply set the 'mark' time in the event to the wall time you want |
| 31 |
it to run again. |
| 32 |
|
| 33 |
(I'd like to make an event called every X seconds of idle time; |
| 34 |
I know the API can't do exactly that but I suspect I can fake |
| 35 |
it well enough.) |
| 36 |
|
| 37 |
Look at backend_timeout() in proxyd.c and/or drac_ping() in |
| 38 |
contrib/drac_auth.patch, they do exactly this. |
| 39 |
|
| 40 |
The API is pretty simple: |
| 41 |
|
| 42 |
* use prot_addwaitevent() to add an event (linked list) callback |
| 43 |
onto a stream. takes the stream, the 'mark' time at which to |
| 44 |
run the event (NOT an interval, but the future clock value), |
| 45 |
the function pointer, and a rock to pass to the callback as |
| 46 |
args, and returns a pointer to the event (to use for future |
| 47 |
removal). |
| 48 |
|
| 49 |
* use prot_removewaitevent() to remove an event. takes the |
| 50 |
stream and a pointer to the event as args. |
| 51 |
|
| 52 |
* the event callback gets the stream, a pointer to the event |
| 53 |
and the rock as args. To reschedule an event, simply set the |
| 54 |
'mark' time and return the event pointer. If the callback |
| 55 |
removes the event, then return NULL. |
| 56 |
|
| 57 |
If you see and flaws in this API, feel free to go ahead and change it. |
| 58 |
|
| 59 |
Ken |