#ifndef TRANSPORT_H
#define TRANSPORT_H

/**
 * @file
 *
 * Defines a intermediate-level (as opposed to high-level or low-level) API for connected streams of data, presumeably
 * non-blocking ones.
 */
#include "error.h"

/**
 * Opaque transport state
 */
struct transport;

/**
 * Because it's so annoying seeing "struct" everywhere
 */
typedef struct transport transport_t;

/**
 * Callbacks for structs
 */
struct transport_callbacks {
    /**
     * The transport is now connected
     */
    void (*on_connect) (transport_t *transport, void *arg);

    /**
     * Data is now available for reading from the transport
     */
    void (*on_read) (transport_t *transport, void *arg);

    /**
     * The transport has become writeable
     */
    void (*on_write) (transport_t *transport, void *arg);

    /**
     * An asynchronous error has occured. This is only called for errors that occur while being called directly from
     * the underlying event loop, and never from inside an API function.
     */
    void (*on_error) (transport_t *transport, error_t *err, void *arg);
};

/**
 * User info required to build a transport
 */
struct transport_info {
    /** The callbacks table */
    const struct transport_callbacks *cb_tbl;

    /** The callback context argument */
    void *cb_arg;
};

/**
 * Read a series of bytes from the transport into the given \a buf (up to \a len bytes). If succesfull, this returns
 * the number of bytes read (which will be less than or equal to \a len). If the transport is nonblocking, and there is
 * no data available, this returns zero, and need not be called again until transport_callbacks::on_read is invoked.
 *
 * On errors, this returns the negative error code, and more info via \a err.
 *
 * @param transport the transport state
 * @param buf the buffer to read the bytes into
 * @param len the number of bytes to read into the buffer
 * @param err returned error info
 * @return bytes read, zero if none available, -err_t
 */
int transport_read (transport_t *transport, void *buf, size_t len, error_t *err);

/**
 * Write a series of bytes from the given \a buf (containing \a len bytes) to the transport. If succesfull, this
 * returns the number of bytes written (which may be less than \a len). If the transport is nonblocking, and the
 * operation would have blocked, no data will be written, and zero is returned.
 *
 * XXX: behaviour of transport_callbacks::on_write?
 *
 * On errors, this returns the negative error code, along with extended info via \a err.
 *
 * @param transport the transport state
 * @param buf the buffer to write the bytes from
 * @param len number of bytes to write
 * @param err returned error info
 * @return bytes written, zero if would have blocked, -err_t
 */
int transport_write (transport_t *transport, const void *buf, size_t len, error_t *err);

/**
 * Close and destroy the transport immediately, severing any established connection rudely.
 *
 * This will release all resources associated with the transport, including the transport itself, which must not be
 * used anymore.
 */
void transport_destroy (transport_t *transport);

#endif