1

#ifndef LINE_PROTO_H

     2

#define LINE_PROTO_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Support for protocols that send/receive lines

     8

 */

     9

#include "sock.h"

    10

#include "error.h"

    11

    12

/**

    13

 * The line_proto state handle

    14

 */

    15

struct line_proto;

    16

    17

/**

    18

 * User callback list

    19

 */

    20

struct line_proto_callbacks {

    21

    /** Handle received line */

    22

    void (*on_line) (char *line, void *arg);

    23

    25

    void (*on_error) (struct error_info *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

 * Note that the given callbacks struct is copied.

    34

 *

    35

 * @param lp_ptr a pointer to the new line_proto will be returned via this pointer

    36

 * @param sock the sock_stream 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, struct sock_stream *sock, size_t buf_size,

    43

        const struct line_proto_callbacks *callbacks, void *cb_arg, struct error_info *err);

    44

    45

/**

    46

 * Runs the socket recv() into 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 unset. 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

int line_proto_flush (struct line_proto *lp);

    69

    70

/**

    71

 * Get current error_info*

    72

 */

    73

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

    74

    75

/**

    76

 * Release any allocated buffers, and the underlying sock_stream.

    77

 *

    78

 * This does not close the connection cleanly, and is intended for use to abort after errors.

    79

 */

    80

void line_proto_release (struct line_proto *lp);

    81

    82

#endif /* LINE_PROTO_H */