docs: Split Stream Server and Stream Client into separate groups
This provides us with proper logical separation between client and server in the documentation. Change-Id: I9e037fedaecb78396f435577b1652284b4951ded
This commit is contained in:
parent
ccc6c194d5
commit
912360157d
|
@ -6,16 +6,7 @@
|
||||||
|
|
||||||
#include <osmocom/core/msgb.h>
|
#include <osmocom/core/msgb.h>
|
||||||
|
|
||||||
/*! \defgroup stream Osmocom Stream Server/Client
|
/*! \file stream.h */
|
||||||
* @{
|
|
||||||
*
|
|
||||||
* This code is intended to abstract any use of stream-type sockets,
|
|
||||||
* such as TCP and SCTP. It offers both server and client side
|
|
||||||
* implementations, fully integrated with the libosmocore select loop
|
|
||||||
* abstraction.
|
|
||||||
*
|
|
||||||
* \file stream.h
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*! \brief Access SCTP flags from the msgb control buffer */
|
/*! \brief Access SCTP flags from the msgb control buffer */
|
||||||
#define OSMO_STREAM_SCTP_MSG_FLAGS_NOTIFICATION 0x80 /* sctp_recvmsg() flags=MSG_NOTIFICATION, msgb_data() contains "union sctp_notification*" */
|
#define OSMO_STREAM_SCTP_MSG_FLAGS_NOTIFICATION 0x80 /* sctp_recvmsg() flags=MSG_NOTIFICATION, msgb_data() contains "union sctp_notification*" */
|
||||||
|
@ -26,6 +17,48 @@
|
||||||
/*! \brief Access the SCTP Stream ID from the msgb control buffer */
|
/*! \brief Access the SCTP Stream ID from the msgb control buffer */
|
||||||
#define msgb_sctp_stream(msg) (msg)->cb[4]
|
#define msgb_sctp_stream(msg) (msg)->cb[4]
|
||||||
|
|
||||||
|
/*! \defgroup stream_srv Osmocom Stream Server
|
||||||
|
* @{
|
||||||
|
*
|
||||||
|
* This code is intended to abstract any server-side use of stream-type sockets, such as TCP and SCTP.
|
||||||
|
*
|
||||||
|
* The Osmocom stream socket helper is an abstraction layer for connected SOCK_STREAM/SOCK_SEQPACKET sockets.
|
||||||
|
* It encapsulates common functionality like binding, accepting client connections, etc.
|
||||||
|
*
|
||||||
|
* osmo_stream_srv can operate in two different modes:
|
||||||
|
* 1. The legacy mode using osmo_fd (from libosmocore)
|
||||||
|
* 2. The modern (2023) mode using osmo_io (from libosmocore)
|
||||||
|
*
|
||||||
|
* For any new applications, you definitely should use the modern mode, as it provides you with a higher
|
||||||
|
* layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io.
|
||||||
|
*
|
||||||
|
* The two main objects are osmo_stream_srv_link (main server accept()ing incoming connections) and
|
||||||
|
* osmo_stream_srv (a single given connection from a remote client).
|
||||||
|
*
|
||||||
|
* A typical stream_srv usage would look like this:
|
||||||
|
*
|
||||||
|
* * create new osmo_stream_srv_link using osmo_stream_srv_link_create()
|
||||||
|
* * call osmo_stream_srv_link_set_addr() to set local bind address/port
|
||||||
|
* * call osmo_stream_srv_link_set_accept_cb() to register the accept call-back
|
||||||
|
* * optionally call further osmo_stream_srv_link_set_*() functions
|
||||||
|
* * call osmo_stream_srv_link_open() to create socket and start listening
|
||||||
|
*
|
||||||
|
* Whenever a client connects to your listening socket, the connection will now be automatically accept()ed
|
||||||
|
* and the registered accept_cb call-back called. From within that accept_cb, you then
|
||||||
|
* * call osmo_stream_srv_create() to create a osmo_stream_srv for that specific connection
|
||||||
|
* * call osmo_stream_srv_set_read_cb() to register the read call-back for incoming data
|
||||||
|
* * call osmo_stream_srv_set_closed_cb() to register the closed call-back
|
||||||
|
* * call osmo_stream_srv_set_data() to associate opaque application-layer state
|
||||||
|
*
|
||||||
|
* Whenever data from a client arrives on a connection, your registered read_cb will be called together
|
||||||
|
* with a message buffer containing the received data. Ownership of the message buffer is transferred
|
||||||
|
* into the call-back, i.e. in your application. It's your responsibility to eventually msgb_free()
|
||||||
|
* it after usage.
|
||||||
|
*
|
||||||
|
* Whenever your application wants to transmit something to a given connection, it uses the
|
||||||
|
* osmo_stream_srv_send() function.
|
||||||
|
*/
|
||||||
|
|
||||||
/*! \brief Osmocom Stream Server Link: A server socket listening/accepting */
|
/*! \brief Osmocom Stream Server Link: A server socket listening/accepting */
|
||||||
struct osmo_stream_srv_link;
|
struct osmo_stream_srv_link;
|
||||||
|
|
||||||
|
@ -89,6 +122,40 @@ int osmo_stream_srv_recv(struct osmo_stream_srv *conn, struct msgb *msg);
|
||||||
|
|
||||||
void osmo_stream_srv_clear_tx_queue(struct osmo_stream_srv *conn);
|
void osmo_stream_srv_clear_tx_queue(struct osmo_stream_srv *conn);
|
||||||
|
|
||||||
|
/*! @} */
|
||||||
|
|
||||||
|
/*! \defgroup stream_cli Osmocom Stream Client
|
||||||
|
* @{
|
||||||
|
*
|
||||||
|
* This code is intended to abstract any client use of stream-type sockets, such as TCP and SCTP
|
||||||
|
*
|
||||||
|
* An osmo_stream_cli represents a client implementation of a SOCK_STREAM or SOCK_SEQPACKET socket. It
|
||||||
|
* contains all the common logic like non-blocking outbound connect to a remote server, re-connecting after
|
||||||
|
* disconnect or connect failure, etc.
|
||||||
|
*
|
||||||
|
* osmo_stream_cli can operate in two different modes:
|
||||||
|
* 1. The legacy mode using osmo_fd (from libosmocore)
|
||||||
|
* 2. The modern (2023) mode using osmo_io_fd (from libosmocore)
|
||||||
|
*
|
||||||
|
* For any new applications, you definitely should use the modern mode, as it provides you with a higher
|
||||||
|
* layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io.
|
||||||
|
*
|
||||||
|
* A typical usage of osmo_stream_cli would look as follows:
|
||||||
|
*
|
||||||
|
* * call osmo_stream_cli_create() to create a new osmo_stream_cli
|
||||||
|
* * call osmo_stream_cli_set_addr() / osmo_stream_cli_set_port() to specify the remote address/port to connect to
|
||||||
|
* * optionally call further functions of the osmo_stream_cli_set_*() family
|
||||||
|
* * call osmo_stream_cli_set_connect_cb() to register the call-back called on completion of outbound connect()
|
||||||
|
* * call osmo_stream_cli_set_read_cb2() to register the call-back called when incoming data has been read
|
||||||
|
* * call osmo_stream_cli_open() to open the connection (start outbound connect process)
|
||||||
|
*
|
||||||
|
* Once the connection is established, your connect_cb is called to notify you.
|
||||||
|
*
|
||||||
|
* You may send data to the connection using osmo_tream_cli_send().
|
||||||
|
*
|
||||||
|
* Any received inbound data on the connection is reported vie the read_cb.
|
||||||
|
*/
|
||||||
|
|
||||||
/*! \brief Osmocom Stream Client: Single client connection */
|
/*! \brief Osmocom Stream Client: Single client connection */
|
||||||
struct osmo_stream_cli;
|
struct osmo_stream_cli;
|
||||||
|
|
||||||
|
|
|
@ -21,9 +21,7 @@
|
||||||
#define OSMO_STREAM_MAX_ADDRS 1
|
#define OSMO_STREAM_MAX_ADDRS 1
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/*! \addtogroup stream
|
/*! \cond private */
|
||||||
* @{
|
|
||||||
*/
|
|
||||||
|
|
||||||
enum osmo_stream_mode {
|
enum osmo_stream_mode {
|
||||||
OSMO_STREAM_MODE_UNKNOWN,
|
OSMO_STREAM_MODE_UNKNOWN,
|
||||||
|
@ -41,4 +39,4 @@ int stream_sctp_recvmsg_wrapper(int fd, struct msgb *msg, const char *log_pfx);
|
||||||
int stream_iofd_sctp_send_msgb(struct osmo_io_fd *iofd, struct msgb *msg, int sendmsg_flags);
|
int stream_iofd_sctp_send_msgb(struct osmo_io_fd *iofd, struct msgb *msg, int sendmsg_flags);
|
||||||
int stream_iofd_sctp_recvmsg_trailer(struct osmo_io_fd *iofd, struct msgb *msg, int ret, const struct msghdr *msgh);
|
int stream_iofd_sctp_recvmsg_trailer(struct osmo_io_fd *iofd, struct msgb *msg, int ret, const struct msghdr *msgh);
|
||||||
|
|
||||||
/*! @} */
|
/*! \endcond */
|
||||||
|
|
12
src/stream.c
12
src/stream.c
|
@ -51,14 +51,7 @@
|
||||||
|
|
||||||
#include <osmocom/netif/sctp.h>
|
#include <osmocom/netif/sctp.h>
|
||||||
|
|
||||||
|
/*! \cond private */
|
||||||
/*! \addtogroup stream
|
|
||||||
* @{
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*! \file stream.c
|
|
||||||
* \brief Osmocom stream socket helpers
|
|
||||||
*/
|
|
||||||
|
|
||||||
#ifdef HAVE_LIBSCTP
|
#ifdef HAVE_LIBSCTP
|
||||||
|
|
||||||
|
@ -344,5 +337,4 @@ int stream_iofd_sctp_send_msgb(struct osmo_io_fd *iofd, struct msgb *msg, int se
|
||||||
}
|
}
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
|
/*! \endccond */
|
||||||
/*! @} */
|
|
||||||
|
|
|
@ -51,41 +51,7 @@
|
||||||
|
|
||||||
#include <osmocom/netif/sctp.h>
|
#include <osmocom/netif/sctp.h>
|
||||||
|
|
||||||
|
/*! \file stream_cli.c */
|
||||||
/*! \addtogroup stream
|
|
||||||
* @{
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*! \file stream_cli.c
|
|
||||||
* Osmocom stream socket helpers (client side)
|
|
||||||
*
|
|
||||||
* An osmo_stream_cli represents a client implementation of a SOCK_STREAM or SOCK_SEQPACKET socket. It
|
|
||||||
* contains all the common logic like non-blocking outbound connect to a remote server, re-connecting after
|
|
||||||
* disconnect or connect failure, etc.
|
|
||||||
*
|
|
||||||
* osmo_stream_cli can operate in two different modes:
|
|
||||||
* 1. The legacy mode using osmo_fd (from libosmocore)
|
|
||||||
* 2. The modern (2023) mode using osmo_io_fd (from libosmocore)
|
|
||||||
*
|
|
||||||
* For any new applications, you definitely should use the modern mode, as it provides you with a higher
|
|
||||||
* layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io.
|
|
||||||
*
|
|
||||||
* A typical usage of osmo_stream_cli would look as follows:
|
|
||||||
*
|
|
||||||
* * call osmo_stream_cli_create() to create a new osmo_stream_cli
|
|
||||||
* * call osmo_stream_cli_set_addr() / osmo_stream_cli_set_port() to specify the remote address/port to connect to
|
|
||||||
* * optionally call further functions of the osmo_stream_cli_set_*() family
|
|
||||||
* * call osmo_stream_cli_set_connect_cb() to register the call-back called on completion of outbound connect()
|
|
||||||
* * call osmo_stream_cli_set_read_cb2() to register the call-back called when incoming data has been read
|
|
||||||
* * call osmo_stream_cli_open() to open the connection (start outbound connect process)
|
|
||||||
*
|
|
||||||
* Once the connection is established, your connect_cb is called to notify you.
|
|
||||||
*
|
|
||||||
* You may send data to the connection using osmo_tream_cli_send().
|
|
||||||
*
|
|
||||||
* Any received inbound data on the connection is reported vie the read_cb.
|
|
||||||
*
|
|
||||||
*/
|
|
||||||
|
|
||||||
#define LOGSCLI(cli, level, fmt, args...) \
|
#define LOGSCLI(cli, level, fmt, args...) \
|
||||||
LOGP(DLINP, level, "CLICONN(%s,%s){%s} " fmt, \
|
LOGP(DLINP, level, "CLICONN(%s,%s){%s} " fmt, \
|
||||||
|
@ -151,6 +117,10 @@ struct osmo_stream_cli {
|
||||||
|
|
||||||
void osmo_stream_cli_close(struct osmo_stream_cli *cli);
|
void osmo_stream_cli_close(struct osmo_stream_cli *cli);
|
||||||
|
|
||||||
|
/*! \addtogroup stream_cli
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
/*! Re-connect an Osmocom Stream Client.
|
/*! Re-connect an Osmocom Stream Client.
|
||||||
* If re-connection is enabled for this client
|
* If re-connection is enabled for this client
|
||||||
* (which is the case unless negative timeout was explicitly set via osmo_stream_cli_set_reconnect_timeout() call),
|
* (which is the case unless negative timeout was explicitly set via osmo_stream_cli_set_reconnect_timeout() call),
|
||||||
|
|
|
@ -52,51 +52,7 @@
|
||||||
|
|
||||||
#include <osmocom/netif/sctp.h>
|
#include <osmocom/netif/sctp.h>
|
||||||
|
|
||||||
|
/*! \file stream_srv.c */
|
||||||
/*! \addtogroup stream
|
|
||||||
* @{
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*! \file stream_srv.c
|
|
||||||
* Osmocom stream socket helpers (server side)
|
|
||||||
*
|
|
||||||
* The Osmocom stream socket helper is an abstraction layer for connected SOCK_STREAM/SOCK_SEQPACKET sockets.
|
|
||||||
* It encapsulates common functionality like binding, accepting client connections, etc.
|
|
||||||
*
|
|
||||||
* osmo_stream_srv can operate in two different modes:
|
|
||||||
* 1. The legacy mode using osmo_fd (from libosmocore)
|
|
||||||
* 2. The modern (2023) mode using osmo_io (from libosmocore)
|
|
||||||
*
|
|
||||||
* For any new applications, you definitely should use the modern mode, as it provides you with a higher
|
|
||||||
* layer of abstraction and allows you to perform efficient I/O using the io_uring backend of osmo_io.
|
|
||||||
*
|
|
||||||
* The two main objects are osmo_stream_srv_link (main server accept()ing incoming connections) and
|
|
||||||
* osmo_stream_srv (a single given connection from a remote client).
|
|
||||||
*
|
|
||||||
* A typical stream_srv usage would look like this:
|
|
||||||
*
|
|
||||||
* * create new osmo_stream_srv_link using osmo_stream_srv_link_create()
|
|
||||||
* * call osmo_stream_srv_link_set_addr() to set local bind address/port
|
|
||||||
* * call osmo_stream_srv_link_set_accept_cb() to register the accept call-back
|
|
||||||
* * optionally call further osmo_stream_srv_link_set_*() functions
|
|
||||||
* * call osmo_stream_srv_link_open() to create socket and start listening
|
|
||||||
*
|
|
||||||
* Whenever a client connects to your listening socket, the connection will now be automatically accept()ed
|
|
||||||
* and the registered accept_cb call-back called. From within that accept_cb, you then
|
|
||||||
* * call osmo_stream_srv_create() to create a osmo_stream_srv for that specific connection
|
|
||||||
* * call osmo_stream_srv_set_read_cb() to register the read call-back for incoming data
|
|
||||||
* * call osmo_stream_srv_set_closed_cb() to register the closed call-back
|
|
||||||
* * call osmo_stream_srv_set_data() to associate opaque application-layer state
|
|
||||||
*
|
|
||||||
* Whenever data from a client arrives on a connection, your registered read_cb will be called together
|
|
||||||
* with a message buffer containing the received data. Ownership of the message buffer is transferred
|
|
||||||
* into the call-back, i.e. in your application. It's your responsibility to eventually msgb_free()
|
|
||||||
* it after usage.
|
|
||||||
*
|
|
||||||
* Whenever your application wants to transmit something to a given connection, it uses the
|
|
||||||
* osmo_stream_srv_send() function.
|
|
||||||
*
|
|
||||||
*/
|
|
||||||
|
|
||||||
#define LOGSLNK(link, level, fmt, args...) \
|
#define LOGSLNK(link, level, fmt, args...) \
|
||||||
LOGP(DLINP, level, "SRV(%s,%s) " fmt, \
|
LOGP(DLINP, level, "SRV(%s,%s) " fmt, \
|
||||||
|
@ -207,6 +163,10 @@ error_close_socket:
|
||||||
return ret;
|
return ret;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*! \addtogroup stream_srv
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
/*! Create an Osmocom Stream Server Link.
|
/*! Create an Osmocom Stream Server Link.
|
||||||
* A Stream Server Link is the listen()+accept() "parent" to individual connections from remote clients.
|
* A Stream Server Link is the listen()+accept() "parent" to individual connections from remote clients.
|
||||||
* \param[in] ctx talloc allocation context
|
* \param[in] ctx talloc allocation context
|
||||||
|
@ -623,6 +583,8 @@ int osmo_stream_srv_link_set_param(struct osmo_stream_srv_link *link, enum osmo_
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*! @} */
|
||||||
|
|
||||||
#define OSMO_STREAM_SRV_F_FLUSH_DESTROY (1 << 0)
|
#define OSMO_STREAM_SRV_F_FLUSH_DESTROY (1 << 0)
|
||||||
|
|
||||||
struct osmo_stream_srv {
|
struct osmo_stream_srv {
|
||||||
|
@ -642,6 +604,10 @@ struct osmo_stream_srv {
|
||||||
int flags;
|
int flags;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/*! \addtogroup stream_srv
|
||||||
|
* @{
|
||||||
|
*/
|
||||||
|
|
||||||
static void stream_srv_iofd_read_cb(struct osmo_io_fd *iofd, int res, struct msgb *msg)
|
static void stream_srv_iofd_read_cb(struct osmo_io_fd *iofd, int res, struct msgb *msg)
|
||||||
{
|
{
|
||||||
struct osmo_stream_srv *conn = osmo_iofd_get_data(iofd);
|
struct osmo_stream_srv *conn = osmo_iofd_get_data(iofd);
|
||||||
|
@ -827,6 +793,7 @@ static int osmo_stream_srv_cb(struct osmo_fd *ofd, unsigned int what)
|
||||||
return rc;
|
return rc;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/*! Create a legacy osmo_fd mode Stream Server inside the specified link.
|
/*! Create a legacy osmo_fd mode Stream Server inside the specified link.
|
||||||
*
|
*
|
||||||
* This is the function an application traditionally calls from within the
|
* This is the function an application traditionally calls from within the
|
||||||
|
|
Loading…
Reference in New Issue