1 /* -*- mode: c; c-file-style: "openbsd" -*- */
3 * Copyright (c) 2012 Vincent Bernat <bernat@luffy.cx>
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22 * @defgroup liblldpctl liblldpctl: library to interface with lldpd
24 * `liblldpctl` allows any program to convenienty query and modify the behaviour
25 * of a running lldpd daemon.
27 * To use this library, use `pkg-config` to get the appropriate options:
28 * * `pkg-config --libs lldpctl` for `LIBS` or `LDFLAGS`
29 * * `pkg-config --cflags lldpctl` for `CFLAGS`
31 * @warning This library is tightly coupled with lldpd. The library to use
32 * should be the one shipped with lldpd. Clients of the library are then tied
33 * by the classic API/ABI rules and may be compiled separatly.
35 * There are two important structures in this library: @c lldpctl_conn_t which
36 * represents a connection and @c lldpctl_atom_t which represents a piece of
37 * information. Those types are opaque. No direct access to them should be done.
39 * The library is expected to be reentrant and therefore thread-safe. It is
40 * however not expected that a connection to be used in several thread
41 * simultaneously. This also applies to the different pieces of information
42 * gathered through this connection. Several connection to lldpd can be used
45 * The first step is to establish a connection. See @ref lldpctl_connection for
46 * more information about this. The next step is to query the lldpd daemon. See
47 * @ref lldpctl_atoms on how to do this.
49 * `liblldpctl` tries to handle errors in a coherent way. Any function returning
50 * a pointer will return @c NULL on error and the last error can be retrieved
51 * through @ref lldpctl_last_error() function. Most functions returning integers
52 * will return a negative integer representing the error if something goes
53 * wrong. The use of @ref lldpctl_last_error() allows one to check if this is a
54 * real error if there is a doubt. See @ref lldpctl_errors_logs for more about
67 #include <sys/types.h>
70 * @defgroup lldpctl_connection Managing connection to lldpd
72 * Connection with lldpd.
74 * This library does not handle IO. They are delegated to a set of functions to
75 * allow a user to specify exactly how IO should be done. A user is expected to
76 * provide two functions: the first one is called when the library requests
77 * incoming data, the other one when it requests outgoing data. Moreover, the
78 * user is also expected to call the appropriate functions when data comes back
79 * (@ref lldpctl_recv()) or needs to be sent (@ref lldpctl_send()).
81 * Because the most common case is synchronous IO, `liblldpctl` will use classic
82 * synchronous IO with the Unix socket if no IO functions are provided by the
83 * user. For all other cases, the user must provide the appropriate functions.
85 * A connection should be allocated by using @ref lldpctl_new(). It needs to be
86 * released with @ref lldpctl_release().
92 * Get default transport name.
94 * Currently, this is the default location of the Unix socket.
96 const char* lldpctl_get_default_transport(void);
99 * Structure referencing a connection with lldpd.
101 * This structure should be handled as opaque. It can be allocated
102 * with @c lldpctl_new() and the associated resources will be freed
103 * with @c lldpctl_release().
105 typedef struct lldpctl_conn_t lldpctl_conn_t
;
108 * Callback function invoked to send data to lldpd.
110 * @param conn Handle to the connection to lldpd.
111 * @param data Bytes to be sent.
112 * @param length Length of provided data.
113 * @param user_data Provided user data.
114 * @return The number of bytes really sent or either @c LLDPCTL_ERR_WOULDBLOCK
115 * if no bytes can be sent without blocking or @c
116 * LLDPCTL_ERR_CALLBACK_FAILURE for other errors.
118 typedef ssize_t (*lldpctl_send_callback
)(lldpctl_conn_t
*conn
,
119 const uint8_t *data
, size_t length
, void *user_data
);
122 * Callback function invoked to receive data from lldpd.
124 * @param conn Handle to the connection to lldpd.
125 * @param data Buffer for receiving data
126 * @param length Maximum bytes we can receive
127 * @param user_data Provided user data.
128 * @return The number of bytes really received or either @c
129 * LLDPCTL_ERR_WOULDBLOCK if no bytes can be received without blocking,
130 * @c LLDPCTL_ERR_CALLBACK_FAILURE for other errors or @c
131 * LLDPCTL_ERR_EOF if end of file was reached.
133 typedef ssize_t (*lldpctl_recv_callback
)(lldpctl_conn_t
*conn
,
134 const uint8_t *data
, size_t length
, void *user_data
);
137 * Function invoked when additional data is available from lldpd.
139 * This function should be invoked in case of asynchronous IO when new data is
140 * available from lldpd (expected or unexpected).
142 * @param conn Handle to the connection to lldpd.
143 * @param data Data received from lldpd.
144 * @param length Length of data received.
145 * @return The number of bytes available or a negative integer if an error has
146 * occurred. 0 is not an error. It usually means that a notification has
149 ssize_t
lldpctl_recv(lldpctl_conn_t
*conn
, const uint8_t *data
, size_t length
);
152 * Function invoked when there is an opportunity to send data to lldpd.
154 * This function should be invoked in case of asynchronous IO when new data can
155 * be written to lldpd.
157 * @param conn Handle to the connection to lldpd.
158 * @return The number of bytes processed or a negative integer if an error has
161 ssize_t
lldpctl_send(lldpctl_conn_t
*conn
);
164 * Function invoked to see if there's more data to be processed in the buffer.
166 * This function should be invoked to check for notifications in the data that
167 * has already been read. Its used typically for asynchronous connections.
169 * @param conn Handle to the connection to lldpd.
170 * @return 0 to indicate maybe more data is available for processing
171 * !0 to indicate no data or insufficient data for processing
173 int lldpctl_process_conn_buffer(lldpctl_conn_t
*conn
);
177 * Allocate a new handler for connecting to lldpd.
179 * @param send Callback to be used when sending new data is requested.
180 * @param recv Callback to be used when receiving new data is requested.
181 * @param user_data Data to pass to callbacks.
182 * @return An handler to be used to connect to lldpd or @c NULL in
183 * case of error. In the later case, the error is probable an
184 * out of memory condition.
186 * The allocated handler can be released with @c lldpctl_release(). If the
187 * provided parameters are both @c NULL, default synchronous callbacks will be
190 lldpctl_conn_t
*lldpctl_new(lldpctl_send_callback send
,
191 lldpctl_recv_callback recv
, void *user_data
);
194 * Allocate a new handler for connecting to lldpd.
196 * @param ctlname the Unix-domain socket to connect to lldpd.
197 * @param send Callback to be used when sending new data is requested.
198 * @param recv Callback to be used when receiving new data is requested.
199 * @param user_data Data to pass to callbacks.
200 * @return An handler to be used to connect to lldpd or @c NULL in
201 * case of error. In the later case, the error is probable an
202 * out of memory condition.
204 * The allocated handler can be released with @c lldpctl_release(). If the
205 * provided parameters are both @c NULL, default synchronous callbacks will be
208 lldpctl_conn_t
*lldpctl_new_name(const char *ctlname
, lldpctl_send_callback send
,
209 lldpctl_recv_callback recv
, void *user_data
);
212 * Release resources associated with a connection to lldpd.
214 * @param conn Previously allocated handler to a connection to lldpd.
215 * @return 0 on success or a negative integer
219 int lldpctl_release(lldpctl_conn_t
*conn
);
223 * @defgroup lldpctl_errors_logs Errors and logs handling
225 * Error codes and logs handling.
227 * When a function returns a pointer, it may return @c NULL to indicate an error
228 * condition. In this case, it is possible to use @ref lldpctl_last_error() to
229 * get the related error code which is one of the values in @ref lldpctl_error_t
230 * enumeration. For display purpose @ref lldpctl_strerror() may be used to
231 * translate this error code.
233 * When a function returns an integer, it may return a negative value. It
234 * usually means this is an error but some functions may return a legitimate
235 * negative value (for example @ref lldpctl_atom_get_int()). When there is a
236 * doubt, @ref lldpctl_last_error() should be checked.
238 * An error is attached to a connection. If there is no connection, no error
239 * handling is available. Most functions use a connection or an atom as first
240 * argument and therefore are attached to a connection. To get the connection
241 * related to an atom, use @ref lldpctl_atom_get_connection().
243 * Also have a look at @ref lldpctl_log_callback() function if you want a custom
250 * Setup log handlers.
252 * By default, liblldpctl will log to stderr. The following function will
253 * register another callback for this purpose. Messages logged through this
254 * callback may be cryptic. They are targeted for the developer. Message for end
255 * users should rely on return codes.
257 void lldpctl_log_callback(void (*cb
)(int severity
, const char *msg
));
262 * By default, liblldpctl will only log warnings. The following function allows
263 * to increase verbosity. This function has no effect if callbacks are
264 * registered with the previous function.
266 * @param level Level of verbosity (1 = warnings, 2 = info, 3 = debug).
268 void lldpctl_log_level(int level
);
271 * Possible error codes for functions that return negative integers on
272 * this purpose or for @c lldpctl_last_error().
276 * No error has happened (yet).
278 LLDPCTL_NO_ERROR
= 0,
280 * A IO related operation would block if performed.
282 LLDPCTL_ERR_WOULDBLOCK
= -501,
284 * A IO related operation has reached a end of file condition.
286 LLDPCTL_ERR_EOF
= -502,
288 * The requested information does not exist. For example, when
289 * requesting an inexistant information from an atom.
291 LLDPCTL_ERR_NOT_EXIST
= -503,
293 * Cannot connect to the lldpd daemon. This error only happens with
294 * default synchronous handlers.
296 LLDPCTL_ERR_CANNOT_CONNECT
= -504,
298 * Atom is of incorrect type for the requested operation.
300 LLDPCTL_ERR_INCORRECT_ATOM_TYPE
= -505,
302 * An error occurred during serialization of message.
304 LLDPCTL_ERR_SERIALIZATION
= -506,
306 * The requested operation cannot be performed because we have another
307 * operation already running.
309 LLDPCTL_ERR_INVALID_STATE
= -507,
311 * The provided atom cannot be iterated.
313 LLDPCTL_ERR_CANNOT_ITERATE
= -508,
315 * The provided value is invalid.
317 LLDPCTL_ERR_BAD_VALUE
= -509,
319 * No new element can be created for this element.
321 LLDPCTL_ERR_CANNOT_CREATE
= -510,
323 * The library is under unexpected conditions and cannot process
324 * any further data reliably.
326 LLDPCTL_ERR_FATAL
= -900,
328 * Out of memory condition. Things may get havoc here but we
329 * should be able to recover.
331 LLDPCTL_ERR_NOMEM
= -901,
333 * An error occurred in a user provided callback.
335 LLDPCTL_ERR_CALLBACK_FAILURE
= -902
339 * Describe a provided error code.
341 * @param error Error code to be described.
342 * @return Statically allocated string describing the error.
344 const char *lldpctl_strerror(lldpctl_error_t error
);
347 * Get the last error associated to a connection to lldpd.
349 * @param conn Previously allocated handler to a connection to lldpd.
350 * @return 0 if no error is currently registered. A negative integer
353 * For functions returning int, this function will return the same
354 * error number. For functions returning something else, you can use
355 * this function to get the appropriate error number.
357 lldpctl_error_t
lldpctl_last_error(lldpctl_conn_t
*conn
);
360 * Describe the last error associate to a connection.
362 * @param conn Previously allocated handler to a connection to lldpd.
363 * @return Statically allocated string describing the error
365 #define lldpctl_last_strerror(conn) lldpctl_strerror(lldpctl_last_error(conn))
369 * @defgroup lldpctl_atoms Extracting information: atoms
371 * Information retrieved from lldpd is represented as an atom.
373 * This is an opaque structure that can be passed along some functions to
374 * transmit chassis, ports, VLAN and other information related to LLDP. Most
375 * information are extracted using @c lldpctl_atom_get(), @c
376 * lldpctl_atom_get_str(), @c lldpctl_atom_get_buffer() or @c
377 * lldpctl_atom_get_int(), unless some IO with lldpd is needed to retrieve the
378 * requested information. In this case, there exists an appropriate function to
379 * convert the "deferred" atom into a normal one (like @c lldpctl_get_port()).
381 * For some information, setters are also available: @c lldpctl_atom_set(), @c
382 * lldpctl_atom_set_str(), @c lldpctl_atom_set_buffer() or @c
383 * lldpctl_atom_set_int(). Unlike getters, some of those may require IO to
384 * achieve their goal.
386 * An atom is reference counted. The semantics are quite similar to Python and
387 * you must be careful of the ownership of a reference. It is possible to own a
388 * reference by calling @c lldpctl_atom_inc_ref(). Once the atom is not needed
389 * any more, you can abandon ownership with @c lldpctl_atom_dec_ref(). Unless
390 * documented otherwise, a function returning an atom will return a new
391 * reference (the ownership is assigned to the caller, no need to call @c
392 * lldpctl_atom_inc_ref()). Unless documented otherwise, when providing an atom
393 * to a function, the atom is usually borrowed (no change in reference
394 * counting). Currently, no function will steal ownership.
396 * It is quite important to use the reference counting functions
397 * correctly. Segfaults or memory leaks may occur otherwise. Once the reference
398 * count reaches 0, the atom is immediately freed. Reusing it will likely lead
399 * to memory corruption.
405 * Structure representing an element (chassis, port, VLAN, ...)
407 * @see lldpctl_atom_inc_ref(), lldpctl_atom_dec_ref().
409 typedef struct lldpctl_atom_t lldpctl_atom_t
;
412 * Structure representing a map from an integer to a character string.
414 * @see lldpctl_key_get_map().
416 typedef const struct {
422 * Return the reference to connection with lldpd.
424 * @param atom The atom we want reference from.
425 * @return The reference to the connection to lldpd.
427 * Each atom contains an internal reference to the corresponding connection to
428 * lldpd. Use this function to get it.
430 lldpctl_conn_t
*lldpctl_atom_get_connection(lldpctl_atom_t
*atom
);
433 * Increment reference count for an atom.
435 * @param atom Atom we which to increase reference count.
437 void lldpctl_atom_inc_ref(lldpctl_atom_t
*atom
);
440 * Decrement reference count for an atom.
442 * @param atom Atom we want to decrease reference count. Can be @c NULL. In this
443 * case, nothing happens.
445 * When the reference count becomes 0, the atom is freed.
447 void lldpctl_atom_dec_ref(lldpctl_atom_t
*atom
);
450 * Possible events for a change (notification).
452 * @see lldpctl_watch_callback
455 lldpctl_c_deleted
, /**< The neighbor has been deleted */
456 lldpctl_c_updated
, /**< The neighbor has been updated */
457 lldpctl_c_added
, /**< This is a new neighbor */
461 * Callback function invoked when a change is detected.
463 * @param conn Connection with lldpd. Should not be used.
464 * @param type Type of change detected.
465 * @param interface Physical interface on which the change has happened.
466 * @param neighbor Changed neighbor.
467 * @param data Data provided when registering the callback.
469 * The provided interface and neighbor atoms are stolen by the callback: their
470 * reference count are decremented when the callback ends. If you want to keep a
471 * reference to it, be sure to increment the reference count in the callback.
473 * @warning The provided connection should not be used at all. Do not use @c
474 * lldpctl_atom_set_*() functions on @c interface or @c neighbor either. If you
475 * do, you will get a @c LLDPCTL_ERR_INVALID_STATE error.
477 * @see lldpctl_watch_callback
479 typedef void (*lldpctl_change_callback
)(lldpctl_conn_t
*conn
,
480 lldpctl_change_t type
,
481 lldpctl_atom_t
*interface
,
482 lldpctl_atom_t
*neighbor
,
486 * Register a callback to be called on changes.
488 * @param conn Connection with lldpd.
489 * @param cb Replace the current callback with the provided one.
490 * @param data Data that will be passed to the callback.
491 * @return 0 in case of success or -1 in case of errors.
493 * This function will register the necessity to push neighbor changes to lldpd
494 * and therefore will issue IO operations. The error code could then be @c
495 * LLDPCTL_ERR_WOULDBLOCK.
497 * @warning Once a callback is registered, the connection shouldn't be used for
498 * anything else than receiving notifications. If you do, you will get a @c
499 * LLDPCTL_ERR_INVALID_STATE error.
501 int lldpctl_watch_callback(lldpctl_conn_t
*conn
,
502 lldpctl_change_callback cb
,
506 * Wait for the next change.
508 * @param conn Connection with lldpd.
509 * @return 0 on success or a negative integer in case of error.
511 * This function will return once a change has been detected. It is only useful
512 * as a main loop when using the builtin blocking IO mechanism.
514 int lldpctl_watch(lldpctl_conn_t
*conn
);
517 * @defgroup liblldpctl_atom_get_special Retrieving atoms from lldpd
519 * Special access functions.
521 * Most information can be retrieved through @ref lldpctl_atom_get(), @ref
522 * lldpctl_atom_get_int(), @ref lldpctl_atom_get_str() or @ref
523 * lldpctl_atom_get_buffer() but some information can only be retrieved through
524 * special functions because IO operation is needed (and also, for some of them,
525 * because we don't have an atom yet).
531 * Retrieve global configuration of lldpd daemon.
533 * @param conn Connection with lldpd.
534 * @return The global configuration or @c NULL if an error happened.
536 * This function will make IO with the daemon to get the
537 * configuration. Depending on the IO model, information may not be available
538 * right now and the function should be called again later. If @c NULL is
539 * returned, check the last error. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again
542 lldpctl_atom_t
*lldpctl_get_configuration(lldpctl_conn_t
*conn
);
545 * Retrieve the list of available interfaces.
547 * @param conn Previously allocated handler to a connection to lldpd.
548 * @return The list of available ports or @c NULL if an error happened.
550 * This function will make IO with the daemon to get the list of
551 * ports. Depending on the IO model, information may not be available right now
552 * and the function should be called again later. If @c NULL is returned, check
553 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
554 * (when more data is available).
556 * The list of available ports can be iterated with @ref lldpctl_atom_foreach().
558 lldpctl_atom_t
*lldpctl_get_interfaces(lldpctl_conn_t
*conn
);
561 * Retrieve the information related to the local chassis.
563 * @param conn Previously allocated handler to a connection to lldpd.
564 * @return Atom related to the local chassis which may be used in subsequent functions.
566 * This function may have to do IO to get the information related to the local
567 * chassis. Depending on the IO mode, information may not be available right now
568 * and the function should be called again later. If @c NULL is returned, check
569 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
570 * (when more data is available).
572 lldpctl_atom_t
*lldpctl_get_local_chassis(lldpctl_conn_t
*conn
);
575 * Retrieve the information related to a given interface.
577 * @param port The port we want to retrieve information from. This port is an
578 * atom retrieved from an interation on @c lldpctl_get_interfaces().
579 * @return Atom related to this port which may be used in subsequent functions.
581 * This function may have to do IO to get the information related to the given
582 * port. Depending on the IO mode, information may not be available right now
583 * and the function should be called again later. If @c NULL is returned, check
584 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
585 * (when more data is available).
587 lldpctl_atom_t
*lldpctl_get_port(lldpctl_atom_t
*port
);
590 * Retrieve the default port information.
592 * This port contains default settings whenever a new port needs to be created.
594 * @param conn Previously allocated handler to a connection to lldpd.
595 * @return Atom of the default port which may be used in subsequent functions.
597 * This function may have to do IO to get the information related to the given
598 * port. Depending on the IO mode, information may not be available right now
599 * and the function should be called again later. If @c NULL is returned, check
600 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
601 * (when more data is available).
603 lldpctl_atom_t
*lldpctl_get_default_port(lldpctl_conn_t
*conn
);
608 * Piece of information that can be retrieved from/written to an atom.
610 * Each piece of information can potentially be retrieved as an atom (A), a
611 * string (S), a buffer (B) or an integer (I). Additionaly, when an information
612 * can be retrieved as an atom, it is usually iterable (L). When an atom can be
613 * retrieved as a string and as an additional type, the string is expected to be
614 * formatted. For example, the MAC address of a local port can be retrieved as a
615 * buffer and a string. As a string, you'll get something like
616 * "00:11:22:33:44:55". Also, all values that can be get as an integer or a
617 * buffer can be get as a string too. There is no special formatting in this
618 * case. "(BS)" means that the string get a special appropriate format.
620 * The name of a key is an indication on the type of atom that information can
621 * be extracted from. For example, @c lldpctl_k_med_policy_type can be extracted
622 * from an atom you got by iterating on @c lldpctl_k_port_med_policies. On the
623 * other hand, @c lldpctl_k_port_descr and @c lldpctl_k_chassis can be retrieved
624 * from an atom retrieved either by iterating @c lldpctl_k_port_neighbors or
625 * with @c lldpctl_get_port().
627 * Some values may be written. They are marked with (W). Such a change may or
628 * may not be transmitted immediatly. If they are not transmitted immediatly,
629 * this means that the resulting atom should be written to another atom. For
630 * example, when writting @c lldpctl_k_med_policy_tagged, you need to write the
631 * resulting atom to @c lldpctl_k_port_med_policies. If the change is
632 * transmitted immediatly, you need to check the error status of the connection
633 * to know if it has been transmitted correctly. Notably, if you get @c
634 * LLDPCTL_ERR_WOULDBLOCK, you need to try again later. Usually, changes are
635 * transmitted immediatly. The exception are changes that need to be grouped to
636 * be consistent, like a LLDP MED location. When a change is transmitted
637 * immediatly, it is marked with (O). @c lldpctl_atom_set_str() may accept a @c
638 * NULL value. This case is marked with (N) and usually reset the item to the
639 * default value or no value.
641 * Some values may also be created. They are flagged with (C). This only applies
642 * to elements that can be iterated (L) and written (W). The element created
643 * still needs to be appended to the list by being written to it. The creation
644 * is done with @c lldpctl_atom_create().
646 * An atom marked with (S) can be retrieved as a string only. It cannot be
647 * written. An atom marked with (IS) can be retrieved as an integer and features
648 * an appropriate representation as a string (usually, the name of a constant)
649 * which is more meaningful than just the integer. An atom marked as (I) can be
650 * retrieved as an integer and as a string. In the later case, this is just a
651 * string representation of the integer. An atom marked with (AL) can be
652 * retrieved as an atom only and can be iterated over. This is usually a list of
653 * things. An atom marked (I,W) can be read as an integer or a string and can be
654 * written as an integer. The change would not be commited until the atom is
655 * written to the nearest atom supporting (A,WO) operation (eventually with an
656 * indirection, i.e first write to a (A,W), then to a (A,WO)).
659 lldpctl_k_config_tx_interval
, /**< `(I,WO)` Transmit interval. When set to -1, it is meant to transmit now. */
660 lldpctl_k_config_receiveonly
, /**< `(I)` Receive only mode */
661 lldpctl_k_config_mgmt_pattern
, /**< `(S,WON)` Pattern to choose the management address */
662 lldpctl_k_config_iface_pattern
, /**< `(S,WON)` Pattern of enabled interfaces */
663 lldpctl_k_config_cid_pattern
, /**< `(S)` Interface pattern to choose the chassis ID */
664 lldpctl_k_config_description
, /**< `(S,WON)` Chassis description overridden */
665 lldpctl_k_config_platform
, /**< `(S,WON)` Platform description overridden (CDP) */
666 lldpctl_k_config_hostname
, /**< `(S,WON)` System name overridden */
667 lldpctl_k_config_advertise_version
, /**< `(I)` Advertise version */
668 lldpctl_k_config_lldpmed_noinventory
, /**< `(I)` Disable LLDP-MED inventory */
669 lldpctl_k_config_paused
, /**< `(I,WO)` lldpd is paused */
670 lldpctl_k_config_fast_start_enabled
, /**< `(I,WO)` Is fast start enabled */
671 lldpctl_k_config_fast_start_interval
, /**< `(I,WO)` Start fast transmit interval */
672 lldpctl_k_config_ifdescr_update
, /**< `(I,WO)` Enable or disable setting interface description */
673 lldpctl_k_config_iface_promisc
, /**< `(I,WO)` Enable or disable promiscuous mode on interfaces */
674 lldpctl_k_config_chassis_cap_advertise
, /**< `(I,WO)` Enable or disable chassis capabilities advertisement */
675 lldpctl_k_config_chassis_mgmt_advertise
, /**< `(I,WO)` Enable or disable management addresses advertisement */
676 lldpctl_k_config_cid_string
, /**< `(S,WON)` User defined string for the chassis ID */
677 lldpctl_k_config_perm_iface_pattern
, /**< `(S,WON)` Pattern of permanent interfaces */
678 lldpctl_k_config_tx_interval_ms
, /**< `(I,WO)` Transmit interval in milliseconds. Set to -1 to transmit now. */
680 lldpctl_k_interface_name
= 1000, /**< `(S)` The interface name. */
682 lldpctl_k_port_name
= 1100, /**< `(S)` The port name. Only works for a local port. */
683 lldpctl_k_port_index
, /**< `(I)` The port index. Only works for a local port. */
685 * `(AL)` The list of known neighbors for this port.
687 * A neighbor is in fact a remote port.
689 lldpctl_k_port_neighbors
= 1200,
690 lldpctl_k_port_protocol
, /**< `(IS)` The protocol that was used to retrieve this information. */
691 lldpctl_k_port_age
, /**< `(I)` Age of information, seconds from epoch. */
692 lldpctl_k_port_id_subtype
, /**< `(IS)` The subtype ID of this port. */
693 lldpctl_k_port_id
, /**< `(BS,WO)` The ID of this port. */
694 lldpctl_k_port_descr
, /**< `(S,WO)` The description of this port. */
695 lldpctl_k_port_hidden
, /**< `(I)` Is this port hidden (or should it be displayed?)? */
696 lldpctl_k_port_status
, /**< `(IS,WO)` Operational status of this (local) port */
697 lldpctl_k_port_chassis
, /**< `(A)` Chassis associated to the port */
698 lldpctl_k_port_ttl
, /**< `(I)` TTL for port, 0 if info is attached to chassis */
700 lldpctl_k_port_dot3_mfs
= 1300, /**< `(I)` MFS */
701 lldpctl_k_port_dot3_aggregid
, /**< `(I)` Port aggregation ID */
702 lldpctl_k_port_dot3_autoneg_support
, /**< `(I)` Autonegotiation support. */
703 lldpctl_k_port_dot3_autoneg_enabled
, /**< `(I)` Autonegotiation enabled. */
704 lldpctl_k_port_dot3_autoneg_advertised
, /**< `(I)` Advertised protocols. See `LLDP_DOT3_LINK_AUTONEG_*` */
705 lldpctl_k_port_dot3_mautype
, /**< `(IS)` Current MAU type. See `LLDP_DOT3_MAU_*` */
707 lldpctl_k_port_dot3_power
= 1400, /**< `(A,WO)` Dot3 power related stuff. */
708 lldpctl_k_dot3_power_devicetype
, /**< `(IS,W)` Device type. See `LLDP_DOT3_POWER_PSE/PD` */
709 lldpctl_k_dot3_power_supported
, /**< `(I,W)` Is MDI power supported. */
710 lldpctl_k_dot3_power_enabled
, /**< `(I,W)` Is MDI power enabled. */
711 lldpctl_k_dot3_power_paircontrol
, /**< `(I,W)` Pair-control enabled? */
712 lldpctl_k_dot3_power_pairs
, /**< `(IS,W)` See `LLDP_DOT3_POWERPAIRS_*` */
713 lldpctl_k_dot3_power_class
, /**< `(IS,W)` Power class. */
714 lldpctl_k_dot3_power_type
, /**< `(I,W)` 802.3AT power type */
715 lldpctl_k_dot3_power_source
, /**< `(IS,W)` 802.3AT power source */
716 lldpctl_k_dot3_power_priority
, /**< `(IS,W)` 802.3AT power priority */
717 lldpctl_k_dot3_power_allocated
, /**< `(I,W)` 802.3AT power allocated */
718 lldpctl_k_dot3_power_requested
, /**< `(I,W)` 802.3AT power requested */
720 /* 802.3bt additions */
721 lldpctl_k_dot3_power_pd_4pid
, /**< `(IS,W)` 802.3BT both modes supported? */
722 lldpctl_k_dot3_power_requested_a
, /**< `(I,W)` 802.3BT power value requested for A */
723 lldpctl_k_dot3_power_requested_b
, /**< `(I,W)` 802.3BT power value requested for B */
724 lldpctl_k_dot3_power_allocated_a
, /**< `(I,W)` 802.3BT power value allocated for A */
725 lldpctl_k_dot3_power_allocated_b
, /**< `(I,W)` 802.3BT power value allocated for B */
726 lldpctl_k_dot3_power_pse_status
, /**< `(IS,W)` 802.3BT PSE powering status */
727 lldpctl_k_dot3_power_pd_status
, /**< `(IS,W)` 802.3BT PD powering status */
728 lldpctl_k_dot3_power_pse_pairs_ext
, /**< `(IS,W)` 802.3BT PSE power pairs */
729 lldpctl_k_dot3_power_class_a
, /**< `(IS,W)` 802.3BT power class for A */
730 lldpctl_k_dot3_power_class_b
, /**< `(IS,W)` 802.3BT power class for B */
731 lldpctl_k_dot3_power_class_ext
, /**< `(IS,W)` 802.3BT power class */
732 lldpctl_k_dot3_power_type_ext
, /**< `(IS,W)` 802.3BT power type */
733 lldpctl_k_dot3_power_pd_load
, /**< `(IS,W)` 802.3BT dualsig isolated? */
734 lldpctl_k_dot3_power_pse_max
, /**< `(I,W)` 802.3BT maximum available power */
736 lldpctl_k_port_vlan_pvid
= 1500, /**< `(I)` Primary VLAN ID */
737 lldpctl_k_port_vlans
, /**< `(AL)` List of VLAN */
738 lldpctl_k_vlan_id
, /**< `(I)` VLAN ID */
739 lldpctl_k_vlan_name
, /**< `(S)` VLAN name */
741 lldpctl_k_port_ppvids
= 1600, /**< `(AL)` List of PPVIDs */
742 lldpctl_k_ppvid_status
, /**< `(I)` Status of PPVID (see `LLDP_PPVID_CAP_*`) */
743 lldpctl_k_ppvid_id
, /**< `(I)` ID of PPVID */
745 lldpctl_k_port_pis
= 1700, /**< `(AL)` List of PIDs */
746 lldpctl_k_pi_id
, /**< `(B)` PID value */
748 lldpctl_k_chassis_index
= 1800, /**< `(I)` The chassis index. */
749 lldpctl_k_chassis_id_subtype
, /**< `(IS)` The subtype ID of this chassis. */
750 lldpctl_k_chassis_id
, /**< `(BS)` The ID of this chassis. */
751 lldpctl_k_chassis_name
, /**< `(S)` The name of this chassis. */
752 lldpctl_k_chassis_descr
, /**< `(S)` The description of this chassis. */
753 lldpctl_k_chassis_cap_available
, /**< `(I)` Available capabalities (see `LLDP_CAP_*`) */
754 lldpctl_k_chassis_cap_enabled
, /**< `(I)` Enabled capabilities (see `LLDP_CAP_*`) */
755 lldpctl_k_chassis_mgmt
, /**< `(AL)` List of management addresses */
756 lldpctl_k_chassis_ttl
, /**< Deprecated */
758 lldpctl_k_chassis_med_type
= 1900, /**< `(IS)` Chassis MED type. See `LLDP_MED_CLASS_*` */
759 lldpctl_k_chassis_med_cap
, /**< `(I)` Available MED capabilitied. See `LLDP_MED_CAP_*` */
760 lldpctl_k_chassis_med_inventory_hw
, /**< `(S)` LLDP MED inventory "Hardware Revision" */
761 lldpctl_k_chassis_med_inventory_sw
, /**< `(S)` LLDP MED inventory "Software Revision" */
762 lldpctl_k_chassis_med_inventory_fw
, /**< `(S)` LLDP MED inventory "Firmware Revision" */
763 lldpctl_k_chassis_med_inventory_sn
, /**< `(S)` LLDP MED inventory "Serial Number" */
764 lldpctl_k_chassis_med_inventory_manuf
, /**< `(S)` LLDP MED inventory "Manufacturer" */
765 lldpctl_k_chassis_med_inventory_model
, /**< `(S)` LLDP MED inventory "Model" */
766 lldpctl_k_chassis_med_inventory_asset
, /**< `(S)` LLDP MED inventory "Asset ID" */
768 lldpctl_k_port_med_policies
= 2000, /**< `(AL,WO)` MED policies attached to a port. */
769 lldpctl_k_med_policy_type
, /**< `(IS,W)` MED policy app type. See `LLDP_MED_APPTYPE_*`. 0 if a policy is not defined. */
770 lldpctl_k_med_policy_unknown
, /**< `(I,W)` Is MED policy defined? */
771 lldpctl_k_med_policy_tagged
, /**< `(I,W)` MED policy tagging */
772 lldpctl_k_med_policy_vid
, /**< `(I,W)` MED policy VID */
773 lldpctl_k_med_policy_priority
, /**< `(I,W)` MED policy priority */
774 lldpctl_k_med_policy_dscp
, /**< `(I,W)` MED policy DSCP */
776 lldpctl_k_port_med_locations
= 2100, /**< `(AL,WO)` MED locations attached to a port. */
777 lldpctl_k_med_location_format
, /**< `(IS,W)` MED location format. See
778 * `LLDP_MED_LOCFORMAT_*`. 0 if this
779 * location is not defined. When written,
780 * the following fields will be zeroed
782 lldpctl_k_med_location_geoid
, /**< `(IS,W)` MED geoid. See `LLDP_MED_LOCATION_GEOID_*`. Only if format is COORD. */
783 lldpctl_k_med_location_latitude
, /**< `(S,W)` MED latitude. Only if format is COORD. */
784 lldpctl_k_med_location_longitude
, /**< `(S,W)` MED longitude. Only if format is COORD. */
785 lldpctl_k_med_location_altitude
, /**< `(S,W)` MED altitude. Only if format is COORD. */
786 lldpctl_k_med_location_altitude_unit
, /**< `(S,W)` MED altitude unit. See `LLDP_MED_LOCATION_ALTITUDE_UNIT_*`.
787 * Only if format is COORD. */
789 lldpctl_k_med_location_country
= 2200, /**< `(S,W)` MED country. Only if format is CIVIC. */
790 lldpctl_k_med_location_elin
, /**< `(S,W)` MED ELIN. Only if format is ELIN. */
792 lldpctl_k_med_location_ca_elements
= 2300, /**< `(AL,WC)` MED civic address elements. Only if format is CIVIC */
793 lldpctl_k_med_civicaddress_type
, /**< `(IS,W)` MED civic address type. */
794 lldpctl_k_med_civicaddress_value
, /**< `(S,W)` MED civic address value. */
796 lldpctl_k_port_med_power
= 2400, /**< `(A,WO)` LLDP-MED power related stuff. */
797 lldpctl_k_med_power_type
, /**< `(IS,W)` LLDP MED power device type. See `LLDP_MED_POW_TYPE_*` */
798 lldpctl_k_med_power_source
, /**< `(IS,W)` LLDP MED power source. See `LLDP_MED_POW_SOURCE_*` */
799 lldpctl_k_med_power_priority
, /**< `(IS,W)` LLDP MED power priority. See `LLDP_MED_POW_PRIO_*` */
800 lldpctl_k_med_power_val
, /**< `(I,W)` LLDP MED power value */
802 lldpctl_k_mgmt_ip
= 3000, /**< `(S)` IP address */
803 lldpctl_k_mgmt_iface_index
= 30001, /**< `(I)` Interface index */
805 lldpctl_k_tx_cnt
= 4000, /**< `(I)` tx cnt. Only works for a local port. */
806 lldpctl_k_rx_cnt
, /**< `(I)` rx cnt. Only works for a local port. */
807 lldpctl_k_rx_discarded_cnt
, /**< `(I)` discarded cnt. Only works for a local port. */
808 lldpctl_k_rx_unrecognized_cnt
, /**< `(I)` unrecognized cnt. Only works for a local port. */
809 lldpctl_k_ageout_cnt
, /**< `(I)` ageout cnt. Only works for a local port. */
810 lldpctl_k_insert_cnt
, /**< `(I)` insert cnt. Only works for a local port. */
811 lldpctl_k_delete_cnt
, /**< `(I)` delete cnt. Only works for a local port. */
812 lldpctl_k_config_tx_hold
, /**< `(I,WO)` Transmit hold interval. */
813 lldpctl_k_config_bond_slave_src_mac_type
, /**< `(I,WO)` bond slave src mac type. */
814 lldpctl_k_config_lldp_portid_type
, /**< `(I,WO)` LLDP PortID TLV Subtype */
815 lldpctl_k_config_lldp_agent_type
, /**< `(I,WO)` LLDP agent type */
816 lldpctl_k_config_max_neighbors
, /**< `(I,WO)`Maximum number of neighbors per port. */
818 lldpctl_k_custom_tlvs
= 5000, /**< `(AL)` custom TLVs */
819 lldpctl_k_custom_tlvs_clear
, /** `(I,WO)` clear list of custom TLVs */
820 lldpctl_k_custom_tlv
, /** `(AL,WO)` custom TLV **/
821 lldpctl_k_custom_tlv_oui
, /**< `(I,WO)` custom TLV Organizationally Unique Identifier. Default is 0 (3 bytes) */
822 lldpctl_k_custom_tlv_oui_subtype
, /**< `(I,WO)` custom TLV subtype. Default is 0 (1 byte) */
823 lldpctl_k_custom_tlv_oui_info_string
, /**< `(I,WO)` custom TLV Organizationally Unique Identifier Information String (up to 507 bytes) */
824 lldpctl_k_custom_tlv_op
, /**< `(I,WO)` custom TLV operation */
829 * Get a map related to a key.
831 * Many keys expect to be written with a discrete number of values. Take for
832 * example @c lldpctl_k_med_civicaddress_type, it can take any integer between 1
833 * and 128. However, each integer can be named. It can be useful for an
834 * application to get a translation between the integer that can be provided and
835 * a more human-readable name. This function allows to retrieve the
838 * @param key The piece of information we want a map from.
839 * @return The map or @c NULL if no map is available.
841 * The returned map has its last element set to 0. It is also expected that the
842 * string value can be used with a set operation. It will be translated to the
845 lldpctl_map_t
*lldpctl_key_get_map(lldpctl_key_t key
);
848 * Retrieve a bit of information as an atom.
850 * @param atom The atom we want to query.
851 * @param key The information we want from the atom.
852 * @return The atom representing the requested information or @c NULL if the
853 * information is not available.
855 * Not every value of @c info will be available as an atom. See the
856 * documentation of @c lldpctl_key_t for values accepting to be extracted as an
857 * atom. Usually, this is only iterable values or values representing a complex
860 * The provided atom is not a _borrowed_ reference. You need to decrement the
861 * reference count when you don't need it anymore.
863 * As a convenience, this function will return @c NULL if the first parameter is
864 * @c NULL and no error will be raised.
866 lldpctl_atom_t
*lldpctl_atom_get(lldpctl_atom_t
*atom
, lldpctl_key_t key
);
869 * Set a bit of information with an atom.
871 * @param atom The atom we want to write to.
872 * @param key The key information we want to write.
873 * @param value The value of the information we want to write.
874 * @return The updated atom with the appropriate information.
876 * This function will return @c NULL in case of error. If the last error is @c
877 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
878 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
881 lldpctl_atom_t
*lldpctl_atom_set(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
882 lldpctl_atom_t
*value
);
885 * Retrieve a bit of information as a null-terminated string.
887 * @param atom The atom we want to query.
888 * @param key The information we want from the atom.
889 * @return The requested string or @c NULL if the information is not available.
891 * Not every value of @c info will be available as a string. See the
892 * documentation of @c lldpctl_key_t for values accepting to be extracted as a
893 * string. Usually, only piece of information stored as string are available in
894 * this form but sometimes, you can get a nice formatted string instead of an
895 * integer with this function.
897 * As a convenience, this function will return @c NULL if the first parameter is
898 * @c NULL and no error will be raised.
900 * The provided string may live inside the atom providing it. If you need it
901 * longer, duplicate it.
903 const char *lldpctl_atom_get_str(lldpctl_atom_t
*atom
, lldpctl_key_t key
);
906 * Set a bit of information using a null-terminated string.
908 * @param atom The atom we want to write to.
909 * @param key The key information we want to write.
910 * @param value The value of the information we want to write.
911 * @return The updated atom with the appropriate information.
913 * This function will return @c NULL in case of error. If the last error is @c
914 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
915 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
918 lldpctl_atom_t
*lldpctl_atom_set_str(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
922 * Retrieve a bit of information as a buffer.
924 * @param atom The atom we want to query.
925 * @param key The information we want from the atom.
926 * @param[out] length The size of the returned buffer.
927 * @return The requested buffer or @c NULL if the information is not available.
929 * Not every value of @c info will be available as a buffer. See the
930 * documentation of @c lldpctl_key_t for values accepting to be extracted as a
931 * string. Usually, only piece of information stored as buffer are available in
934 * As a convenience, this function will return @c NULL if the first parameter is
935 * @c NULL and no error will be raised. If this function returns @c NULL, the
936 * third parameter is set to 0.
938 * The provided buffer may live inside the atom providing it. If you need it
939 * longer, duplicate it.
941 const uint8_t *lldpctl_atom_get_buffer(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
945 * Set a bit of information using a buffer
947 * @param atom The atom we want to write to.
948 * @param key The key information we want to write.
949 * @param value The value of the information we want to write.
950 * @param length The length of the provided buffer.
951 * @return The updated atom with the appropriate information.
953 * This function will return @c NULL in case of error. If the last error is @c
954 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
955 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
958 lldpctl_atom_t
*lldpctl_atom_set_buffer(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
959 const uint8_t *value
, size_t length
);
962 * Retrieve a bit of information as an integer.
964 * @param atom The atom we want to query.
965 * @param key The information we want from the atom.
966 * @return The requested integer or -1 if the information is not available
968 * Not every value of @c info will be available as an integer. See the
969 * documentation of @c lldpctl_key_t for values accepting to be extracted as a
970 * string. Usually, only piece of information stored as an integer are available
973 * Only @c lldpctl_last_error() can tell if the returned value is an error or
974 * not. However, most values extracted from lldpd cannot be negative.
976 long int lldpctl_atom_get_int(lldpctl_atom_t
*atom
, lldpctl_key_t key
);
979 * Set a bit of information using an integer
981 * @param atom The atom we want to write to.
982 * @param key The key information we want to write.
983 * @param value The value of the information we want to write.
984 * @return The updated atom with the appropriate information.
986 * This function will return @c NULL in case of error. If the last error is @c
987 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
988 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
991 lldpctl_atom_t
*lldpctl_atom_set_int(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
995 * @defgroup liblldpctl_atom_iter Iterating over atoms
997 * Iterate over atoms (lists).
1002 * Iterator over an iterable atom (a list of ports, a list of VLAN, ...). When
1003 * an atom is a list, it can be iterated over to extract the appropriate values.
1005 * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(), lldpctl_atom_iter_value()
1007 typedef struct lldpctl_atom_iter_t lldpctl_atom_iter_t
;
1010 * Return an iterator over a given atom.
1012 * If an atom is iterable (if it is a list, like a list of ports, a list of
1013 * VLAN, a list of neighbors), it is possible to iterate over it. First use this
1014 * function to get an iterator then use @c lldpctl_atom_iter_next() to get the
1015 * next item and @c lldpctl_atom_iter_value() to the actuel item.
1017 * @param atom The atom we want to create an iterator from.
1018 * @return The iterator or @c NULL if an error happened or if the atom is empty
1019 * (check with @c lldpctl_last_error()).
1021 * As a convenience, if the provided atom is @c NULL, this function will return
1022 * @c NULL and no error will be raised.
1024 lldpctl_atom_iter_t
*lldpctl_atom_iter(lldpctl_atom_t
*atom
);
1027 * Return the next element of an iterator.
1029 * @param atom The atom we are currently iterating.
1030 * @param iter The iterator we want the next element from.
1031 * @return An iterator starting on the next element or @c NULL if we have no
1034 * @see lldpctl_atom_iter(), lldpctl_atom_iter_value().
1036 * As a convenience, if the provided atom is @c NULL, this function will return
1037 * @c NULL and no error will be raised.
1039 lldpctl_atom_iter_t
*lldpctl_atom_iter_next(lldpctl_atom_t
*atom
, lldpctl_atom_iter_t
*iter
);
1042 * Return the value of an iterator.
1044 * @param atom The atom we are currently iterating.
1045 * @param iter The iterator we want the next element from.
1046 * @return The atom currently associated with the iterator.
1048 * @see lldpctl_atom_iter(), lldpctl_atom_iter_next().
1050 lldpctl_atom_t
*lldpctl_atom_iter_value(lldpctl_atom_t
*atom
, lldpctl_atom_iter_t
*iter
);
1053 * Convenience macro to iter over every value of an iterable object.
1055 * @param atom The atom you want to iterate on.
1056 * @param value Atom name that will be used to contain each value.
1058 * This macro behaves as a for loop. Moreover, at the end of each iteration, the
1059 * reference count of the provided value is decremented. If you need to use it
1060 * outside of the loop, you need to increment it.
1062 #define lldpctl_atom_foreach(atom, value) \
1063 for (lldpctl_atom_iter_t *iter##_LINE_ = lldpctl_atom_iter(atom); \
1064 iter##_LINE_ && (value = lldpctl_atom_iter_value(atom, iter##_LINE_)); \
1065 iter##_LINE_ = lldpctl_atom_iter_next(atom, iter##_LINE_), \
1066 lldpctl_atom_dec_ref(value))
1069 * Create a new value for an iterable element.
1071 * The value is meant to be appended using @c lldpctl_atom_set(). Currently,
1072 * there is no way to delete an element from a list. It is also not advisable to
1073 * use getters on a newly created object until it is fully initialized. If its
1074 * internal representation is using a buffer, it may not be initialized until
1077 * @param atom The atom we want to create a new element for.
1078 * @return The new element.
1080 lldpctl_atom_t
*lldpctl_atom_create(lldpctl_atom_t
*atom
);