Callbacks/Customization
[Core Netlink API]

Callbacks and overwriting capabilities are provided to take influence in various control flows inside the library. More...

Enumerations

enum  nl_cb_action { NL_OK, NL_SKIP, NL_STOP }
 

Callback actions.

More...
enum  nl_cb_kind {
  NL_CB_DEFAULT, NL_CB_VERBOSE, NL_CB_DEBUG, NL_CB_CUSTOM,
  __NL_CB_KIND_MAX
}
 

Callback kinds.

More...
enum  nl_cb_type {
  NL_CB_VALID, NL_CB_FINISH, NL_CB_OVERRUN, NL_CB_SKIPPED,
  NL_CB_ACK, NL_CB_MSG_IN, NL_CB_MSG_OUT, NL_CB_INVALID,
  NL_CB_SEQ_CHECK, NL_CB_SEND_ACK, __NL_CB_TYPE_MAX
}
 

Callback types.

More...

Callback Typedefs



typedef int(* nl_recvmsg_msg_cb_t )(struct nl_msg *msg, void *arg)
 nl_recvmsgs() callback for message processing customization
typedef int(* nl_recvmsg_err_cb_t )(struct sockaddr_nl *nla, struct nlmsgerr *nlerr, void *arg)
 nl_recvmsgs() callback for error message processing customization

Callback Handle Management



struct nl_cb * nl_cb_alloc (enum nl_cb_kind kind)
 Allocate a new callback handle.
struct nl_cb * nl_cb_clone (struct nl_cb *orig)
 Clone an existing callback handle.
struct nl_cb * nl_cb_get (struct nl_cb *cb)
void nl_cb_put (struct nl_cb *cb)

Callback Setup



int nl_cb_set (struct nl_cb *cb, enum nl_cb_type type, enum nl_cb_kind kind, nl_recvmsg_msg_cb_t func, void *arg)
 Set up a callback.
int nl_cb_set_all (struct nl_cb *cb, enum nl_cb_kind kind, nl_recvmsg_msg_cb_t func, void *arg)
 Set up a all callbacks.
int nl_cb_err (struct nl_cb *cb, enum nl_cb_kind kind, nl_recvmsg_err_cb_t func, void *arg)
 Set up an error callback.

Overwriting



void nl_cb_overwrite_recvmsgs (struct nl_cb *cb, int(*func)(struct nl_handle *, struct nl_cb *))
 Overwrite internal calls to nl_recvmsgs().
void nl_cb_overwrite_recv (struct nl_cb *cb, int(*func)(struct nl_handle *, struct sockaddr_nl *, unsigned char **, struct ucred **))
 Overwrite internal calls to nl_recv().
void nl_cb_overwrite_send (struct nl_cb *cb, int(*func)(struct nl_handle *, struct nl_msg *))
 Overwrite internal calls to nl_send().

Detailed Description

All callbacks are packed together in struct nl_cb which is then attached to a netlink socket or passed on to the respective functions directly.

Callbacks can control the flow of the underlying layer by returning the appropriate error codes:

 Action ID        | Description
 -----------------+-------------------------------------------------------
 NL_OK       | Proceed with whatever comes next.
 NL_SKIP          | Skip message currently being processed and continue
                  | with next message.
 NL_STOP          | Stop parsing and discard all remaining messages in
                  | this set of messages.

All callbacks are optional and a default action is performed if no application specific implementation is provided:

 Callback ID       | Default Return Value
 ------------------+----------------------
 NL_CB_VALID       | NL_OK
 NL_CB_FINISH      | NL_STOP
 NL_CB_OVERRUN     | NL_STOP
 NL_CB_SKIPPED     | NL_SKIP
 NL_CB_ACK         | NL_STOP
 NL_CB_MSG_IN      | NL_OK
 NL_CB_MSG_OUT     | NL_OK
 NL_CB_INVALID     | NL_STOP
 NL_CB_SEQ_CHECK   | NL_OK
 NL_CB_SEND_ACK    | NL_OK
                   |
 Error Callback    | NL_STOP

In order to simplify typical usages of the library, different sets of default callback implementations exist:

 NL_CB_DEFAULT: No additional actions
 NL_CB_VERBOSE: Automatically print warning and error messages to a file
                descriptor as appropriate. This is useful for CLI based
                applications.
 NL_CB_DEBUG:   Print informal debugging information for each message
                received. This will result in every message beint sent or
                received to be printed to the screen in a decoded,
                human-readable format.
1) Setting up a callback set
 // Allocate a callback set and initialize it to the verbose default set
 struct nl_cb *cb = nl_cb_alloc(NL_CB_VERBOSE);

 // Modify the set to call my_func() for all valid messages
 nl_cb_set(cb, NL_CB_VALID, NL_CB_CUSTOM, my_func, NULL);

 // Set the error message handler to the verbose default implementation
 // and direct it to print all errors to the given file descriptor.
 FILE *file = fopen(...);
 nl_cb_err(cb, NL_CB_VERBOSE, NULL, file);

Typedef Documentation

typedef int(* nl_recvmsg_msg_cb_t)(struct nl_msg *msg, void *arg)
Parameters:
msg netlink message being processed
arg argument passwd on through caller

Definition at line 40 of file handlers.h.

typedef int(* nl_recvmsg_err_cb_t)(struct sockaddr_nl *nla, struct nlmsgerr *nlerr, void *arg)
Parameters:
nla netlink address of the peer
nlerr netlink error message being processed
arg argument passed on through caller

Definition at line 49 of file handlers.h.


Enumeration Type Documentation

Enumerator:
NL_OK 

Proceed with wathever would come next.

NL_SKIP 

Skip this message.

NL_STOP 

Stop parsing altogether and discard remaining messages.

Definition at line 58 of file handlers.h.

00058                   {
00059         /** Proceed with wathever would come next */
00060         NL_OK,
00061         /** Skip this message */
00062         NL_SKIP,
00063         /** Stop parsing altogether and discard remaining messages */
00064         NL_STOP,
00065 };

enum nl_cb_kind
Enumerator:
NL_CB_DEFAULT 

Default handlers (quiet).

NL_CB_VERBOSE 

Verbose default handlers (error messages printed).

NL_CB_DEBUG 

Debug handlers for debugging.

NL_CB_CUSTOM 

Customized handler specified by the user.

Definition at line 75 of file handlers.h.

00075                 {
00076         /** Default handlers (quiet) */
00077         NL_CB_DEFAULT,
00078         /** Verbose default handlers (error messages printed) */
00079         NL_CB_VERBOSE,
00080         /** Debug handlers for debugging */
00081         NL_CB_DEBUG,
00082         /** Customized handler specified by the user */
00083         NL_CB_CUSTOM,
00084         __NL_CB_KIND_MAX,
00085 };

enum nl_cb_type
Enumerator:
NL_CB_VALID 

Message is valid.

NL_CB_FINISH 

Last message in a series of multi part messages received.

NL_CB_OVERRUN 

Report received that data was lost.

NL_CB_SKIPPED 

Message wants to be skipped.

NL_CB_ACK 

Message is an acknowledge.

NL_CB_MSG_IN 

Called for every message received.

NL_CB_MSG_OUT 

Called for every message sent out except for nl_sendto().

NL_CB_INVALID 

Message is malformed and invalid.

NL_CB_SEQ_CHECK 

Called instead of internal sequence number checking.

NL_CB_SEND_ACK 

Sending of an acknowledge message has been requested.

Definition at line 93 of file handlers.h.

00093                 {
00094         /** Message is valid */
00095         NL_CB_VALID,
00096         /** Last message in a series of multi part messages received */
00097         NL_CB_FINISH,
00098         /** Report received that data was lost */
00099         NL_CB_OVERRUN,
00100         /** Message wants to be skipped */
00101         NL_CB_SKIPPED,
00102         /** Message is an acknowledge */
00103         NL_CB_ACK,
00104         /** Called for every message received */
00105         NL_CB_MSG_IN,
00106         /** Called for every message sent out except for nl_sendto() */
00107         NL_CB_MSG_OUT,
00108         /** Message is malformed and invalid */
00109         NL_CB_INVALID,
00110         /** Called instead of internal sequence number checking */
00111         NL_CB_SEQ_CHECK,
00112         /** Sending of an acknowledge message has been requested */
00113         NL_CB_SEND_ACK,
00114         __NL_CB_TYPE_MAX,
00115 };


Function Documentation

struct nl_cb* nl_cb_alloc ( enum nl_cb_kind  kind  )  [read]
Parameters:
kind callback kind to be used for initialization
Returns:
Newly allocated callback handle or NULL

Definition at line 255 of file handlers.c.

References nl_cb_err(), and nl_cb_set().

Referenced by nl_cb_clone(), and nl_handle_alloc().

00256 {
00257         int i;
00258         struct nl_cb *cb;
00259 
00260         if (kind < 0 || kind > NL_CB_KIND_MAX)
00261                 return NULL;
00262 
00263         cb = calloc(1, sizeof(*cb));
00264         if (!cb) {
00265                 nl_errno(ENOMEM);
00266                 return NULL;
00267         }
00268 
00269         cb->cb_refcnt = 1;
00270 
00271         for (i = 0; i <= NL_CB_TYPE_MAX; i++)
00272                 nl_cb_set(cb, i, kind, NULL, NULL);
00273 
00274         nl_cb_err(cb, kind, NULL, NULL);
00275 
00276         return cb;
00277 }

struct nl_cb* nl_cb_clone ( struct nl_cb *  orig  )  [read]
Parameters:
orig original callback handle
Returns:
Newly allocated callback handle being a duplicate of orig or NULL

Definition at line 285 of file handlers.c.

References nl_cb_alloc(), and NL_CB_DEFAULT.

Referenced by nl_wait_for_ack().

00286 {
00287         struct nl_cb *cb;
00288         
00289         cb = nl_cb_alloc(NL_CB_DEFAULT);
00290         if (!cb)
00291                 return NULL;
00292 
00293         memcpy(cb, orig, sizeof(*orig));
00294         cb->cb_refcnt = 1;
00295 
00296         return cb;
00297 }

int nl_cb_set ( struct nl_cb *  cb,
enum nl_cb_type  type,
enum nl_cb_kind  kind,
nl_recvmsg_msg_cb_t  func,
void *  arg 
)
Parameters:
cb callback set
type callback to modify
kind kind of implementation
func callback function (NL_CB_CUSTOM)
arg argument passed to callback
Returns:
0 on success or a negative error code

Definition at line 337 of file handlers.c.

References NL_CB_CUSTOM.

Referenced by nl_cb_alloc(), nl_cb_set_all(), nl_disable_sequence_check(), nl_socket_modify_cb(), and nl_wait_for_ack().

00339 {
00340         if (type < 0 || type > NL_CB_TYPE_MAX)
00341                 return nl_error(ERANGE, "Callback type out of range");
00342 
00343         if (kind < 0 || kind > NL_CB_KIND_MAX)
00344                 return nl_error(ERANGE, "Callback kind out of range");
00345 
00346         if (kind == NL_CB_CUSTOM) {
00347                 cb->cb_set[type] = func;
00348                 cb->cb_args[type] = arg;
00349         } else {
00350                 cb->cb_set[type] = cb_def[type][kind];
00351                 cb->cb_args[type] = arg;
00352         }
00353 
00354         return 0;
00355 }

int nl_cb_set_all ( struct nl_cb *  cb,
enum nl_cb_kind  kind,
nl_recvmsg_msg_cb_t  func,
void *  arg 
)
Parameters:
cb callback set
kind kind of callback
func callback function
arg argument to be passwd to callback function
Returns:
0 on success or a negative error code

Definition at line 366 of file handlers.c.

References nl_cb_set().

00368 {
00369         int i, err;
00370 
00371         for (i = 0; i <= NL_CB_TYPE_MAX; i++) {
00372                 err = nl_cb_set(cb, i, kind, func, arg);
00373                 if (err < 0)
00374                         return err;
00375         }
00376 
00377         return 0;
00378 }

int nl_cb_err ( struct nl_cb *  cb,
enum nl_cb_kind  kind,
nl_recvmsg_err_cb_t  func,
void *  arg 
)
Parameters:
cb callback set
kind kind of callback
func callback function
arg argument to be passed to callback function

Definition at line 387 of file handlers.c.

References NL_CB_CUSTOM.

Referenced by nl_cb_alloc().

00389 {
00390         if (kind < 0 || kind > NL_CB_KIND_MAX)
00391                 return nl_error(ERANGE, "Callback kind out of range");
00392 
00393         if (kind == NL_CB_CUSTOM) {
00394                 cb->cb_err = func;
00395                 cb->cb_err_arg = arg;
00396         } else {
00397                 cb->cb_err = cb_err_def[kind];
00398                 cb->cb_err_arg = arg;
00399         }
00400 
00401         return 0;
00402 }

void nl_cb_overwrite_recvmsgs ( struct nl_cb *  cb,
int(*)(struct nl_handle *, struct nl_cb *)  func 
)
Parameters:
cb callback set
func replacement callback for nl_recvmsgs()

Definition at line 416 of file handlers.c.

00418 {
00419         cb->cb_recvmsgs_ow = func;
00420 }

void nl_cb_overwrite_recv ( struct nl_cb *  cb,
int(*)(struct nl_handle *, struct sockaddr_nl *, unsigned char **, struct ucred **)  func 
)
Parameters:
cb callback set
func replacement callback for nl_recv()

Definition at line 427 of file handlers.c.

00430 {
00431         cb->cb_recv_ow = func;
00432 }

void nl_cb_overwrite_send ( struct nl_cb *  cb,
int(*)(struct nl_handle *, struct nl_msg *)  func 
)
Parameters:
cb callback set
func replacement callback for nl_send()

Definition at line 439 of file handlers.c.

00441 {
00442         cb->cb_send_ow = func;
00443 }


Generated on 30 Oct 2009 for libnl by  doxygen 1.6.1