FD.io VPP  v20.09-64-g4f7b92f0a
Vector Packet Processing
vapi.h File Reference

common vpp api C declarations More...

+ Include dependency graph for vapi.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct vapi_ctx_svapi_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
ctxopaque vapi context
idmessage id

Definition at line 837 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
ctxopaque vapi context

Definition at line 851 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
ctxopaque vapi context, must be allocated using vapi_ctx_alloc first
nameapplication name
chroot_prefixshared memory prefix
max_outstanding_requestsmax number of outstanding requests queued
response_queue_sizesize of the response queue
modemode 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 305 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]pointerto result variable
Returns
VAPI_OK on success, other error code on error

Definition at line 255 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 287 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
ctxopaque vapi context
Returns
VAPI_OK on success, other error code on error

Definition at line 423 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 813 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 756 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
ctxopaque vapi context
[out]fdpointer to result variable
Returns
VAPI_OK on success, other error code on error

Definition at line 439 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 299 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
ctxopaque 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
ctxopaque vapi context
msgmessage to be freed

Definition at line 232 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
ctxopaque vapi context
[out]msgpointer to result variable containing message
[out]msg_sizepointer to result variable containing message size
condenum type for blocking, non-blocking or timed wait call
timein sec for timed wait
Returns
VAPI_OK on success, other error code on error

Definition at line 535 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
ctxopaque vapi context
msgmessage to send
Returns
VAPI_OK on success, other error code on error

Definition at line 445 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
ctxopaque vapi context
msg1first message to send
msg2second message to send
Returns
VAPI_OK on success, other error code on error

Definition at line 489 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
ctxopaque vapi context
idmessage id
callbackcallback
callback_ctxcontext pointer stored and passed to callback

Definition at line 828 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
ctxopaque vapi context
callbackcallback
callback_ctxcontext pointer stored and passed to callback

Definition at line 843 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
ctxopaque vapi context
modetype of property to wait for - readability, writability or both
Returns
VAPI_OK on success, other error code on error

Definition at line 625 of file vapi.c.