This code is intended to abstract any client use of stream-type sockets, such as TCP and SCTP. More...

Typedefs
typedef int(*	osmo_stream_cli_connect_cb_t) (struct osmo_stream_cli *cli)

typedef int(*	osmo_stream_cli_disconnect_cb_t) (struct osmo_stream_cli *cli)

typedef int(*	osmo_stream_cli_read_cb_t) (struct osmo_stream_cli *cli)

typedef int(*	osmo_stream_cli_read_cb2_t) (struct osmo_stream_cli cli, int res, struct msgb msg)
	Completion call-back function when something was read from from the stream client socket. More...

typedef int(*	osmo_stream_cli_segmentation_cb_t) (struct msgb *msg)

Enumerations
enum	osmo_stream_cli_param { OSMO_STREAM_CLI_PAR_SCTP_SOCKOPT_AUTH_SUPPORTED , OSMO_STREAM_CLI_PAR_SCTP_SOCKOPT_ASCONF_SUPPORTED , OSMO_STREAM_CLI_PAR_SCTP_INIT_NUM_OSTREAMS , OSMO_STREAM_CLI_PAR_SCTP_INIT_MAX_INSTREAMS , OSMO_STREAM_CLI_PAR_SCTP_INIT_MAX_ATTEMPTS , OSMO_STREAM_CLI_PAR_SCTP_INIT_TIMEOUT }

Functions
void	osmo_stream_cli_set_name (struct osmo_stream_cli cli, const char name)
	Set a name on the cli object (used during logging). More...

const char *	osmo_stream_cli_get_name (const struct osmo_stream_cli *cli)
	Retrieve name previously set on the cli object (see osmo_stream_cli_set_name()). More...

void	osmo_stream_cli_set_nodelay (struct osmo_stream_cli *cli, bool nodelay)
	Set the NODELAY socket option to avoid Nagle-like behavior. More...

void	osmo_stream_cli_set_addr (struct osmo_stream_cli cli, const char addr)
	Set the remote address to which we connect. More...

int	osmo_stream_cli_set_addrs (struct osmo_stream_cli cli, const char *addr, size_t addrcnt)
	Set the remote address set to which we connect. More...

void	osmo_stream_cli_set_port (struct osmo_stream_cli *cli, uint16_t port)
	Set the remote port number to which we connect. More...

int	osmo_stream_cli_set_type (struct osmo_stream_cli *cli, int type)
	Set the socket type for the stream server link. More...

int	osmo_stream_cli_set_domain (struct osmo_stream_cli *cli, int domain)
	Set the socket type for the stream server link. More...

void	osmo_stream_cli_set_proto (struct osmo_stream_cli *cli, uint16_t proto)
	Set the protocol for the stream client socket. More...

void	osmo_stream_cli_set_local_addr (struct osmo_stream_cli cli, const char addr)
	Set the local address for the socket (to be bound to). More...

int	osmo_stream_cli_set_local_addrs (struct osmo_stream_cli cli, const char *addr, size_t addrcnt)
	Set the local address set to which we bind. More...

void	osmo_stream_cli_set_local_port (struct osmo_stream_cli *cli, uint16_t port)
	Set the local port number for the socket (to be bound to). More...

void	osmo_stream_cli_set_data (struct osmo_stream_cli cli, void data)
	Set application private data of the stream client socket. More...

void	osmo_stream_cli_set_reconnect_timeout (struct osmo_stream_cli *cli, int timeout)
	Set the reconnect time of the stream client socket. More...

void *	osmo_stream_cli_get_data (struct osmo_stream_cli *cli)
	Retrieve application private data of the stream client socket. More...

char *	osmo_stream_cli_get_sockname (const struct osmo_stream_cli *cli)
	Retrieve the stream client socket description. More...

struct osmo_fd *	osmo_stream_cli_get_ofd (struct osmo_stream_cli *cli)
	Retrieve Osmocom File Descriptor of the stream client socket. More...

int	osmo_stream_cli_get_fd (const struct osmo_stream_cli *cli)
	Retrieve file descriptor of the stream client socket. More...

struct osmo_io_fd *	osmo_stream_cli_get_iofd (const struct osmo_stream_cli *cli)
	Retrieve osmo_io descriptor of the stream client socket. More...

void	osmo_stream_cli_set_connect_cb (struct osmo_stream_cli *cli, osmo_stream_cli_connect_cb_t connect_cb)
	Set the call-back function called on connect of the stream client socket. More...

void	osmo_stream_cli_set_disconnect_cb (struct osmo_stream_cli *cli, osmo_stream_cli_disconnect_cb_t disconnect_cb)
	Set the call-back function called on disconnect of the stream client socket. More...

void	osmo_stream_cli_set_read_cb (struct osmo_stream_cli *cli, osmo_stream_cli_read_cb_t read_cb)
	Set the call-back function called to read from the stream client socket. More...

void	osmo_stream_cli_set_read_cb2 (struct osmo_stream_cli *cli, osmo_stream_cli_read_cb2_t read_cb)
	Set the call-back function called to read from the stream client socket. More...

void	osmo_stream_cli_set_segmentation_cb (struct osmo_stream_cli *cli, osmo_stream_cli_segmentation_cb_t segmentation_cb)
	Set the segmentation callback for the client. More...

void	osmo_stream_cli_reconnect (struct osmo_stream_cli *cli)
	Re-connect an Osmocom Stream Client. More...

bool	osmo_stream_cli_is_connected (struct osmo_stream_cli *cli)
	Check if Osmocom Stream Client is in connected state. More...

struct osmo_stream_cli *	osmo_stream_cli_create (void *ctx)
	Create an Osmocom stream client. More...

void	osmo_stream_cli_destroy (struct osmo_stream_cli *cli)
	Destroy a Osmocom stream client (includes close). More...

int	osmo_stream_cli_open (struct osmo_stream_cli *cli)
	Open connection of an Osmocom stream client. More...

int	osmo_stream_cli_open2 (struct osmo_stream_cli *cli, int reconnect)
	DEPRECATED: use osmo_stream_cli_set_reconnect_timeout() or osmo_stream_cli_reconnect() instead! Open connection of an Osmocom stream client. More...

void	osmo_stream_cli_close (struct osmo_stream_cli *cli)
	Close an Osmocom Stream Client. More...

void	osmo_stream_cli_send (struct osmo_stream_cli cli, struct msgb msg)
	Enqueue data to be sent via an Osmocom stream client. More...

int	osmo_stream_cli_recv (struct osmo_stream_cli cli, struct msgb msg)
	Receive data via an Osmocom stream client in osmo_fd mode. More...

void	osmo_stream_cli_clear_tx_queue (struct osmo_stream_cli *cli)
	Clear the transmit queue of the stream client. More...

int	osmo_stream_cli_set_param (struct osmo_stream_cli cli, enum osmo_stream_cli_param par, void val, size_t val_len)
	Set given parameter of stream client to given value. More...

Detailed Description

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:

The legacy mode using osmo_fd (from libosmocore)
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.

Typedef Documentation

◆ osmo_stream_cli_read_cb2_t

typedef int(* osmo_stream_cli_read_cb2_t) (struct osmo_stream_cli *cli, int res, struct msgb *msg)

Completion call-back function when something was read from from the stream client socket.

Parameters

[in]	cli	Stream Client that got receive event.
[in]	res	return value of the read()/recvmsg()/... call, or -errno in case of error.
[in]	msg	message buffer containing the read data. Ownership is transferred to the call-back, and it must make sure to msgb_free() it eventually!

Function Documentation

◆ osmo_stream_cli_clear_tx_queue()

void osmo_stream_cli_clear_tx_queue ( struct osmo_stream_cli * cli )

Clear the transmit queue of the stream client.

Calling this function wil clear (delete) any pending, not-yet transmitted data from the transmit queue.

◆ osmo_stream_cli_close()

void osmo_stream_cli_close ( struct osmo_stream_cli * cli )

Close an Osmocom Stream Client.

Parameters

[in] cli Osmocom Stream Client to be closed We unregister the socket fd from the osmocom select() loop abstraction and close the socket

Referenced by osmo_stream_cli_destroy(), and osmo_stream_cli_reconnect().

◆ osmo_stream_cli_create()

struct osmo_stream_cli * osmo_stream_cli_create ( void * ctx )

Create an Osmocom stream client.

Parameters

[in] ctx talloc context from which to allocate memory This function allocates a new osmo_stream_cli and initializes it with default values (5s reconnect timer, TCP protocol)

Returns: allocated stream client, or NULL in case of error

◆ osmo_stream_cli_destroy()

void osmo_stream_cli_destroy ( struct osmo_stream_cli * cli )

Destroy a Osmocom stream client (includes close).

Parameters

[in] cli Stream Client to destroy

References osmo_stream_cli_close().

◆ osmo_stream_cli_get_data()

void * osmo_stream_cli_get_data ( struct osmo_stream_cli * cli )

Retrieve application private data of the stream client socket.

Parameters

[in] cli Stream Client to modify

Returns: Application private data, as set by osmo_stream_cli_set_data()

◆ osmo_stream_cli_get_fd()

int osmo_stream_cli_get_fd ( const struct osmo_stream_cli * cli )

Retrieve file descriptor of the stream client socket.

Parameters

[in] cli Stream Client of which we want to obtain the file descriptor

Returns: File descriptor or negative in case of error

Referenced by osmo_stream_cli_get_sockname().

◆ osmo_stream_cli_get_iofd()

struct osmo_io_fd * osmo_stream_cli_get_iofd ( const struct osmo_stream_cli * cli )

Retrieve osmo_io descriptor of the stream client socket.

This function must not be called on a stream client in legacy osmo_fd mode! The iofd is only valid once/after osmo_stream_cli_open() has successfully returned.

Parameters

[in] cli Stream Client of which we want to obtain the file descriptor

Returns: osmo_io_fd of stream client, or NULL if stream not yet opened.

◆ osmo_stream_cli_get_name()

const char * osmo_stream_cli_get_name ( const struct osmo_stream_cli * cli )

Retrieve name previously set on the cli object (see osmo_stream_cli_set_name()).

Parameters

[in] cli stream_cli whose name is to be retrieved

Returns: The name to be set on cli; NULL if never set

◆ osmo_stream_cli_get_ofd()

struct osmo_fd * osmo_stream_cli_get_ofd ( struct osmo_stream_cli * cli )

Retrieve Osmocom File Descriptor of the stream client socket.

This function only works in case you operate osmo_stream_cli in osmo_fd mode!

Parameters

[in] cli Stream Client to modify

Returns: Pointer to osmo_fd

◆ osmo_stream_cli_get_sockname()

char * osmo_stream_cli_get_sockname ( const struct osmo_stream_cli * cli )

Retrieve the stream client socket description.

Calling this function will build a string that describes the socket in terms of its local/remote address/port. The returned name is stored in a static buffer; it is hence not re-entrant or thread-safe.

Parameters

[in] cli Stream Client to examine

Returns: Socket description or NULL in case of error

References osmo_stream_cli_get_fd().

◆ osmo_stream_cli_is_connected()

bool osmo_stream_cli_is_connected ( struct osmo_stream_cli * cli )

Check if Osmocom Stream Client is in connected state.

Parameters

[in] cli Osmocom Stream Client

Returns: true if connected, false otherwise

Referenced by osmo_stream_cli_send().

◆ osmo_stream_cli_open()

int osmo_stream_cli_open ( struct osmo_stream_cli * cli )

Open connection of an Osmocom stream client.

This will initiate an non-blocking outbound connect to the configured destination (server) address. By default the client will automatically attempt to reconnect after default timeout. To disable this, use osmo_stream_cli_set_reconnect_timeout() before calling this function.

Parameters

[in] cli Stream Client to connect

Returns: negative on error, 0 on success

◆ osmo_stream_cli_open2()

int osmo_stream_cli_open2	(	struct osmo_stream_cli *	cli,
		int	reconnect
	)

DEPRECATED: use osmo_stream_cli_set_reconnect_timeout() or osmo_stream_cli_reconnect() instead! Open connection of an Osmocom stream client.

Parameters

[in]	cli	Stream Client to connect
[in]	reconect	1 if we should not automatically reconnect

Returns: negative on error, 0 on success

◆ osmo_stream_cli_reconnect()

void osmo_stream_cli_reconnect ( struct osmo_stream_cli * cli )

Re-connect an Osmocom Stream 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), we close any existing connection (if any) and schedule a re-connect timer

References osmo_stream_cli_close().

◆ osmo_stream_cli_recv()

int osmo_stream_cli_recv	(	struct osmo_stream_cli *	cli,
		struct msgb *	msg
	)

Receive data via an Osmocom stream client in osmo_fd mode.

Parameters

[in]	cli	Stream Client through which we want to send
	msg	pre-allocate message buffer to which received data is appended

Returns: number of bytes read; <=0 in case of error

Application programs using the legacy osmo_fd mode of osmo_stream_cli will use this function to read/receive from a stream client socket after they have been notified that it is readable (via select/poll).

If conn is an SCTP connection, additional specific considerations shall be taken:

msg->cb is always filled with SCTP ppid, and SCTP stream values, see msgb_sctp_*() APIs.
If an SCTP notification was received when reading from the SCTP socket, msgb_sctp_msg_flags(msg) will contain bit flag OSMO_STREAM_SCTP_MSG_FLAGS_NOTIFICATION set, and the msgb will contain a "union sctp_notification" instead of user data. In this case the return code will be either 0 (if conn is considered dead after the notification) or -EAGAIN (if conn is considered still alive after the notification) resembling the standard recv() API.

◆ osmo_stream_cli_send()

void osmo_stream_cli_send	(	struct osmo_stream_cli *	cli,
		struct msgb *	msg
	)

Enqueue data to be sent via an Osmocom stream client.

This is the function you use for writing/sending/transmitting data via the osmo_stream_cli.

Parameters

[in]	cli	Stream Client through which we want to send
[in]	msg	Message buffer to enqueue in transmit queue

References osmo_stream_cli_is_connected().

◆ osmo_stream_cli_set_addr()

void osmo_stream_cli_set_addr	(	struct osmo_stream_cli *	cli,
		const char *	addr
	)

Set the remote address to which we connect.

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	addr	Remote IP address

References osmo_stream_cli_set_addrs().

◆ osmo_stream_cli_set_addrs()

int osmo_stream_cli_set_addrs	(	struct osmo_stream_cli *	cli,
		const char **	addr,
		size_t	addrcnt
	)

Set the remote address set to which we connect.

Useful for protocols allowing connecting to more than one address (such as SCTP) Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	addr	Remote IP address set

Returns: negative on error, 0 on success

Referenced by osmo_stream_cli_set_addr().

◆ osmo_stream_cli_set_connect_cb()

void osmo_stream_cli_set_connect_cb	(	struct osmo_stream_cli *	cli,
		osmo_stream_cli_connect_cb_t	connect_cb
	)

Set the call-back function called on connect of the stream client socket.

The call-back function registered via this function will be called upon completion of the non-blocking outbound connect operation.

Parameters

[in]	cli	Stream Client to modify
[in]	connect_cb	Call-back function to be called upon connect

◆ osmo_stream_cli_set_data()

void osmo_stream_cli_set_data	(	struct osmo_stream_cli *	cli,
		void *	data
	)

Set application private data of the stream client socket.

Parameters

[in]	cli	Stream Client to modify
[in]	data	User-specific data (available in call-back functions)

◆ osmo_stream_cli_set_disconnect_cb()

void osmo_stream_cli_set_disconnect_cb	(	struct osmo_stream_cli *	cli,
		osmo_stream_cli_disconnect_cb_t	disconnect_cb
	)

Set the call-back function called on disconnect of the stream client socket.

Parameters

[in]	cli	Stream Client to modify
[in]	disconnect_cb	Call-back function to be called upon disconnect

◆ osmo_stream_cli_set_domain()

int osmo_stream_cli_set_domain	(	struct osmo_stream_cli *	cli,
		int	domain
	)

Set the socket type for the stream server link.

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	type	Socket Domain (like AF_UNSPEC (default for IP), AF_UNIX, AF_INET, ...)

Returns: zero on success, negative -errno on error.

◆ osmo_stream_cli_set_local_addr()

void osmo_stream_cli_set_local_addr	(	struct osmo_stream_cli *	cli,
		const char *	addr
	)

Set the local address for the socket (to be bound to).

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	port	Local host name

References osmo_stream_cli_set_local_addrs().

◆ osmo_stream_cli_set_local_addrs()

int osmo_stream_cli_set_local_addrs	(	struct osmo_stream_cli *	cli,
		const char **	addr,
		size_t	addrcnt
	)

Set the local address set to which we bind.

Useful for protocols allowing bind to more than one address (such as SCTP) Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	addr	Local IP address set

Returns: negative on error, 0 on success

Referenced by osmo_stream_cli_set_local_addr().

◆ osmo_stream_cli_set_local_port()

void osmo_stream_cli_set_local_port	(	struct osmo_stream_cli *	cli,
		uint16_t	port
	)

Set the local port number for the socket (to be bound to).

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	port	Local port number

◆ osmo_stream_cli_set_name()

void osmo_stream_cli_set_name	(	struct osmo_stream_cli *	cli,
		const char *	name
	)

Set a name on the cli object (used during logging).

Parameters

[in]	cli	stream_cli whose name is to be set
[in]	name	the name to be set on cli

◆ osmo_stream_cli_set_nodelay()

void osmo_stream_cli_set_nodelay	(	struct osmo_stream_cli *	cli,
		bool	nodelay
	)

Set the NODELAY socket option to avoid Nagle-like behavior.

Setting this to nodelay=true will automatically set the NODELAY socket option on any socket established via osmo_stream_cli_open or any re-connect. You have to set this before opening the socket.

Parameters

[in]	cli	Stream client whose sockets are to be configured
[in]	nodelay	whether to set (true) NODELAY before connect()

◆ osmo_stream_cli_set_param()

int osmo_stream_cli_set_param	(	struct osmo_stream_cli *	cli,
		enum osmo_stream_cli_param	par,
		void *	val,
		size_t	val_len
	)

Set given parameter of stream client to given value.

Parameters

[in]	cli	stream client on which to set parameter.
[in]	par	identifier of the parameter to be set.
[in]	val	value of the parameter to be set.
[in]	val_len	length of the parameter value.

Returns: 0 in success; negative -errno on error.

◆ osmo_stream_cli_set_port()

void osmo_stream_cli_set_port	(	struct osmo_stream_cli *	cli,
		uint16_t	port
	)

Set the remote port number to which we connect.

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	port	Remote port number

◆ osmo_stream_cli_set_proto()

void osmo_stream_cli_set_proto	(	struct osmo_stream_cli *	cli,
		uint16_t	proto
	)

Set the protocol for the stream client socket.

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	proto	Protocol (like IPPROTO_TCP (default), IPPROTO_SCTP, ...)

◆ osmo_stream_cli_set_read_cb()

void osmo_stream_cli_set_read_cb	(	struct osmo_stream_cli *	cli,
		osmo_stream_cli_read_cb_t	read_cb
	)

Set the call-back function called to read from the stream client socket.

This function will implicitly configure osmo_stream_cli to use legacy osmo_ofd mode.

Parameters

[in]	cli	Stream Client to modify
[in]	read_cb	Call-back function to be called when we want to read

◆ osmo_stream_cli_set_read_cb2()

void osmo_stream_cli_set_read_cb2	(	struct osmo_stream_cli *	cli,
		osmo_stream_cli_read_cb2_t	read_cb
	)

Set the call-back function called to read from the stream client socket.

This function will implicitly configure osmo_stream_cli to use osmo_iofd mode.

Parameters

[in]	cli	Stream Client to modify
[in]	read_cb	Call-back function to be called when data was read from the socket

◆ osmo_stream_cli_set_reconnect_timeout()

void osmo_stream_cli_set_reconnect_timeout	(	struct osmo_stream_cli *	cli,
		int	timeout
	)

Set the reconnect time of the stream client socket.

Parameters

[in]	cli	Stream Client to modify
[in]	timeout	Re-connect timeout in seconds or negative value to disable auto-reconnection

◆ osmo_stream_cli_set_segmentation_cb()

void osmo_stream_cli_set_segmentation_cb	(	struct osmo_stream_cli *	cli,
		osmo_stream_cli_segmentation_cb_t	segmentation_cb
	)

Set the segmentation callback for the client.

Parameters

[in,out]	cli	Stream Client to modify
[in]	segmentation_cb	Target segmentation callback

◆ osmo_stream_cli_set_type()

int osmo_stream_cli_set_type	(	struct osmo_stream_cli *	cli,
		int	type
	)

Set the socket type for the stream server link.

Any changes to this setting will only become active upon next (re)connect.

Parameters

[in]	cli	Stream Client to modify
[in]	type	Socket Type (like SOCK_STREAM (default), SOCK_SEQPACKET, ...)

Returns: zero on success, negative -errno on error.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ osmo_stream_cli_read_cb2_t

Function Documentation

◆ osmo_stream_cli_clear_tx_queue()

◆ osmo_stream_cli_close()

◆ osmo_stream_cli_create()

◆ osmo_stream_cli_destroy()

◆ osmo_stream_cli_get_data()

◆ osmo_stream_cli_get_fd()

◆ osmo_stream_cli_get_iofd()

◆ osmo_stream_cli_get_name()

◆ osmo_stream_cli_get_ofd()

◆ osmo_stream_cli_get_sockname()

◆ osmo_stream_cli_is_connected()

◆ osmo_stream_cli_open()

◆ osmo_stream_cli_open2()

◆ osmo_stream_cli_reconnect()

◆ osmo_stream_cli_recv()

◆ osmo_stream_cli_send()

◆ osmo_stream_cli_set_addr()

◆ osmo_stream_cli_set_addrs()

◆ osmo_stream_cli_set_connect_cb()

◆ osmo_stream_cli_set_data()

◆ osmo_stream_cli_set_disconnect_cb()

◆ osmo_stream_cli_set_domain()

◆ osmo_stream_cli_set_local_addr()

◆ osmo_stream_cli_set_local_addrs()

◆ osmo_stream_cli_set_local_port()

◆ osmo_stream_cli_set_name()

◆ osmo_stream_cli_set_nodelay()

◆ osmo_stream_cli_set_param()

◆ osmo_stream_cli_set_port()

◆ osmo_stream_cli_set_proto()

◆ osmo_stream_cli_set_read_cb()

◆ osmo_stream_cli_set_read_cb2()

◆ osmo_stream_cli_set_reconnect_timeout()

◆ osmo_stream_cli_set_segmentation_cb()

◆ osmo_stream_cli_set_type()