Debian Codegraph @

doc/html/_sources/imap/developer/guidance/prot.rst.txt

raw
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 $