3

     4

/**

     5

 * @file

     6

 *

     7

 * Support for transport implementations that use POSIX file descriptor streams.

     8

 *

     9

 * This provides the read/write methods, as well as functions to implement the event-based behaviour.

    10

 */

    11

#include "transport_internal.h"

    12

    13

#include <event2/event.h>

    14

#include <stdbool.h>

    15

    16

// forward-declare

    17

struct transport_fd;

    18

    19

/**

    20

 * Our transport_type

    21

 */

    22

extern const struct transport_type transport_fd_type;

    23

    24

/**

    25

 * Low-level callback

    26

 */

    27

typedef void (*transport_fd_callback_func) (struct transport_fd *fd, short what, void *arg);

    28

    29

/**

    30

 * The fd-based transport implementation

    31

 */

    32

struct transport_fd {

    33

    /** Base transport state */

    34

    struct transport base;

    35

    36

    /** Libevent base to use */

    37

    struct event_base *ev_base;

    38

    39

    /** OS file descriptor */

    40

    evutil_socket_t fd;

    41

    42

    /** IO events */

    43

    struct event *ev_read, *ev_write;

    44

    45

    /** Low-level callback */

    46

    transport_fd_callback_func cb_func;

    47

    48

    /** Callback context argument */

    49

    void *cb_arg;

    50

    51

};

    52

    53

/**

    54

 * Get a transport_t pointer from a transport_fd

    55

 */

    56

#define TRANSPORT_FD_BASE(tp_ptr) (&(tp_ptr)->base)

    57

    58

/**

    59

 * Invalid OS FD

    60

 */

    61

#define TRANSPORT_FD_INVALID ((evutil_socket_t) -1)

    62

    63

/**

    64

 * Implementation of transport_methods::read

    65

 */

    66

err_t transport_fd__read (transport_t *transport, void *buf, size_t *len, error_t *err);

    67

    68

/**

    69

 * Implementation of transport_methods::write.

    70

 *

    71

 * If this gets EAGAIN, it will automatically enable the write event, unless masked out.

    72

 */

    73

err_t transport_fd__write (transport_t *transport, const void *buf, size_t *len, error_t *err);

    74

    75

/**

    76

 * Implementation of transport_methods::events.

    77

 *

    78

 * For TRANSPORT_READ, this will simply apply enable/disable as given.

    79

 *

    80

 * For TRANSPORT_WRITE, the write event will only be enabled if given in the mask, *and* the ev_write event is currently

    81

 * active (via transport_fd_methods_write()); otherwise, the write event will not be enabled.

    82

 */

    83

err_t transport_fd__events (transport_t *transport, short mask, error_t *err);

    84

    85

/**

    86

 * Implementation of transport_methods::deinit.

    87

 *

    88

 * This simply calls transport_fd_deinit().

    89

 */

    90

void transport_fd__deinit (transport_t *transport);

    91

    92

/**

    93

 * A transport_fd_callback_func that simply invokes the transport_callback user functions.

    94

 *

    95

 * Register with a NULL cb_arg.

    96

 */

    97

void transport_fd_callback_user (struct transport_fd *fd, short what, void *arg);

    98

    99

   100

   101

   102

/**

   103

 * Initialize the transport_fd to use the given, connected fd, or TRANSPORT_FD_INVALID if we don't yet have an fd.

   104

 *

   105

 * It is an error to call this if the transport_fd already has an fd set

   106

 *

   107

 * @param fd the transport_fd state

   108

 * @param ev_base the libevent base to use

   109

 * @param _fd the OS file descriptor, or TRANSPORT_FD_INVALID

   110

 */

   111

void transport_fd_init (struct transport_fd *fd, struct event_base *ev_base, int _fd);

   112

   113

/**

   114

 * Set the fd's nonblocking mode using fcntl.

   115

 */

   116

err_t transport_fd_nonblock (struct transport_fd *fd, bool nonblock);

   117

   118

/**

   119

 * Set or replace the fd's event callback. The callback will not be enabled.

   120

 *

   121

 * The transport must have a valid fd bound to it.

   122

 */

   123

err_t transport_fd_setup (struct transport_fd *fd, transport_fd_callback_func cb_func, void *cb_arg);

   124

   125

/**

   126

 * Enable the specified events, any of { TRANSPORT_READ, TRANSPORT_WRITE }.

   127

 */

   128

err_t transport_fd_enable (struct transport_fd *fd, short mask);

   129

   130

/**

   131

 * Disable the specified events, any of { TRANSPORT_READ, TRANSPORT_WRITE }.

   132

 */

   133

err_t transport_fd_disable (struct transport_fd *fd, short mask);

   134

   135

/**

   136

 * Set the enable/disable state of our events to the given mask.

   137

 */

   138

err_t transport_fd_events (struct transport_fd *fd, short mask);

   139

   140

/**

   141

 * Remove any old event callback present, so it will not be called anymore.

   142

 *

   143

 * It is perfectly safe to call this without any callbacks installed.

   144

 */

   145

void transport_fd_clear (struct transport_fd *fd);

   146

   147

/**

   148

 * Setup and enable the default event handlers for transport operation, that is, use transport_fd_callback_user as the 

   149

 * callback and enable TRANSPORT_READ, unless masked out.

   150

 */

   151

err_t transport_fd_defaults (struct transport_fd *fd);

   152

   153

/**

   154

 * Replace the old fd with a new one, maintaining any event callbacks set with transport_fd_callback. If any events were

   155

 * enabled before, they are not enabled anymore.

   156

 */

   158

   159

/**

   160

 * Close an opened fd, releasing all resources within our state.

   161

 */

   163

   164

/**

   165

 * Deinitialize the transport_fd.

   166

 *

   167

 * This logs a warning if the close() fails.

   168

 *

   169

 * XXX: this may actually block, I think? SO_LINGER?

   170

 */

   171

void transport_fd_deinit (struct transport_fd *fd);

   172

   173

#endif