1

#ifndef SOCK_H

     2

#define SOCK_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Low-level socket-related functions

     8

 */

     9

#include "error.h"

    10

#include <sys/types.h>

    11

#include <event2/event.h>

    12

    13

/**

    14

 * The generic stream socket handle

    15

 */

    16

struct sock_stream;

    17

    18

/**

    19

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

    20

 * otherwise, it failed.

    21

 */

    22

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

    23

    24

/**

    25

 * Async callbacks for socket operation

    26

 */

    27

struct sock_stream_callbacks {

    28

    /** Socket is readable */

    29

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

    30

    31

    /** Socket is writeable */

    32

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

    33

};

    34

    35

/**

    36

 * Socket function error codes

    37

 */

    38

enum sock_error_code {

    39

    _ERR_SOCK_BEGIN = _ERR_SOCK,

    40

    ERR_SOCKET,

    41

    42

    /** connect() error, either direct or async */

    43

    ERR_CONNECT,

    44

    ERR_READ,

    45

    46

    /** EOF on read() */

    47

    ERR_READ_EOF,

    48

    ERR_WRITE,

    49

    50

    /** EOF on write()  */

    51

    ERR_WRITE_EOF,

    52

    ERR_FCNTL,

    53

    54

    /** Lingering error on close() */

    55

    ERR_CLOSE,

    56

    ERR_GETSOCKOPT,

    57

};

    58

    59

/**

    60

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

    61

 *

    62

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

    63

 *

    64

 * @param ev_base the libevent base to use for events

    65

 * @param err returned error info

    66

 */

    67

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

    68

    69

/**

    70

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

    71

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

    72

 *

    73

 * @param sock_ptr the new sock_stream

    74

 * @param host the hostname to connect to

    75

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

    76

 * @param err returned error info

    77

 */

    78

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

    79

    80

/**

    81

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

    82

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

    83

 *

    84

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

    85

 *

    86

 * XXX: blocking DNS resolution

    87

 *

    88

 * @param sock_ptr the new sock_stream

    89

 * @param host the hostname to connect to

    90

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

    91

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

    92

 * @param cb_arg opaque context argument passed back to cb_func

    93

 * @param err returned error info

    94

 */

    95

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

    96

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

    97

    98

/**

    99

 * A simple blocking SSL connect to the given host/service. The connected/handshake'd SSL socket is returned via

   100

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

   101

 *

   102

 * @param sock_ptr the new sock_stream

   103

 * @param host the hostname to connect to

   104

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

   105

 * @param err returned error info

   106

 *

   107

 * XXX: blocking

   108

 * XXX: doesn't do any certificate verification.

   109

 */

   110

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

   111

   112

/**

   113

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

   114

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

   115

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

   116

 * sock_stream_event_enable() to wait for more data.

   117

 *

   118

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

   119

 * sock_stream_error()..

   120

 *

   121

 * @param sock the socket to read the bytes from

   122

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

   123

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

   124

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

   125

 */

   126

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

   127

   128

/**

   129

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

   130

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

   131

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

   132

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

   133

 *

   134

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

   135

 * sock_stream_error().

   136

 *

   137

 * @param sock the socket to write the bytes to

   138

 * @param buf the byte buffer

   139

 * @param len number of bytes to write

   140

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

   141

 */

   142

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

   143

   144

/**

   145

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

   146

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

   147

 *

   148

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

   149

 *

   150

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

   151

 * @param callbacks the on_read/on_write callbacks to invoke

   152

 * @param arg the context argument for the callbacks

   153

 */

   154

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

   155

   156

/**

   157

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

   158

 *

   159

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

   160

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

   161

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

   162

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

   163

 */

   164

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

   165

   166

/**

   167

 * Get current error_info for \a sock.

   168

 */

   169

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

   170

   171

/**

   172

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

   173

 *

   174

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

   175

 */

   176

void sock_stream_release (struct sock_stream *sock);

   177

   178

#endif