| 1 |
.. _imap-developer-guidance-prot-layer: |
| 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. |
| 6 |
|
| 7 |
Cyrus IMAP Server: prot layer |
| 8 |
============================= |
| 9 |
|
| 10 |
The prot layer, defined in ``prot.h``, is a stdio replacement for |
| 11 |
network i/o. It does the standard buffering of input and output and |
| 12 |
allows certain operations especially suited for request/response |
| 13 |
protocols like IMAP. |
| 14 |
|
| 15 |
Events |
| 16 |
------ |
| 17 |
|
| 18 |
The prot layer allows "events" to be associated with each prot stream. |
| 19 |
These events are trigger at the given time or after when the protstream |
| 20 |
is attempted to be read from. |
| 21 |
|
| 22 |
An event is currently represented by the following datastructure: |
| 23 |
|
| 24 |
:: |
| 25 |
|
| 26 |
struct prot_waitevent; |
| 27 |
|
| 28 |
typedef struct prot_waitevent *prot_waiteventcallback_t(struct protstream *s, |
| 29 |
struct prot_waitevent *ev, |
| 30 |
void *rock); |
| 31 |
|
| 32 |
struct prot_waitevent { |
| 33 |
time_t mark; |
| 34 |
prot_waiteventcallback_t *proc; |
| 35 |
void *rock; |
| 36 |
struct prot_waitevent *next; |
| 37 |
}; |
| 38 |
|
| 39 |
The application is currently allowed to modify *mark*, *proc*, and |
| 40 |
*rock* as desired when there are no active calls to a prot function on |
| 41 |
the stream which this event is associated. |
| 42 |
|
| 43 |
The API is as follows: |
| 44 |
|
| 45 |
- Use ``prot_addwaitevent()`` to add an event callback onto the stream: |
| 46 |
|
| 47 |
:: |
| 48 |
|
| 49 |
extern struct prot_waitevent *prot_addwaitevent(struct protstream *s, |
| 50 |
time_t mark, |
| 51 |
prot_waiteventcallback_t *proc, |
| 52 |
void *rock); |
| 53 |
|
| 54 |
where *s* is the stream to add the event to, *mark* is the time to |
| 55 |
trigger the event, *proc* is the callback to make, and *rock* is an |
| 56 |
opaque data item handed to the callback. It returns a pointer to the |
| 57 |
event structure; this is the pointer that must be used to remove the |
| 58 |
event or modify it in some way. |
| 59 |
|
| 60 |
- Use ``prot_removewaitevent()`` to remove an event: |
| 61 |
|
| 62 |
:: |
| 63 |
|
| 64 |
extern void prot_removewaitevent(struct protstream *s, |
| 65 |
struct prot_waitevent *event); |
| 66 |
|
| 67 |
It requires *event* to have been returned from |
| 68 |
``prot_addwaitevent()`` previously. No further references are allowed |
| 69 |
to *event* or its fields. *event->rock* is not free'd nor examined in |
| 70 |
any way. This function may be called while inside the callback |
| 71 |
*event->proc()*. If an event is removed inside of its callback, that |
| 72 |
callback must return ``NULL``. |
| 73 |
|
| 74 |
Some common things to do with events: |
| 75 |
|
| 76 |
- To reschedule an event *ev*, simply set *ev->mark* to the next time |
| 77 |
it should trigger. If currently in *ev->proc()*, it should return |
| 78 |
*ev*. |
| 79 |
|
| 80 |
-------------- |
| 81 |
|
| 82 |
last modified: $Date: 2003/08/06 21:28:05 $ |