Skip to content

File tunnel.h

FileList > docs > sandwich_c > tunnel.h

Go to the source code of this file

Sandwich Tunnel API.

  • #include <sys/types.h>
  • #include "sandwich_c/export.h"
  • #include "sandwich_c/io.h"
  • #include "sandwich_c/tunnel_types.h"

Classes

Type Name
struct SandwichTunnelConfigurationSerialized
A serialized TunnelConfiguration message.
struct SandwichTunnelContextConfigurationSerialized
A serialized Configuration message.
struct SandwichTunnelIO
An IO specific to tunnels.

Public Types

Type Name
typedef void() SandwichTunnelIOSetStateFunction
An IO callback triggered when the state of the tunnel changes.
typedef SandwichTunnelIOSetStateFunction * SandwichTunnelIOSetStateFunctionPtr

Public Attributes

Type Name
struct SandwichTunnelConfigurationSerialized SandwichTunnelConfigurationVerifierEmpty
A tunnel configuration containing an empty Tunnel Verifier.

Public Functions

Type Name
SANDWICH_API struct SandwichTunnelIO sandwich_owned_io_to_tunnel_io (const struct SandwichIOOwned * owned_io)
Return the view of a tunnel IO from an owned IO.
SANDWICH_API void sandwich_tunnel_close (struct SandwichTunnel * tun)
Close the tunnel.
SANDWICH_API void sandwich_tunnel_context_free (struct SandwichTunnelContext * ctx)
Free a Sandwich tunnel context.
SANDWICH_API struct SandwichError * sandwich_tunnel_context_new (const struct SandwichContext * sw, struct SandwichTunnelContextConfigurationSerialized configuration, struct SandwichTunnelContext ** ctx)
Create a context from an encoded protobuf message.
SANDWICH_API void sandwich_tunnel_free (struct SandwichTunnel * tun)
Free a Sandwich tunnel.
SANDWICH_API struct SandwichError * sandwich_tunnel_handshake (struct SandwichTunnel * tun, enum SandwichTunnelHandshakeState * state)
Perform the handshake.
SANDWICH_API struct SandwichError * sandwich_tunnel_new (struct SandwichTunnelContext * ctx, const struct SandwichTunnelIO * io, struct SandwichTunnelConfigurationSerialized configuration, struct SandwichTunnel ** tun)
Create a tunnel.
SANDWICH_API enum SandwichTunnelRecordError sandwich_tunnel_read (struct SandwichTunnel * tun, void * dst, size_t n, size_t * r)
Read some bytes from the record plane of the tunnel.
SANDWICH_API enum SandwichTunnelState sandwich_tunnel_state (const struct SandwichTunnel * tun)
Get the state of the tunnel.
SANDWICH_API enum SandwichTunnelRecordError sandwich_tunnel_write (struct SandwichTunnel * tun, const void * src, size_t n, size_t * w)
Write some bytes to the record plane of the tunnel.

Public Types Documentation

typedef SandwichTunnelIOSetStateFunction

An IO callback triggered when the state of the tunnel changes. 

typedef void() SandwichTunnelIOSetStateFunction(void *uarg, enum SandwichTunnelState tunnel_state);

It is guaranteed that the state of the tunnel will not change between two calls to this callback.

Parameters:

  • uarg User opaque argument.
  • tunnel_state The new state of the tunnel.

typedef SandwichTunnelIOSetStateFunctionPtr

typedef SandwichTunnelIOSetStateFunction* SandwichTunnelIOSetStateFunctionPtr;

Public Attributes Documentation

variable SandwichTunnelConfigurationVerifierEmpty

struct SandwichTunnelConfigurationSerialized SandwichTunnelConfigurationVerifierEmpty;

Public Functions Documentation

function sandwich_owned_io_to_tunnel_io

Return the view of a tunnel IO from an owned IO. 

SANDWICH_API struct SandwichTunnelIO sandwich_owned_io_to_tunnel_io (
    const struct SandwichIOOwned * owned_io
)

Parameters:

  • owned_io Owned io.

The tunnel IO returned by this function is a view of the owned IO. It means that the user is STILL responsible for freeing the owned IO using sandwich_io_owned_free. Once freed, the view can no longer be used.

Returns:

A view of the owned IO as a tunnel IO.

function sandwich_tunnel_close

Close the tunnel. 

SANDWICH_API void sandwich_tunnel_close (
    struct SandwichTunnel * tun
)

Parameters:

  • tun Tunnel to close.

function sandwich_tunnel_context_free

Free a Sandwich tunnel context. 

SANDWICH_API void sandwich_tunnel_context_free (
    struct SandwichTunnelContext * ctx
)

Parameters:

  • ctx Context to free.

NULL for ctx is allowed.

function sandwich_tunnel_context_new

Create a context from an encoded protobuf message. 

SANDWICH_API struct SandwichError * sandwich_tunnel_context_new (
    const struct SandwichContext * sw,
    struct SandwichTunnelContextConfigurationSerialized configuration,
    struct SandwichTunnelContext ** ctx
)

Parameters:

  • sw Top-level Sandwich context.
  • configuration Serialized configuration.
  • ctx The new Sandwich context object.

Returns:

NULL if no error occured, else a chain of errors.

function sandwich_tunnel_free

Free a Sandwich tunnel. 

SANDWICH_API void sandwich_tunnel_free (
    struct SandwichTunnel * tun
)

If the I/O interface is still owned by the tunnel, it will be freed too.

Parameters:

  • tun Tunnel to free.

NULL for tun is allowed.

function sandwich_tunnel_handshake

Perform the handshake. 

SANDWICH_API struct SandwichError * sandwich_tunnel_handshake (
    struct SandwichTunnel * tun,
    enum SandwichTunnelHandshakeState * state
)

Parameters:

  • tun Tunnel.
  • state The state of the tunnel

Returns:

Null if no error occured, else a chain of errors.

function sandwich_tunnel_new

Create a tunnel. 

SANDWICH_API struct SandwichError * sandwich_tunnel_new (
    struct SandwichTunnelContext * ctx,
    const struct SandwichTunnelIO * io,
    struct SandwichTunnelConfigurationSerialized configuration,
    struct SandwichTunnel ** tun
)

A tunnel is created from an IO interface. SandwichTunnelIO are used to create an IO interface that forwards calls to the read, and write of SandwichTunnelIO. The state of the tunnel is exposed to the IO interface through the SandwichTunnelIO->set_state function.

Since the implementation of sandwich_tunnel_new makes a copy of SandwichTunnelIO, the caller does not need to keep io in memory. In other words, Sandwich does not take the ownership of io.

Parameters:

  • ctx Sandwich context used for setting up the tunnel.
  • io I/O interface to use to create the I/O interface.
  • configuration Additional configuration the connection is subject to. A null pointer is undefined behavior.
  • tun The new Sandwich tunnel object.

Returns:

NULL if no error occured, else a chain of errors.

function sandwich_tunnel_read

Read some bytes from the record plane of the tunnel. 

SANDWICH_API enum SandwichTunnelRecordError sandwich_tunnel_read (
    struct SandwichTunnel * tun,
    void * dst,
    size_t n,
    size_t * r
)

Parameters:

  • tun Tunnel..
  • dst Destination buffer.
  • n Amount of bytes to read.
  • r Amount of bytes successfully read.

NULL for r is allowed.

Returns:

An error code.

function sandwich_tunnel_state

Get the state of the tunnel. 

SANDWICH_API enum SandwichTunnelState sandwich_tunnel_state (
    const struct SandwichTunnel * tun
)

Parameters:

  • tun Tunnel.

Returns:

The state of the tunnel.

function sandwich_tunnel_write

Write some bytes to the record plane of the tunnel. 

SANDWICH_API enum SandwichTunnelRecordError sandwich_tunnel_write (
    struct SandwichTunnel * tun,
    const void * src,
    size_t n,
    size_t * w
)

Parameters:

  • tun Tunnel.
  • src Source buffer.
  • n Amount of bytes to read.
  • w Amount of bytes successfully written.

NULL for w is allowed.

Returns:

An error code.

The documentation for this class was generated from the following file docs/sandwich_c/tunnel.h