1 #ifndef LINE_PROTO_H |
|
2 #define LINE_PROTO_H |
|
3 |
|
4 /** |
|
5 * @file |
|
6 * |
|
7 * Support for protocols that send/receive lines |
|
8 */ |
|
9 #include "transport.h" |
|
10 #include "error.h" |
|
11 |
|
12 /** |
|
13 * The line_proto state handle |
|
14 */ |
|
15 struct line_proto; |
|
16 |
|
17 /** |
|
18 * User callbacks for event-based line_proto behaviour |
|
19 */ |
|
20 struct line_proto_callbacks { |
|
21 /** Handle received line */ |
|
22 void (*on_line) (char *line, void *arg); |
|
23 |
|
24 /** Transport failed, the line_proto is corrupt, you should call line_proto_release next. */ |
|
25 void (*on_error) (const error_t *err, void *arg); |
|
26 }; |
|
27 |
|
28 /** |
|
29 * Create a new line_proto off the the given sock_stream. The newly allocated line_proto will be returned via *lp_ptr. |
|
30 * |
|
31 * The incoming lines are buffered in a buffer of \a buf_size bytes. This imposes a maximum limit on the line length. |
|
32 * |
|
33 * In case of errors, \a transport will be destroyed in any case. |
|
34 * |
|
35 * @param lp_ptr a pointer to the new line_proto will be returned via this pointer |
|
36 * @param transport the connected transport to use |
|
37 * @param buf_size the incoming/outgoing buffer size, should be enough to hold the biggest possible line |
|
38 * @param callbacks the callbacks to use, a copy is stored |
|
39 * @param cb_arg the read_cb callback argument |
|
40 * @param err error information is returned via this pointer |
|
41 */ |
|
42 err_t line_proto_create (struct line_proto **lp_ptr, transport_t *transport, size_t buf_size, |
|
43 const struct line_proto_callbacks *callbacks, void *cb_arg, error_t *err); |
|
44 |
|
45 /** |
|
46 * Runs transport_read() with our internal buffer. If a full line was received, a pointer to our internal bufffer is |
|
47 * returned via *line_ptr, and we return SUCCESS. If we don't yet have a full line, and receiving more would block, |
|
48 * NULL is returned via *line_ptr instead. Otherwise, nonzero error return code. |
|
49 * |
|
50 * @param line_ptr a pointer to the received line is returned via this pointer |
|
51 */ |
|
52 err_t line_proto_recv (struct line_proto *lp, char **line_ptr); |
|
53 |
|
54 /** |
|
55 * Write a single line to the sock_stream, buffering any incomplete fragment that remains unsent. Returns zero if the |
|
56 * line was succesfully sent, >0 if it was only partially sent, or -err on errors. |
|
57 * |
|
58 * The given line should already include the terminating '\r\n' character sequence. |
|
59 * |
|
60 * @param line pointer to buffer containing \r\n\0 terminated line |
|
61 */ |
|
62 int line_proto_send (struct line_proto *lp, const char *line); |
|
63 |
|
64 /** |
|
65 * Flush out any buffered line fragment. Returns zero if the buffer was flushed empty, >0 if there's still fragments |
|
66 * remaining, or -err on errors. |
|
67 * |
|
68 * It is a bug to call this if there is no data waiting to be sent. |
|
69 */ |
|
70 int line_proto_flush (struct line_proto *lp); |
|
71 |
|
72 /** |
|
73 * Get current error_info* |
|
74 */ |
|
75 const error_t* line_proto_error (struct line_proto *lp); |
|
76 |
|
77 /** |
|
78 * Destroy any buffers and the underlying transport. |
|
79 * |
|
80 * This does not close the connection cleanly, and is intended for use to abort after errors. |
|
81 */ |
|
82 void line_proto_destroy (struct line_proto *lp); |
|
83 |
|
84 #endif /* LINE_PROTO_H */ |
|