1

#ifndef SOCK_H

     2

#define SOCK_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Low-level socket-related functions

     8

 *

     9

 * XXX: not just sockets anymore

    10

 */

    11

#include "error.h"

    12

#include <sys/types.h>

    13

#include <event2/event.h>

    14

    15

/**

    16

 * The generic stream socket handle

    17

 */

    18

struct sock_stream;

    19

    20

/**

    21

 * Callback for connect_async completion notification. If err is NULL, the connection completed succesfully,

    22

 * otherwise, it failed.

    23

 */

    24

typedef void (*sock_stream_connect_cb) (struct sock_stream *sock, struct error_info *err, void *arg);

    25

    26

/**

    27

 * Async callbacks for socket operation

    28

 */

    29

struct sock_stream_callbacks {

    30

    /** Socket is readable */

    31

    void (*on_read) (struct sock_stream *sock, void *arg);

    32

    33

    /** Socket is writeable */

    34

    void (*on_write) (struct sock_stream *sock, void *arg);

    35

};

    36

    37

/**

    38

 * Socket function error codes

    39

 */

    40

enum sock_error_code {

    41

    _ERR_SOCK_BEGIN = _ERR_SOCK,

    42

    ERR_SOCKET,         ///< socket(2) failed

    43

    ERR_CONNECT,        ///< connect(2) error - either direct or async

    44

    ERR_READ,           ///< read(2) error - will probably show up as an ERR_WRITE as well

    45

    ERR_READ_EOF,       ///< EOF on read(2)

    46

    ERR_WRITE,          ///< write(2) error - data was unsent, will probably show up as an ERR_READ as well

    47

    ERR_WRITE_EOF,      ///< write(2) gave EOF - zero bytes written

    48

    ERR_FCNTL,          ///< fcntl(2) failed

    49

    ERR_CLOSE,          ///< close(2) failed, some written data was probably not sent

    50

    ERR_GETSOCKOPT,     ///< getsockopt(2) failed

    51

    ERR_OPEN,           ///< open(2) failed

    52

};

    53

    54

/**

    55

 * Initialize the socket module's global state. Call this before calling any other sock_* functions.

    56

 *

    57

 * The given \a ev_base is the libevent base to use for nonblocking operation.

    58

 *

    59

 * @param ev_base the libevent base to use for events

    60

 * @param err returned error info

    61

 */

    62

err_t sock_init (struct event_base *ev_base, struct error_info *err);

    63

    64

/**

    65

 * A simple TCP connect to the given host/service, using getaddrinfo. The connected socket is returned via *sock_ptr. 

    66

 * In case of errors, additional error information is stored in *err.

    67

 *

    68

 * @param sock_ptr the new sock_stream

    69

 * @param host the hostname to connect to

    70

 * @param service the service name (i.e. port) to connect to

    71

 * @param err returned error info

    72

 */

    73

err_t sock_tcp_connect (struct sock_stream **sock_ptr, const char *host, const char *service, struct error_info *err);

    74

    75

/**

    76

 * Start a non-blocking TCP connect to the given host/service. The socket will not yet be connected once the function

    77

 * returns, but rather, the readyness of the socket will be indicated later using the given \a cb_func.

    78

 *

    79

 * Note that currently it is an error to call sock_stream_event_init before the cb_func has been called.

    80

 *

    81

 * XXX: blocking DNS resolution

    82

 *

    83

 * @param sock_ptr the new sock_stream

    84

 * @param host the hostname to connect to

    85

 * @param service the service name (i.e. port) to connect to

    86

 * @param cb_func the callback used to handle the result of the async operation

    87

 * @param cb_arg opaque context argument passed back to cb_func

    88

 * @param err returned error info

    89

 */

    90

err_t sock_tcp_connect_async (struct sock_stream **sock_ptr, const char *host, const char *service, 

    91

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

    92

    93

/**

    94

 * A read-only "socket" based on a FIFO, this provides nonblocking read operations by re-opening the FIFO on EOF.

    95

 */

    96

err_t fifo_open_read (struct sock_stream **stream_ptr, const char *path, struct error_info *err);

    97

    98

/**

    99

 * Read a series of bytes from the socket into the given \a buf (up to \a len bytes). If succesfull, this returns

   100

 * the number of bytes read (which will be less than or equal to \a len). If the socket is nonblocking (i.e.

   101

 * sock_stream_event_init() was set), and there is no data available, this returns zero, and one should use

   102

 * sock_stream_event_enable() to wait for more data.

   103

 *

   104

 * On errors, this returns the negative err_t code, and the specific error information can be accessed using

   105

 * sock_stream_error()..

   106

 *

   107

 * @param sock the socket to read the bytes from

   108

 * @param buf the byte buffer to write the bytes into

   109

 * @param len the number of bytes to read into the buffer

   110

 * @return bytes read, zero if none available, -err_t

   111

 */

   112

int sock_stream_read (struct sock_stream *sock, void *buf, size_t len);

   113

   114

/**

   115

 * Write a series of bytes from the given \a buf (containing \a len bytes) to the socket. If succesfull, this returns

   116

 * the number of bytes written (which may be less than \a len if the OS write buffer was full). If the socket is

   117

 * nonblocking (i.e. sock_stream_event_init() was set), and the operation would have blocked, no data was written, and

   118

 * this returns zero, and one should use sock_stream_event_enable() to retry.

   119

 *

   120

 * On errors, this returns the negative err_t code, and the specific error information can be accessed using

   121

 * sock_stream_error().

   122

 *

   123

 * @param sock the socket to write the bytes to

   124

 * @param buf the byte buffer

   125

 * @param len number of bytes to write

   126

 * @return bytes written, zero if would have blocked, -err_t

   127

 */

   128

int sock_stream_write (struct sock_stream *sock, const void *buf, size_t len);

   129

   130

/**

   131

 * Initialize event-based operation for this sock_stream. This will set the stream into nonblocking mode, and the given

   132

 * callbacks will be fired once enabled using sock_stream_event_enable().

   133

 *

   134

 * Note that the callbacks struct isn't copied - it's used as-is-given.

   135

 *

   136

 * @param sock the socket to set up for nonblocking operation

   137

 * @param callbacks the on_read/on_write callbacks to invoke

   138

 * @param arg the context argument for the callbacks

   139

 */

   140

err_t sock_stream_event_init (struct sock_stream *sock, const struct sock_stream_callbacks *callbacks, void *arg);

   141

   142

/**

   143

 * Enable some events for this sock, as set up earlier with event_init. Mask should contain EV_READ/EV_WRITE.

   144

 *

   145

 * The implementation of this is slightly hazy for complex protocols; this should only be used to map from

   146

 * sock_stream_read/write to the corresponding sock_stream_callback. That is, if sock_stream_read returns zero, then

   147

 * call event_enable(EV_READ), wherepon on_read will later be called. Other operations (such as calling

   148

 * sock_stream_write with *different* data after it once returns zero) might result in errors.

   149

 */

   150

err_t sock_stream_event_enable (struct sock_stream *sock, short mask);

   151

   152

/**

   153

 * Get current error_info for \a sock.

   154

 */

   155

const struct error_info* sock_stream_error (struct sock_stream *sock);

   156

   157

/**

   158

 * Close and release the given socket, ignoring errors. It must not be used anymore after this.

   159

 *

   160

 * This is intended to be used to abort in case of errors, and does not close the connection cleanly.

   161

 */

   162

void sock_stream_release (struct sock_stream *sock);

   163

   164

#endif