1

#ifndef LINE_PROTO_H

     2

#define LINE_PROTO_H

     3

     4

/*

     5

 * Support for protocols that send/receive lines

     6

 */

     7

#include "sock.h"

     8

#include "error.h"

     9

    10

/*

    11

 * The state handle

    12

 */

    13

struct line_proto;

    14

    15

/*

    16

 * The callback for receiving lines

    17

 */

    18

typedef void (*line_proto_read_cb)(char *line, void *arg);

    19

    20

/**

    21

 * Create a new line_proto off the the given sock_stream. The newly allocated line_proto will be returned via *lp_ptr.

    22

 *

    23

 * The incoming lines are buffered in a buffer of \a buf_size bytes. This imposes a maximum limit on the line length.

    24

 *

    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

    33

 */

    34

err_t line_proto_create (struct line_proto **lp_ptr, struct sock_stream *sock, size_t buf_size,

    35

        line_proto_read_cb cb_func, void *cb_arg, struct error_info *err);

    36

    37

/**

    38

 * Runs the socket recv() into our internal buffer. If a full line was received, a pointer to our internal bufffer is

    39

 * returned via *line_ptr, and we return SUCCESS. If we don't yet have a full line, and receiving more would block,

    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

    43

 */

    44

err_t line_proto_recv (struct line_proto *lp, char **line_ptr);

    45

    46

/**

    47

 * Write a single line to the sock_stream, buffering any incomplete fragment that remains unset. Returns zero if the

    48

 * line was succesfully sent, >0 if it was only partially sent, or -err on errors.

    49

 *

    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

    53

 */

    54

int line_proto_send (struct line_proto *lp, const char *line);

    55

    56

/**

    57

 * Flush out any buffered line fragment. Returns zero if the buffer was flushed empty, >0 if there's still fragments

    58

 * remaining, or -err on errors.

    59

 */

    60

int line_proto_flush (struct line_proto *lp);

    61

    62

/**

    63

 * Get current error_info*

    64

 */

    65

const struct error_info* line_proto_error (struct line_proto *lp);

    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

    74

#endif /* LINE_PROTO_H */