terom@8: #ifndef LINE_PROTO_H
terom@8: #define LINE_PROTO_H
terom@8: 
terom@32: /**
terom@32:  * @file
terom@32:  *
terom@8:  * Support for protocols that send/receive lines
terom@8:  */
terom@8: #include "sock.h"
terom@8: #include "error.h"
terom@8: 
terom@32: /**
terom@32:  * The line_proto state handle
terom@8:  */
terom@8: struct line_proto;
terom@8: 
terom@32: /**
terom@32:  * User callback list
terom@10:  */
terom@32: struct line_proto_callbacks {
terom@32:     /** Handle received line */
terom@32:     void (*on_line) (char *line, void *arg);
terom@33:     
terom@45:     /** Transport failed, the line_proto is corrupt, you should call line_proto_release next. */
terom@33:     void (*on_error) (struct error_info *err, void *arg);
terom@32: };
terom@10: 
terom@28: /**
terom@8:  * Create a new line_proto off the the given sock_stream. The newly allocated line_proto will be returned via *lp_ptr.
terom@10:  *
terom@10:  * The incoming lines are buffered in a buffer of \a buf_size bytes. This imposes a maximum limit on the line length.
terom@10:  *
terom@41:  * Note that the given callbacks struct is copied.
terom@41:  *
terom@28:  * @param lp_ptr a pointer to the new line_proto will be returned via this pointer
terom@28:  * @param sock the sock_stream to use
terom@28:  * @param buf_size the incoming/outgoing buffer size, should be enough to hold the biggest possible line
terom@41:  * @param callbacks the callbacks to use, a copy is stored
terom@28:  * @param cb_arg the read_cb callback argument
terom@28:  * @param err error information is returned via this pointer
terom@8:  */
terom@10: err_t line_proto_create (struct line_proto **lp_ptr, struct sock_stream *sock, size_t buf_size,
terom@32:         const struct line_proto_callbacks *callbacks, void *cb_arg, struct error_info *err);
terom@8: 
terom@28: /**
terom@11:  * Runs the socket recv() into our internal buffer. If a full line was received, a pointer to our internal bufffer is
terom@11:  * returned via *line_ptr, and we return SUCCESS. If we don't yet have a full line, and receiving more would block,
terom@11:  * NULL is returned via *line_ptr instead. Otherwise, nonzero error return code.
terom@28:  *
terom@28:  * @param line_ptr a pointer to the received line is returned via this pointer
terom@8:  */
terom@19: err_t line_proto_recv (struct line_proto *lp, char **line_ptr);
terom@8: 
terom@28: /**
terom@18:  * Write a single line to the sock_stream, buffering any incomplete fragment that remains unset. Returns zero if the
terom@18:  * line was succesfully sent, >0 if it was only partially sent, or -err on errors.
terom@18:  *
terom@18:  * The given line should already include the terminating '\r\n' character sequence.
terom@28:  *
terom@28:  * @param line pointer to buffer containing \r\n\0 terminated line
terom@12:  */
terom@19: int line_proto_send (struct line_proto *lp, const char *line);
terom@19: 
terom@28: /**
terom@19:  * Flush out any buffered line fragment. Returns zero if the buffer was flushed empty, >0 if there's still fragments
terom@19:  * remaining, or -err on errors.
terom@19:  */
terom@19: int line_proto_flush (struct line_proto *lp);
terom@12: 
terom@28: /**
terom@8:  * Get current error_info*
terom@8:  */
terom@8: const struct error_info* line_proto_error (struct line_proto *lp);
terom@8: 
terom@28: /**
terom@28:  * Release any allocated buffers, and the underlying sock_stream.
terom@28:  *
terom@28:  * This does not close the connection cleanly, and is intended for use to abort after errors.
terom@28:  */
terom@28: void line_proto_release (struct line_proto *lp);
terom@28: 
terom@8: #endif /* LINE_PROTO_H */