common vpp api C declarations More...

Include dependency graph for vapi.h:

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

Typedefs
typedef struct vapi_ctx_s *	vapi_ctx_t

typedef vapi_error_e(*	vapi_event_cb) (vapi_ctx_t ctx, void callback_ctx, void payload)
	generic vapi event callback More...

typedef vapi_error_e(*	vapi_generic_event_cb) (vapi_ctx_t ctx, void callback_ctx, vapi_msg_id_t id, void msg)
	generic vapi event callback More...

Functions
void *	vapi_msg_alloc (vapi_ctx_t ctx, size_t size)
	allocate vapi message of given size More...

void	vapi_msg_free (vapi_ctx_t ctx, void *msg)
	free a vapi message More...

vapi_error_e	vapi_ctx_alloc (vapi_ctx_t *result)
	allocate vapi context More...

void	vapi_ctx_free (vapi_ctx_t ctx)
	free vapi context More...

bool	vapi_is_msg_available (vapi_ctx_t ctx, vapi_msg_id_t type)
	check if message identified by it's message id is known by the vpp to which the connection is open More...

vapi_error_e	vapi_connect (vapi_ctx_t ctx, const char name, const char chroot_prefix, int max_outstanding_requests, int response_queue_size, vapi_mode_e mode, bool handle_keepalives)
	connect to vpp More...

vapi_error_e	vapi_disconnect (vapi_ctx_t ctx)
	disconnect from vpp More...

vapi_error_e	vapi_get_fd (vapi_ctx_t ctx, int *fd)
	get event file descriptor More...

vapi_error_e	vapi_send (vapi_ctx_t ctx, void *msg)
	low-level api for sending messages to vpp More...

vapi_error_e	vapi_send2 (vapi_ctx_t ctx, void msg1, void msg2)
	low-level api for atomically sending two messages to vpp - either both messages are sent or neither one is More...

vapi_error_e	vapi_recv (vapi_ctx_t ctx, void *msg, size_t msg_size, svm_q_conditional_wait_t cond, u32 time)
	low-level api for reading messages from vpp More...

vapi_error_e	vapi_wait (vapi_ctx_t ctx, vapi_wait_mode_e mode)
	wait for connection to become readable or writable More...

vapi_error_e	vapi_dispatch_one (vapi_ctx_t ctx)
	pick next message sent by vpp and call the appropriate callback More...

vapi_error_e	vapi_dispatch (vapi_ctx_t ctx)
	loop vapi_dispatch_one until responses to all currently outstanding requests have been received and their callbacks called More...

void	vapi_set_event_cb (vapi_ctx_t ctx, vapi_msg_id_t id, vapi_event_cb callback, void *callback_ctx)
	set event callback to call when message with given id is dispatched More...

void	vapi_clear_event_cb (vapi_ctx_t ctx, vapi_msg_id_t id)
	clear event callback for given message id More...

void	vapi_set_generic_event_cb (vapi_ctx_t ctx, vapi_generic_event_cb callback, void *callback_ctx)
	set generic event callback More...

void	vapi_clear_generic_event_cb (vapi_ctx_t ctx)
	clear generic event callback More...

Detailed Description

common vpp api C declarations

This file declares the common C API functions. These include connect, disconnect and utility functions as well as the low-level vapi_send and vapi_recv API. This is only the transport layer.

Message formats and higher-level APIs are generated by running the vapi_c_gen.py script (which is run for in-tree APIs as part of the build process). It's not recommended to mix the higher and lower level APIs. Due to version issues, the higher-level APIs are not part of the shared library.

Definition in file vapi.h.

Typedef Documentation

◆ vapi_ctx_t

typedef struct vapi_ctx_s* vapi_ctx_t

Definition at line 47 of file vapi.h.

◆ vapi_event_cb

typedef vapi_error_e(* vapi_event_cb) (vapi_ctx_t ctx, void *callback_ctx, void *payload)

generic vapi event callback

Definition at line 211 of file vapi.h.

◆ vapi_generic_event_cb

typedef vapi_error_e(* vapi_generic_event_cb) (vapi_ctx_t ctx, void *callback_ctx, vapi_msg_id_t id, void *msg)

generic vapi event callback

Definition at line 234 of file vapi.h.

Function Documentation

◆ vapi_clear_event_cb()

void vapi_clear_event_cb	(	vapi_ctx_t	ctx,
		vapi_msg_id_t	id
	)

clear event callback for given message id

Parameters

ctx	opaque vapi context
id	message id

Definition at line 833 of file vapi.c.

Here is the call graph for this function:

◆ vapi_clear_generic_event_cb()

void vapi_clear_generic_event_cb ( vapi_ctx_t ctx )

clear generic event callback

Parameters

ctx	opaque vapi context

Definition at line 847 of file vapi.c.

◆ vapi_connect()

vapi_error_e vapi_connect	(	vapi_ctx_t	ctx,
		const char *	name,
		const char *	chroot_prefix,
		int	max_outstanding_requests,
		int	response_queue_size,
		vapi_mode_e	mode,
		bool	handle_keepalives
	)

connect to vpp

Parameters

ctx	opaque vapi context, must be allocated using vapi_ctx_alloc first
name	application name
chroot_prefix	shared memory prefix
max_outstanding_requests	max number of outstanding requests queued
response_queue_size	size of the response queue
mode	mode of operation - blocking or nonblocking
handle_keepalives	- if true, automatically handle memclnt_keepalive

Returns: VAPI_OK on success, other error code on error

Definition at line 301 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_ctx_alloc()

vapi_error_e vapi_ctx_alloc ( vapi_ctx_t * result )

allocate vapi context

Parameters

[out] pointer to result variable

Returns: VAPI_OK on success, other error code on error

Definition at line 251 of file vapi.c.

Here is the caller graph for this function:

◆ vapi_ctx_free()

void vapi_ctx_free ( vapi_ctx_t ctx )

free vapi context

Definition at line 283 of file vapi.c.

Here is the caller graph for this function:

◆ vapi_disconnect()

vapi_error_e vapi_disconnect ( vapi_ctx_t ctx )

disconnect from vpp

Parameters

ctx	opaque vapi context

Returns: VAPI_OK on success, other error code on error

Definition at line 419 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_dispatch()

vapi_error_e vapi_dispatch ( vapi_ctx_t ctx )

loop vapi_dispatch_one until responses to all currently outstanding requests have been received and their callbacks called

Note: the dispatch loop is interrupted if any error is encountered or returned from the callback, in which case this error is returned as the result of vapi_dispatch. In this case it might be necessary to call dispatch again to process the remaining messages. Returning VAPI_EUSER from a callback allows the user to break the dispatch loop (and distinguish this case in the calling code from other failures). VAPI never returns VAPI_EUSER on its own.

Returns: VAPI_OK on success, other error code on error

Definition at line 809 of file vapi.c.

Here is the call graph for this function:

◆ vapi_dispatch_one()

vapi_error_e vapi_dispatch_one ( vapi_ctx_t ctx )

pick next message sent by vpp and call the appropriate callback

Returns: VAPI_OK on success, other error code on error

Definition at line 752 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_get_fd()

vapi_error_e vapi_get_fd	(	vapi_ctx_t	ctx,
		int *	fd
	)

get event file descriptor

Note: this file descriptor becomes readable when messages (from vpp) are waiting in queue

Parameters

	ctx	opaque vapi context
[out]	fd	pointer to result variable

Returns: VAPI_OK on success, other error code on error

Definition at line 435 of file vapi.c.

Here is the caller graph for this function:

◆ vapi_is_msg_available()

bool vapi_is_msg_available	(	vapi_ctx_t	ctx,
		vapi_msg_id_t	type
	)

check if message identified by it's message id is known by the vpp to which the connection is open

Definition at line 295 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_msg_alloc()

void* vapi_msg_alloc	(	vapi_ctx_t	ctx,
		size_t	size
	)

allocate vapi message of given size

Note: message must be freed by vapi_msg_free if not consumed by vapi_send call

Parameters

ctx	opaque vapi context

Returns: pointer to message or NULL if out of memory

Definition at line 217 of file vapi.c.

Here is the call graph for this function:

◆ vapi_msg_free()

void vapi_msg_free	(	vapi_ctx_t	ctx,
		void *	msg
	)

free a vapi message

Note: messages received by vapi_recv must be freed when no longer needed

Parameters

ctx	opaque vapi context
msg	message to be freed

Definition at line 228 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_recv()

vapi_error_e vapi_recv	(	vapi_ctx_t	ctx,
		void **	msg,
		size_t *	msg_size,
		svm_q_conditional_wait_t	cond,
		u32	time
	)

low-level api for reading messages from vpp

Note: it is not recommended to use this api directly, use generated api instead

Parameters

	ctx	opaque vapi context
[out]	msg	pointer to result variable containing message
[out]	msg_size	pointer to result variable containing message size
	cond	enum type for blocking, non-blocking or timed wait call
	time	in sec for timed wait

Returns: VAPI_OK on success, other error code on error

Definition at line 531 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_send()

vapi_error_e vapi_send	(	vapi_ctx_t	ctx,
		void *	msg
	)

low-level api for sending messages to vpp

Note: it is not recommended to use this api directly, use generated api instead

Parameters

ctx	opaque vapi context
msg	message to send

Returns: VAPI_OK on success, other error code on error

Definition at line 441 of file vapi.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vapi_send2()

vapi_error_e vapi_send2	(	vapi_ctx_t	ctx,
		void *	msg1,
		void *	msg2
	)

low-level api for atomically sending two messages to vpp - either both messages are sent or neither one is

Note: it is not recommended to use this api directly, use generated api instead

Parameters

ctx	opaque vapi context
msg1	first message to send
msg2	second message to send

Returns: VAPI_OK on success, other error code on error

Definition at line 485 of file vapi.c.

Here is the call graph for this function:

◆ vapi_set_event_cb()

void vapi_set_event_cb	(	vapi_ctx_t	ctx,
		vapi_msg_id_t	id,
		vapi_event_cb	callback,
		void *	callback_ctx
	)

set event callback to call when message with given id is dispatched

Parameters

ctx	opaque vapi context
id	message id
callback	callback
callback_ctx	context pointer stored and passed to callback

Definition at line 824 of file vapi.c.

Here is the caller graph for this function:

◆ vapi_set_generic_event_cb()

void vapi_set_generic_event_cb	(	vapi_ctx_t	ctx,
		vapi_generic_event_cb	callback,
		void *	callback_ctx
	)

set generic event callback

Note: this callback is called by dispatch if no message-type specific callback is set (so it's a fallback callback)

Parameters

ctx	opaque vapi context
callback	callback
callback_ctx	context pointer stored and passed to callback

Definition at line 839 of file vapi.c.

◆ vapi_wait()

vapi_error_e vapi_wait	(	vapi_ctx_t	ctx,
		vapi_wait_mode_e	mode
	)

wait for connection to become readable or writable

Parameters

ctx	opaque vapi context
mode	type of property to wait for - readability, writability or both

Returns: VAPI_OK on success, other error code on error

Definition at line 621 of file vapi.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ vapi_ctx_t

◆ vapi_event_cb

◆ vapi_generic_event_cb

Function Documentation

◆ vapi_clear_event_cb()

◆ vapi_clear_generic_event_cb()

◆ vapi_connect()

◆ vapi_ctx_alloc()

◆ vapi_ctx_free()

◆ vapi_disconnect()

◆ vapi_dispatch()

◆ vapi_dispatch_one()

◆ vapi_get_fd()

◆ vapi_is_msg_available()

◆ vapi_msg_alloc()

◆ vapi_msg_free()

◆ vapi_recv()

◆ vapi_send()

◆ vapi_send2()

◆ vapi_set_event_cb()

◆ vapi_set_generic_event_cb()

◆ vapi_wait()