proto_clnt.c File Reference

e1d protocol client library (libosmo-e1d). More...

#include <errno.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <talloc.h>
#include <osmocom/core/linuxlist.h>
#include <osmocom/core/logging.h>
#include <osmocom/core/msgb.h>
#include <osmocom/core/select.h>
#include <osmocom/core/socket.h>
#include <osmocom/core/utils.h>
#include <osmocom/e1d/proto.h>
#include <osmocom/e1d/proto_clnt.h>
#include "log.h"

Data Structures
struct	osmo_e1dp_client
	Internal representation of client program connected to the CTL socket. More...

Typedefs
typedef void(*	osmo_e1dp_event_cb_t) (enum osmo_e1dp_msg_type, uint8_t, uint8_t, uint8_t, uint8_t *, int)

Functions
struct osmo_e1dp_client *	osmo_e1dp_client_create (void *ctx, const char *path)
	Create a new client talking to the CTL server socket of osmo-e1d.
void	osmo_e1dp_client_destroy (struct osmo_e1dp_client *clnt)
	Destroy a previously created client.
int	osmo_e1dp_client_intf_query (struct osmo_e1dp_client *clnt, struct osmo_e1dp_intf_info **ii, int *n, uint8_t intf)
	Query osmo-e1d for information about a specific E1 interface.
int	osmo_e1dp_client_line_query (struct osmo_e1dp_client *clnt, struct osmo_e1dp_line_info **li, int *n, uint8_t intf, uint8_t line)
	Query osmo-e1d for information about a specific E1 line.
int	osmo_e1dp_client_ts_query (struct osmo_e1dp_client *clnt, struct osmo_e1dp_ts_info **ti, int *n, uint8_t intf, uint8_t line, uint8_t ts)
	Query osmo-e1d for information about a specific E1 timeslot.
int	osmo_e1dp_client_line_config (struct osmo_e1dp_client *clnt, uint8_t intf, uint8_t line, enum osmo_e1dp_line_mode mode)
	Configure a specific E1 line in osmo-e1d.
int	osmo_e1dp_client_set_sa_bits (struct osmo_e1dp_client *clnt, uint8_t intf, uint8_t line, uint8_t sa_bits)
	Set Sa-bits of a specific E1 line in osmo-e1d.
int	osmo_e1dp_client_ts_open (struct osmo_e1dp_client *clnt, uint8_t intf, uint8_t line, uint8_t ts, enum osmo_e1dp_ts_mode mode, uint16_t read_bufsize)
	Open a specific E1 timeslot of osmo-e1d.
int	osmo_e1dp_client_ts_open_force (struct osmo_e1dp_client *clnt, uint8_t intf, uint8_t line, uint8_t ts, enum osmo_e1dp_ts_mode mode, uint16_t read_bufsize)
	Force-Open a specific E1 timeslot of osmo-e1d.
void	osmo_e1dp_client_event_register (struct osmo_e1dp_client *clnt, void(*cb)(enum osmo_e1dp_msg_type event, uint8_t intf, uint8_t line, uint8_t ts, uint8_t *data, int len))
	Register event handler for incoming event messages.

Detailed Description

e1d protocol client library (libosmo-e1d).

This library implements ways how an external client (application program) can talk to osmo-e1d. The primary purpose is to open specific E1 timeslots in order to receive and/or transmit data on them.

Each such open timeslot is represented to the client program as a file descriptor, which the client can read and/or write as usual. This is implemented using underlying UNIX domain sockets and file descriptor passing.

In addition to opening timeslots, client applications can also query osmo-e1d for information about its E1 interfaces, E1 lines and E1 timeslots.

The functions provided by this client library are implemented as synchronous/blocking calls to osmo-e1d. This means that an API call will be blocking until there is a response received from osmo-e1d.

Typedef Documentation

osmo_e1dp_event_cb_t

typedef void(* osmo_e1dp_event_cb_t) (enum osmo_e1dp_msg_type, uint8_t, uint8_t, uint8_t, uint8_t *, int)

Function Documentation

osmo_e1dp_client_create()

struct osmo_e1dp_client * osmo_e1dp_client_create	(	void *	ctx,
		const char *	path )

Create a new client talking to the CTL server socket of osmo-e1d.

Parameters

[in]	ctx	talloc context from which this client is allocated
[in]	path	path of the CTL unix domain socket of osmo-e1d

Returns

handle to newly-created client; NULL in case of errors

References osmo_e1dp_client::ctl_fd, and osmo_e1dp_client::ctx.

osmo_e1dp_client_destroy()

void osmo_e1dp_client_destroy

(

struct osmo_e1dp_client *

clnt

)

Destroy a previously created client.

Closes socket and releases memory.

Parameters

[in]

clnt

Client previously returned from osmo_e1dp_client_create().

References osmo_e1dp_client::ctl_fd.

osmo_e1dp_client_event_register()

void osmo_e1dp_client_event_register	(	struct osmo_e1dp_client *	clnt,
		void(*	cb )(enum osmo_e1dp_msg_type event, uint8_t intf, uint8_t line, uint8_t ts, uint8_t *data, int len) )

Register event handler for incoming event messages.

Parameters

[in]

clnt

Client previously returned from osmo_e1dp_client_create().

References osmo_e1dp_client::event_cb, intf, len, line, and ts.

osmo_e1dp_client_intf_query()

int osmo_e1dp_client_intf_query	(	struct osmo_e1dp_client *	clnt,
		struct osmo_e1dp_intf_info **	ii,
		int *	n,
		uint8_t	intf )

Query osmo-e1d for information about a specific E1 interface.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[out]	ii	callee-allocated array of interface information structures.
[out]	n	caller-provided pointer to integer. Will contain number of entries in ii.
[in]	intf	E1 interface number to query, or E1DP_INVALID to query all interfaces.

Returns

zero in case of success; negative in case of error.

References osmo_e1dp_client::ctx, E1DP_CMD_INTF_QUERY, E1DP_INVALID, intf, osmo_e1dp_msg_hdr::intf, osmo_e1dp_msg_hdr::line, osmo_e1dp_msg_hdr::ts, and osmo_e1dp_msg_hdr::type.

osmo_e1dp_client_line_config()

int osmo_e1dp_client_line_config	(	struct osmo_e1dp_client *	clnt,
		uint8_t	intf,
		uint8_t	line,
		enum osmo_e1dp_line_mode	mode )

Configure a specific E1 line in osmo-e1d.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[in]	intf	E1 interface number to configure.
[in]	line	E1 line number (within interface) to configure.
[in]	mode	E1 line mode to set on line.

Returns

zero in case of success; negative in case of error.

References cfg, E1DP_CMD_LINE_CONFIG, E1DP_INVALID, intf, osmo_e1dp_msg_hdr::intf, line, osmo_e1dp_msg_hdr::line, mode, osmo_e1dp_msg_hdr::ts, and osmo_e1dp_msg_hdr::type.

osmo_e1dp_client_line_query()

int osmo_e1dp_client_line_query	(	struct osmo_e1dp_client *	clnt,
		struct osmo_e1dp_line_info **	li,
		int *	n,
		uint8_t	intf,
		uint8_t	line )

Query osmo-e1d for information about a specific E1 line.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[out]	li	callee-allocated array of line information structures.
[out]	n	caller-provided pointer to integer. Will contain number of entries in li.
[in]	intf	E1 interface number to query.
[in]	line	E1 line number (within interface) to query, or E1DP_INVALID to query all lines within the interface.

Returns

zero in case of success; negative in case of error.

References osmo_e1dp_client::ctx, E1DP_CMD_LINE_QUERY, E1DP_INVALID, intf, osmo_e1dp_msg_hdr::intf, line, osmo_e1dp_msg_hdr::line, osmo_e1dp_msg_hdr::ts, and osmo_e1dp_msg_hdr::type.

osmo_e1dp_client_set_sa_bits()

int osmo_e1dp_client_set_sa_bits	(	struct osmo_e1dp_client *	clnt,
		uint8_t	intf,
		uint8_t	line,
		uint8_t	sa_bits )

Set Sa-bits of a specific E1 line in osmo-e1d.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[in]	intf	E1 interface number to configure.
[in]	line	E1 line number (within interface) to configure.
[in]	sa_bits	Sa bits to set on line.

Returns

zero in case of success; negative in case of error.

References E1DP_CMD_SABITS, E1DP_INVALID, intf, osmo_e1dp_msg_hdr::intf, line, osmo_e1dp_msg_hdr::line, osmo_e1dp_msg_hdr::ts, and osmo_e1dp_msg_hdr::type.

osmo_e1dp_client_ts_open()

int osmo_e1dp_client_ts_open	(	struct osmo_e1dp_client *	clnt,
		uint8_t	intf,
		uint8_t	line,
		uint8_t	ts,
		enum osmo_e1dp_ts_mode	mode,
		uint16_t	read_bufsize )

Open a specific E1 timeslot of osmo-e1d.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[in]	intf	E1 interface number of line containing timeslot.
[in]	line	E1 line number (within interface) of line containing timeslot.
[in]	ts	E1 timeslot number (within line) to open.
[in]	mode	timeslot mode (RAW, HDLC-FCE) in which to open timeslot.
[in]	read_bufsize	size of read buffer (in octets) to use.

Returns

file descriptor of opened timeslot in case of success; negative in case of error.

References intf, line, mode, read_bufsize, and ts.

osmo_e1dp_client_ts_open_force()

int osmo_e1dp_client_ts_open_force	(	struct osmo_e1dp_client *	clnt,
		uint8_t	intf,
		uint8_t	line,
		uint8_t	ts,
		enum osmo_e1dp_ts_mode	mode,
		uint16_t	read_bufsize )

Force-Open a specific E1 timeslot of osmo-e1d.

The normal (non-force) opening of a timeslot will fail in case the given timeslot is already open (by either this or some other client). Using the open_force variant you can force osmo-e1d to disregard the existing client/timeslot and transfer ownership of the timeslot to this client.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[in]	intf	E1 interface number of line containing timeslot.
[in]	line	E1 line number (within interface) of line containing timeslot.
[in]	ts	E1 timeslot number (within line) to open.
[in]	mode	timeslot mode (RAW, HDLC-FCE) in which to open timeslot.
[in]	read_bufsize	size of read buffer (in octets) to use.

Returns

file descriptor of opened timeslot in case of success; negative in case of error.

References E1DP_TS_OPEN_F_FORCE, intf, line, mode, read_bufsize, and ts.

osmo_e1dp_client_ts_query()

int osmo_e1dp_client_ts_query	(	struct osmo_e1dp_client *	clnt,
		struct osmo_e1dp_ts_info **	ti,
		int *	n,
		uint8_t	intf,
		uint8_t	line,
		uint8_t	ts )

Query osmo-e1d for information about a specific E1 timeslot.

Parameters

[in]	clnt	Client previously returned from osmo_e1dp_client_create().
[out]	ti	callee-allocated array of timeslot information structures.
[out]	n	caller-provided pointer to integer. Will contain number of entries in ti.
[in]	intf	E1 interface number to query.
[in]	line	E1 line number (within interface) to query.
[in]	ts	E1 timeslot numer (within line) to query, or E1DP_INVALID to query all of the timeslots within the line.

Returns

zero in case of success; negative in case of error.

References osmo_e1dp_client::ctx, E1DP_CMD_TS_QUERY, intf, osmo_e1dp_msg_hdr::intf, line, osmo_e1dp_msg_hdr::line, osmo_e1dp_msg_hdr::ts, ts, and osmo_e1dp_msg_hdr::type.