libnl  1.1
Enumerations
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 Handle Management

struct nl_cb * nl_cb_alloc (enum nl_cb_kind kind)
 Allocate a new callback handle. More...
 
struct nl_cb * nl_cb_clone (struct nl_cb *orig)
 Clone an existing callback handle. More...
 
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. More...
 
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. More...
 
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. More...
 

Overwriting

void nl_cb_overwrite_recvmsgs (struct nl_cb *cb, int(*func)(struct nl_handle *, struct nl_cb *))
 Overwrite internal calls to nl_recvmsgs() More...
 
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() More...
 
void nl_cb_overwrite_send (struct nl_cb *cb, int(*func)(struct nl_handle *, struct nl_msg *))
 Overwrite internal calls to nl_send() More...
 

Callback Typedefs

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

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
------------------+----------------------
|
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
msgnetlink message being processed
argargument 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
nlanetlink address of the peer
nlerrnetlink error message being processed
argargument 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.

58  {
59  /** Proceed with wathever would come next */
60  NL_OK,
61  /** Skip this message */
62  NL_SKIP,
63  /** Stop parsing altogether and discard remaining messages */
64  NL_STOP,
65 };
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.

75  {
76  /** Default handlers (quiet) */
78  /** Verbose default handlers (error messages printed) */
80  /** Debug handlers for debugging */
82  /** Customized handler specified by the user */
84  __NL_CB_KIND_MAX,
85 };
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.

93  {
94  /** Message is valid */
96  /** Last message in a series of multi part messages received */
98  /** Report received that data was lost */
100  /** Message wants to be skipped */
102  /** Message is an acknowledge */
103  NL_CB_ACK,
104  /** Called for every message received */
105  NL_CB_MSG_IN,
106  /** Called for every message sent out except for nl_sendto() */
108  /** Message is malformed and invalid */
110  /** Called instead of internal sequence number checking */
112  /** Sending of an acknowledge message has been requested */
114  __NL_CB_TYPE_MAX,
115 };

Function Documentation

struct nl_cb* nl_cb_alloc ( enum nl_cb_kind  kind)
read
Parameters
kindcallback 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().

256 {
257  int i;
258  struct nl_cb *cb;
259 
260  if (kind < 0 || kind > NL_CB_KIND_MAX)
261  return NULL;
262 
263  cb = calloc(1, sizeof(*cb));
264  if (!cb) {
265  nl_errno(ENOMEM);
266  return NULL;
267  }
268 
269  cb->cb_refcnt = 1;
270 
271  for (i = 0; i <= NL_CB_TYPE_MAX; i++)
272  nl_cb_set(cb, i, kind, NULL, NULL);
273 
274  nl_cb_err(cb, kind, NULL, NULL);
275 
276  return cb;
277 }
struct nl_cb* nl_cb_clone ( struct nl_cb *  orig)
read
Parameters
origoriginal 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().

286 {
287  struct nl_cb *cb;
288 
290  if (!cb)
291  return NULL;
292 
293  memcpy(cb, orig, sizeof(*orig));
294  cb->cb_refcnt = 1;
295 
296  return cb;
297 }
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
cbcallback set
typecallback to modify
kindkind of implementation
funccallback function (NL_CB_CUSTOM)
argargument 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().

339 {
340  if (type < 0 || type > NL_CB_TYPE_MAX)
341  return nl_error(ERANGE, "Callback type out of range");
342 
343  if (kind < 0 || kind > NL_CB_KIND_MAX)
344  return nl_error(ERANGE, "Callback kind out of range");
345 
346  if (kind == NL_CB_CUSTOM) {
347  cb->cb_set[type] = func;
348  cb->cb_args[type] = arg;
349  } else {
350  cb->cb_set[type] = cb_def[type][kind];
351  cb->cb_args[type] = arg;
352  }
353 
354  return 0;
355 }
int nl_cb_set_all ( struct nl_cb *  cb,
enum nl_cb_kind  kind,
nl_recvmsg_msg_cb_t  func,
void *  arg 
)
Parameters
cbcallback set
kindkind of callback
funccallback function
argargument 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().

368 {
369  int i, err;
370 
371  for (i = 0; i <= NL_CB_TYPE_MAX; i++) {
372  err = nl_cb_set(cb, i, kind, func, arg);
373  if (err < 0)
374  return err;
375  }
376 
377  return 0;
378 }
int nl_cb_err ( struct nl_cb *  cb,
enum nl_cb_kind  kind,
nl_recvmsg_err_cb_t  func,
void *  arg 
)
Parameters
cbcallback set
kindkind of callback
funccallback function
argargument to be passed to callback function

Definition at line 387 of file handlers.c.

References NL_CB_CUSTOM.

Referenced by nl_cb_alloc().

389 {
390  if (kind < 0 || kind > NL_CB_KIND_MAX)
391  return nl_error(ERANGE, "Callback kind out of range");
392 
393  if (kind == NL_CB_CUSTOM) {
394  cb->cb_err = func;
395  cb->cb_err_arg = arg;
396  } else {
397  cb->cb_err = cb_err_def[kind];
398  cb->cb_err_arg = arg;
399  }
400 
401  return 0;
402 }
void nl_cb_overwrite_recvmsgs ( struct nl_cb *  cb,
int(*)(struct nl_handle *, struct nl_cb *)  func 
)
Parameters
cbcallback set
funcreplacement callback for nl_recvmsgs()

Definition at line 416 of file handlers.c.

418 {
419  cb->cb_recvmsgs_ow = func;
420 }
void nl_cb_overwrite_recv ( struct nl_cb *  cb,
int(*)(struct nl_handle *, struct sockaddr_nl *, unsigned char **, struct ucred **)  func 
)
Parameters
cbcallback set
funcreplacement callback for nl_recv()

Definition at line 427 of file handlers.c.

430 {
431  cb->cb_recv_ow = func;
432 }
void nl_cb_overwrite_send ( struct nl_cb *  cb,
int(*)(struct nl_handle *, struct nl_msg *)  func 
)
Parameters
cbcallback set
funcreplacement callback for nl_send()

Definition at line 439 of file handlers.c.

441 {
442  cb->cb_send_ow = func;
443 }