Callbacks/Customization

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

nl_recvmsg_msg_cb_t

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 41 of file handlers.h.

nl_recvmsg_err_cb_t

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 50 of file handlers.h.

Enumeration Type Documentation

nl_cb_action

enum nl_cb_action

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 59 of file handlers.h.

                  {
        /** Proceed with wathever would come next */
        NL_OK,
        /** Skip this message */
        NL_SKIP,
        /** Stop parsing altogether and discard remaining messages */
        NL_STOP,
};

nl_cb_kind

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 76 of file handlers.h.

                {
        /** Default handlers (quiet) */
        NL_CB_DEFAULT,
        /** Verbose default handlers (error messages printed) */
        NL_CB_VERBOSE,
        /** Debug handlers for debugging */
        NL_CB_DEBUG,
        /** Customized handler specified by the user */
        NL_CB_CUSTOM,
        __NL_CB_KIND_MAX,
};

nl_cb_type

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 94 of file handlers.h.

                {
        /** Message is valid */
        NL_CB_VALID,
        /** Last message in a series of multi part messages received */
        NL_CB_FINISH,
        /** Report received that data was lost */
        NL_CB_OVERRUN,
        /** Message wants to be skipped */
        NL_CB_SKIPPED,
        /** Message is an acknowledge */
        NL_CB_ACK,
        /** Called for every message received */
        NL_CB_MSG_IN,
        /** Called for every message sent out except for nl_sendto() */
        NL_CB_MSG_OUT,
        /** Message is malformed and invalid */
        NL_CB_INVALID,
        /** Called instead of internal sequence number checking */
        NL_CB_SEQ_CHECK,
        /** Sending of an acknowledge message has been requested */
        NL_CB_SEND_ACK,
        __NL_CB_TYPE_MAX,
};

Function Documentation

nl_cb_alloc()

struct nl_cb * nl_cb_alloc

(

enum nl_cb_kind

kind

)

Parameters

kind	callback kind to be used for initialization

Returns

Newly allocated callback handle or NULL

Definition at line 256 of file handlers.c.

{
        int i;
        struct nl_cb *cb;
 
        if (kind < 0 || kind > NL_CB_KIND_MAX)
                return NULL;
 
        cb = calloc(1, sizeof(*cb));
        if (!cb) {
                nl_errno(ENOMEM);
                return NULL;
        }
 
        cb->cb_refcnt = 1;
 
        for (i = 0; i <= NL_CB_TYPE_MAX; i++)
                nl_cb_set(cb, i, kind, NULL, NULL);
 
        nl_cb_err(cb, kind, NULL, NULL);
 
        return cb;
}

References nl_cb_err(), and nl_cb_set().

Referenced by nl_cb_clone(), and nl_handle_alloc().

nl_cb_clone()

struct nl_cb * nl_cb_clone

(

struct nl_cb *

orig

)

Parameters

orig	original callback handle

Returns

Newly allocated callback handle being a duplicate of orig or NULL

Definition at line 286 of file handlers.c.

{
        struct nl_cb *cb;
        
        cb = nl_cb_alloc(NL_CB_DEFAULT);
        if (!cb)
                return NULL;
 
        memcpy(cb, orig, sizeof(*orig));
        cb->cb_refcnt = 1;
 
        return cb;
}

References nl_cb_alloc(), and NL_CB_DEFAULT.

Referenced by nl_wait_for_ack().

nl_cb_get()

struct nl_cb * nl_cb_get

(

struct nl_cb *

cb

)

Definition at line 300 of file handlers.c.

{
        cb->cb_refcnt++;
 
        return cb;
}

nl_cb_put()

void nl_cb_put

(

struct nl_cb *

cb

)

Definition at line 307 of file handlers.c.

{
        if (!cb)
                return;
 
        cb->cb_refcnt--;
 
        if (cb->cb_refcnt < 0)
                BUG();
 
        if (cb->cb_refcnt <= 0)
                free(cb);
}

nl_cb_set()

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 338 of file handlers.c.

{
        if (type < 0 || type > NL_CB_TYPE_MAX)
                return nl_error(ERANGE, "Callback type out of range");
 
        if (kind < 0 || kind > NL_CB_KIND_MAX)
                return nl_error(ERANGE, "Callback kind out of range");
 
        if (kind == NL_CB_CUSTOM) {
                cb->cb_set[type] = func;
                cb->cb_args[type] = arg;
        } else {
                cb->cb_set[type] = cb_def[type][kind];
                cb->cb_args[type] = arg;
        }
 
        return 0;
}

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().

nl_cb_set_all()

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 367 of file handlers.c.

{
        int i, err;
 
        for (i = 0; i <= NL_CB_TYPE_MAX; i++) {
                err = nl_cb_set(cb, i, kind, func, arg);
                if (err < 0)
                        return err;
        }
 
        return 0;
}

References nl_cb_set().

nl_cb_err()

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 388 of file handlers.c.

{
        if (kind < 0 || kind > NL_CB_KIND_MAX)
                return nl_error(ERANGE, "Callback kind out of range");
 
        if (kind == NL_CB_CUSTOM) {
                cb->cb_err = func;
                cb->cb_err_arg = arg;
        } else {
                cb->cb_err = cb_err_def[kind];
                cb->cb_err_arg = arg;
        }
 
        return 0;
}

References NL_CB_CUSTOM.

Referenced by nl_cb_alloc().

nl_cb_overwrite_recvmsgs()

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 417 of file handlers.c.

{
        cb->cb_recvmsgs_ow = func;
}

nl_cb_overwrite_recv()

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 428 of file handlers.c.

{
        cb->cb_recv_ow = func;
}

nl_cb_overwrite_send()

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 440 of file handlers.c.

{
        cb->cb_send_ow = func;
}