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