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 * @section liblldpctl Interfacing with lldpd
24 * Interfacing with a running instance of lldpd can be done through liblldpctl
34 #include <sys/types.h>
37 * Get default transport name.
39 * Currently, this is the default location of the Unix socket.
41 const char* lldpctl_get_default_transport(void);
46 * By default, liblldpctl will log to stderr. The following function will
47 * register another callback for this purpose. Messages logged through this
48 * callback may be cryptic. They are targeted for the developer. Message for end
49 * users should rely on return codes.
51 void lldpctl_log_callback(void (*cb
)(int severity
, const char *msg
));
55 * Structure referencing a connection with lldpd.
57 * This structure should be handled as opaque. It can be allocated
58 * with @c lldpctl_new() and the associated resources will be freed
59 * with @c lldpctl_release().
61 typedef struct lldpctl_conn_t lldpctl_conn_t
;
64 * Callback function invoked to send data to lldpd.
66 * @param lldpctl Handle to the connection to lldpd.
67 * @param data Bytes to be sent.
68 * @param length Length of provided data.
69 * @param user_data Provided user data.
70 * @return The number of bytes really sent or either @c LLDPCTL_ERR_WOULDBLOCK
71 * if no bytes can be sent without blocking or @c
72 * LLDPCTL_ERR_CALLBACK_FAILURE for other errors.
74 typedef ssize_t (*lldpctl_send_callback
)(lldpctl_conn_t
*lldpctl
,
75 const uint8_t *data
, size_t length
, void *user_data
);
78 * Callback function invoked to receive data from lldpd.
80 * @param lldpctl Handle to the connection to lldpd.
81 * @param data Buffer for receiving data
82 * @param length Maximum bytes we can receive
83 * @param user_data Provided user data.
84 * @return The number of bytes really received or either @c
85 * LLDPCTL_ERR_WOULDBLOCK if no bytes can be received without blocking,
86 * @c LLDPCTL_ERR_CALLBACK_FAILURE for other errors or @c
87 * LLDPCTL_ERR_EOF if end of file was reached.
89 typedef ssize_t (*lldpctl_recv_callback
)(lldpctl_conn_t
*lldpctl
,
90 const uint8_t *data
, size_t length
, void *user_data
);
93 * Function invoked when additional data is available from lldpd.
95 * This function should be invoked in case of asynchronous IO when new data is
96 * available from lldpd (expected or unexpected).
98 * @param lldpctl Handle to the connection to lldpd.
99 * @param data Data received from lldpd.
100 * @param length Length of data received.
101 * @return The number of bytes available or a negative integer if an error has
102 * occurred. 0 is not an error. It usually means that a notification has
105 ssize_t
lldpctl_recv(lldpctl_conn_t
*lldpctl
, const uint8_t *data
, size_t length
);
108 * Function invoked when there is an opportunity to send data to lldpd.
110 * This function should be invoked in case of asynchronous IO when new data can
111 * be written to lldpd.
113 * @param lldpctl Handle to the connection to lldpd.
114 * @return The number of bytes processed or a negative integer if an error has
117 ssize_t
lldpctl_send(lldpctl_conn_t
*lldpctl
);
120 * Allocate a new handler for connecting to lldpd.
122 * This library does not handle IO. They are delegated to a set of functions to
123 * allow a user to specify exactly how IO should be done. This open the
124 * possibility to query a remote lldpd through SSH for example. A user is
125 * expected to provide two functions: the first one is called when the library
126 * requests incoming data, the other one when it requests outgoing
127 * data. Moreover, the user is also expected to call the appropriate functions
128 * when data comes back or is effectively sent (in case of asynchronous IO).
130 * @param send Callback to be used when sending new data is requested.
131 * @param recv Callback to be used when receiving new data is requested.
132 * @param user_data Data to pass to callbacks.
133 * @return An handler to be used to connect to lldpd or @c NULL in
134 * case of error. In the later case, the error is probable an
135 * out of memory condition.
137 * The allocated handler can be released with @c lldpctl_release(). If the
138 * provided parameters are both @c NULL, default synchronous callbacks will be
141 lldpctl_conn_t
*lldpctl_new(lldpctl_send_callback send
,
142 lldpctl_recv_callback recv
, void *user_data
);
145 * Release resources associated with a connection to lldpd.
147 * @param lldpctl Previously allocated handler to a connection to lldpd.
148 * @return 0 on success or a negative integer
152 int lldpctl_release(lldpctl_conn_t
*lldpctl
);
157 * Possible error codes for functions that return negative integers on
158 * this purpose or for @c lldpctl_last_error().
162 * No error has happened (yet).
164 LLDPCTL_NO_ERROR
= 0,
166 * A IO related operation would block if performed.
168 LLDPCTL_ERR_WOULDBLOCK
= -501,
170 * A IO related operation has reached a end of file condition.
172 LLDPCTL_ERR_EOF
= -502,
174 * The requested information does not exist. For example, when
175 * requesting an inexistant information from an atom.
177 LLDPCTL_ERR_NOT_EXIST
= -503,
179 * Cannot connect to the lldpd daemon. This error only happens with
180 * default synchronous handlers.
182 LLDPCTL_ERR_CANNOT_CONNECT
= -504,
184 * Atom is of incorrect type for the requested operation.
186 LLDPCTL_ERR_INCORRECT_ATOM_TYPE
= -505,
188 * An error occurred during serialization of message.
190 LLDPCTL_ERR_SERIALIZATION
= -506,
192 * The requested operation cannot be performed because we have another
193 * operation already running.
195 LLDPCTL_ERR_INVALID_STATE
= -507,
197 * The provided atom cannot be iterated.
199 LLDPCTL_ERR_CANNOT_ITERATE
= -508,
201 * The provided value is invalid.
203 LLDPCTL_ERR_BAD_VALUE
= -509,
205 * No new element can be created for this element.
207 LLDPCTL_ERR_CANNOT_CREATE
= -510,
209 * The library is under unexpected conditions and cannot process
210 * any further data reliably.
212 LLDPCTL_ERR_FATAL
= -900,
214 * Out of memory condition. Things may get havoc here but we
215 * should be able to recover.
217 LLDPCTL_ERR_NOMEM
= -901,
219 * An error occurred in a user provided callback.
221 LLDPCTL_ERR_CALLBACK_FAILURE
= -902
225 * Describe a provided error code.
227 * @param error Error code to be described.
228 * @return Statically allocated string describing the error.
230 const char *lldpctl_strerror(lldpctl_error_t error
);
233 * Get the last error associated to a connection to lldpd.
235 * @param lldpctl Previously allocated handler to a connection to lldpd.
236 * @return 0 if no error is currently registered. A negative integer
239 * For functions returning int, this function will return the same
240 * error number. For functions returning something else, you can use
241 * this function to get the appropriate error number.
243 lldpctl_error_t
lldpctl_last_error(lldpctl_conn_t
*lldpctl
);
246 * Describe the last error associate to a connection.
248 * @param conn Previously allocated handler to a connection to lldpd.
249 * @return Statically allocated string describing the error
251 #define lldpctl_last_strerror(conn) lldpctl_strerror(lldpctl_last_error(conn))
256 * Structure representing an element (chassis, port, VLAN, ...)
258 * This is an opaque structure that can be passed along some functions to
259 * transmit chassis, ports, VLAN and other information related to LLDP. Most
260 * information are extracted using @c lldpctl_atom_get(), @c
261 * lldpctl_atom_get_str(), @c lldpctl_atom_get_buffer() or @c
262 * lldpctl_atom_get_int(), unless some IO with lldpd is needed to retrieve the
263 * requested information. In this case, there exists an appropriate function to
264 * convert the "deferred" atom into a normal one (like @c lldpctl_get_port()).
266 * An atom is reference counted. Unless documented otherwise, a function
267 * returning an atom will return a new reference that should be decremented if
270 * @see lldpctl_atom_inc_ref(), lldpctl_atom_dec_ref().
272 typedef struct lldpctl_atom_t lldpctl_atom_t
;
275 * Return the reference to connection with lldpd.
277 * @param atom The atom we want reference from.
278 * @return The reference to the connection to lldpd.
280 * Each atom contains an internal reference to the corresponding connection to
281 * lldpd. Use this function to get it.
283 lldpctl_conn_t
*lldpctl_atom_get_connection(lldpctl_atom_t
*atom
);
286 * Increment reference count for an atom.
288 * @param atom Atom we which to increase reference count.
290 void lldpctl_atom_inc_ref(lldpctl_atom_t
*atom
);
293 * Decrement reference count for an atom.
295 * @param atom Atom we want to decrease reference count. Can be @c NULL. In this
296 * case, nothing happens.
298 * When the reference count becomes 0, the atom is freed.
300 void lldpctl_atom_dec_ref(lldpctl_atom_t
*atom
);
303 * Possible events for a change.
306 lldpctl_c_deleted
, /**< The neighbor has been deleted */
307 lldpctl_c_updated
, /**< The neighbor has been updated */
308 lldpctl_c_added
, /**< This is a new neighbor */
312 * Callback function invoked when a change is detected.
314 * @param conn Connection with lldpd.
315 * @param type Type of change detected.
316 * @param interface Physical interface on which the change has happened.
317 * @param neighbor Changed neighbor.
318 * @param data Data provided when registering the callback.
320 * The provided interface and neighbor atoms will have their reference count
321 * decremented when the callback ends. If you want to keep a reference to it, be
322 * sure to increment the reference count in the callback.
324 typedef void (*lldpctl_change_callback
)(lldpctl_conn_t
*conn
,
325 lldpctl_change_t type
,
326 lldpctl_atom_t
*interface
,
327 lldpctl_atom_t
*neighbor
,
331 * Register a callback to be called on changes.
333 * @param conn Connection with lldpd.
334 * @param cb Replace the current callback with the provided one.
335 * @param data Data that will be passed to the callback.
336 * @return 0 in case of success or -1 in case of errors.
338 * This function will register the necessity to push neighbor changes to lldpd
339 * and therefore will issue IO operations. The error code could then be @c
340 * LLDPCTL_ERR_WOULDBLOCK.
342 int lldpctl_watch_callback(lldpctl_conn_t
*conn
,
343 lldpctl_change_callback cb
,
347 * Wait for the next change.
349 * @param conn Connection with lldpd.
350 * @return 0 on success or a negative integer in case of error.
352 * This function will return once a change has been detected. It is only useful
353 * as a main loop when using the builtin blocking IO mechanism.
355 int lldpctl_watch(lldpctl_conn_t
*conn
);
358 * Retrieve global configuration of lldpd daemon.
360 * @param conn Connection with lldpd.
361 * @return The global configuration or @c NULL if an error happened.
363 * This function will make IO with the daemon to get the
364 * configuration. Depending on the IO model, information may not be available
365 * right now and the function should be called again later. If @c NULL is
366 * returned, check the last error. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again
369 lldpctl_atom_t
*lldpctl_get_configuration(lldpctl_conn_t
*conn
);
372 * Retrieve the list of available interfaces.
374 * @param lldpctl Previously allocated handler to a connection to lldpd.
375 * @return The list of available ports or @c NULL if an error happened.
377 * This function will make IO with the daemon to get the list of
378 * ports. Depending on the IO model, information may not be available right now
379 * and the function should be called again later. If @c NULL is returned, check
380 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
381 * (when more data is available).
383 lldpctl_atom_t
*lldpctl_get_interfaces(lldpctl_conn_t
*lldpctl
);
386 * Retrieve the information related to a given interface.
388 * @param port The port we want to retrieve information from. This port is an
389 * atom retrieved from @c lldpctl_get_interfaces().
390 * @return Atom related to this port which may be used in subsequent functions.
392 * This functions may have to do IO to get the information related to the given
393 * port. Depending on the IO mode, information may not be available tight now
394 * and the function should be called again later. If @c NULL is returned, check
395 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
396 * (when more data is available).
398 lldpctl_atom_t
*lldpctl_get_port(lldpctl_atom_t
*port
);
401 * Piece of information that can be retrieved from/written to an atom.
403 * Each piece of information can potentially be retrieved as an atom (A), a
404 * string (S), a buffer (B) or an integer (I). Additionaly, when an information
405 * can be retrieved as an atom, it is usually iterable (L). When an atom can be
406 * retrieved as a string and as an additional type, the string is expected to be
407 * formatted. For example, the MAC address of a local port can be retrieved as a
408 * buffer and a string. As a string, you'll get something like
409 * "00:11:22:33:44:55". Also, all values that can be get as an integer or a
410 * buffer can be get as a string too. There is no special formatting in this
411 * case. "(BS)" means that the string get a special appropriate format.
413 * The name of a key is an indication on the type of atom that information can
414 * be extracted from. For example, @c lldpctl_k_med_policy_type can be extracted
415 * from an atom you got by iterating on @c lldpctl_k_port_med_policies. On the
416 * other hand, @c lldpctl_k_port_descr and @c lldpctl_k_chassis can be retrieved
417 * from an atom retrieved either by iterating @c lldpctl_k_port_neighbors or
418 * with @c lldpctl_get_port().
420 * Some values may be written. They are marked with (W). Such a change may or
421 * may not be transmitted immediatly. If they are not transmitted immediatly,
422 * this means that the resulting atom should be written to another atom. For
423 * example, when writting @c lldpctl_k_med_policy_tagged, you need to write the
424 * resulting atom to @c lldpctl_k_port_med_policies. If the change is
425 * transmitted immediatly, you need to check the error status of the connection
426 * to know if it has been transmitted correctly. Notably, if you get @c
427 * LLDPCTL_ERR_WOULDBLOCK, you need to try again later. Usually, changes are
428 * transmitted immediatly. The exception are changes that need to be grouped to
429 * be consistent, like a LLDP MED location. When a change is transmitted
430 * immediatly, it is marked with (O).
432 * Some values may also be created. They are flagged with (C). This only applies
433 * to elements that can be iterated (L) and written (W). The element created
434 * still needs to be appended to the list by being written to it. The creation
435 * is done with @c lldpctl_atom_create().
437 * An atom marked with (S) can be retrieved as a string only. It cannot be
438 * written. An atom marked with (IS) can be retrieved as an integer and features
439 * an appropriate representation as a string (usually, the name of a constant)
440 * which is more meaningful than just the integer. An atom marked as (I) can be
441 * retrieved and as a string. In the later case, this is just a string
442 * representation of the integer. An atom marked with (AL) can be retrieved as
443 * an atom only and can be iterated over. This is usually a list of things. An
444 * atom marked (I,W) can be read as an integer or a string and can be written as
445 * an integer. The change would not be commited until the atom is written to the
446 * nearest atom supporting (A,WO) operation (eventually with an indirection, i.e
447 * first write to a (A,W), then to a (A,WO)).
450 lldpctl_k_config_delay
, /* (I,WO) Transmit delay. When set to -1, it is meant to transmit now. */
451 lldpctl_k_config_receiveonly
, /* (I) Receive only mode */
452 lldpctl_k_config_mgmt_pattern
, /* (S) Pattern to choose the management address */
453 lldpctl_k_config_iface_pattern
, /* (S) Pattern of enabled interfaces */
454 lldpctl_k_config_cid_pattern
, /* (S) Interface pattern to choose the chassis ID */
455 lldpctl_k_config_description
, /* (S) Chassis description overriden */
456 lldpctl_k_config_platform
, /* (S) Platform description overriden (CDP) */
457 lldpctl_k_config_advertise_version
, /* (I) Advertise version */
458 lldpctl_k_config_lldpmed_noinventory
, /* (I) Disable LLDP-MED inventory */
460 lldpctl_k_interface_name
, /**< (S) The interface name. */
462 lldpctl_k_port_name
, /**< (S) The port name. Only works for a local port. */
463 lldpctl_k_port_index
, /**< (I) The port index. Only works for a local port. */
465 * (AL) The list of known neighbors for this port.
467 * A neighbor is in fact a remote port.
469 lldpctl_k_port_neighbors
,
470 lldpctl_k_port_protocol
, /**< (IS) The protocol that was used to retrieve this information. */
471 lldpctl_k_port_age
, /**< (I) Age of information, seconds from epoch. */
472 lldpctl_k_port_id_subtype
, /**< (IS) The subtype ID of this port. */
473 lldpctl_k_port_id
, /**< (BS) The ID of this port. */
474 lldpctl_k_port_descr
, /**< (S) The description of this port. */
475 lldpctl_k_port_hidden
, /**< (I) Is this port hidden (or should it be displayed?)? */
477 lldpctl_k_port_dot3_mfs
, /**< (I) MFS */
478 lldpctl_k_port_dot3_aggregid
, /**< (I) Port aggregation ID */
479 lldpctl_k_port_dot3_autoneg_support
, /**< (I) Autonegotiation support. */
480 lldpctl_k_port_dot3_autoneg_enabled
, /**< (I) Autonegotiation enabled. */
481 lldpctl_k_port_dot3_autoneg_advertised
, /**< (I) Advertised protocols. See LLDP_DOT3_LINK_AUTONEG_* */
482 lldpctl_k_port_dot3_mautype
, /**< (IS) Current MAU type. See LLDP_DOT3_MAU_* */
484 lldpctl_k_port_dot3_power
, /**< (A,WO) Dot3 power related stuff. */
485 lldpctl_k_dot3_power_devicetype
, /**< (IS,W) Device type. See LLDP_DOT3_POWER_PSE/PD. */
486 lldpctl_k_dot3_power_supported
, /**< (I,W) Is MDI power supported. */
487 lldpctl_k_dot3_power_enabled
, /**< (I,W) Is MDI power enabled. */
488 lldpctl_k_dot3_power_paircontrol
, /**< (I,W) Pair-control enabled? */
489 lldpctl_k_dot3_power_pairs
, /**< (IS,W) See LLDP_DOT3_POWERPAIRS_ */
490 lldpctl_k_dot3_power_class
, /**< (IS,W) Power class. */
491 lldpctl_k_dot3_power_type
, /**< (I,W) 802.3AT power type */
492 lldpctl_k_dot3_power_source
, /**< (IS,W) 802.3AT power source */
493 lldpctl_k_dot3_power_priority
, /**< (IS,W) 802.3AT power priority */
494 lldpctl_k_dot3_power_allocated
, /**< (I,W) 802.3AT power allocated */
495 lldpctl_k_dot3_power_requested
, /**< (I,W) 802.3AT power requested */
497 lldpctl_k_port_vlan_pvid
, /**< (I) Primary VLAN ID */
498 lldpctl_k_port_vlans
, /**< (AL) List of VLAN */
499 lldpctl_k_vlan_id
, /**< (I) VLAN ID */
500 lldpctl_k_vlan_name
, /**< (S) VLAN name */
502 lldpctl_k_port_ppvids
, /**< (AL) List of PPVIDs */
503 lldpctl_k_ppvid_status
, /**< (I) Status of PPVID (see LLDP_PPVID_CAP_*) */
504 lldpctl_k_ppvid_id
, /**< (I) ID of PPVID */
506 lldpctl_k_port_pis
, /**< (AL) List of PIDs */
507 lldpctl_k_pi_id
, /**< (B) PID value */
509 lldpctl_k_chassis_index
, /**< (I) The chassis index. */
510 lldpctl_k_chassis_id_subtype
, /**< (IS) The subtype ID of this chassis. */
511 lldpctl_k_chassis_id
, /**< (BS) The ID of this chassis. */
512 lldpctl_k_chassis_name
, /**< (S) The name of this chassis. */
513 lldpctl_k_chassis_descr
, /**< (S) The description of this chassis. */
514 lldpctl_k_chassis_cap_available
, /**< (I) Available capabalities (see LLDP_CAP_*) */
515 lldpctl_k_chassis_cap_enabled
, /**< (I) Enabled capabilities (see LLDP_CAP_*) */
516 lldpctl_k_chassis_mgmt
, /**< (AL) List of management addresses */
518 lldpctl_k_chassis_med_type
, /**< (IS) Chassis MED type. See LLDP_MED_CLASS_* */
519 lldpctl_k_chassis_med_cap
, /**< (I) Available MED capabilitied. See LLDP_MED_CAP_* */
520 lldpctl_k_chassis_med_inventory_hw
, /**< (S) LLDP MED inventory "Hardware Revision" */
521 lldpctl_k_chassis_med_inventory_sw
, /**< (S) LLDP MED inventory "Software Revision" */
522 lldpctl_k_chassis_med_inventory_fw
, /**< (S) LLDP MED inventory "Firmware Revision" */
523 lldpctl_k_chassis_med_inventory_sn
, /**< (S) LLDP MED inventory "Serial Number" */
524 lldpctl_k_chassis_med_inventory_manuf
, /**< (S) LLDP MED inventory "Manufacturer" */
525 lldpctl_k_chassis_med_inventory_model
, /**< (S) LLDP MED inventory "Model" */
526 lldpctl_k_chassis_med_inventory_asset
, /**< (S) LLDP MED inventory "Asset ID" */
528 lldpctl_k_port_med_policies
, /**< (AL,WO) MED policies attached to a port. */
529 lldpctl_k_med_policy_type
, /**< (IS,W) MED policy app type. See LLDP_MED_APPTYPE_*. 0 if a policy is not defined. */
530 lldpctl_k_med_policy_unknown
, /**< (I,W) Is MED policy defined? */
531 lldpctl_k_med_policy_tagged
, /**< (I,W) MED policy tagging */
532 lldpctl_k_med_policy_vid
, /**< (I,W) MED policy VID */
533 lldpctl_k_med_policy_priority
, /**< (I,W) MED policy priority */
534 lldpctl_k_med_policy_dscp
, /**< (I,W) MED policy DSCP */
536 lldpctl_k_port_med_locations
, /**< (AL,WO) MED locations attached to a port. */
537 lldpctl_k_med_location_format
, /**< (IS,W) MED location format. See
538 * LLDP_MED_LOCFORMAT_*. 0 if this
539 * location is not defined. When written,
540 * the following fields will be zeroed
542 lldpctl_k_med_location_geoid
, /**< (IS,W) MED geoid. See LLDP_MED_LOCATION_GEOID_*. Only if format is COORD. */
543 lldpctl_k_med_location_latitude
, /**< (S,W) MED latitude. Only if format is COORD. */
544 lldpctl_k_med_location_longitude
, /**< (S,W) MED longitude. Only if format is COORD. */
545 lldpctl_k_med_location_altitude
, /**< (S,W) MED altitude. Only if format is COORD. */
546 lldpctl_k_med_location_altitude_unit
, /**< (S,W) MED altitude unit. See LLDP_MED_LOCATION_ALTITUDE_UNIT_*.
547 * Only if format is COORD. */
549 lldpctl_k_med_location_country
, /**< (S,W) MED country. Only if format is CIVIC. */
550 lldpctl_k_med_location_elin
, /**< (S,W) MED ELIN. Only if format is ELIN. */
552 lldpctl_k_med_location_ca_elements
, /**< (AL,WC) MED civic address elements. Only if format is CIVIC */
553 lldpctl_k_med_civicaddress_type
, /**< (IS,W) MED civic address type. */
554 lldpctl_k_med_civicaddress_value
, /**< (S,W) MED civic address value. */
556 lldpctl_k_port_med_power
, /**< (A,WO) LLDP-MED power related stuff. */
557 lldpctl_k_med_power_type
, /**< (IS,W) LLDP MED power device type. See LLDP_MED_POW_TYPE_* */
558 lldpctl_k_med_power_source
, /**< (IS,W) LLDP MED power source. See LLDP_MED_POW_SOURCE_* */
559 lldpctl_k_med_power_priority
, /**< (IS,W) LLDP MED power priority. See LLDP_MED_POW_PRIO_* */
560 lldpctl_k_med_power_val
, /**< (I,W) LLDP MED power value */
562 lldpctl_k_mgmt_ip
, /**< (S) IP address */
566 * Retrieve a bit of information as an atom.
568 * @param atom The atom we want to query.
569 * @param key The information we want from the atom.
570 * @return The atom representing the requested information or @c NULL if the
571 * information is not available.
573 * Not every value of @c info will be available as an atom. See the
574 * documentation of @c lldpctl_key_t for values accepting to be extracted as an
575 * atom. Usually, this is only iterable values or values representing a complex
578 * The provided atom is not a _borrowed_ reference. You need to decrement the
579 * reference count when you don't need it anymore.
581 * As a convenience, this function will return @c NULL if the first parameter is
582 * @c NULL and no error will be raised.
584 lldpctl_atom_t
*lldpctl_atom_get(lldpctl_atom_t
*atom
, lldpctl_key_t key
);
587 * Set a bit of information with an atom.
589 * @param atom The atom we want to write to.
590 * @param key The key information we want to write.
591 * @param value The value of the information we want to write.
592 * @return The updated atom with the appropriate information.
594 * This function will return @c NULL in case of error. If the last error is @c
595 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
596 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
599 lldpctl_atom_t
*lldpctl_atom_set(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
600 lldpctl_atom_t
*value
);
603 * Retrieve a bit of information as a null-terminated string.
605 * @param atom The atom we want to query.
606 * @param key The information we want from the atom.
607 * @return The requested string or @c NULL if the information is not available.
609 * Not every value of @c info will be available as a string. See the
610 * documentation of @c lldpctl_key_t for values accepting to be extracted as a
611 * string. Usually, only piece of information stored as string are available in
612 * this form but sometimes, you can get a nice formatted string instead of an
613 * integer with this function.
615 * As a convenience, this function will return @c NULL if the first parameter is
616 * @c NULL and no error will be raised.
618 * The provided string may live inside the atom providing it. If you need it
619 * longer, duplicate it.
621 const char *lldpctl_atom_get_str(lldpctl_atom_t
*atom
, lldpctl_key_t key
);
624 * Set a bit of information using a null-terminated string.
626 * @param atom The atom we want to write to.
627 * @param key The key information we want to write.
628 * @param value The value of the information we want to write.
629 * @return The updated atom with the appropriate information.
631 * This function will return @c NULL in case of error. If the last error is @c
632 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
633 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
636 lldpctl_atom_t
*lldpctl_atom_set_str(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
640 * Retrieve a bit of information as a buffer.
642 * @param atom The atom we want to query.
643 * @param key The information we want from the atom.
644 * @param length[out] The size of the returned buffer.
645 * @return The requested buffer or @c NULL if the information is not available.
647 * Not every value of @c info will be available as a buffer. See the
648 * documentation of @c lldpctl_key_t for values accepting to be extracted as a
649 * string. Usually, only piece of information stored as buffer are available in
652 * As a convenience, this function will return @c NULL if the first parameter is
653 * @c NULL and no error will be raised. If this function returns @c NULL, the
654 * third parameter is set to 0.
656 * The provided buffer may live inside the atom providing it. If you need it
657 * longer, duplicate it.
659 const u_int8_t
*lldpctl_atom_get_buffer(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
663 * Set a bit of information using a buffer
665 * @param atom The atom we want to write to.
666 * @param key The key information we want to write.
667 * @param value The value of the information we want to write.
668 * @param length The length of the provided buffer.
669 * @return The updated atom with the appropriate information.
671 * This function will return @c NULL in case of error. If the last error is @c
672 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
673 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
676 lldpctl_atom_t
*lldpctl_atom_set_buffer(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
677 const u_int8_t
*value
, size_t length
);
680 * Retrieve a bit of information as an integer.
682 * @param atom The atom we want to query.
683 * @param key The information we want from the atom.
684 * @return The requested integer or -1 if the information is not available
686 * Not every value of @c info will be available as an integer. See the
687 * documentation of @c lldpctl_key_t for values accepting to be extracted as a
688 * string. Usually, only piece of information stored as an integer are available
691 * Only @c lldpctl_last_error() can tell if the returned value is an error or
692 * not. However, most values extracted from lldpd cannot be negative.
694 long int lldpctl_atom_get_int(lldpctl_atom_t
*atom
, lldpctl_key_t key
);
697 * Set a bit of information using an integer
699 * @param atom The atom we want to write to.
700 * @param key The key information we want to write.
701 * @param value The value of the information we want to write.
702 * @return The updated atom with the appropriate information.
704 * This function will return @c NULL in case of error. If the last error is @c
705 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same
706 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not
709 lldpctl_atom_t
*lldpctl_atom_set_int(lldpctl_atom_t
*atom
, lldpctl_key_t key
,
716 * Iterator over an iterable atom (a list of ports, a list of VLAN, ...). When
717 * an atom is a list, it can be iterated over to extract the appropriate values.
719 * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(), lldpctl_atom_iter_value()
721 typedef struct lldpctl_atom_iter_t lldpctl_atom_iter_t
;
724 * Return an iterator over a given atom.
726 * If an atom is iterable (if it is a list, like a list of ports, a list of
727 * VLAN, a list of neighbors), it is possible to iterate over it. First use this
728 * function to get an iterator then use @c lldpctl_atom_iter_next() to get the
729 * next item and @c lldpctl_atom_iter_value() to the actuel item.
731 * @param atom The atom we want to create an iterator from.
732 * @return The iterator or @c NULL if an error happened or if the atom is empty
733 * (check with @c lldpctl_last_error()).
735 * As a convenience, if the provided atom is @c NULL, this function will return
736 * @c NULL and no error will be raised.
738 lldpctl_atom_iter_t
*lldpctl_atom_iter(lldpctl_atom_t
*atom
);
741 * Return the next element of an iterator.
743 * @param atom The atom we are currently iterating.
744 * @param iter The iterator we want the next element from.
745 * @return An iterator starting on the next element or @c NULL if we have no
748 * @see lldpctl_atom_iter(), lldpctl_atom_iter_value().
750 * As a convenience, if the provided atom is @c NULL, this function will return
751 * @c NULL and no error will be raised.
753 lldpctl_atom_iter_t
*lldpctl_atom_iter_next(lldpctl_atom_t
*atom
, lldpctl_atom_iter_t
*iter
);
756 * Return the value of an iterator.
758 * @param atom The atom we are currently iterating.
759 * @param iter The iterator we want the next element from.
760 * @return The atom currently associated with the iterator.
762 * @see lldpctl_atom_iter(), lldpctl_atom_iter_next().
764 lldpctl_atom_t
*lldpctl_atom_iter_value(lldpctl_atom_t
*atom
, lldpctl_atom_iter_t
*iter
);
767 * Convenience macro to iter over every value of an iterable object.
769 * @param atom The atom you want to iterate on.
770 * @param value Atom that will be used to contain each value.
772 * This macro behaves as a for loop. Moreover, at the end of each iteration,
773 * value is deallocated. Don't use it outside of the loop!
775 #define lldpctl_atom_foreach(atom, value) \
776 for (lldpctl_atom_iter_t *iter = lldpctl_atom_iter(atom); \
777 iter && (value = lldpctl_atom_iter_value(atom, iter)); \
778 iter = lldpctl_atom_iter_next(atom, iter), \
779 lldpctl_atom_dec_ref(value))
782 * Create a new value for an iterable element.
784 * The value is meant to be appended using @c lldpctl_atom_set(). Currently,
785 * there is no way to delete an element from a list. It is also not advisable to
786 * use getters on a newly created object until it is fully initialized. If its
787 * internal representation is using a buffer, it may not be initialized until
790 * @param atom The atom we want to create a new element for.
791 * @return The new element.
793 lldpctl_atom_t
*lldpctl_atom_create(lldpctl_atom_t
*atom
);