1 #ifndef LIBQMSK_TRANSPORT_INTERNAL_H

     2 #define LIBQMSK_TRANSPORT_INTERNAL_H

     3 

     4 /**

     5  * @file

     6  *

     7  * The internal interface for transport implementations.

     8  */ 

     9 #include "transport.h"

    10 #include "object.h"

    11 

    12 #include <stdbool.h>

    13 

    14 /**

    15  * The object_type for a transport_type

    16  */

    17 extern const struct object_type transport_type_type;

    18 

    19 /**

    20  * The definition of a transport type

    21  */

    22 struct transport_type {

    23     struct object_type base_type;

    24 

    25     /**

    26      * Method table for implementation stuff.

    27      *

    28      * Note that it is the transport's resposibility to implement the behaviour described in transport.h

    29      */

    30     struct transport_methods {

    31         /** For transport_read() */

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

    33 

    34         /** For transport_write() */

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

    36 

    37         /**

    38          * The mask of event flags will be set to the given mask if this method is succesfull.

    39          *

    40          * The old mask is still available in transport::info::ev_mask.

    41          */

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

    43 

    44         /** 

    45          * Release the transport's internal state, but not the transport itself.

    46          *

    47          * In other words, this should release everything inside the transport_t, but not free() the transport_t itself.

    48          */

    49         void (*deinit) (transport_t *transport);

    50 

    51         /**

    52          * Used by layered transports to handle transport_connected.

    53          *

    54          * If this is NULL, transport_connected will call the user callback directly, otherwise, it will proxy through this.

    55          *

    56          * The \a err param follows the same rules as for transport_connected() - NULL for success, error info otherwise.

    57          *

    58          * @param transport the transport state

    59          * @param err error info if the connect failed

    60          */

    61         void (*_connected) (transport_t *transport, const error_t *err);

    62     } methods;

    63 };

    64 

    65 /**

    66  * The base transport type

    67  */

    68 struct transport {

    69     struct object base_obj;

    70 

    71     /** User info */

    72     struct transport_info info;

    73     

    74     /** Are we connected? */

    75     bool connected;

    76 };

    77 

    78 /**

    79  * Bind the given transport to the given type with the given user info.

    80  *

    81  * \a info may be given as NULL to not have any callbacks, but this will crash if any transport_* is called before

    82  * transport_set_callbacks().

    83  *

    84  * It is a bug to call this with a transport that is already bound.

    85  */

    86 void transport_init (transport_t *transport, const struct transport_type *type, const struct transport_info *info);

    87 

    88 /**

    89  * Check the type of the transport, and return the transport as a void* suitable for casting to the appropriate struct

    90  * for the type, or any of its children.

    91  *

    92  * It is a bug to call this with a transport of a different type.

    93  */

    94 void* transport_check (transport_t *transport, const struct transport_type *type);

    95 

    96 /**

    97  * Mark the transport as connected, calling transport_methods::_connected if it exists and \a direct is not given,

    98  * transport_callbacks::on_connected/transport_callbacks::on_error otherwise.

    99  *

   100  * If the connect succeeded, \a err should be given as NULL. If the connect failed, \a err should contain the error

   101  * info.

   102  *

   103  * If called from the transport_methods::_connected method, pass in direct to avoid recursion.

   104  *

   105  * This sets the transport::connected flag before calling transport_callbacks::on_connected (i.e. directly) without any

   106  * error set.

   107  *

   108  * XXX: implement proper layering of types by taking a transport_type arg and chaining down from there.

   109  *

   110  * @param transport the transport state

   111  * @param err NULL for success, otherwise connect error code

   112  * @param direct call the user callback directly, ignoring any method

   113  */

   114 void transport_connected (transport_t *transport, const error_t *err, bool direct);

   115 

   116 /**

   117  * Invoke the user callbacks based on the given TRANSPORT_* flags

   118  */

   119 void transport_invoke (transport_t *transport, short what);

   120 

   121 /**

   122  * Mark the transport as failed, calling transport_methods::on_error with the given error code.

   123  */

   124 void transport_error (transport_t *transport, const error_t *err);

   125 

   126 #endif