path_manager.h File Reference

mptcpd generic netlink commands. More...

#include <stdbool.h>
#include <mptcpd/export.h>
#include <mptcpd/types.h>

Include dependency graph for path_manager.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	mptcpd_pm_ops
	Path manager event tracking operations. More...

Functions
MPTCPD_API bool	mptcpd_pm_register_ops (struct mptcpd_pm *pm, struct mptcpd_pm_ops const *ops, void *user_data)
	Subscribe to mptcpd path manager events.
MPTCPD_API bool	mptcpd_pm_ready (struct mptcpd_pm const *pm)
	Is mptcpd path manager ready for use?
MPTCPD_API struct mptcpd_nm const *	mptcpd_pm_get_nm (struct mptcpd_pm const *pm)
	Get pointer to the underlying network monitor.
MPTCPD_API struct mptcpd_idm *	mptcpd_pm_get_idm (struct mptcpd_pm const *pm)
	Get pointer to the global MPTCP address ID manager.
MPTCPD_API struct mptcpd_lm *	mptcpd_pm_get_lm (struct mptcpd_pm const *pm)
	Get pointer to the global MPTCP listener manager.
Client-oriented Path Management Commands
Client-oriented path management commands that allow for per-connection path management.
MPTCPD_API int	mptcpd_pm_add_addr (struct mptcpd_pm *pm, struct sockaddr *addr, mptcpd_aid_t id, mptcpd_token_t token)
	Advertise new network address to peers.
MPTCPD_API int	mptcpd_pm_add_addr_no_listener (struct mptcpd_pm *pm, struct sockaddr *addr, mptcpd_aid_t id, mptcpd_token_t token)
	Advertise new network address to peers without creating a listener.
MPTCPD_API int	mptcpd_pm_remove_addr (struct mptcpd_pm *pm, struct sockaddr const *addr, mptcpd_aid_t address_id, mptcpd_token_t token)
	Stop advertising network address to peers.
MPTCPD_API int	mptcpd_pm_add_subflow (struct mptcpd_pm *pm, mptcpd_token_t token, mptcpd_aid_t local_address_id, mptcpd_aid_t remote_address_id, struct sockaddr const *local_addr, struct sockaddr const *remote_addr, bool backup)
	Create a new subflow.
MPTCPD_API int	mptcpd_pm_set_backup (struct mptcpd_pm *pm, mptcpd_token_t token, struct sockaddr const *local_addr, struct sockaddr const *remote_addr, bool backup)
	Set priority of a subflow.
MPTCPD_API int	mptcpd_pm_remove_subflow (struct mptcpd_pm *pm, mptcpd_token_t token, struct sockaddr const *local_addr, struct sockaddr const *remote_addr)
	Remove a subflow.
Server-oriented Path Management Commands
Server-oriented path management commands supported by the upstream Linux kernel. Path management is handled by the in-kernel path manager.
MPTCPD_API int	mptcpd_kpm_add_addr (struct mptcpd_pm *pm, struct sockaddr const *addr, mptcpd_aid_t id, mptcpd_flags_t flags, int index)
	Advertise new network address to peers.
MPTCPD_API int	mptcpd_kpm_remove_addr (struct mptcpd_pm *pm, mptcpd_aid_t address_id)
	Stop advertising network address to peers.
MPTCPD_API int	mptcpd_kpm_get_addr (struct mptcpd_pm *pm, mptcpd_aid_t id, mptcpd_kpm_get_addr_cb_t callback, void *data, mptcpd_complete_func_t complete)
	Get network address corresponding to an address ID.
MPTCPD_API int	mptcpd_kpm_dump_addrs (struct mptcpd_pm *pm, mptcpd_kpm_get_addr_cb_t callback, void *data, mptcpd_complete_func_t complete)
	Get list (array) of MPTCP network addresses.
MPTCPD_API int	mptcpd_kpm_flush_addrs (struct mptcpd_pm *pm)
	Flush MPTCP addresses.
MPTCPD_API int	mptcpd_kpm_set_limits (struct mptcpd_pm *pm, struct mptcpd_limit const *limits, size_t len)
	Set MPTCP resource limits.
MPTCPD_API int	mptcpd_kpm_get_limits (struct mptcpd_pm *pm, mptcpd_pm_get_limits_cb callback, void *data)
	Get MPTCP resource limits.
MPTCPD_API int	mptcpd_kpm_set_flags (struct mptcpd_pm *pm, struct sockaddr const *addr, mptcpd_flags_t flags)
	Set MPTCP flags for a local IP address.

Detailed Description

mptcpd generic netlink commands.

Copyright (c) 2017-2022, Intel Corporation

Function Documentation

mptcpd_kpm_add_addr()

MPTCPD_API int mptcpd_kpm_add_addr	(	struct mptcpd_pm *	pm,
		struct sockaddr const *	addr,
		mptcpd_aid_t	id,
		mptcpd_flags_t	flags,
		int	index
	)

Advertise new network address to peers.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	addr	Local IP address and port to be advertised through the MPTCP protocol ADD_ADDR option. The port is optional, and is ignored if it is zero. A non-zero port implies MPTCPD_ADDR_FLAG_SIGNAL in flags.
[in]	id	MPTCP local address ID.
[in]	flags	Bitset of MPTCP flags associated with the network address, e.g. MPTCPD_ADDR_FLAG_SUBFLOW | MPTCPD_ADDR_FLAG_BACKUP. Optional for upstream kernel (e.g. set to zero).
[in]	index	Network interface index. Optional for upstream Linux kernel (e.g. set to zero).

Returns

0 if operation was successful. errno otherwise.

mptcpd_kpm_dump_addrs()

MPTCPD_API int mptcpd_kpm_dump_addrs	(	struct mptcpd_pm *	pm,
		mptcpd_kpm_get_addr_cb_t	callback,
		void *	data,
		mptcpd_complete_func_t	complete
	)

Get list (array) of MPTCP network addresses.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	callback	Function to be called when a network address has been retrieved. This function will be called when each address dump is available, or possibly not at all.
[in]	data	Data to be passed to the callback function.
[in]	complete	Function called when the asynchronous dump_addrs call completes.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_kpm_flush_addrs()

MPTCPD_API int mptcpd_kpm_flush_addrs

(

struct mptcpd_pm *

pm

)

Flush MPTCP addresses.

Purge all MPTCP addresses.

Parameters

[in]

pm

The mptcpd path manager object.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_kpm_get_addr()

MPTCPD_API int mptcpd_kpm_get_addr	(	struct mptcpd_pm *	pm,
		mptcpd_aid_t	id,
		mptcpd_kpm_get_addr_cb_t	callback,
		void *	data,
		mptcpd_complete_func_t	complete
	)

Get network address corresponding to an address ID.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	id	MPTCP local address ID.
[in]	callback	Function to be called when the network address corresponding to the given MPTCP address id has been retrieved.
[in]	data	Data to be passed to the callback function.
[in]	complete	Function called when the asynchronous get_addr call completes.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_kpm_get_limits()

MPTCPD_API int mptcpd_kpm_get_limits	(	struct mptcpd_pm *	pm,
		mptcpd_pm_get_limits_cb	callback,
		void *	data
	)

Get MPTCP resource limits.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	callback	Function to be called when the MPTCP resource limits have been retrieved.
[in]	data	Data to be passed to the callback function.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_kpm_remove_addr()

MPTCPD_API int mptcpd_kpm_remove_addr	(	struct mptcpd_pm *	pm,
		mptcpd_aid_t	address_id
	)

Stop advertising network address to peers.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	address_id	MPTCP local address ID to be sent in the MPTCP protocol REMOVE_ADDR option corresponding to the local address that will no longer be available.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_kpm_set_flags()

MPTCPD_API int mptcpd_kpm_set_flags	(	struct mptcpd_pm *	pm,
		struct sockaddr const *	addr,
		mptcpd_flags_t	flags
	)

Set MPTCP flags for a local IP address.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	addr	Local IP address. A non-zero port implies MPTCPD_ADDR_FLAG_SIGNAL in flags.
[in]	flags	Flags to be associated with addr.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_kpm_set_limits()

MPTCPD_API int mptcpd_kpm_set_limits	(	struct mptcpd_pm *	pm,
		struct mptcpd_limit const *	limits,
		size_t	len
	)

Set MPTCP resource limits.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	limits	Array of MPTCP resource type/limit pairs.
[in]	len	Length of the limits array.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_pm_add_addr()

MPTCPD_API int mptcpd_pm_add_addr	(	struct mptcpd_pm *	pm,
		struct sockaddr *	addr,
		mptcpd_aid_t	id,
		mptcpd_token_t	token
	)

Advertise new network address to peers.

Parameters

[in]	pm	The mptcpd path manager object.
[in,out]	addr	Local IP address and port to be advertised through the MPTCP protocol ADD_ADDR option. If the port is zero an ephemeral port will be chosen, and assigned to the appropriate underlying address family-specific port member, e.g. sin_port or sin6_port. The port will be in network byte order.
[in]	id	MPTCP local address ID.
[in]	token	MPTCP connection token.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_pm_add_addr_no_listener()

MPTCPD_API int mptcpd_pm_add_addr_no_listener	(	struct mptcpd_pm *	pm,
		struct sockaddr *	addr,
		mptcpd_aid_t	id,
		mptcpd_token_t	token
	)

Advertise new network address to peers without creating a listener.

Parameters

[in]	pm	The mptcpd path manager object.
[in,out]	addr	Local IP address and port to be advertised through the MPTCP protocol ADD_ADDR option. If the port is zero no port will be specified on the underlying protocol level.
[in]	id	MPTCP local address ID.
[in]	token	MPTCP connection token.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_pm_add_subflow()

MPTCPD_API int mptcpd_pm_add_subflow	(	struct mptcpd_pm *	pm,
		mptcpd_token_t	token,
		mptcpd_aid_t	local_address_id,
		mptcpd_aid_t	remote_address_id,
		struct sockaddr const *	local_addr,
		struct sockaddr const *	remote_addr,
		bool	backup
	)

Create a new subflow.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	token	MPTCP connection token.
[in]	local_address_id	MPTCP local address ID.
[in]	remote_address_id	MPTCP remote address ID.
[in]	local_addr	MPTCP subflow local address information, including the port. This argument is optional and may be NULL.
[in]	remote_addr	MPTCP subflow remote address information, including the port.
[in]	backup	Whether or not to set the MPTCP subflow backup priority flag.

Returns

0 if operation was successful. -1 or errno otherwise.

Todo:

There far too many parameters. Reduce.

mptcpd_pm_get_idm()

MPTCPD_API struct mptcpd_idm * mptcpd_pm_get_idm

(

struct mptcpd_pm const *

pm

)

Get pointer to the global MPTCP address ID manager.

Parameters

[in]

pm

Mptcpd path manager data.

Note

The global MPTCP address ID manager is meant to track address IDs associated with the in-kernel path manager.

Returns

Global mptcpd MPTCP address ID manager.

mptcpd_pm_get_lm()

MPTCPD_API struct mptcpd_lm * mptcpd_pm_get_lm

(

struct mptcpd_pm const *

pm

)

Get pointer to the global MPTCP listener manager.

Parameters

[in]

pm

Mptcpd path manager data.

Note

The global MPTCP listener manager tracks MPTCP listening sockets associated with a local address.

Returns

Global mptcpd MPTCP listener manager.

mptcpd_pm_get_nm()

MPTCPD_API struct mptcpd_nm const * mptcpd_pm_get_nm

(

struct mptcpd_pm const *

pm

)

Get pointer to the underlying network monitor.

Parameters

[in]

pm

Mptcpd path manager.

Returns

Mptcpd network monitor.

mptcpd_pm_ready()

MPTCPD_API bool mptcpd_pm_ready

(

struct mptcpd_pm const *

pm

)

Is mptcpd path manager ready for use?

The mptcpd path manager is ready for use when the "mptcp" generic netlink family is available in the Linux kernel. No path management related interaction with the kernel can occur until that family appears.

Parameters

[in]

pm

Mptcpd path manager.

Returns

true if the mptcpd path manager is ready for use, and false otherwise.

mptcpd_pm_register_ops()

MPTCPD_API bool mptcpd_pm_register_ops	(	struct mptcpd_pm *	pm,
		struct mptcpd_pm_ops const *	ops,
		void *	user_data
	)

Subscribe to mptcpd path manager events.

Register a set of operations that will be called on a corresponding mptcpd path manager event, e.g. path manager readiness.

Parameters

[in,out]	pm	Pointer to the mptcpd path manager object.
[in]	ops	Set of path manager event handling functions.
[in]	user_data	Data to be passed to the path manager event tracking operations.

Return values

true	Registration succeeded.
false	Registration failed.

mptcpd_pm_remove_addr()

MPTCPD_API int mptcpd_pm_remove_addr	(	struct mptcpd_pm *	pm,
		struct sockaddr const *	addr,
		mptcpd_aid_t	address_id,
		mptcpd_token_t	token
	)

Stop advertising network address to peers.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	addr	Local IP address and port that should no longer be advertised through MPTCP.
[in]	address_id	MPTCP local address ID to be sent in the MPTCP protocol REMOVE_ADDR option corresponding to the local address that will no longer be available.
[in]	token	MPTCP connection token.

Returns

0 if operation was successful. -1 or errno otherwise.

mptcpd_pm_remove_subflow()

MPTCPD_API int mptcpd_pm_remove_subflow	(	struct mptcpd_pm *	pm,
		mptcpd_token_t	token,
		struct sockaddr const *	local_addr,
		struct sockaddr const *	remote_addr
	)

Remove a subflow.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	token	MPTCP connection token.
[in]	local_addr	MPTCP subflow local address information, including the port.
[in]	remote_addr	MPTCP subflow remote address information, including the port.

Returns

0 if operation was successful. errno otherwise.

mptcpd_pm_set_backup()

MPTCPD_API int mptcpd_pm_set_backup	(	struct mptcpd_pm *	pm,
		mptcpd_token_t	token,
		struct sockaddr const *	local_addr,
		struct sockaddr const *	remote_addr,
		bool	backup
	)

Set priority of a subflow.

Parameters

[in]	pm	The mptcpd path manager object.
[in]	token	MPTCP connection token.
[in]	local_addr	MPTCP subflow local address information, including the port.
[in]	remote_addr	MPTCP subflow remote address information, including the port.
[in]	backup	Whether or not to set the MPTCP subflow backup priority flag.

Returns

0 if operation was successful. errno otherwise.