hICN control library API More...

#include <stdbool.h>
#include <stdint.h>
#include <hicn/util/ip_address.h>
#include <hicn/ctrl/commands.h>
#include "face.h"

Include dependency graph for api.h:

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

Go to the source code of this file.

Classes
struct	hc_data_s
	Holds the results of an hICN control request. More...

struct	hc_listener_t

struct	hc_connection_t

struct	hc_face_t

struct	hc_route_t

struct	hc_punting_t

struct	hc_strategy_t

Macros
#define	HICN_DEFAULT_PORT 9695

#define	HOTFIXMARGIN 0

#define	DEFAULT_SIZE_LOG 3
	Defines the default size for the allocated data arrays holding the results of API calls. More...

#define	UNION_CAST(x, destType)

#define	foreach_command

#define	_(x) ACTION_##x,

#define	GENERATE_FIND_HEADER(TYPE)
	Find en element in the data structure. More...

#define	GENERATE_FIND(TYPE)

#define	RECV_BUFLEN 8192

#define	INTERFACE_LEN 16

#define	MAXSZ_HC_NAME_ SYMBOLIC_NAME_LEN

#define	MAXSZ_HC_NAME MAXSZ_HC_NAME_ + NULLTERM

#define	MAXSZ_HC_ID_ 10 /* Number of digits for MAX_INT */

#define	MAXSZ_HC_ID MAXSZ_HC_ID_ + NULLTERM

#define	foreach_type(TYPE, VAR, data)

#define	foreach_connection_type

#define	_(x) CONNECTION_TYPE_##x,

#define	MAXSZ_HC_CONNECTION_TYPE_ 9

#define	MAXSZ_HC_CONNECTION_TYPE MAXSZ_HC_CONNECTION_TYPE_ + NULLTERM + HOTFIXMARGIN

#define	foreach_connection_state

#define	_(x) HC_CONNECTION_STATE_##x,

#define	MAXSZ_HC_CONNECTION_STATE_ 9

#define	MAXSZ_HC_CONNECTION_STATE MAXSZ_HC_CONNECTION_STATE_ + NULLTERM

#define	foreach_listener(VAR, data) foreach_type(hc_listener_t, VAR, data)

#define	MAXSZ_HC_LISTENER_ INTERFACE_LEN + SPACE + MAXSZ_URL_ + SPACE + MAXSZ_HC_CONNECTION_TYPE_

#define	MAXSZ_HC_LISTENER MAXSZ_HC_LISTENER_ + NULLTERM

#define	foreach_connection(VAR, data) foreach_type(hc_connection_t, VAR, data)

#define	MAXSZ_HC_CONNECTION_

#define	MAXSZ_HC_CONNECTION MAXSZ_HC_CONNECTION_ + NULLTERM

#define	foreach_face(VAR, data) foreach_type(hc_face_t, VAR, data)

#define	MAX_FACE_ID 255

#define	MAXSZ_FACE_ID_ 3

#define	MAXSZ_FACE_ID MAXSZ_FACE_ID_ + NULLTERM

#define	MAXSZ_FACE_NAME_ SYMBOLIC_NAME_LEN

#define	MAXSZ_FACE_NAME MAXSZ_FACE_NAME_ + NULLTERM

#define	MAXSZ_HC_FACE_ MAXSZ_FACE_ID_ + MAXSZ_FACE_NAME_ + MAXSZ_FACE_ + 5 + HOTFIXMARGIN

#define	MAXSZ_HC_FACE MAXSZ_HC_FACE_ + NULLTERM

#define	foreach_route(VAR, data) foreach_type(hc_route_t, VAR, data)

#define	MAX_COST 65535

#define	MAXSZ_COST 5

#define	MAX_LEN 255

#define	MAXSZ_LEN 3

#define	MAXSZ_HC_ROUTE_ MAXSZ_FACE_ID + 1 + MAXSZ_COST + 1 + MAXSZ_IP_ADDRESS + 1 + MAXSZ_LEN

#define	MAXSZ_HC_ROUTE MAXSZ_HC_ROUTE_ + NULLTERM

#define	foreach_punting(VAR, data) foreach_type(hc_punting_t, VAR, data)

#define	MAXSZ_HC_PUNTING_ 0

#define	MAXSZ_HC_PUNTING MAXSZ_HC_PUNTING_ + NULLTERM

#define	MAXSZ_STRATEGY_NAME 255

#define	foreach_strategy(VAR, data) foreach_type(hc_strategy_t, VAR, data)

#define	MAXSZ_HC_STRATEGY_ MAXSZ_STRATEGY_NAME

#define	MAXSZ_HC_STRATEGY MAXSZ_HC_STRATEGY_ + NULLTERM

Typedefs
typedef struct hc_msg_s	hc_msg_t
	hICN control message header

typedef int(*	data_callback_t) (struct hc_data_s , void )

typedef struct hc_data_s	hc_data_t
	Holds the results of an hICN control request.

typedef struct hc_sock_s	hc_sock_t
	Holds the state of an hICN control socket.

typedef int(*	HC_PARSE) (const u8 , u8 )

Enumerations
enum	hc_action_t { foreach_command }

enum	forwarder_t { HICNLIGHT, VPP, UNDEFINED }

enum	hc_connection_type_t { foreach_connection_type }

enum	hc_connection_state_t { foreach_connection_state }

Functions
hc_data_t *	hc_data_create (size_t in_element_size, size_t out_element_size, data_callback_t complete_cb)

void	hc_data_free (hc_data_t *data)

int	hc_data_push_many (hc_data_t data, const void elements, size_t count)
	Adds many new results at the end of the data structure, eventually allocating buffer space for it. More...

int	hc_data_push (hc_data_t data, const void element)
	Adds a new result at the end of the data structure, eventually allocating buffer space for it. More...

int	hc_data_set_callback (hc_data_t data, data_callback_t cb, void cb_data)
	Configure a callback (along with private data) to be called upon completion of a request. More...

int	hc_data_set_complete (hc_data_t *data)
	Mark the data structure as complete. More...

int	hc_data_reset (hc_data_t *data)
	Reset the data structure holding control data. More...

hc_sock_t *	hc_sock_create_url (const char *url)
	Create an hICN control socket using the specified URL. More...

hc_sock_t *	hc_sock_create_forwarder (forwarder_t forwarder)
	Create an hICN control socket using the provided forwarder. More...

hc_sock_t *	hc_sock_create (void)
	Create an hICN control socket using the default connection type. More...

void	hc_sock_free (hc_sock_t *s)
	Frees an hICN control socket. More...

int	hc_sock_get_next_seq (hc_sock_t *s)
	Returns the next available sequence number to use for requests to the API. More...

int	hc_sock_set_nonblocking (hc_sock_t *s)
	Sets the socket as non-blocking. More...

int	hc_sock_get_fd (hc_sock_t *s)
	Return the file descriptor associated to the hICN contorl sock. More...

int	hc_sock_connect (hc_sock_t *s)
	Connect the socket. More...

int	hc_sock_get_available (hc_sock_t s, u8 buffer, size_t size)
	Return the offset and size of available buffer space. More...

int	hc_sock_send (hc_sock_t s, hc_msg_t msg, size_t msglen, int seq)
	Write/read iexchance on the control socket (internal helper function) More...

int	hc_sock_recv (hc_sock_t *s)
	Helper for reading socket contents. More...

int	hc_sock_process (hc_sock_t s, hc_data_t *data)
	Processing data received by socket. More...

int	hc_sock_callback (hc_sock_t s, hc_data_t *data)
	Callback used in async mode when data is available on the socket. More...

int	hc_sock_reset (hc_sock_t *s)
	Reset the state of the sock (eg. to handle a reconnecton) More...

hc_connection_type_t	connection_type_from_str (const char *str)

int	hc_listener_create (hc_sock_t s, hc_listener_t listener)

int	hc_listener_get (hc_sock_t s, hc_listener_t listener, hc_listener_t **listener_found)

int	hc_listener_delete (hc_sock_t s, hc_listener_t listener)

int	hc_listener_list (hc_sock_t s, hc_data_t *pdata)

int	hc_listener_validate (const hc_listener_t *listener)

int	hc_listener_cmp (const hc_listener_t l1, const hc_listener_t l2)

int	hc_listener_parse (void in, hc_listener_t listener)

	GENERATE_FIND_HEADER (listener)

int	hc_listener_snprintf (char s, size_t size, hc_listener_t listener)

int	hc_connection_create (hc_sock_t s, hc_connection_t connection)

int	hc_connection_get (hc_sock_t s, hc_connection_t connection, hc_connection_t **connection_found)

int	hc_connection_update_by_id (hc_sock_t s, int hc_connection_id, hc_connection_t connection)

int	hc_connection_update (hc_sock_t s, hc_connection_t connection_current, hc_connection_t *connection_updated)

int	hc_connection_delete (hc_sock_t s, hc_connection_t connection)

int	hc_connection_list (hc_sock_t s, hc_data_t *pdata)

int	hc_connection_validate (const hc_connection_t *connection)

int	hc_connection_cmp (const hc_connection_t c1, const hc_connection_t c2)

int	hc_connection_parse (void in, hc_connection_t connection)

int	hc_connection_set_admin_state (hc_sock_t s, const char conn_id_or_name, face_state_t state)

	GENERATE_FIND_HEADER (connection)

int	hc_connection_snprintf (char s, size_t size, const hc_connection_t connection)

int	hc_face_create (hc_sock_t s, hc_face_t face)
	Create a face. More...

int	hc_face_get (hc_sock_t s, hc_face_t face, hc_face_t **face_found)

int	hc_face_delete (hc_sock_t s, hc_face_t face)

int	hc_face_list (hc_sock_t s, hc_data_t *pdata)

int	hc_face_list_async (hc_sock_t *s)

int	hc_face_set_admin_state (hc_sock_t s, const char conn_id_or_name, face_state_t state)

int	hc_face_snprintf (char s, size_t size, hc_face_t face)

int	hc_route_parse (void in, hc_route_t route)

int	hc_route_create (hc_sock_t s, hc_route_t route)

int	hc_route_delete (hc_sock_t s, hc_route_t route)

int	hc_route_list (hc_sock_t s, hc_data_t *pdata)

int	hc_route_list_async (hc_sock_t *s)

int	hc_route_snprintf (char s, size_t size, hc_route_t route)

int	hc_punting_create (hc_sock_t s, hc_punting_t punting)

int	hc_punting_get (hc_sock_t s, hc_punting_t punting, hc_punting_t **punting_found)

int	hc_punting_delete (hc_sock_t s, hc_punting_t punting)

int	hc_punting_list (hc_sock_t s, hc_data_t *pdata)

int	hc_punting_validate (const hc_punting_t *punting)

int	hc_punting_cmp (const hc_punting_t c1, const hc_punting_t c2)

int	hc_punting_parse (void in, hc_punting_t punting)

	GENERATE_FIND_HEADER (punting)

int	hc_punting_snprintf (char s, size_t size, hc_punting_t punting)

int	hc_cache_set_store (hc_sock_t *s, int enabled)

int	hc_cache_set_serve (hc_sock_t *s, int enabled)

int	hc_strategy_list (hc_sock_t s, hc_data_t *data)

int	hc_strategy_snprintf (char s, size_t size, hc_strategy_t strategy)

int	hc_strategy_set (hc_sock_t *s)

int	hc_wldr_set (hc_sock_t *s)

int	hc_mapme_set (hc_sock_t *s, int enabled)

int	hc_mapme_set_discovery (hc_sock_t *s, int enabled)

int	hc_mapme_set_timescale (hc_sock_t *s, double timescale)

int	hc_mapme_set_retx (hc_sock_t *s, double timescale)

Variables
const char *	connection_type_str []

const char *	connection_state_str []

Detailed Description

hICN control library API

This API supports basic hICN objects (face, route, punting) plus implementation-specific ones (connection, listener). Currently, this library only supports the hicn-light forwarder.

For each object, a set of methods is provided among:

CREATE, GET, UPDATE, DELETE, LIST
CMP, PARSE, SNPRINTF
additionally, attribute getters and/or setters are provided and denoted GET( attribute ) and SET( attribute )

A summary per-object is presented here:

         | CRE GET UPD DEL LST | VAL CMP PAR SNP | attributes [GET/SET]

+---------—+------------------—+----------—+------------------------— | face | O O ! O O | ! ! O | state [-S] | route | O - ! O O | ! O - | | punting | ! - ! ! ! | ! ! ! | +---------—+------------------—+--------------—+------------------------— | cache | | | store [!!], serve [!!] | strategy | | | | FIB | | | | PIT | | | | WLDR | | | | MAP-Me | | | +---------—+------------------—+--------------—+------------------------— | connection | O O ! O O | O O O | state [-S] | listener | O O ! O O | O O O O | +---------—+------------------—+--------------—+------------------------—

LEGEND: [O] implemented, [!] in progress / TODO, [-] not supported

NOTES:

Different extensions of the forwarder functionalities bring both new API calls, and new object attributes. While it is expected that the former will only raised NACK answers because of unsupported API calls, the latter will certainly trigger incompatibilities. It is expected that the forwarder validates the message length and returns a NACK too. In that case, we provide a set of defines to preserve backwards compatibility. At the moment, those defines are :

WITH_POLICY:

Macro Definition Documentation

◆ DEFAULT_SIZE_LOG

#define DEFAULT_SIZE_LOG 3

Defines the default size for the allocated data arrays holding the results of API calls.

This size should not be too small to avoid wasting memoyy, but also not too big to avoid unnecessary realloc's. Later on this size is doubled at each reallocation.

◆ foreach_command

#define foreach_command

Value:

  _(UNDEFINED)          \
  _(CREATE)             \
  _(UPDATE)             \
  _(DELETE)             \
  _(LIST)               \
  _(SET)                \
  _(N)

◆ foreach_connection_state

#define foreach_connection_state

Value:

  _(UNDEFINED)                   \
  _(DOWN)                        \
  _(UP)                          \
  _(N)

◆ foreach_connection_type

#define foreach_connection_type

Value:

  _(UNDEFINED)                  \
  _(TCP)                        \
  _(UDP)                        \
  _(HICN)                       \
  _(N)

New type is defined to reconciliate different enum for add and list. Also, values not implemented have been removed for clarity.

◆ foreach_type

#define foreach_type	(	TYPE,
		VAR,
		data
	)

Value:

  for (TYPE *VAR = (TYPE *)data->buffer;                                   \
       VAR < (TYPE *)(data->buffer + data->size * data->out_element_size); \
       VAR++)

◆ GENERATE_FIND

#define GENERATE_FIND ( TYPE )

Value:

int                                                                         \
hc_ ## TYPE ## _find(hc_data_t * data, const hc_ ## TYPE ## _t * element,   \
        hc_ ## TYPE ## _t **found)                                          \
{                                                                           \
    foreach_type(hc_ ## TYPE ## _t, x, data) {                              \
        if (hc_ ## TYPE ## _cmp(x, element) == 0) {                         \
            *found = x;                                                     \
            return 0;                                                       \
        }                                                                   \
    };                                                                      \
    *found = NULL; /* this is optional */                                   \
    return 0;                                                               \
}

◆ GENERATE_FIND_HEADER

#define GENERATE_FIND_HEADER ( TYPE )

Value:

int                                                                         \
hc_ ## TYPE ## _find(hc_data_t * data, const hc_ ## TYPE ## _t * element,   \
        hc_ ## TYPE ## _t **found)

Find en element in the data structure.

Parameters

[in]	data	- The data structure in which to find
[in]	element	- The element to find
[out]	found	- A pointer to the element, or NULL if not found.

Returns: Error code

◆ MAXSZ_HC_CONNECTION_

#define MAXSZ_HC_CONNECTION_

Value:

MAXSZ_HC_CONNECTION_STATE_ + INTERFACE_LEN + SPACE + 2 * MAXSZ_URL_ + \

MAXSZ_HC_CONNECTION_TYPE_ + SPACES(3)

◆ UNION_CAST

#define UNION_CAST	(	x,
		destType
	)

Value:

  (((union {                    \
     __typeof__(x) a;           \
     destType b;                \
   })x)                         \
       .b)

Function Documentation

◆ hc_data_create()

hc_data_t* hc_data_create	(	size_t	in_element_size,
		size_t	out_element_size,
		data_callback_t	complete_cb
	)

Create a structure holding the results of an hICN control request.

Returns: The newly create data structure.

◆ hc_data_free()

void hc_data_free ( hc_data_t * data )

Free a structure holding the results of an hICN control request.

Parameters

[in] data - The data structure to free.

◆ hc_data_push()

int hc_data_push	(	hc_data_t *	data,
		const void *	element
	)

Adds a new result at the end of the data structure, eventually allocating buffer space for it.

Parameters

[in]	data	- The data structure to which to add an element.
[in]	element	- The element to add

Returns: Error code

NOTE: The size of the element should match the one declared at structure initialization.

◆ hc_data_push_many()

int hc_data_push_many	(	hc_data_t *	data,
		const void *	elements,
		size_t	count
	)

Adds many new results at the end of the data structure, eventually allocating buffer space for it.

Parameters

[in]	data	- The data structure to which to add elements.
[in]	elements	- The array of elements to add.
[in]	count	- The number of elements to add.

Returns: Error code

NOTE: The size of the element should match the one declared at structure initialization.

◆ hc_data_reset()

int hc_data_reset ( hc_data_t * data )

Reset the data structure holding control data.

Parameters

[in] data - hICN control data

Returns: Error code

◆ hc_data_set_callback()

int hc_data_set_callback	(	hc_data_t *	data,
		data_callback_t	cb,
		void *	cb_data
	)

Configure a callback (along with private data) to be called upon completion of a request.

Parameters

[in]	data	- hICN control data
[in]	cb	- Callback function
[in]	cb_data	- Callback private data

◆ hc_data_set_complete()

int hc_data_set_complete ( hc_data_t * data )

Mark the data structure as complete.

Parameters

[in] data - The data structure to which to add an element.

Returns: The error code resulting from callback execution if any. 0 is returned if the callback executed successfully, or if no callback were defined.

◆ hc_face_create()

int hc_face_create	(	hc_sock_t *	s,
		hc_face_t *	face
	)

Create a face.

Parameters

[in]	s	- hICN socket
[in,out]	face	- Parameters of the face to create

Returns: Error code

The face parameters will be updated with the face ID.

◆ hc_sock_callback()

int hc_sock_callback	(	hc_sock_t *	s,
		hc_data_t **	data
	)

Callback used in async mode when data is available on the socket.

Parameters

[in] s - hICN control socket

Returns: Error code

◆ hc_sock_connect()

int hc_sock_connect ( hc_sock_t * s )

Connect the socket.

Returns: Error code

◆ hc_sock_create()

hc_sock_t* hc_sock_create ( void )

Create an hICN control socket using the default connection type.

Returns: an hICN control socket

◆ hc_sock_create_forwarder()

hc_sock_t* hc_sock_create_forwarder ( forwarder_t forwarder )

Create an hICN control socket using the provided forwarder.

Returns: an hICN control socket

◆ hc_sock_create_url()

hc_sock_t* hc_sock_create_url ( const char * url )

Create an hICN control socket using the specified URL.

Parameters

[in] url - The URL to connect to.

Returns: an hICN control socket

◆ hc_sock_free()

void hc_sock_free ( hc_sock_t * s )

Frees an hICN control socket.

Parameters

[in] s - hICN control socket

◆ hc_sock_get_available()

int hc_sock_get_available	(	hc_sock_t *	s,
		u8 **	buffer,
		size_t *	size
	)

Return the offset and size of available buffer space.

Parameters

[in]	s	- hICN control socket
[out]	buffer	- Offset in buffer
[out]	size	- Remaining size

Returns: Error code

◆ hc_sock_get_fd()

int hc_sock_get_fd ( hc_sock_t * s )

Return the file descriptor associated to the hICN contorl sock.

Parameters

[in] s - hICN control socket

Returns: The file descriptor (positive value), or a negative integer in case of error

◆ hc_sock_get_next_seq()

int hc_sock_get_next_seq ( hc_sock_t * s )

Returns the next available sequence number to use for requests to the API.

Parameters

[in] s - hICN control socket

◆ hc_sock_process()

int hc_sock_process	(	hc_sock_t *	s,
		hc_data_t **	data
	)

Processing data received by socket.

Parameters

[in]	s	- hICN control socket
[in]	parse	- Parse function to convert remote types into lib native types, or NULL not to perform any translation.

Returns: Error code

◆ hc_sock_recv()

int hc_sock_recv ( hc_sock_t * s )

Helper for reading socket contents.

Parameters

[in] s - hICN control socket

Returns: Error code

◆ hc_sock_reset()

int hc_sock_reset ( hc_sock_t * s )

Reset the state of the sock (eg. to handle a reconnecton)

Parameters

[in] s - hICN control socket

Returns: Error code

◆ hc_sock_send()

int hc_sock_send	(	hc_sock_t *	s,
		hc_msg_t *	msg,
		size_t	msglen,
		int	seq
	)

Write/read iexchance on the control socket (internal helper function)

Parameters

[in]	s	- hICN control socket
[in]	msg	- Message to send
[in]	msglen	- Length of the message to send

Returns: Error code

◆ hc_sock_set_nonblocking()

int hc_sock_set_nonblocking ( hc_sock_t * s )

Sets the socket as non-blocking.

Parameters

[in] s - hICN control socket

Returns: Error code

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEFAULT_SIZE_LOG

◆ foreach_command

◆ foreach_connection_state

◆ foreach_connection_type

◆ foreach_type

◆ GENERATE_FIND

◆ GENERATE_FIND_HEADER

◆ MAXSZ_HC_CONNECTION_

◆ UNION_CAST

Function Documentation

◆ hc_data_create()

◆ hc_data_free()

◆ hc_data_push()

◆ hc_data_push_many()

◆ hc_data_reset()

◆ hc_data_set_callback()

◆ hc_data_set_complete()

◆ hc_face_create()

◆ hc_sock_callback()

◆ hc_sock_connect()

◆ hc_sock_create()

◆ hc_sock_create_forwarder()

◆ hc_sock_create_url()

◆ hc_sock_free()

◆ hc_sock_get_available()

◆ hc_sock_get_fd()

◆ hc_sock_get_next_seq()

◆ hc_sock_process()

◆ hc_sock_recv()

◆ hc_sock_reset()

◆ hc_sock_send()

◆ hc_sock_set_nonblocking()