RIOT/sys/include/net/sock.h

/*
 * Copyright (C) 2016 Alexander Aring <aar@pengutronix.de>
 *                    Freie Universität Berlin
 *                    HAW Hamburg
 *                    Kaspar Schleiser <kaspar@schleiser.de>
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
 * @defgroup    net_sock    Sock API
 * @ingroup     net
 * @brief       Provides a minimal common API for applications to connect to the
 *              different network stacks.
 *
 * About
 * =====
 *
 *    +---------------+
 *    |  Application  |
 *    +---------------+
 *            ^
 *            |
 *            v
 *          sock
 *            ^
 *            |
 *            v
 *    +---------------+
 *    | Network Stack |
 *    +---------------+
 *
 * This module provides a minimal set of functions to establish connections or
 * send and receives datagrams using different types of communication. Together,
 * they serve as a common API that connects application- and network stack code.
 *
 * Currently the following sock types are defined:
 *
 * * @ref sock_ip_t (net/sock/ip.h): raw IP sock
 * * @ref sock_tcp_t (net/sock/tcp.h): TCP sock
 * * @ref sock_udp_t (net/sock/udp.h): UDP sock
 *
 * Each network stack must implement at least one sock type.
 *
 * Note that there might be no relation between the different sock types.
 * For simplicity and modularity this API doesn't put any restriction of the
 * actual implementation of the type. For example, one implementation might
 * choose to have all sock types have a common base class or use the raw IP
 * sock type to send e.g. UDP packets, while others will keep them
 * completely separate from each other.
 *
 * How To Use
 * ==========
 *
 * A RIOT application uses the functions provided by one or more of the
 * sock type headers (for example @ref sock_udp), regardless of the
 * network stack it uses.
 * The network stack used under the bonnet is specified by including the
 * appropriate module (for example USEMODULE += gnrc_sock_udp)
 *
 * This allows for network stack agnostic code on the application layer.
 * The application code to establish a connection is always the same, allowing
 * the network stack underneath to be switched simply by changing the
 * `USEMODULE` definitions in the application's Makefile.
 *
 * @{
 *
 * @file
 * @brief   Sock API definitions
 *
 * @author  Alexander Aring <aar@pengutronix.de>
 * @author  Simon Brummer <simon.brummer@haw-hamburg.de>
 * @author  Cenk Gündoğan <mail@cgundogan.de>
 * @author  Peter Kietzmann <peter.kietzmann@haw-hamburg.de>
 * @author  Martine Lenders <m.lenders@fu-berlin.de>
 * @author  Kaspar Schleiser <kaspar@schleiser.de>
 */

#ifndef NET_SOCK_H_
#define NET_SOCK_H_

#include <stdbool.h>

#include "net/sock/ip.h"
#include "net/sock/tcp.h"
#include "net/sock/udp.h"

#ifdef __cplusplus
extern "C" {
#endif

#if defined(DOXYGEN)
/**
 * @brief compile flag to activate IPv6 support for sock.
 */
#define SOCK_HAS_IPV6
#endif

/**
 * @brief   Common flags for @ref net_conn
 * @{
 */
#define SOCK_FLAGS_REUSE_EP     (0x00000001)    /**< allow to reuse end point on bind */
/** @} */


#ifdef __cplusplus
}
#endif

#endif /* NET_SOCK_H_ */
/** @} */