libosmo-netif: Osmocom Stream Server

libosmo-netif 1.7.0.15-fe2d Osmocom network interface library

Typedefs | Enumerations | Functions
Osmocom Stream Server

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

## Typedefs
typedef int(* | osmo_stream_srv_link_accept_cb_t) (struct osmo_stream_srv_link *link, int fd)
typedef int(* | osmo_stream_srv_read_cb_t) (struct osmo_stream_srv *conn)
typedef int(* | osmo_stream_srv_closed_cb_t) (struct osmo_stream_srv *conn)
typedef int(* | osmo_stream_srv_read_cb2_t) (struct osmo_stream_srv *conn, int res, struct msgb *msg)
| Completion call-back function when something was read from from the stream client socket. More...
typedef int(* | osmo_stream_srv_segmentation_cb_t) (struct msgb *msg)
typedef int(* | osmo_stream_srv_segmentation_cb2_t) (struct osmo_stream_srv *conn, struct msgb *msg)

## Enumerations
enum | osmo_stream_srv_link_param { OSMO_STREAM_SRV_LINK_PAR_SCTP_SOCKOPT_AUTH_SUPPORTED , OSMO_STREAM_SRV_LINK_PAR_SCTP_SOCKOPT_ASCONF_SUPPORTED , OSMO_STREAM_SRV_LINK_PAR_SCTP_INIT_NUM_OSTREAMS , OSMO_STREAM_SRV_LINK_PAR_SCTP_INIT_MAX_INSTREAMS , OSMO_STREAM_SRV_LINK_PAR_TCP_SOCKOPT_KEEPALIVE = 256 , OSMO_STREAM_SRV_LINK_PAR_TCP_SOCKOPT_KEEPIDLE , OSMO_STREAM_SRV_LINK_PAR_TCP_SOCKOPT_KEEPINTVL , OSMO_STREAM_SRV_LINK_PAR_TCP_SOCKOPT_KEEPCNT , OSMO_STREAM_SRV_LINK_PAR_TCP_SOCKOPT_USER_TIMEOUT }
enum | osmo_stream_srv_param { OSMO_STREAM_SRV_PAR_TCP_SOCKOPT_KEEPALIVE = 256 , OSMO_STREAM_SRV_PAR_TCP_SOCKOPT_KEEPIDLE , OSMO_STREAM_SRV_PAR_TCP_SOCKOPT_KEEPINTVL , OSMO_STREAM_SRV_PAR_TCP_SOCKOPT_KEEPCNT , OSMO_STREAM_SRV_PAR_TCP_SOCKOPT_USER_TIMEOUT }

## Functions
struct osmo_stream_srv_link * | osmo_stream_srv_link_create (void *ctx)
| Create an Osmocom Stream Server Link. More...
void | osmo_stream_srv_link_destroy (struct osmo_stream_srv_link *link)
| Destroy the stream server link. More...
void | osmo_stream_srv_link_set_name (struct osmo_stream_srv_link *link, const char *name)
| Set a name on the srv_link object (used during logging). More...
const char * | osmo_stream_srv_link_get_name (const struct osmo_stream_srv_link *link)
| Retrieve name previously set on the srv_link object (see osmo_stream_srv_link_set_name()). More...
void | osmo_stream_srv_link_set_nodelay (struct osmo_stream_srv_link *link, bool nodelay)
| Set the NODELAY socket option to avoid Nagle-like behavior. More...
int | osmo_stream_srv_link_set_priority (struct osmo_stream_srv_link *link, int sk_prio)
| Set the priority value of the stream socket. More...
int | osmo_stream_srv_link_set_ip_dscp (struct osmo_stream_srv_link *link, uint8_t ip_dscp)
| Set the DSCP (differentiated services code point) of the stream socket. More...
void | osmo_stream_srv_link_set_addr (struct osmo_stream_srv_link *link, const char *addr)
| Set the local address to which we bind. More...
int | osmo_stream_srv_link_set_addrs (struct osmo_stream_srv_link *link, const char **addr, size_t addrcnt)
| Set the local address set to which we bind. More...
void | osmo_stream_srv_link_set_port (struct osmo_stream_srv_link *link, uint16_t port)
| Set the local port number to which we bind. More...
void | osmo_stream_srv_link_set_proto (struct osmo_stream_srv_link *link, uint16_t proto)
| Set the protocol for the stream server link. More...
int | osmo_stream_srv_link_set_type (struct osmo_stream_srv_link *link, int type)
| Set the socket type for the stream server link. More...
int | osmo_stream_srv_link_set_domain (struct osmo_stream_srv_link *link, int domain)
| Set the socket domain for the stream server link. More...
void | osmo_stream_srv_link_set_accept_cb (struct osmo_stream_srv_link *link, int(*accept_cb)(struct osmo_stream_srv_link *link, int fd))
| Set the accept() call-back of the stream server link. More...
void | osmo_stream_srv_link_set_data (struct osmo_stream_srv_link *link, void *data)
| Set application private data of the stream server link. More...
void * | osmo_stream_srv_link_get_data (struct osmo_stream_srv_link *link)
| Retrieve application private data of the stream server link. More...
int | osmo_stream_srv_link_set_tx_queue_max_length (struct osmo_stream_srv_link *link, unsigned int size)
| Set the maximum length queue of the stream servers accepted and allocated from this server link. More...
char * | osmo_stream_srv_link_get_sockname (const struct osmo_stream_srv_link *link)
| Retrieve description of the stream server link e. More...
struct osmo_fd * | osmo_stream_srv_link_get_ofd (struct osmo_stream_srv_link *link)
| Retrieve Osmocom File Descriptor of the stream server link. More...
int | osmo_stream_srv_link_get_fd (const struct osmo_stream_srv_link *link)
| Retrieve File Descriptor of the stream server link. More...
int | osmo_stream_srv_link_set_msgb_alloc_info (struct osmo_stream_srv_link *link, unsigned int size, unsigned int headroom)
| Set the msgb allocation parameters on child osmo_stream_srv objects. More...
bool | osmo_stream_srv_link_is_opened (const struct osmo_stream_srv_link *link)
| Check whether the stream server link is opened. More...
int | osmo_stream_srv_link_open (struct osmo_stream_srv_link *link)
| Open the stream server link. More...
void | osmo_stream_srv_link_close (struct osmo_stream_srv_link *link)
| Close the stream server link and unregister from select loop. More...
int | osmo_stream_srv_link_set_param (struct osmo_stream_srv_link *link, enum osmo_stream_srv_link_param par, void *val, size_t val_len)
| Set given parameter of stream_srv_link to given value. More...
struct osmo_stream_srv * | osmo_stream_srv_create (void *ctx, struct osmo_stream_srv_link *link, int fd, osmo_stream_srv_read_cb_t read_cb, osmo_stream_srv_closed_cb_t closed_cb, void *data)
| Create a legacy osmo_fd mode Stream Server inside the specified link. More...
struct osmo_stream_srv * | osmo_stream_srv_create2 (void *ctx, struct osmo_stream_srv_link *link, int fd, void *data)
| Create an osmo_iofd mode Stream Server inside the specified link. More...
void | osmo_stream_srv_set_name (struct osmo_stream_srv *conn, const char *name)
| Set a name on the srv object (used during logging). More...
void | osmo_stream_srv_set_name_f (struct osmo_stream_srv *conn, const char *fmt,...)
| Set a name on the srv object using arguments like printf() (used during logging). More...
const char * | osmo_stream_srv_get_name (const struct osmo_stream_srv *conn)
| Retrieve name previously set on the srv object (see osmo_stream_srv_set_name()). More...
void | osmo_stream_srv_set_read_cb (struct osmo_stream_srv *conn, osmo_stream_srv_read_cb2_t read_cb)
| Set the call-back function for incoming data on an osmo_io stream_srv. More...
void | osmo_stream_srv_set_closed_cb (struct osmo_stream_srv *conn, osmo_stream_srv_closed_cb_t closed_cb)
| Set the call-back function called when the stream server socket was closed. More...
void * | osmo_stream_srv_get_data (struct osmo_stream_srv *conn)
| Retrieve application private data of the stream server. More...
int | osmo_stream_srv_set_tx_queue_max_length (struct osmo_stream_srv *conn, unsigned int size)
| Set the maximum length queue of the stream server connection. More...
struct osmo_stream_srv_link * | osmo_stream_srv_get_master (struct osmo_stream_srv *conn)
| Retrieve the master (Link) from a Stream Server. More...
const char * | osmo_stream_srv_get_sockname (const struct osmo_stream_srv *conn)
| Retrieve the stream server socket description. More...
struct osmo_fd * | osmo_stream_srv_get_ofd (struct osmo_stream_srv *conn)
| Retrieve Osmocom File Descriptor of a stream server in osmo_fd mode. More...
int | osmo_stream_srv_get_fd (const struct osmo_stream_srv *conn)
| Retrieve File Descriptor of the stream server. More...
struct osmo_io_fd * | osmo_stream_srv_get_iofd (const struct osmo_stream_srv *srv)
| Retrieve osmo_io descriptor of the stream server socket. More...
void | osmo_stream_srv_destroy (struct osmo_stream_srv *conn)
| Destroy given Stream Server. More...
void | osmo_stream_srv_set_flush_and_destroy (struct osmo_stream_srv *conn)
| Prepare to send out all pending messages on the connection's Tx queue. More...
void | osmo_stream_srv_set_data (struct osmo_stream_srv *conn, void *data)
| Set application private data of the stream server. More...
void | osmo_stream_srv_set_segmentation_cb (struct osmo_stream_srv *conn, osmo_stream_srv_segmentation_cb_t segmentation_cb)
| Set the segmentation callback for target osmo_stream_srv structure. More...
void | osmo_stream_srv_set_segmentation_cb2 (struct osmo_stream_srv *conn, osmo_stream_srv_segmentation_cb2_t segmentation_cb2)
| Set the segmentation callback for target osmo_stream_srv structure. More...
void | osmo_stream_srv_send (struct osmo_stream_srv *conn, struct msgb *msg)
| Enqueue data to be sent via an Osmocom stream server. More...
int | osmo_stream_srv_recv (struct osmo_stream_srv *conn, struct msgb *msg)
| Receive data via an Osmocom stream server in osmo_fd mode. More...
void | osmo_stream_srv_clear_tx_queue (struct osmo_stream_srv *conn)
int | osmo_stream_srv_set_param (struct osmo_stream_srv *conn, enum osmo_stream_srv_param par, void *val, size_t val_len)
| Set given parameter of stream_srv to given value. More...

## Detailed Description

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 modern mode is chosen by invoking osmo_stream_srv_create2(). The legacy mode is chosen by invoking the older osmo_stream_srv_create().

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.

## Typedef Documentation

## ◆ osmo_stream_srv_read_cb2_t

typedef int(* osmo_stream_srv_read_cb2_t) (struct osmo_stream_srv *conn, int res, struct msgb *msg)

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

Parameters

  [in] | conn | Stream Server 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_srv_create()

struct osmo_stream_srv * osmo_stream_srv_create | ( | void * | ctx,
|  | struct osmo_stream_srv_link * | link,
|  | int | fd,
|  | osmo_stream_srv_read_cb_t | read_cb,
|  | osmo_stream_srv_closed_cb_t | closed_cb,
|  | void * | data
| ) |  |

Create a legacy osmo_fd mode Stream Server inside the specified link.

This is the function an application traditionally calls from within the accept_cb call-back of the osmo_stream_srv_link. It creates a new osmo_stream_srv within that link.

New users/programs should use osmo_stream_srv_create2 to operate in osmo_io mode instead.

Parameters

  [in] | ctx | talloc allocation context from which to allocate
  [in] | link | Stream Server Link to which we belong
  [in] | fd | system file descriptor of the new connection
  [in] | read_cb | Call-back to call when the socket is readable
  [in] | closed_cb | Call-back to call when the connection is closed
  [in] | data | User data to save in the new Stream Server struct

Returns
  Stream Server in case of success; NULL on error

Note: In case of error, the caller is responsible for closing the fd.

## ◆ osmo_stream_srv_create2()

struct osmo_stream_srv * osmo_stream_srv_create2 | ( | void * | ctx,
|  | struct osmo_stream_srv_link * | link,
|  | int | fd,
|  | void * | data
| ) |  |

Create an osmo_iofd mode Stream Server inside the specified link.

This is the function an application typically calls from within the accept_cb call-back of the osmo_stream_srv_link. It creates a new osmo_stream_srv in osmo_io mode within that link.

Parameters

  [in] | ctx | talloc allocation context from which to allocate
  [in] | link | Stream Server Link to which we belong
  [in] | fd | system file descriptor of the new connection
  [in] | data | User data to save in the new Stream Server struct

Returns
  Stream Server in case of success; NULL on error

Note: In case of error, the caller is responsible for closing the fd.

## ◆ osmo_stream_srv_destroy()

void osmo_stream_srv_destroy | ( | struct osmo_stream_srv * | conn | ) |

Destroy given Stream Server.

This function closes the Stream Server socket, unregisters from the underlying I/O mechanism, invokes the connection's closed_cb() callback to allow API users to clean up any associated state they have for this connection, and then de-allocates associated memory.

Parameters

  [in] | conn | Stream Server to be destroyed

## ◆ osmo_stream_srv_get_data()

void * osmo_stream_srv_get_data | ( | struct osmo_stream_srv * | conn | ) |

Retrieve application private data of the stream server.

Parameters

  [in] | conn | Stream Server

Returns
  Application private data, as set by osmo_stream_srv_set_data()

## ◆ osmo_stream_srv_get_fd()

int osmo_stream_srv_get_fd | ( | const struct osmo_stream_srv * | conn | ) |

Retrieve File Descriptor of the stream server.

Parameters

  [in] | conn | Stream Server

Returns
  file descriptor or negative on error

Referenced by osmo_stream_srv_get_sockname().

## ◆ osmo_stream_srv_get_iofd()

struct osmo_io_fd * osmo_stream_srv_get_iofd | ( | const struct osmo_stream_srv * | srv | ) |

Retrieve osmo_io descriptor of the stream server socket.

This function must not be called on a stream server in legacy osmo_fd mode!

Parameters

  [in] | srv | Stream Server of which we want to obtain the osmo_io descriptor

Returns
  osmo_io_fd of stream server.

## ◆ osmo_stream_srv_get_master()

struct osmo_stream_srv_link * osmo_stream_srv_get_master | ( | struct osmo_stream_srv * | conn | ) |

Retrieve the master (Link) from a Stream Server.

Parameters

  [in] | conn | Stream Server of which we want to know the Link

Returns
  Link through which the given Stream Server is established

## ◆ osmo_stream_srv_get_name()

const char * osmo_stream_srv_get_name | ( | const struct osmo_stream_srv * | conn | ) |

Retrieve name previously set on the srv object (see osmo_stream_srv_set_name()).

Parameters

  [in] | conn | server whose name is to be retrieved

Returns
  The name to be set on conn; NULL if never set

## ◆ osmo_stream_srv_get_ofd()

struct osmo_fd * osmo_stream_srv_get_ofd | ( | struct osmo_stream_srv * | conn | ) |

Retrieve Osmocom File Descriptor of a stream server in osmo_fd mode.

Parameters

  [in] | conn | Stream Server

Returns
  Pointer to osmo_fd

## ◆ osmo_stream_srv_get_sockname()

const char * osmo_stream_srv_get_sockname | ( | const struct osmo_stream_srv * | conn | ) |

Retrieve the stream server socket description.

The returned name is stored in a static buffer; it is hence not re-entrant or thread-safe!

Parameters

  [in] | conn | Stream Server to examine

Returns
  Socket description or NULL in case of error

References osmo_stream_srv_get_fd().

## ◆ osmo_stream_srv_link_close()

void osmo_stream_srv_link_close | ( | struct osmo_stream_srv_link * | link | ) |

Close the stream server link and unregister from select loop.

Does not destroy the server link, merely closes it!

Parameters

  [in] | link | Stream Server Link to close

References osmo_stream_srv_link_is_opened().

Referenced by osmo_stream_srv_link_destroy().

## ◆ osmo_stream_srv_link_create()

struct osmo_stream_srv_link * osmo_stream_srv_link_create | ( | void * | ctx | ) |

Create an Osmocom Stream Server Link.

A Stream Server Link is the listen()+accept() "parent" to individual connections from remote clients.

Parameters

  [in] | ctx | talloc allocation context

Returns
  Stream Server Link with default values (AF_UNSPEC, SOCK_STREAM, IPPROTO_TCP)

## ◆ osmo_stream_srv_link_destroy()

void osmo_stream_srv_link_destroy | ( | struct osmo_stream_srv_link * | link | ) |

Destroy the stream server link.

Closes + Releases Memory.

Parameters

  [in] | link | Stream Server Link

References osmo_stream_srv_link_close().

## ◆ osmo_stream_srv_link_get_data()

void * osmo_stream_srv_link_get_data | ( | struct osmo_stream_srv_link * | link | ) |

Retrieve application private data of the stream server link.

Parameters

  [in] | link | Stream Server Link to modify

Returns
  Application private data, as set by osmo_stream_cli_set_data()

## ◆ osmo_stream_srv_link_get_fd()

int osmo_stream_srv_link_get_fd | ( | const struct osmo_stream_srv_link * | link | ) |

Retrieve File Descriptor of the stream server link.

Parameters

  [in] | conn | Stream Server Link

Returns
  file descriptor or negative on error

## ◆ osmo_stream_srv_link_get_name()

const char * osmo_stream_srv_link_get_name | ( | const struct osmo_stream_srv_link * | link | ) |

Retrieve name previously set on the srv_link object (see osmo_stream_srv_link_set_name()).

Parameters

  [in] | link | server link whose name is to be retrieved

Returns
  The name to be set on link; NULL if never set

## ◆ osmo_stream_srv_link_get_ofd()

struct osmo_fd * osmo_stream_srv_link_get_ofd | ( | struct osmo_stream_srv_link * | link | ) |

Retrieve Osmocom File Descriptor of the stream server link.

Parameters

  [in] | link | Stream Server Link

Returns
  Pointer to osmo_fd

## ◆ osmo_stream_srv_link_get_sockname()

char * osmo_stream_srv_link_get_sockname | ( | const struct osmo_stream_srv_link * | link | ) |

Retrieve description of the stream server link e.

g. 127.0.0.1:1234. 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] | link | Stream Server Link to examine

Returns
  Link description or NULL in case of error

## ◆ osmo_stream_srv_link_is_opened()

bool osmo_stream_srv_link_is_opened | ( | const struct osmo_stream_srv_link * | link | ) |

Check whether the stream server link is opened.

Parameters

  [in] | link | Stream Server Link to check

Referenced by osmo_stream_srv_link_close().

## ◆ osmo_stream_srv_link_open()

int osmo_stream_srv_link_open | ( | struct osmo_stream_srv_link * | link | ) |

Open the stream server link.

This actually initializes the underlying socket and binds it to the configured ip/port.

Parameters

  [in] | link | Stream Server Link to open

Returns
  negative on error, 0 on success

## ◆ osmo_stream_srv_link_set_accept_cb()

void osmo_stream_srv_link_set_accept_cb | ( | struct osmo_stream_srv_link * | link,
|  | int(*)(struct osmo_stream_srv_link *link, int fd) | accept_cb
| ) |  |

Set the accept() call-back of the stream server link.

The provided call-back will be called whenever a new inbound connection is accept()ed. The call-back then typically creates a new osmo_stream_srv. If the call-back returns a negative value, the file descriptor will be closed.

Parameters

  [in] | link | Stream Server Link
  [in] | accept_cb | Call-back function executed upon accept()

## ◆ osmo_stream_srv_link_set_addr()

void osmo_stream_srv_link_set_addr | ( | struct osmo_stream_srv_link * | link,
|  | const char * | addr
| ) |  |

Set the local address to which we bind.

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

Parameters

  [in] | link | Stream Server Link to modify
  [in] | addr | Local IP address

References osmo_stream_srv_link_set_addrs().

## ◆ osmo_stream_srv_link_set_addrs()

int osmo_stream_srv_link_set_addrs | ( | struct osmo_stream_srv_link * | link,
|  | const char ** | addr,
|  | size_t | addrcnt
| ) |  |

Set the local address set to which we bind.

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

Parameters

  [in] | link | Stream Server Link to modify
  [in] | addr | Local IP address

Returns
  negative on error, 0 on success

Referenced by osmo_stream_srv_link_set_addr().

## ◆ osmo_stream_srv_link_set_data()

void osmo_stream_srv_link_set_data | ( | struct osmo_stream_srv_link * | link,
|  | void * | data
| ) |  |

Set application private data of the stream server link.

Parameters

  [in] | link | Stream Server Link to modify
  [in] | data | User-specific data (available in call-back functions)

## ◆ osmo_stream_srv_link_set_domain()

int osmo_stream_srv_link_set_domain | ( | struct osmo_stream_srv_link * | link,
|  | int | domain
| ) |  |

Set the socket domain for the stream server link.

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

Parameters

  [in] | link | Stream Server Link to modify
  [in] | domain | Socket Domain (like AF_UNSPEC (default for IP), AF_UNIX, AF_INET, ...)

Returns
  zero on success, negative on error.

## ◆ osmo_stream_srv_link_set_ip_dscp()

int osmo_stream_srv_link_set_ip_dscp | ( | struct osmo_stream_srv_link * | link,
|  | uint8_t | ip_dscp
| ) |  |

Set the DSCP (differentiated services code point) of the stream socket.

Setting this will automatically set the IP DSCP option on any socket on any socket established via this server link, before calling the accept_cb().

Parameters

  [in] | link | server link whose sockets are to be configured
  [in] | ip_dscp | DSCP value. Value range 0..63.

Returns
  negative on error, 0 on success

## ◆ osmo_stream_srv_link_set_msgb_alloc_info()

int osmo_stream_srv_link_set_msgb_alloc_info | ( | struct osmo_stream_srv_link * | link,
|  | unsigned int | size,
|  | unsigned int | headroom
| ) |  |

Set the msgb allocation parameters on child osmo_stream_srv objects.

Parameters

  [in] | link | Stream Server Link
  [in] | size | Size of msgb to allocate (excluding headroom)
  [in] | headroom | Headroom to allocate when allocating msgb's

The parameters are applied to osmo_stream_srv objects upon creation. Setting both to 0 leaves it as implementation default.

## ◆ osmo_stream_srv_link_set_name()

void osmo_stream_srv_link_set_name | ( | struct osmo_stream_srv_link * | link,
|  | const char * | name
| ) |  |

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

Parameters

  [in] | link | server link whose name is to be set. The name is copied into the osmo_stream_srv_link, so the caller memory is not required to be valid beyond the call of this function.
  [in] | name | the name to be set on link

## ◆ osmo_stream_srv_link_set_nodelay()

void osmo_stream_srv_link_set_nodelay | ( | struct osmo_stream_srv_link * | link,
|  | 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 this server link, before calling the accept_cb()

Parameters

  [in] | link | server link whose sockets are to be configured
  [in] | nodelay | whether to set (true) NODELAY after accept

## ◆ osmo_stream_srv_link_set_param()

int osmo_stream_srv_link_set_param | ( | struct osmo_stream_srv_link * | link,
|  | enum osmo_stream_srv_link_param | par,
|  | void * | val,
|  | size_t | val_len
| ) |  |

Set given parameter of stream_srv_link to given value.

Parameters

  [in] | link | stream server link 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_srv_link_set_port()

void osmo_stream_srv_link_set_port | ( | struct osmo_stream_srv_link * | link,
|  | uint16_t | port
| ) |  |

Set the local port number to which we bind.

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

Parameters

  [in] | link | Stream Server Link to modify
  [in] | port | Local port number

## ◆ osmo_stream_srv_link_set_priority()

int osmo_stream_srv_link_set_priority | ( | struct osmo_stream_srv_link * | link,
|  | int | sk_prio
| ) |  |

Set the priority value of the stream socket.

Setting this will automatically set the socket priority option on any socket established via this server link, before calling the accept_cb().

Parameters

  [in] | link | server link whose sockets are to be configured
  [in] | sk_prio | priority value. Values outside 0..6 require CAP_NET_ADMIN.

Returns
  negative on error, 0 on success

## ◆ osmo_stream_srv_link_set_proto()

void osmo_stream_srv_link_set_proto | ( | struct osmo_stream_srv_link * | link,
|  | uint16_t | proto
| ) |  |

Set the protocol for the stream server link.

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

Parameters

  [in] | link | Stream Server Link to modify
  [in] | proto | Protocol (like IPPROTO_TCP (default), IPPROTO_SCTP, ...)

## ◆ osmo_stream_srv_link_set_tx_queue_max_length()

int osmo_stream_srv_link_set_tx_queue_max_length | ( | struct osmo_stream_srv_link * | link,
|  | unsigned int | size
| ) |  |

Set the maximum length queue of the stream servers accepted and allocated from this server link.

Parameters

  [in] | link | Stream Server Link to modify
  [in] | size | maximum amount of msgbs which can be queued in the internal tx queue.

Returns
  0 on success, negative on error.

The maximum length queue default value is 1024 msgbs.

## ◆ osmo_stream_srv_link_set_type()

int osmo_stream_srv_link_set_type | ( | struct osmo_stream_srv_link * | link,
|  | 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] | link | Stream Server Link to modify
  [in] | type | Socket Type (like SOCK_STREAM (default), SOCK_SEQPACKET, ...)

Returns
  zero on success, negative on error.

## ◆ osmo_stream_srv_recv()

int osmo_stream_srv_recv | ( | struct osmo_stream_srv * | conn,
|  | struct msgb * | msg
| ) |  |

Receive data via an Osmocom stream server in osmo_fd mode.

Parameters

  [in] | conn | Stream Server from which to receive
  | msg | pre-allocate message buffer to which received data is appended

Returns
  number of bytes read, negative on error.

Application programs using the legacy osmo_fd mode of osmo_stream_srv will use this function to read/receive from a stream 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_srv_send()

void osmo_stream_srv_send | ( | struct osmo_stream_srv * | conn,
|  | struct msgb * | msg
| ) |  |

Enqueue data to be sent via an Osmocom stream server.

Parameters

  [in] | conn | Stream Server through which we want to send
  [in] | msg | Message buffer to enqueue in transmit queue

## ◆ osmo_stream_srv_set_closed_cb()

void osmo_stream_srv_set_closed_cb | ( | struct osmo_stream_srv * | conn,
|  | osmo_stream_srv_closed_cb_t | closed_cb
| ) |  |

Set the call-back function called when the stream server socket was closed.

Whenever the socket was closed (network error, client disconnect, etc.), the user-provided call-back function given here is called. This is typically used by the application to clean up any of its internal state related to this specific client/connection.

Parameters

  [in] | conn | Stream Server to modify
  [in] | closed_cb | Call-back function to be called when the connection was closed

## ◆ osmo_stream_srv_set_data()

void osmo_stream_srv_set_data | ( | struct osmo_stream_srv * | conn,
|  | void * | data
| ) |  |

Set application private data of the stream server.

Parameters

  [in] | conn | Stream Server to modify
  [in] | data | User-specific data (available in call-back functions)

## ◆ osmo_stream_srv_set_flush_and_destroy()

void osmo_stream_srv_set_flush_and_destroy | ( | struct osmo_stream_srv * | conn | ) |

Prepare to send out all pending messages on the connection's Tx queue.

and then automatically destroy the stream with osmo_stream_srv_destroy(). This function disables queuing of new messages on the connection and also disables reception of new messages on the connection.

Parameters

  [in] | conn | Stream Server to modify

## ◆ osmo_stream_srv_set_name()

void osmo_stream_srv_set_name | ( | struct osmo_stream_srv * | conn,
|  | const char * | name
| ) |  |

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

Parameters

  [in] | conn | server whose name is to be set. The name is copied into the osmo_stream_srv_link, so the caller memory is not required to be valid beyond the call of this function.
  [in] | name | the name to be set on conn

References osmo_stream_srv_set_name_f().

## ◆ osmo_stream_srv_set_name_f()

void osmo_stream_srv_set_name_f | ( | struct osmo_stream_srv * | conn,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Set a name on the srv object using arguments like printf() (used during logging).

Parameters

  [in] | srv | stream_srv whose name is to be set
  [in] | name | the name to be set on srv

Referenced by osmo_stream_srv_set_name().

## ◆ osmo_stream_srv_set_param()

int osmo_stream_srv_set_param | ( | struct osmo_stream_srv * | conn,
|  | enum osmo_stream_srv_param | par,
|  | void * | val,
|  | size_t | val_len
| ) |  |

Set given parameter of stream_srv to given value.

Parameters

  [in] | conn | stream server conn 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_srv_set_read_cb()

void osmo_stream_srv_set_read_cb | ( | struct osmo_stream_srv * | conn,
|  | osmo_stream_srv_read_cb2_t | read_cb
| ) |  |

Set the call-back function for incoming data on an osmo_io stream_srv.

This function only works with osmo_stream_srv in osmo_io mode, created by osmo_stream_srv_create2()!

Whenever data is received on the osmo_stram_srv, the read_cb call-back function of the user application is called.

Parameters

  [in] | conn | Stream Server to modify
  [in] | read_cb | Call-back function to be called when data was read

## ◆ osmo_stream_srv_set_segmentation_cb()

void osmo_stream_srv_set_segmentation_cb | ( | struct osmo_stream_srv * | conn,
|  | osmo_stream_srv_segmentation_cb_t | segmentation_cb
| ) |  |

Set the segmentation callback for target osmo_stream_srv structure.

Parameters

  [in,out] | conn | Target Stream Server to modify
  [in] | segmentation_cb | Segmentation callback to be set

A segmentation call-back can optionally be used when a packet based protocol (like TCP) is used within a STREAM style socket that does not preserve message boundaries within the stream. If a segmentation call-back is given, the osmo_stream_srv library code will makes sure that the read_cb called only for complete single messages, and not arbitrary segments of the stream.

This function only works with osmo_stream_srv in osmo_io mode, created by osmo_stream_srv_create2()! The connection has to have been established prior to calling this function.

## ◆ osmo_stream_srv_set_segmentation_cb2()

void osmo_stream_srv_set_segmentation_cb2 | ( | struct osmo_stream_srv * | conn,
|  | osmo_stream_srv_segmentation_cb2_t | segmentation_cb2
| ) |  |

Set the segmentation callback for target osmo_stream_srv structure.

Parameters

  [in,out] | conn | Target Stream Server to modify
  [in] | segmentation_cb2 | Segmentation callback to be set

Same as osmo_stream_srv_set_segmentation_cb(), but a osmo_stream_srv_segmentation_cb2_t is called instead which allows access to the related conn object.

## ◆ osmo_stream_srv_set_tx_queue_max_length()

int osmo_stream_srv_set_tx_queue_max_length | ( | struct osmo_stream_srv * | conn,
|  | unsigned int | size
| ) |  |

Set the maximum length queue of the stream server connection.

Parameters

  [in] | conn | Stream Server to modify
  [in] | size | maximum amount of msgbs which can be queued in the internal tx queue.

Returns
  0 on success, negative on error.

The default queue size of a osmo_stream_srv is inherited during creation time from osmo_stream_srv_link.