15 /* |
15 /* |
16 * The callback for receiving lines |
16 * The callback for receiving lines |
17 */ |
17 */ |
18 typedef void (*line_proto_read_cb)(char *line, void *arg); |
18 typedef void (*line_proto_read_cb)(char *line, void *arg); |
19 |
19 |
20 /* |
20 /** |
21 * Create a new line_proto off the the given sock_stream. The newly allocated line_proto will be returned via *lp_ptr. |
21 * Create a new line_proto off the the given sock_stream. The newly allocated line_proto will be returned via *lp_ptr. |
22 * |
22 * |
23 * The incoming lines are buffered in a buffer of \a buf_size bytes. This imposes a maximum limit on the line length. |
23 * The incoming lines are buffered in a buffer of \a buf_size bytes. This imposes a maximum limit on the line length. |
24 * |
24 * |
25 * The given callback function/argument will be used to provide event-based recv support. |
25 * The given callback function/argument will be used to provide event-based recv support. |
|
26 * |
|
27 * @param lp_ptr a pointer to the new line_proto will be returned via this pointer |
|
28 * @param sock the sock_stream to use |
|
29 * @param buf_size the incoming/outgoing buffer size, should be enough to hold the biggest possible line |
|
30 * @param cb_func the read_cb callback |
|
31 * @param cb_arg the read_cb callback argument |
|
32 * @param err error information is returned via this pointer |
26 */ |
33 */ |
27 err_t line_proto_create (struct line_proto **lp_ptr, struct sock_stream *sock, size_t buf_size, |
34 err_t line_proto_create (struct line_proto **lp_ptr, struct sock_stream *sock, size_t buf_size, |
28 line_proto_read_cb cb_func, void *cb_arg, struct error_info *err); |
35 line_proto_read_cb cb_func, void *cb_arg, struct error_info *err); |
29 |
36 |
30 /* |
37 /** |
31 * Runs the socket recv() into our internal buffer. If a full line was received, a pointer to our internal bufffer is |
38 * Runs the socket recv() into our internal buffer. If a full line was received, a pointer to our internal bufffer is |
32 * returned via *line_ptr, and we return SUCCESS. If we don't yet have a full line, and receiving more would block, |
39 * returned via *line_ptr, and we return SUCCESS. If we don't yet have a full line, and receiving more would block, |
33 * NULL is returned via *line_ptr instead. Otherwise, nonzero error return code. |
40 * NULL is returned via *line_ptr instead. Otherwise, nonzero error return code. |
|
41 * |
|
42 * @param line_ptr a pointer to the received line is returned via this pointer |
34 */ |
43 */ |
35 err_t line_proto_recv (struct line_proto *lp, char **line_ptr); |
44 err_t line_proto_recv (struct line_proto *lp, char **line_ptr); |
36 |
45 |
37 /* |
46 /** |
38 * Write a single line to the sock_stream, buffering any incomplete fragment that remains unset. Returns zero if the |
47 * Write a single line to the sock_stream, buffering any incomplete fragment that remains unset. Returns zero if the |
39 * line was succesfully sent, >0 if it was only partially sent, or -err on errors. |
48 * line was succesfully sent, >0 if it was only partially sent, or -err on errors. |
40 * |
49 * |
41 * The given line should already include the terminating '\r\n' character sequence. |
50 * The given line should already include the terminating '\r\n' character sequence. |
|
51 * |
|
52 * @param line pointer to buffer containing \r\n\0 terminated line |
42 */ |
53 */ |
43 int line_proto_send (struct line_proto *lp, const char *line); |
54 int line_proto_send (struct line_proto *lp, const char *line); |
44 |
55 |
45 /* |
56 /** |
46 * Flush out any buffered line fragment. Returns zero if the buffer was flushed empty, >0 if there's still fragments |
57 * Flush out any buffered line fragment. Returns zero if the buffer was flushed empty, >0 if there's still fragments |
47 * remaining, or -err on errors. |
58 * remaining, or -err on errors. |
48 */ |
59 */ |
49 int line_proto_flush (struct line_proto *lp); |
60 int line_proto_flush (struct line_proto *lp); |
50 |
61 |
51 /* |
62 /** |
52 * Get current error_info* |
63 * Get current error_info* |
53 */ |
64 */ |
54 const struct error_info* line_proto_error (struct line_proto *lp); |
65 const struct error_info* line_proto_error (struct line_proto *lp); |
55 |
66 |
|
67 /** |
|
68 * Release any allocated buffers, and the underlying sock_stream. |
|
69 * |
|
70 * This does not close the connection cleanly, and is intended for use to abort after errors. |
|
71 */ |
|
72 void line_proto_release (struct line_proto *lp); |
|
73 |
56 #endif /* LINE_PROTO_H */ |
74 #endif /* LINE_PROTO_H */ |