1 #ifndef LIBQMSK_LINE_PROTO_H

     2 #define LIBQMSK_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