1

#ifndef TRANSPORT_H

     2

#define TRANSPORT_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Defines a intermediate-level (as opposed to high-level or low-level) API for connected streams of data, presumeably

     8

 * non-blocking ones.

     9

 */

    10

#include "error.h"

    11

    12

/**

    13

 * Opaque transport state handle.

    14

 *

    15

 * Transports are reliable byte streams, connected with some endpoint over some medium. Common implementations are

    16

 * e.g. TCP, SSL or fifo transports (using the OS file/socket API).

    17

 *

    18

 * Transports can be connected or unconnected. For synchronous opens (e.g. fifo_open_read()), the transport returned

    19

 * will already be connected, meaning that the transport_callbacks::on_connect callback is unused. For async connects

    20

 * such as sock_tcp_connect()/sock_ssl_connect(), the transport returned is *not* connected, and you must wait for

    21

 * transport_callbacks::on_connect to be called before being able to send/recieve data on the transport.

    22

 *

    23

 * Once you have an opened transport, sending and receiving data is simple - just call transport_read()/transport_write().

    24

 * These implement unbuffered I/O, so they may do partial reads/writes. In terms of the system read/write calls, the

    25

 * main difference is in the error return codes. On EOF, instead of returning zero, they return ERR_EOF (or

    26

 * ERR_WRITE_EOF for transport_write, for whoever knows what that means...). This means that when the underlying

    28

 * something simliar to EAGAIN.

    29

 *

    30

 * The transport API also implements non-blocking/event-based operation (usually on top of libevent), although at a

    31

 * slightly different level than the normal select/poll API. Instead of the user asking the transport to notify for

    32

 * read/write after transport_read/transport_write return zero, the transport will take care of this itself. 

    33

 * 

    34

 * Specifically, the user can supply a mask of events they are currently interested in. By default, this should be the

    35

 * full TRANSPORT_READ | TRANSPORT_WRITE, as the transport will take care of managing events by itself. If you wish to

    36

 * e.g. throttle read/write, you may set a different event mask using transport_events(), which will prevent the

    37

 * relevant callback from being triggered.

    38

 *

    39

 * For reads, the transport maintains a persistent read event, and will always call on_read when data is available on

    40

 * the socket (i.e. normal select() semantics). If masked out using transport_events(), there should be no event

    41

 * activity on the transport (i.e. the fd read event is removed).

    42

 *

    44

 * become enabled *once*, and consequently trigger transport_callbacks::on_write *once*, after which you must call

    45

 * transport_write() to possibly enable it again. If masked out using transport_events(), transport_write() will not

    46

 * enable the write event, and any pending write event is cancelled. If masked back in using transport_events(), the

    47

 * write event will *not* be registered, so if you have pending data, do a transport_write() after enabling

    48

 * TRANSPORT_WRITE.

    49

 */

    50

struct transport;

    51

    52

/**

    53

 * @see transport

    54

 */

    55

typedef struct transport transport_t;

    56

    57

/**

    58

 * User callbacks for transports

    59

 *

    60

 * @see transport

    61

 */

    62

struct transport_callbacks {

    63

    /**

    64

     * The transport is now connected

    65

     */

    66

    void (*on_connect) (transport_t *transport, void *arg);

    67

    68

    /**

    69

     * Data is now available for reading from the transport

    70

     */

    71

    void (*on_read) (transport_t *transport, void *arg);

    72

    73

    /**

    74

     * The transport has become writeable

    75

     */

    76

    void (*on_write) (transport_t *transport, void *arg);

    77

    78

    /**

    79

     * An asynchronous error has occured. This is only called for errors that occur while being called directly from

    80

     * the underlying event loop, and never from inside an API function.

    81

     *

    82

     * You must call transport_destroy to release the transport.

    83

     */

    84

    void (*on_error) (transport_t *transport, const error_t *err, void *arg);

    85

};

    86

    87

/**

    88

 * Bitmask of available events

    89

 *

    90

 * @see transport

    91

 */

    92

enum transport_event {

    93

    TRANSPORT_READ  = 0x01,

    94

    TRANSPORT_WRITE = 0x02,

    95

};

    96

    97

/**

    98

 * User info required to build a transport

    99

 *

   100

 * @see transport

   101

 */

   102

struct transport_info {

   103

    /** The callbacks table */

   104

    const struct transport_callbacks *cb_tbl;

   105

   106

    /** The callback context argument */

   107

    void *cb_arg;

   108

   109

    /** Initial event mask using transport_event flags */

   110

    short ev_mask;

   111

};

   112

   113

/**

   114

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

   115

 * the number of bytes read (which will be less than or equal to \a len). If the transport is nonblocking, and there is

   116

 * no data available, this returns zero, and need not be called again until transport_callbacks::on_read is invoked.

   117

 *

   118

 * On errors, this returns the negative error code, and more info via \a err. Note that as opposed to read(2), EOF is

   119

 * handled as an error, returning ERR_EOF.

   120

 *

   121

 * @param transport the transport state

   122

 * @param buf the buffer to read the bytes into

   123

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

   124

 * @param err returned error info

   125

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

   126

 */

   127

int transport_read (transport_t *transport, void *buf, size_t len, error_t *err);

   128

   129

/**

   130

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

   131

 * returns the number of bytes written (which may be less than \a len). If the transport is nonblocking, and the

   132

 * operation would have blocked, no data will be written, and zero is returned.

   133

 *

   134

 * On errors, this returns the negative error code, along with extended info via \a err.

   135

 *

   136

 * @param transport the transport state

   137

 * @param buf the buffer to write the bytes from

   138

 * @param len number of bytes to write

   139

 * @param err returned error info

   140

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

   141

 */

   142

int transport_write (transport_t *transport, const void *buf, size_t len, error_t *err);

   143

   144

/**

   145

 * Change the mask of enabled events.

   146

 */

   147

err_t transport_events (transport_t *transport, short mask);

   148

   149

/**

   150

 * Install a new set of callback handlers, replacing the old ones.

   151

 */

   152

void transport_set_callbacks (transport_t *transport, const struct transport_callbacks *cb_tbl, void *cb_arg);

   153

   154

/**

   155

 * Close and destroy the transport immediately, severing any established connection rudely.

   156

 *

   157

 * This will release all resources associated with the transport, including the transport itself, which must not be

   158

 * used anymore.

   159

 */

   160

void transport_destroy (transport_t *transport);

   161

   162

#endif