1 /* -*- mode: c; c-file-style: "openbsd" -*- */ 2 /* 3 * Copyright (c) 2012 Vincent Bernat <bernat@luffy.cx> 4 * 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. 8 * 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. 16 */ 17 18 #ifndef LLDPCTL_H 19 #define LLDPCTL_H 20 21 /** 22 * @defgroup liblldpctl liblldpctl: library to interface with lldpd 23 * 24 * `liblldpctl` allows any program to convenienty query and modify the behaviour 25 * of a running lldpd daemon. 26 * 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` 30 * 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. 34 * 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. 38 * 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 43 * simultaneously. 44 * 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. 48 * 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 55 * this. 56 * 57 * @{ 58 */ 59 60 61 #ifdef __cplusplus 62 extern "C" { 63 #endif 64 65 #include <stdlib.h> 66 #include <stdint.h> 67 #include <sys/types.h> 68 69 /** 70 * @defgroup lldpctl_connection Managing connection to lldpd 71 * 72 * Connection with lldpd. 73 * 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()). 80 * 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. 84 * 85 * A connection should be allocated by using @ref lldpctl_new(). It needs to be 86 * released with @ref lldpctl_release(). 87 * 88 * @{ 89 */ 90 91 /** 92 * Get default transport name. 93 * 94 * Currently, this is the default location of the Unix socket. 95 */ 96 const char* lldpctl_get_default_transport(void); 97 98 /** 99 * Structure referencing a connection with lldpd. 100 * 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(). 104 */ 105 typedef struct lldpctl_conn_t lldpctl_conn_t; 106 107 /** 108 * Callback function invoked to send data to lldpd. 109 * 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. 117 */ 118 typedef ssize_t (*lldpctl_send_callback)(lldpctl_conn_t *conn, 119 const uint8_t *data, size_t length, void *user_data); 120 121 /** 122 * Callback function invoked to receive data from lldpd. 123 * 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. 132 */ 133 typedef ssize_t (*lldpctl_recv_callback)(lldpctl_conn_t *conn, 134 const uint8_t *data, size_t length, void *user_data); 135 136 /** 137 * Function invoked when additional data is available from lldpd. 138 * 139 * This function should be invoked in case of asynchronous IO when new data is 140 * available from lldpd (expected or unexpected). 141 * 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 147 * been processed. 148 */ 149 ssize_t lldpctl_recv(lldpctl_conn_t *conn, const uint8_t *data, size_t length); 150 151 /** 152 * Function invoked when there is an opportunity to send data to lldpd. 153 * 154 * This function should be invoked in case of asynchronous IO when new data can 155 * be written to lldpd. 156 * 157 * @param conn Handle to the connection to lldpd. 158 * @return The number of bytes processed or a negative integer if an error has 159 * occurred. 160 */ 161 ssize_t lldpctl_send(lldpctl_conn_t *conn); 162 163 /** 164 * Function invoked to see if there's more data to be processed in the buffer. 165 * 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. 168 * 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 172 */ 173 int lldpctl_process_conn_buffer(lldpctl_conn_t *conn); 174 175 176 /** 177 * Allocate a new handler for connecting to lldpd. 178 * 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. 185 * 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 188 * used. 189 */ 190 lldpctl_conn_t *lldpctl_new(lldpctl_send_callback send, 191 lldpctl_recv_callback recv, void *user_data); 192 193 /** 194 * Allocate a new handler for connecting to lldpd. 195 * 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. 203 * 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 206 * used. 207 */ 208 lldpctl_conn_t *lldpctl_new_name(const char *ctlname, lldpctl_send_callback send, 209 lldpctl_recv_callback recv, void *user_data); 210 211 /** 212 * Release resources associated with a connection to lldpd. 213 * 214 * @param conn Previously allocated handler to a connection to lldpd. 215 * @return 0 on success or a negative integer 216 * 217 * @see lldpctl_new() 218 */ 219 int lldpctl_release(lldpctl_conn_t *conn); 220 /**@}*/ 221 222 /** 223 * @defgroup lldpctl_errors_logs Errors and logs handling 224 * 225 * Error codes and logs handling. 226 * 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. 232 * 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. 237 * 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(). 242 * 243 * Also have a look at @ref lldpctl_log_callback() function if you want a custom 244 * log handling. 245 * 246 * @{ 247 */ 248 249 /** 250 * Setup log handlers. 251 * 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. 256 */ 257 void lldpctl_log_callback(void (*cb)(int severity, const char *msg)); 258 259 /** 260 * Setup log level. 261 * 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. 265 * 266 * @param level Level of verbosity (1 = warnings, 2 = info, 3 = debug). 267 */ 268 void lldpctl_log_level(int level); 269 270 /** 271 * Possible error codes for functions that return negative integers on 272 * this purpose or for @c lldpctl_last_error(). 273 */ 274 typedef enum { 275 /** 276 * No error has happened (yet). 277 */ 278 LLDPCTL_NO_ERROR = 0, 279 /** 280 * A IO related operation would block if performed. 281 */ 282 LLDPCTL_ERR_WOULDBLOCK = -501, 283 /** 284 * A IO related operation has reached a end of file condition. 285 */ 286 LLDPCTL_ERR_EOF = -502, 287 /** 288 * The requested information does not exist. For example, when 289 * requesting an inexistant information from an atom. 290 */ 291 LLDPCTL_ERR_NOT_EXIST = -503, 292 /** 293 * Cannot connect to the lldpd daemon. This error only happens with 294 * default synchronous handlers. 295 */ 296 LLDPCTL_ERR_CANNOT_CONNECT = -504, 297 /** 298 * Atom is of incorrect type for the requested operation. 299 */ 300 LLDPCTL_ERR_INCORRECT_ATOM_TYPE = -505, 301 /** 302 * An error occurred during serialization of message. 303 */ 304 LLDPCTL_ERR_SERIALIZATION = -506, 305 /** 306 * The requested operation cannot be performed because we have another 307 * operation already running. 308 */ 309 LLDPCTL_ERR_INVALID_STATE = -507, 310 /** 311 * The provided atom cannot be iterated. 312 */ 313 LLDPCTL_ERR_CANNOT_ITERATE = -508, 314 /** 315 * The provided value is invalid. 316 */ 317 LLDPCTL_ERR_BAD_VALUE = -509, 318 /** 319 * No new element can be created for this element. 320 */ 321 LLDPCTL_ERR_CANNOT_CREATE = -510, 322 /** 323 * The library is under unexpected conditions and cannot process 324 * any further data reliably. 325 */ 326 LLDPCTL_ERR_FATAL = -900, 327 /** 328 * Out of memory condition. Things may get havoc here but we 329 * should be able to recover. 330 */ 331 LLDPCTL_ERR_NOMEM = -901, 332 /** 333 * An error occurred in a user provided callback. 334 */ 335 LLDPCTL_ERR_CALLBACK_FAILURE = -902 336 } lldpctl_error_t; 337 338 /** 339 * Describe a provided error code. 340 * 341 * @param error Error code to be described. 342 * @return Statically allocated string describing the error. 343 */ 344 const char *lldpctl_strerror(lldpctl_error_t error); 345 346 /** 347 * Get the last error associated to a connection to lldpd. 348 * 349 * @param conn Previously allocated handler to a connection to lldpd. 350 * @return 0 if no error is currently registered. A negative integer 351 * otherwise. 352 * 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. 356 */ 357 lldpctl_error_t lldpctl_last_error(lldpctl_conn_t *conn); 358 359 /** 360 * Describe the last error associate to a connection. 361 * 362 * @param conn Previously allocated handler to a connection to lldpd. 363 * @return Statically allocated string describing the error 364 */ 365 #define lldpctl_last_strerror(conn) lldpctl_strerror(lldpctl_last_error(conn)) 366 /**@}*/ 367 368 /** 369 * @defgroup lldpctl_atoms Extracting information: atoms 370 * 371 * Information retrieved from lldpd is represented as an atom. 372 * 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()). 380 * 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. 385 * 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. 395 * 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. 400 * 401 * @{ 402 */ 403 404 /** 405 * Structure representing an element (chassis, port, VLAN, ...) 406 * 407 * @see lldpctl_atom_inc_ref(), lldpctl_atom_dec_ref(). 408 */ 409 typedef struct lldpctl_atom_t lldpctl_atom_t; 410 411 /** 412 * Structure representing a map from an integer to a character string. 413 * 414 * @see lldpctl_key_get_map(). 415 */ 416 typedef const struct { 417 int value; 418 char *string; 419 } lldpctl_map_t; 420 421 /** 422 * Return the reference to connection with lldpd. 423 * 424 * @param atom The atom we want reference from. 425 * @return The reference to the connection to lldpd. 426 * 427 * Each atom contains an internal reference to the corresponding connection to 428 * lldpd. Use this function to get it. 429 */ 430 lldpctl_conn_t *lldpctl_atom_get_connection(lldpctl_atom_t *atom); 431 432 /** 433 * Increment reference count for an atom. 434 * 435 * @param atom Atom we which to increase reference count. 436 */ 437 void lldpctl_atom_inc_ref(lldpctl_atom_t *atom); 438 439 /** 440 * Decrement reference count for an atom. 441 * 442 * @param atom Atom we want to decrease reference count. Can be @c NULL. In this 443 * case, nothing happens. 444 * 445 * When the reference count becomes 0, the atom is freed. 446 */ 447 void lldpctl_atom_dec_ref(lldpctl_atom_t *atom); 448 449 /** 450 * Possible events for a change (notification). 451 * 452 * @see lldpctl_watch_callback2 453 */ 454 typedef enum { 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 */ 458 } lldpctl_change_t; 459 460 /** 461 * Callback function invoked when a change is detected. 462 * 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. 468 * 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. 472 * 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. 476 * 477 * @see lldpctl_watch_callback 478 */ 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, 483 void *data); 484 485 /** 486 * Callback function invoked when a change is detected. 487 * 488 * @param type Type of change detected. 489 * @param interface Physical interface on which the change has happened. 490 * @param neighbor Changed neighbor. 491 * @param data Data provided when registering the callback. 492 * 493 * The provided interface and neighbor atoms are stolen by the callback: their 494 * reference count are decremented when the callback ends. If you want to keep a 495 * reference to it, be sure to increment the reference count in the callback. 496 * 497 * @see lldpctl_watch_callback2 498 */ 499 typedef void (*lldpctl_change_callback2)(lldpctl_change_t type, 500 lldpctl_atom_t *interface, 501 lldpctl_atom_t *neighbor, 502 void *data); 503 504 /** 505 * Register a callback to be called on changes. 506 * 507 * @param conn Connection with lldpd. 508 * @param cb Replace the current callback with the provided one. 509 * @param data Data that will be passed to the callback. 510 * @return 0 in case of success or -1 in case of errors. 511 * 512 * This function will register the necessity to push neighbor changes to lldpd 513 * and therefore will issue IO operations. The error code could then be @c 514 * LLDPCTL_ERR_WOULDBLOCK. 515 * 516 * @warning Once a callback is registered, the connection shouldn't be used for 517 * anything else than receiving notifications. If you do, you will get a @c 518 * LLDPCTL_ERR_INVALID_STATE error. 519 * 520 * @deprecated This function is deprecated and lldpctl_watch_callback2 should be 521 * used instead. 522 */ 523 int lldpctl_watch_callback(lldpctl_conn_t *conn, 524 lldpctl_change_callback cb, 525 void *data) __attribute__ ((deprecated)); 526 527 /** 528 * Register a callback to be called on changes. 529 * 530 * @param conn Connection with lldpd. 531 * @param cb Replace the current callback with the provided one. 532 * @param data Data that will be passed to the callback. 533 * @return 0 in case of success or -1 in case of errors. 534 * 535 * This function will register the necessity to push neighbor changes to lldpd 536 * and therefore will issue IO operations. The error code could then be @c 537 * LLDPCTL_ERR_WOULDBLOCK. 538 * 539 * @warning Once a callback is registered, the connection shouldn't be used for 540 * anything else than receiving notifications. If you do, you will get a @c 541 * LLDPCTL_ERR_INVALID_STATE error. 542 */ 543 int lldpctl_watch_callback2(lldpctl_conn_t *conn, 544 lldpctl_change_callback2 cb, 545 void *data); 546 547 /** 548 * Wait for the next change. 549 * 550 * @param conn Connection with lldpd. 551 * @return 0 on success or a negative integer in case of error. 552 * 553 * This function will return once a change has been detected. It is only useful 554 * as a main loop when using the builtin blocking IO mechanism. 555 */ 556 int lldpctl_watch(lldpctl_conn_t *conn); 557 558 /** 559 * @defgroup liblldpctl_atom_get_special Retrieving atoms from lldpd 560 * 561 * Special access functions. 562 * 563 * Most information can be retrieved through @ref lldpctl_atom_get(), @ref 564 * lldpctl_atom_get_int(), @ref lldpctl_atom_get_str() or @ref 565 * lldpctl_atom_get_buffer() but some information can only be retrieved through 566 * special functions because IO operation is needed (and also, for some of them, 567 * because we don't have an atom yet). 568 * 569 * @{ 570 */ 571 572 /** 573 * Retrieve global configuration of lldpd daemon. 574 * 575 * @param conn Connection with lldpd. 576 * @return The global configuration or @c NULL if an error happened. 577 * 578 * This function will make IO with the daemon to get the 579 * configuration. Depending on the IO model, information may not be available 580 * right now and the function should be called again later. If @c NULL is 581 * returned, check the last error. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again 582 * later. 583 */ 584 lldpctl_atom_t *lldpctl_get_configuration(lldpctl_conn_t *conn); 585 586 /** 587 * Retrieve the list of available interfaces. 588 * 589 * @param conn Previously allocated handler to a connection to lldpd. 590 * @return The list of available ports or @c NULL if an error happened. 591 * 592 * This function will make IO with the daemon to get the list of 593 * ports. Depending on the IO model, information may not be available right now 594 * and the function should be called again later. If @c NULL is returned, check 595 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later 596 * (when more data is available). 597 * 598 * The list of available ports can be iterated with @ref lldpctl_atom_foreach(). 599 */ 600 lldpctl_atom_t *lldpctl_get_interfaces(lldpctl_conn_t *conn); 601 602 /** 603 * Retrieve the information related to the local chassis. 604 * 605 * @param conn Previously allocated handler to a connection to lldpd. 606 * @return Atom related to the local chassis which may be used in subsequent functions. 607 * 608 * This function may have to do IO to get the information related to the local 609 * chassis. Depending on the IO mode, information may not be available right now 610 * and the function should be called again later. If @c NULL is returned, check 611 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later 612 * (when more data is available). 613 */ 614 lldpctl_atom_t *lldpctl_get_local_chassis(lldpctl_conn_t *conn); 615 616 /** 617 * Retrieve the information related to a given interface. 618 * 619 * @param port The port we want to retrieve information from. This port is an 620 * atom retrieved from an interation on @c lldpctl_get_interfaces(). 621 * @return Atom related to this port which may be used in subsequent functions. 622 * 623 * This function may have to do IO to get the information related to the given 624 * port. Depending on the IO mode, information may not be available right now 625 * and the function should be called again later. If @c NULL is returned, check 626 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later 627 * (when more data is available). 628 */ 629 lldpctl_atom_t *lldpctl_get_port(lldpctl_atom_t *port); 630 631 /** 632 * Retrieve the default port information. 633 * 634 * This port contains default settings whenever a new port needs to be created. 635 * 636 * @param conn Previously allocated handler to a connection to lldpd. 637 * @return Atom of the default port which may be used in subsequent functions. 638 * 639 * This function may have to do IO to get the information related to the given 640 * port. Depending on the IO mode, information may not be available right now 641 * and the function should be called again later. If @c NULL is returned, check 642 * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later 643 * (when more data is available). 644 */ 645 lldpctl_atom_t *lldpctl_get_default_port(lldpctl_conn_t *conn); 646 647 /**@}*/ 648 649 /** 650 * Piece of information that can be retrieved from/written to an atom. 651 * 652 * Each piece of information can potentially be retrieved as an atom (A), a 653 * string (S), a buffer (B) or an integer (I). Additionaly, when an information 654 * can be retrieved as an atom, it is usually iterable (L). When an atom can be 655 * retrieved as a string and as an additional type, the string is expected to be 656 * formatted. For example, the MAC address of a local port can be retrieved as a 657 * buffer and a string. As a string, you'll get something like 658 * "00:11:22:33:44:55". Also, all values that can be get as an integer or a 659 * buffer can be get as a string too. There is no special formatting in this 660 * case. "(BS)" means that the string get a special appropriate format. 661 * 662 * The name of a key is an indication on the type of atom that information can 663 * be extracted from. For example, @c lldpctl_k_med_policy_type can be extracted 664 * from an atom you got by iterating on @c lldpctl_k_port_med_policies. On the 665 * other hand, @c lldpctl_k_port_descr and @c lldpctl_k_chassis can be retrieved 666 * from an atom retrieved either by iterating @c lldpctl_k_port_neighbors or 667 * with @c lldpctl_get_port(). 668 * 669 * Some values may be written. They are marked with (W). Such a change may or 670 * may not be transmitted immediatly. If they are not transmitted immediatly, 671 * this means that the resulting atom should be written to another atom. For 672 * example, when writting @c lldpctl_k_med_policy_tagged, you need to write the 673 * resulting atom to @c lldpctl_k_port_med_policies. If the change is 674 * transmitted immediatly, you need to check the error status of the connection 675 * to know if it has been transmitted correctly. Notably, if you get @c 676 * LLDPCTL_ERR_WOULDBLOCK, you need to try again later. Usually, changes are 677 * transmitted immediatly. The exception are changes that need to be grouped to 678 * be consistent, like a LLDP MED location. When a change is transmitted 679 * immediatly, it is marked with (O). @c lldpctl_atom_set_str() may accept a @c 680 * NULL value. This case is marked with (N) and usually reset the item to the 681 * default value or no value. 682 * 683 * Some values may also be created. They are flagged with (C). This only applies 684 * to elements that can be iterated (L) and written (W). The element created 685 * still needs to be appended to the list by being written to it. The creation 686 * is done with @c lldpctl_atom_create(). 687 * 688 * An atom marked with (S) can be retrieved as a string only. It cannot be 689 * written. An atom marked with (IS) can be retrieved as an integer and features 690 * an appropriate representation as a string (usually, the name of a constant) 691 * which is more meaningful than just the integer. An atom marked as (I) can be 692 * retrieved as an integer and as a string. In the later case, this is just a 693 * string representation of the integer. An atom marked with (AL) can be 694 * retrieved as an atom only and can be iterated over. This is usually a list of 695 * things. An atom marked (I,W) can be read as an integer or a string and can be 696 * written as an integer. The change would not be commited until the atom is 697 * written to the nearest atom supporting (A,WO) operation (eventually with an 698 * indirection, i.e first write to a (A,W), then to a (A,WO)). 699 */ 700 typedef enum { 701 lldpctl_k_config_tx_interval, /**< `(I,WO)` Transmit interval. When set to -1, it is meant to transmit now. */ 702 lldpctl_k_config_receiveonly, /**< `(I)` Receive only mode */ 703 lldpctl_k_config_mgmt_pattern, /**< `(S,WON)` Pattern to choose the management address */ 704 lldpctl_k_config_iface_pattern, /**< `(S,WON)` Pattern of enabled interfaces */ 705 lldpctl_k_config_cid_pattern, /**< `(S)` Interface pattern to choose the chassis ID */ 706 lldpctl_k_config_description, /**< `(S,WON)` Chassis description overridden */ 707 lldpctl_k_config_platform, /**< `(S,WON)` Platform description overridden (CDP) */ 708 lldpctl_k_config_hostname, /**< `(S,WON)` System name overridden */ 709 lldpctl_k_config_advertise_version, /**< `(I)` Advertise version */ 710 lldpctl_k_config_lldpmed_noinventory, /**< `(I)` Disable LLDP-MED inventory */ 711 lldpctl_k_config_paused, /**< `(I,WO)` lldpd is paused */ 712 lldpctl_k_config_fast_start_enabled, /**< `(I,WO)` Is fast start enabled */ 713 lldpctl_k_config_fast_start_interval, /**< `(I,WO)` Start fast transmit interval */ 714 lldpctl_k_config_ifdescr_update, /**< `(I,WO)` Enable or disable setting interface description */ 715 lldpctl_k_config_iface_promisc, /**< `(I,WO)` Enable or disable promiscuous mode on interfaces */ 716 lldpctl_k_config_chassis_cap_advertise, /**< `(I,WO)` Enable or disable chassis capabilities advertisement */ 717 lldpctl_k_config_chassis_mgmt_advertise, /**< `(I,WO)` Enable or disable management addresses advertisement */ 718 lldpctl_k_config_cid_string, /**< `(S,WON)` User defined string for the chassis ID */ 719 lldpctl_k_config_perm_iface_pattern, /**< `(S,WON)` Pattern of permanent interfaces */ 720 lldpctl_k_config_tx_interval_ms, /**< `(I,WO)` Transmit interval in milliseconds. Set to -1 to transmit now. */ 721 722 lldpctl_k_interface_name = 1000, /**< `(S)` The interface name. */ 723 724 lldpctl_k_port_name = 1100, /**< `(S)` The port name. Only works for a local port. */ 725 lldpctl_k_port_index, /**< `(I)` The port index. Only works for a local port. */ 726 /** 727 * `(AL)` The list of known neighbors for this port. 728 * 729 * A neighbor is in fact a remote port. 730 */ 731 lldpctl_k_port_neighbors = 1200, 732 lldpctl_k_port_protocol, /**< `(IS)` The protocol that was used to retrieve this information. */ 733 lldpctl_k_port_age, /**< `(I)` Age of information, seconds from epoch. */ 734 lldpctl_k_port_id_subtype, /**< `(IS)` The subtype ID of this port. */ 735 lldpctl_k_port_id, /**< `(BS,WO)` The ID of this port. */ 736 lldpctl_k_port_descr, /**< `(S,WO)` The description of this port. */ 737 lldpctl_k_port_hidden, /**< `(I)` Is this port hidden (or should it be displayed?)? */ 738 lldpctl_k_port_status, /**< `(IS,WO)` Operational status of this (local) port */ 739 lldpctl_k_port_chassis, /**< `(A)` Chassis associated to the port */ 740 lldpctl_k_port_ttl, /**< `(I)` TTL for port, 0 if info is attached to chassis */ 741 lldpctl_k_port_vlan_tx, /**< `(I,W)` VLAN tag for TX on port, -1 VLAN disabled */ 742 743 lldpctl_k_port_dot3_mfs = 1300, /**< `(I)` MFS */ 744 lldpctl_k_port_dot3_aggregid, /**< `(I)` Port aggregation ID */ 745 lldpctl_k_port_dot3_autoneg_support, /**< `(I)` Autonegotiation support. */ 746 lldpctl_k_port_dot3_autoneg_enabled, /**< `(I)` Autonegotiation enabled. */ 747 lldpctl_k_port_dot3_autoneg_advertised, /**< `(I)` Advertised protocols. See `LLDP_DOT3_LINK_AUTONEG_*` */ 748 lldpctl_k_port_dot3_mautype, /**< `(IS)` Current MAU type. See `LLDP_DOT3_MAU_*` */ 749 750 lldpctl_k_port_dot3_power = 1400, /**< `(A,WO)` Dot3 power related stuff. */ 751 lldpctl_k_dot3_power_devicetype, /**< `(IS,W)` Device type. See `LLDP_DOT3_POWER_PSE/PD` */ 752 lldpctl_k_dot3_power_supported, /**< `(I,W)` Is MDI power supported. */ 753 lldpctl_k_dot3_power_enabled, /**< `(I,W)` Is MDI power enabled. */ 754 lldpctl_k_dot3_power_paircontrol, /**< `(I,W)` Pair-control enabled? */ 755 lldpctl_k_dot3_power_pairs, /**< `(IS,W)` See `LLDP_DOT3_POWERPAIRS_*` */ 756 lldpctl_k_dot3_power_class, /**< `(IS,W)` Power class. */ 757 lldpctl_k_dot3_power_type, /**< `(I,W)` 802.3AT power type */ 758 lldpctl_k_dot3_power_source, /**< `(IS,W)` 802.3AT power source */ 759 lldpctl_k_dot3_power_priority, /**< `(IS,W)` 802.3AT power priority */ 760 lldpctl_k_dot3_power_allocated, /**< `(I,W)` 802.3AT power allocated */ 761 lldpctl_k_dot3_power_requested, /**< `(I,W)` 802.3AT power requested */ 762 763 /* 802.3bt additions */ 764 lldpctl_k_dot3_power_pd_4pid, /**< `(IS,W)` 802.3BT both modes supported? */ 765 lldpctl_k_dot3_power_requested_a, /**< `(I,W)` 802.3BT power value requested for A */ 766 lldpctl_k_dot3_power_requested_b, /**< `(I,W)` 802.3BT power value requested for B */ 767 lldpctl_k_dot3_power_allocated_a, /**< `(I,W)` 802.3BT power value allocated for A */ 768 lldpctl_k_dot3_power_allocated_b, /**< `(I,W)` 802.3BT power value allocated for B */ 769 lldpctl_k_dot3_power_pse_status, /**< `(IS,W)` 802.3BT PSE powering status */ 770 lldpctl_k_dot3_power_pd_status, /**< `(IS,W)` 802.3BT PD powering status */ 771 lldpctl_k_dot3_power_pse_pairs_ext, /**< `(IS,W)` 802.3BT PSE power pairs */ 772 lldpctl_k_dot3_power_class_a, /**< `(IS,W)` 802.3BT power class for A */ 773 lldpctl_k_dot3_power_class_b, /**< `(IS,W)` 802.3BT power class for B */ 774 lldpctl_k_dot3_power_class_ext, /**< `(IS,W)` 802.3BT power class */ 775 lldpctl_k_dot3_power_type_ext, /**< `(IS,W)` 802.3BT power type */ 776 lldpctl_k_dot3_power_pd_load, /**< `(IS,W)` 802.3BT dualsig isolated? */ 777 lldpctl_k_dot3_power_pse_max, /**< `(I,W)` 802.3BT maximum available power */ 778 779 lldpctl_k_port_vlan_pvid = 1500, /**< `(I)` Primary VLAN ID */ 780 lldpctl_k_port_vlans, /**< `(AL)` List of VLAN */ 781 lldpctl_k_vlan_id, /**< `(I)` VLAN ID */ 782 lldpctl_k_vlan_name, /**< `(S)` VLAN name */ 783 784 lldpctl_k_port_ppvids = 1600, /**< `(AL)` List of PPVIDs */ 785 lldpctl_k_ppvid_status, /**< `(I)` Status of PPVID (see `LLDP_PPVID_CAP_*`) */ 786 lldpctl_k_ppvid_id, /**< `(I)` ID of PPVID */ 787 788 lldpctl_k_port_pis = 1700, /**< `(AL)` List of PIDs */ 789 lldpctl_k_pi_id, /**< `(B)` PID value */ 790 791 lldpctl_k_chassis_index = 1800, /**< `(I)` The chassis index. */ 792 lldpctl_k_chassis_id_subtype, /**< `(IS)` The subtype ID of this chassis. */ 793 lldpctl_k_chassis_id, /**< `(BS)` The ID of this chassis. */ 794 lldpctl_k_chassis_name, /**< `(S)` The name of this chassis. */ 795 lldpctl_k_chassis_descr, /**< `(S)` The description of this chassis. */ 796 lldpctl_k_chassis_cap_available, /**< `(I)` Available capabalities (see `LLDP_CAP_*`) */ 797 lldpctl_k_chassis_cap_enabled, /**< `(I)` Enabled capabilities (see `LLDP_CAP_*`) */ 798 lldpctl_k_chassis_mgmt, /**< `(AL)` List of management addresses */ 799 lldpctl_k_chassis_ttl, /**< Deprecated */ 800 801 lldpctl_k_chassis_med_type = 1900, /**< `(IS)` Chassis MED type. See `LLDP_MED_CLASS_*` */ 802 lldpctl_k_chassis_med_cap, /**< `(I)` Available MED capabilitied. See `LLDP_MED_CAP_*` */ 803 lldpctl_k_chassis_med_inventory_hw, /**< `(S)` LLDP MED inventory "Hardware Revision" */ 804 lldpctl_k_chassis_med_inventory_sw, /**< `(S)` LLDP MED inventory "Software Revision" */ 805 lldpctl_k_chassis_med_inventory_fw, /**< `(S)` LLDP MED inventory "Firmware Revision" */ 806 lldpctl_k_chassis_med_inventory_sn, /**< `(S)` LLDP MED inventory "Serial Number" */ 807 lldpctl_k_chassis_med_inventory_manuf, /**< `(S)` LLDP MED inventory "Manufacturer" */ 808 lldpctl_k_chassis_med_inventory_model, /**< `(S)` LLDP MED inventory "Model" */ 809 lldpctl_k_chassis_med_inventory_asset, /**< `(S)` LLDP MED inventory "Asset ID" */ 810 811 lldpctl_k_port_med_policies = 2000, /**< `(AL,WO)` MED policies attached to a port. */ 812 lldpctl_k_med_policy_type, /**< `(IS,W)` MED policy app type. See `LLDP_MED_APPTYPE_*`. 0 if a policy is not defined. */ 813 lldpctl_k_med_policy_unknown, /**< `(I,W)` Is MED policy defined? */ 814 lldpctl_k_med_policy_tagged, /**< `(I,W)` MED policy tagging */ 815 lldpctl_k_med_policy_vid, /**< `(I,W)` MED policy VID */ 816 lldpctl_k_med_policy_priority, /**< `(I,W)` MED policy priority */ 817 lldpctl_k_med_policy_dscp, /**< `(I,W)` MED policy DSCP */ 818 819 lldpctl_k_port_med_locations = 2100, /**< `(AL,WO)` MED locations attached to a port. */ 820 lldpctl_k_med_location_format, /**< `(IS,W)` MED location format. See 821 * `LLDP_MED_LOCFORMAT_*`. 0 if this 822 * location is not defined. When written, 823 * the following fields will be zeroed 824 * out. */ 825 lldpctl_k_med_location_geoid, /**< `(IS,W)` MED geoid. See `LLDP_MED_LOCATION_GEOID_*`. Only if format is COORD. */ 826 lldpctl_k_med_location_latitude, /**< `(S,W)` MED latitude. Only if format is COORD. */ 827 lldpctl_k_med_location_longitude, /**< `(S,W)` MED longitude. Only if format is COORD. */ 828 lldpctl_k_med_location_altitude, /**< `(S,W)` MED altitude. Only if format is COORD. */ 829 lldpctl_k_med_location_altitude_unit, /**< `(S,W)` MED altitude unit. See `LLDP_MED_LOCATION_ALTITUDE_UNIT_*`. 830 * Only if format is COORD. */ 831 832 lldpctl_k_med_location_country = 2200, /**< `(S,W)` MED country. Only if format is CIVIC. */ 833 lldpctl_k_med_location_elin, /**< `(S,W)` MED ELIN. Only if format is ELIN. */ 834 835 lldpctl_k_med_location_ca_elements = 2300, /**< `(AL,WC)` MED civic address elements. Only if format is CIVIC */ 836 lldpctl_k_med_civicaddress_type, /**< `(IS,W)` MED civic address type. */ 837 lldpctl_k_med_civicaddress_value, /**< `(S,W)` MED civic address value. */ 838 839 lldpctl_k_port_med_power = 2400, /**< `(A,WO)` LLDP-MED power related stuff. */ 840 lldpctl_k_med_power_type, /**< `(IS,W)` LLDP MED power device type. See `LLDP_MED_POW_TYPE_*` */ 841 lldpctl_k_med_power_source, /**< `(IS,W)` LLDP MED power source. See `LLDP_MED_POW_SOURCE_*` */ 842 lldpctl_k_med_power_priority, /**< `(IS,W)` LLDP MED power priority. See `LLDP_MED_POW_PRIO_*` */ 843 lldpctl_k_med_power_val, /**< `(I,W)` LLDP MED power value */ 844 845 lldpctl_k_mgmt_ip = 3000, /**< `(S)` IP address */ 846 lldpctl_k_mgmt_iface_index = 30001, /**< `(I)` Interface index */ 847 848 lldpctl_k_tx_cnt = 4000, /**< `(I)` tx cnt. Only works for a local port. */ 849 lldpctl_k_rx_cnt, /**< `(I)` rx cnt. Only works for a local port. */ 850 lldpctl_k_rx_discarded_cnt, /**< `(I)` discarded cnt. Only works for a local port. */ 851 lldpctl_k_rx_unrecognized_cnt, /**< `(I)` unrecognized cnt. Only works for a local port. */ 852 lldpctl_k_ageout_cnt, /**< `(I)` ageout cnt. Only works for a local port. */ 853 lldpctl_k_insert_cnt, /**< `(I)` insert cnt. Only works for a local port. */ 854 lldpctl_k_delete_cnt, /**< `(I)` delete cnt. Only works for a local port. */ 855 lldpctl_k_config_tx_hold, /**< `(I,WO)` Transmit hold interval. */ 856 lldpctl_k_config_bond_slave_src_mac_type, /**< `(I,WO)` bond slave src mac type. */ 857 lldpctl_k_config_lldp_portid_type, /**< `(I,WO)` LLDP PortID TLV Subtype */ 858 lldpctl_k_config_lldp_agent_type, /**< `(I,WO)` LLDP agent type */ 859 lldpctl_k_config_max_neighbors, /**< `(I,WO)`Maximum number of neighbors per port. */ 860 861 lldpctl_k_custom_tlvs = 5000, /**< `(AL)` custom TLVs */ 862 lldpctl_k_custom_tlvs_clear, /** `(I,WO)` clear list of custom TLVs */ 863 lldpctl_k_custom_tlv, /** `(AL,WO)` custom TLV **/ 864 lldpctl_k_custom_tlv_oui, /**< `(I,WO)` custom TLV Organizationally Unique Identifier. Default is 0 (3 bytes) */ 865 lldpctl_k_custom_tlv_oui_subtype, /**< `(I,WO)` custom TLV subtype. Default is 0 (1 byte) */ 866 lldpctl_k_custom_tlv_oui_info_string, /**< `(I,WO)` custom TLV Organizationally Unique Identifier Information String (up to 507 bytes) */ 867 lldpctl_k_custom_tlv_op, /**< `(I,WO)` custom TLV operation */ 868 869 } lldpctl_key_t; 870 871 /** 872 * Get a map related to a key. 873 * 874 * Many keys expect to be written with a discrete number of values. Take for 875 * example @c lldpctl_k_med_civicaddress_type, it can take any integer between 1 876 * and 128. However, each integer can be named. It can be useful for an 877 * application to get a translation between the integer that can be provided and 878 * a more human-readable name. This function allows to retrieve the 879 * corresponding map. 880 * 881 * @param key The piece of information we want a map from. 882 * @return The map or @c NULL if no map is available. 883 * 884 * The returned map has its last element set to 0. It is also expected that the 885 * string value can be used with a set operation. It will be translated to the 886 * integer value. 887 */ 888 lldpctl_map_t *lldpctl_key_get_map(lldpctl_key_t key); 889 890 /** 891 * Retrieve a bit of information as an atom. 892 * 893 * @param atom The atom we want to query. 894 * @param key The information we want from the atom. 895 * @return The atom representing the requested information or @c NULL if the 896 * information is not available. 897 * 898 * Not every value of @c info will be available as an atom. See the 899 * documentation of @c lldpctl_key_t for values accepting to be extracted as an 900 * atom. Usually, this is only iterable values or values representing a complex 901 * object. 902 * 903 * The provided atom is not a _borrowed_ reference. You need to decrement the 904 * reference count when you don't need it anymore. 905 * 906 * As a convenience, this function will return @c NULL if the first parameter is 907 * @c NULL and no error will be raised. 908 */ 909 lldpctl_atom_t *lldpctl_atom_get(lldpctl_atom_t *atom, lldpctl_key_t key); 910 911 /** 912 * Set a bit of information with an atom. 913 * 914 * @param atom The atom we want to write to. 915 * @param key The key information we want to write. 916 * @param value The value of the information we want to write. 917 * @return The updated atom with the appropriate information. 918 * 919 * This function will return @c NULL in case of error. If the last error is @c 920 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same 921 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not 922 * correct. 923 */ 924 lldpctl_atom_t *lldpctl_atom_set(lldpctl_atom_t *atom, lldpctl_key_t key, 925 lldpctl_atom_t *value); 926 927 /** 928 * Retrieve a bit of information as a null-terminated string. 929 * 930 * @param atom The atom we want to query. 931 * @param key The information we want from the atom. 932 * @return The requested string or @c NULL if the information is not available. 933 * 934 * Not every value of @c info will be available as a string. See the 935 * documentation of @c lldpctl_key_t for values accepting to be extracted as a 936 * string. Usually, only piece of information stored as string are available in 937 * this form but sometimes, you can get a nice formatted string instead of an 938 * integer with this function. 939 * 940 * As a convenience, this function will return @c NULL if the first parameter is 941 * @c NULL and no error will be raised. 942 * 943 * The provided string may live inside the atom providing it. If you need it 944 * longer, duplicate it. 945 */ 946 const char *lldpctl_atom_get_str(lldpctl_atom_t *atom, lldpctl_key_t key); 947 948 /** 949 * Set a bit of information using a null-terminated string. 950 * 951 * @param atom The atom we want to write to. 952 * @param key The key information we want to write. 953 * @param value The value of the information we want to write. 954 * @return The updated atom with the appropriate information. 955 * 956 * This function will return @c NULL in case of error. If the last error is @c 957 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same 958 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not 959 * correct. 960 */ 961 lldpctl_atom_t *lldpctl_atom_set_str(lldpctl_atom_t *atom, lldpctl_key_t key, 962 const char *value); 963 964 /** 965 * Retrieve a bit of information as a buffer. 966 * 967 * @param atom The atom we want to query. 968 * @param key The information we want from the atom. 969 * @param[out] length The size of the returned buffer. 970 * @return The requested buffer or @c NULL if the information is not available. 971 * 972 * Not every value of @c info will be available as a buffer. See the 973 * documentation of @c lldpctl_key_t for values accepting to be extracted as a 974 * string. Usually, only piece of information stored as buffer are available in 975 * this form. 976 * 977 * As a convenience, this function will return @c NULL if the first parameter is 978 * @c NULL and no error will be raised. If this function returns @c NULL, the 979 * third parameter is set to 0. 980 * 981 * The provided buffer may live inside the atom providing it. If you need it 982 * longer, duplicate it. 983 */ 984 const uint8_t *lldpctl_atom_get_buffer(lldpctl_atom_t *atom, lldpctl_key_t key, 985 size_t *length); 986 987 /** 988 * Set a bit of information using a buffer 989 * 990 * @param atom The atom we want to write to. 991 * @param key The key information we want to write. 992 * @param value The value of the information we want to write. 993 * @param length The length of the provided buffer. 994 * @return The updated atom with the appropriate information. 995 * 996 * This function will return @c NULL in case of error. If the last error is @c 997 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same 998 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not 999 * correct. 1000 */ 1001 lldpctl_atom_t *lldpctl_atom_set_buffer(lldpctl_atom_t *atom, lldpctl_key_t key, 1002 const uint8_t *value, size_t length); 1003 1004 /** 1005 * Retrieve a bit of information as an integer. 1006 * 1007 * @param atom The atom we want to query. 1008 * @param key The information we want from the atom. 1009 * @return The requested integer or -1 if the information is not available 1010 * 1011 * Not every value of @c info will be available as an integer. See the 1012 * documentation of @c lldpctl_key_t for values accepting to be extracted as a 1013 * string. Usually, only piece of information stored as an integer are available 1014 * in this form. 1015 * 1016 * Only @c lldpctl_last_error() can tell if the returned value is an error or 1017 * not. However, most values extracted from lldpd cannot be negative. 1018 */ 1019 long int lldpctl_atom_get_int(lldpctl_atom_t *atom, lldpctl_key_t key); 1020 1021 /** 1022 * Set a bit of information using an integer 1023 * 1024 * @param atom The atom we want to write to. 1025 * @param key The key information we want to write. 1026 * @param value The value of the information we want to write. 1027 * @return The updated atom with the appropriate information. 1028 * 1029 * This function will return @c NULL in case of error. If the last error is @c 1030 * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same 1031 * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not 1032 * correct. 1033 */ 1034 lldpctl_atom_t *lldpctl_atom_set_int(lldpctl_atom_t *atom, lldpctl_key_t key, 1035 long int value); 1036 1037 /** 1038 * @defgroup liblldpctl_atom_iter Iterating over atoms 1039 * 1040 * Iterate over atoms (lists). 1041 * 1042 * @{ 1043 */ 1044 /** 1045 * Iterator over an iterable atom (a list of ports, a list of VLAN, ...). When 1046 * an atom is a list, it can be iterated over to extract the appropriate values. 1047 * 1048 * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(), lldpctl_atom_iter_value() 1049 */ 1050 typedef struct lldpctl_atom_iter_t lldpctl_atom_iter_t; 1051 1052 /** 1053 * Return an iterator over a given atom. 1054 * 1055 * If an atom is iterable (if it is a list, like a list of ports, a list of 1056 * VLAN, a list of neighbors), it is possible to iterate over it. First use this 1057 * function to get an iterator then use @c lldpctl_atom_iter_next() to get the 1058 * next item and @c lldpctl_atom_iter_value() to the actuel item. 1059 * 1060 * @param atom The atom we want to create an iterator from. 1061 * @return The iterator or @c NULL if an error happened or if the atom is empty 1062 * (check with @c lldpctl_last_error()). 1063 * 1064 * As a convenience, if the provided atom is @c NULL, this function will return 1065 * @c NULL and no error will be raised. 1066 */ 1067 lldpctl_atom_iter_t *lldpctl_atom_iter(lldpctl_atom_t *atom); 1068 1069 /** 1070 * Return the next element of an iterator. 1071 * 1072 * @param atom The atom we are currently iterating. 1073 * @param iter The iterator we want the next element from. 1074 * @return An iterator starting on the next element or @c NULL if we have no 1075 * more elements 1076 * 1077 * @see lldpctl_atom_iter(), lldpctl_atom_iter_value(). 1078 * 1079 * As a convenience, if the provided atom is @c NULL, this function will return 1080 * @c NULL and no error will be raised. 1081 */ 1082 lldpctl_atom_iter_t *lldpctl_atom_iter_next(lldpctl_atom_t *atom, lldpctl_atom_iter_t *iter); 1083 1084 /** 1085 * Return the value of an iterator. 1086 * 1087 * @param atom The atom we are currently iterating. 1088 * @param iter The iterator we want the next element from. 1089 * @return The atom currently associated with the iterator. 1090 * 1091 * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(). 1092 */ 1093 lldpctl_atom_t *lldpctl_atom_iter_value(lldpctl_atom_t *atom, lldpctl_atom_iter_t *iter); 1094 1095 /** 1096 * Convenience macro to iter over every value of an iterable object. 1097 * 1098 * @param atom The atom you want to iterate on. 1099 * @param value Atom name that will be used to contain each value. 1100 * 1101 * This macro behaves as a for loop. Moreover, at the end of each iteration, the 1102 * reference count of the provided value is decremented. If you need to use it 1103 * outside of the loop, you need to increment it. 1104 */ 1105 #define lldpctl_atom_foreach(atom, value) \ 1106 for (lldpctl_atom_iter_t *iter##_LINE_ = lldpctl_atom_iter(atom); \ 1107 iter##_LINE_ && (value = lldpctl_atom_iter_value(atom, iter##_LINE_)); \ 1108 iter##_LINE_ = lldpctl_atom_iter_next(atom, iter##_LINE_), \ 1109 lldpctl_atom_dec_ref(value)) 1110 1111 /** 1112 * Create a new value for an iterable element. 1113 * 1114 * The value is meant to be appended using @c lldpctl_atom_set(). Currently, 1115 * there is no way to delete an element from a list. It is also not advisable to 1116 * use getters on a newly created object until it is fully initialized. If its 1117 * internal representation is using a buffer, it may not be initialized until 1118 * the first set. 1119 * 1120 * @param atom The atom we want to create a new element for. 1121 * @return The new element. 1122 */ 1123 lldpctl_atom_t *lldpctl_atom_create(lldpctl_atom_t *atom); 1124 /**@}*/ 1125 /**@}*/ 1126 1127 #ifdef __cplusplus 1128 } 1129 #endif 1130 1131 /**@}*/ 1132 1133 #endif 1134