]>
Commit | Line | Data |
---|---|---|
4b292b55 VB |
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 | /** | |
b1eceab6 | 22 | * @defgroup liblldpctl liblldpctl: library to interface with lldpd |
4b292b55 | 23 | * |
b1eceab6 VB |
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 | * @{ | |
4b292b55 VB |
58 | */ |
59 | ||
b1eceab6 | 60 | |
4b292b55 VB |
61 | #ifdef __cplusplus |
62 | extern "C" { | |
63 | #endif | |
64 | ||
65 | #include <stdlib.h> | |
66 | #include <stdint.h> | |
67 | #include <sys/types.h> | |
68 | ||
69 | /** | |
b1eceab6 | 70 | * @defgroup lldpctl_connection Managing connection to lldpd |
4b292b55 | 71 | * |
94d2efe5 VB |
72 | * Connection with lldpd. |
73 | * | |
b1eceab6 VB |
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 | * @{ | |
4b292b55 | 89 | */ |
4b292b55 VB |
90 | |
91 | /** | |
b1eceab6 | 92 | * Get default transport name. |
4b292b55 | 93 | * |
b1eceab6 | 94 | * Currently, this is the default location of the Unix socket. |
4b292b55 | 95 | */ |
b1eceab6 | 96 | const char* lldpctl_get_default_transport(void); |
4b292b55 | 97 | |
4b292b55 VB |
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 | * | |
b35cfd03 | 110 | * @param conn Handle to the connection to lldpd. |
4b292b55 VB |
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 | */ | |
b1eceab6 | 118 | typedef ssize_t (*lldpctl_send_callback)(lldpctl_conn_t *conn, |
4b292b55 VB |
119 | const uint8_t *data, size_t length, void *user_data); |
120 | ||
121 | /** | |
122 | * Callback function invoked to receive data from lldpd. | |
123 | * | |
b35cfd03 | 124 | * @param conn Handle to the connection to lldpd. |
4b292b55 VB |
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 | */ | |
b1eceab6 | 133 | typedef ssize_t (*lldpctl_recv_callback)(lldpctl_conn_t *conn, |
4b292b55 VB |
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 | * | |
b1eceab6 | 142 | * @param conn Handle to the connection to lldpd. |
4b292b55 VB |
143 | * @param data Data received from lldpd. |
144 | * @param length Length of data received. | |
4e90a9e0 VB |
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. | |
4b292b55 | 148 | */ |
b1eceab6 | 149 | ssize_t lldpctl_recv(lldpctl_conn_t *conn, const uint8_t *data, size_t length); |
4b292b55 VB |
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 | * | |
b1eceab6 | 157 | * @param conn Handle to the connection to lldpd. |
4b292b55 | 158 | * @return The number of bytes processed or a negative integer if an error has |
0cddb489 | 159 | * occurred. |
4b292b55 | 160 | */ |
b1eceab6 | 161 | ssize_t lldpctl_send(lldpctl_conn_t *conn); |
4b292b55 | 162 | |
1fa64c11 ST |
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 | ||
4b292b55 VB |
176 | /** |
177 | * Allocate a new handler for connecting to lldpd. | |
178 | * | |
4b292b55 VB |
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 | ||
0262adbb ZM |
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 | ||
4b292b55 VB |
211 | /** |
212 | * Release resources associated with a connection to lldpd. | |
213 | * | |
b1eceab6 | 214 | * @param conn Previously allocated handler to a connection to lldpd. |
4b292b55 VB |
215 | * @return 0 on success or a negative integer |
216 | * | |
217 | * @see lldpctl_new() | |
218 | */ | |
b1eceab6 VB |
219 | int lldpctl_release(lldpctl_conn_t *conn); |
220 | /**@}*/ | |
221 | ||
222 | /** | |
223 | * @defgroup lldpctl_errors_logs Errors and logs handling | |
224 | * | |
94d2efe5 VB |
225 | * Error codes and logs handling. |
226 | * | |
b1eceab6 VB |
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 | |
07ecfcd1 | 234 | * usually means this is an error but some functions may return a legitimate |
b1eceab6 VB |
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)); | |
4b292b55 | 258 | |
2389d2cc VB |
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 | ||
4b292b55 VB |
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 | * | |
b1eceab6 | 349 | * @param conn Previously allocated handler to a connection to lldpd. |
4b292b55 VB |
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 | */ | |
b1eceab6 | 357 | lldpctl_error_t lldpctl_last_error(lldpctl_conn_t *conn); |
4b292b55 VB |
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)) | |
b1eceab6 | 366 | /**@}*/ |
4b292b55 | 367 | |
4b292b55 | 368 | /** |
b1eceab6 VB |
369 | * @defgroup lldpctl_atoms Extracting information: atoms |
370 | * | |
94d2efe5 | 371 | * Information retrieved from lldpd is represented as an atom. |
4b292b55 VB |
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 | * | |
b1eceab6 VB |
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 | * | |
3c5634c1 VB |
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. | |
b1eceab6 VB |
400 | * |
401 | * @{ | |
402 | */ | |
403 | ||
404 | /** | |
405 | * Structure representing an element (chassis, port, VLAN, ...) | |
4b292b55 VB |
406 | * |
407 | * @see lldpctl_atom_inc_ref(), lldpctl_atom_dec_ref(). | |
408 | */ | |
409 | typedef struct lldpctl_atom_t lldpctl_atom_t; | |
410 | ||
6fcf11ca VB |
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 | ||
4b292b55 VB |
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 | * | |
4e90a9e0 | 445 | * When the reference count becomes 0, the atom is freed. |
4b292b55 VB |
446 | */ |
447 | void lldpctl_atom_dec_ref(lldpctl_atom_t *atom); | |
448 | ||
4e90a9e0 | 449 | /** |
b1eceab6 VB |
450 | * Possible events for a change (notification). |
451 | * | |
9d7e82a1 | 452 | * @see lldpctl_watch_callback2 |
4e90a9e0 VB |
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 | * | |
c0363157 | 463 | * @param conn Connection with lldpd. Should not be used. |
4e90a9e0 VB |
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 | * | |
3c5634c1 VB |
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. | |
b1eceab6 | 472 | * |
c0363157 | 473 | * @warning The provided connection should not be used at all. Do not use @c |
cb38337c VB |
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. | |
c0363157 | 476 | * |
b1eceab6 | 477 | * @see lldpctl_watch_callback |
4e90a9e0 VB |
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 | ||
9d7e82a1 VB |
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 | ||
4e90a9e0 VB |
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. | |
09a267fc | 515 | * |
c0363157 | 516 | * @warning Once a callback is registered, the connection shouldn't be used for |
cb38337c VB |
517 | * anything else than receiving notifications. If you do, you will get a @c |
518 | * LLDPCTL_ERR_INVALID_STATE error. | |
9d7e82a1 VB |
519 | * |
520 | * @deprecated This function is deprecated and lldpctl_watch_callback2 should be | |
521 | * used instead. | |
4e90a9e0 VB |
522 | */ |
523 | int lldpctl_watch_callback(lldpctl_conn_t *conn, | |
524 | lldpctl_change_callback cb, | |
9d7e82a1 VB |
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, | |
4e90a9e0 VB |
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 | ||
b1eceab6 VB |
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 | ||
8729d69f VB |
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 | ||
4b292b55 VB |
586 | /** |
587 | * Retrieve the list of available interfaces. | |
588 | * | |
b1eceab6 | 589 | * @param conn Previously allocated handler to a connection to lldpd. |
4b292b55 VB |
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). | |
b1eceab6 VB |
597 | * |
598 | * The list of available ports can be iterated with @ref lldpctl_atom_foreach(). | |
4b292b55 | 599 | */ |
b1eceab6 | 600 | lldpctl_atom_t *lldpctl_get_interfaces(lldpctl_conn_t *conn); |
4b292b55 | 601 | |
99ef55d3 VB |
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 | ||
4b292b55 VB |
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 | |
b1eceab6 | 620 | * atom retrieved from an interation on @c lldpctl_get_interfaces(). |
4b292b55 VB |
621 | * @return Atom related to this port which may be used in subsequent functions. |
622 | * | |
9da663f7 | 623 | * This function may have to do IO to get the information related to the given |
99ef55d3 | 624 | * port. Depending on the IO mode, information may not be available right now |
4b292b55 VB |
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 | ||
9da663f7 VB |
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 | ||
b1eceab6 VB |
647 | /**@}*/ |
648 | ||
4b292b55 VB |
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 | |
28431fae VB |
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. | |
4b292b55 VB |
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 | |
db76b228 VB |
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)). | |
4b292b55 VB |
699 | */ |
700 | typedef enum { | |
8843f168 | 701 | lldpctl_k_config_tx_interval, /**< `(I,WO)` Transmit interval. When set to -1, it is meant to transmit now. */ |
2de09499 | 702 | lldpctl_k_config_receiveonly, /**< `(I)` Receive only mode */ |
28431fae VB |
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 */ | |
b1eceab6 | 705 | lldpctl_k_config_cid_pattern, /**< `(S)` Interface pattern to choose the chassis ID */ |
28431fae VB |
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 */ | |
b1eceab6 VB |
709 | lldpctl_k_config_advertise_version, /**< `(I)` Advertise version */ |
710 | lldpctl_k_config_lldpmed_noinventory, /**< `(I)` Disable LLDP-MED inventory */ | |
7742be39 | 711 | lldpctl_k_config_paused, /**< `(I,WO)` lldpd is paused */ |
486a6133 VB |
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 */ | |
bb37268d | 714 | lldpctl_k_config_ifdescr_update, /**< `(I,WO)` Enable or disable setting interface description */ |
f84199dd | 715 | lldpctl_k_config_iface_promisc, /**< `(I,WO)` Enable or disable promiscuous mode on interfaces */ |
ca838758 | 716 | lldpctl_k_config_chassis_cap_advertise, /**< `(I,WO)` Enable or disable chassis capabilities advertisement */ |
1c2217aa | 717 | lldpctl_k_config_chassis_mgmt_advertise, /**< `(I,WO)` Enable or disable management addresses advertisement */ |
8481f490 | 718 | lldpctl_k_config_cid_string, /**< `(S,WON)` User defined string for the chassis ID */ |
0a78e14f | 719 | lldpctl_k_config_perm_iface_pattern, /**< `(S,WON)` Pattern of permanent interfaces */ |
6f66d108 | 720 | lldpctl_k_config_tx_interval_ms, /**< `(I,WO)` Transmit interval in milliseconds. Set to -1 to transmit now. */ |
4c8e6e37 | 721 | lldpctl_k_config_chassis_cap_override, /**< `(I,WO)` Override chassis capabilities */ |
b1eceab6 | 722 | |
d1dc456f | 723 | lldpctl_k_interface_name = 1000, /**< `(S)` The interface name. */ |
b1eceab6 | 724 | |
d1dc456f | 725 | lldpctl_k_port_name = 1100, /**< `(S)` The port name. Only works for a local port. */ |
b1eceab6 | 726 | lldpctl_k_port_index, /**< `(I)` The port index. Only works for a local port. */ |
4b292b55 | 727 | /** |
b1eceab6 | 728 | * `(AL)` The list of known neighbors for this port. |
4b292b55 VB |
729 | * |
730 | * A neighbor is in fact a remote port. | |
731 | */ | |
d1dc456f | 732 | lldpctl_k_port_neighbors = 1200, |
b1eceab6 VB |
733 | lldpctl_k_port_protocol, /**< `(IS)` The protocol that was used to retrieve this information. */ |
734 | lldpctl_k_port_age, /**< `(I)` Age of information, seconds from epoch. */ | |
735 | lldpctl_k_port_id_subtype, /**< `(IS)` The subtype ID of this port. */ | |
8e46010c | 736 | lldpctl_k_port_id, /**< `(BS,WO)` The ID of this port. */ |
8003e789 | 737 | lldpctl_k_port_descr, /**< `(S,WO)` The description of this port. */ |
b1eceab6 | 738 | lldpctl_k_port_hidden, /**< `(I)` Is this port hidden (or should it be displayed?)? */ |
e7331ce9 | 739 | lldpctl_k_port_status, /**< `(IS,WO)` Operational status of this (local) port */ |
99ef55d3 | 740 | lldpctl_k_port_chassis, /**< `(A)` Chassis associated to the port */ |
78346c89 | 741 | lldpctl_k_port_ttl, /**< `(I)` TTL for port, 0 if info is attached to chassis */ |
1e85286a | 742 | lldpctl_k_port_vlan_tx, /**< `(I,W)` VLAN tag for TX on port, -1 VLAN disabled */ |
b1eceab6 | 743 | |
d1dc456f | 744 | lldpctl_k_port_dot3_mfs = 1300, /**< `(I)` MFS */ |
b1eceab6 VB |
745 | lldpctl_k_port_dot3_aggregid, /**< `(I)` Port aggregation ID */ |
746 | lldpctl_k_port_dot3_autoneg_support, /**< `(I)` Autonegotiation support. */ | |
747 | lldpctl_k_port_dot3_autoneg_enabled, /**< `(I)` Autonegotiation enabled. */ | |
748 | lldpctl_k_port_dot3_autoneg_advertised, /**< `(I)` Advertised protocols. See `LLDP_DOT3_LINK_AUTONEG_*` */ | |
749 | lldpctl_k_port_dot3_mautype, /**< `(IS)` Current MAU type. See `LLDP_DOT3_MAU_*` */ | |
750 | ||
d1dc456f | 751 | lldpctl_k_port_dot3_power = 1400, /**< `(A,WO)` Dot3 power related stuff. */ |
b1eceab6 VB |
752 | lldpctl_k_dot3_power_devicetype, /**< `(IS,W)` Device type. See `LLDP_DOT3_POWER_PSE/PD` */ |
753 | lldpctl_k_dot3_power_supported, /**< `(I,W)` Is MDI power supported. */ | |
754 | lldpctl_k_dot3_power_enabled, /**< `(I,W)` Is MDI power enabled. */ | |
755 | lldpctl_k_dot3_power_paircontrol, /**< `(I,W)` Pair-control enabled? */ | |
756 | lldpctl_k_dot3_power_pairs, /**< `(IS,W)` See `LLDP_DOT3_POWERPAIRS_*` */ | |
757 | lldpctl_k_dot3_power_class, /**< `(IS,W)` Power class. */ | |
758 | lldpctl_k_dot3_power_type, /**< `(I,W)` 802.3AT power type */ | |
759 | lldpctl_k_dot3_power_source, /**< `(IS,W)` 802.3AT power source */ | |
760 | lldpctl_k_dot3_power_priority, /**< `(IS,W)` 802.3AT power priority */ | |
761 | lldpctl_k_dot3_power_allocated, /**< `(I,W)` 802.3AT power allocated */ | |
762 | lldpctl_k_dot3_power_requested, /**< `(I,W)` 802.3AT power requested */ | |
763 | ||
7cfcd3b7 PD |
764 | /* 802.3bt additions */ |
765 | lldpctl_k_dot3_power_pd_4pid, /**< `(IS,W)` 802.3BT both modes supported? */ | |
766 | lldpctl_k_dot3_power_requested_a, /**< `(I,W)` 802.3BT power value requested for A */ | |
767 | lldpctl_k_dot3_power_requested_b, /**< `(I,W)` 802.3BT power value requested for B */ | |
768 | lldpctl_k_dot3_power_allocated_a, /**< `(I,W)` 802.3BT power value allocated for A */ | |
769 | lldpctl_k_dot3_power_allocated_b, /**< `(I,W)` 802.3BT power value allocated for B */ | |
770 | lldpctl_k_dot3_power_pse_status, /**< `(IS,W)` 802.3BT PSE powering status */ | |
771 | lldpctl_k_dot3_power_pd_status, /**< `(IS,W)` 802.3BT PD powering status */ | |
772 | lldpctl_k_dot3_power_pse_pairs_ext, /**< `(IS,W)` 802.3BT PSE power pairs */ | |
773 | lldpctl_k_dot3_power_class_a, /**< `(IS,W)` 802.3BT power class for A */ | |
774 | lldpctl_k_dot3_power_class_b, /**< `(IS,W)` 802.3BT power class for B */ | |
775 | lldpctl_k_dot3_power_class_ext, /**< `(IS,W)` 802.3BT power class */ | |
776 | lldpctl_k_dot3_power_type_ext, /**< `(IS,W)` 802.3BT power type */ | |
777 | lldpctl_k_dot3_power_pd_load, /**< `(IS,W)` 802.3BT dualsig isolated? */ | |
778 | lldpctl_k_dot3_power_pse_max, /**< `(I,W)` 802.3BT maximum available power */ | |
779 | ||
d1dc456f | 780 | lldpctl_k_port_vlan_pvid = 1500, /**< `(I)` Primary VLAN ID */ |
b1eceab6 VB |
781 | lldpctl_k_port_vlans, /**< `(AL)` List of VLAN */ |
782 | lldpctl_k_vlan_id, /**< `(I)` VLAN ID */ | |
783 | lldpctl_k_vlan_name, /**< `(S)` VLAN name */ | |
784 | ||
d1dc456f | 785 | lldpctl_k_port_ppvids = 1600, /**< `(AL)` List of PPVIDs */ |
b1eceab6 VB |
786 | lldpctl_k_ppvid_status, /**< `(I)` Status of PPVID (see `LLDP_PPVID_CAP_*`) */ |
787 | lldpctl_k_ppvid_id, /**< `(I)` ID of PPVID */ | |
788 | ||
d1dc456f | 789 | lldpctl_k_port_pis = 1700, /**< `(AL)` List of PIDs */ |
b1eceab6 VB |
790 | lldpctl_k_pi_id, /**< `(B)` PID value */ |
791 | ||
d1dc456f | 792 | lldpctl_k_chassis_index = 1800, /**< `(I)` The chassis index. */ |
b1eceab6 VB |
793 | lldpctl_k_chassis_id_subtype, /**< `(IS)` The subtype ID of this chassis. */ |
794 | lldpctl_k_chassis_id, /**< `(BS)` The ID of this chassis. */ | |
795 | lldpctl_k_chassis_name, /**< `(S)` The name of this chassis. */ | |
796 | lldpctl_k_chassis_descr, /**< `(S)` The description of this chassis. */ | |
4c8e6e37 | 797 | lldpctl_k_chassis_cap_available, /**< `(I)` Available capabilities (see `LLDP_CAP_*`) */ |
b1eceab6 VB |
798 | lldpctl_k_chassis_cap_enabled, /**< `(I)` Enabled capabilities (see `LLDP_CAP_*`) */ |
799 | lldpctl_k_chassis_mgmt, /**< `(AL)` List of management addresses */ | |
71b0f981 | 800 | lldpctl_k_chassis_ttl, /**< Deprecated */ |
b1eceab6 | 801 | |
d1dc456f | 802 | lldpctl_k_chassis_med_type = 1900, /**< `(IS)` Chassis MED type. See `LLDP_MED_CLASS_*` */ |
4c8e6e37 | 803 | lldpctl_k_chassis_med_cap, /**< `(I)` Available MED capabilities. See `LLDP_MED_CAP_*` */ |
8ef9c766 HG |
804 | lldpctl_k_chassis_med_inventory_hw, /**< `(S,W)` LLDP MED inventory "Hardware Revision" */ |
805 | lldpctl_k_chassis_med_inventory_sw, /**< `(S,W)` LLDP MED inventory "Software Revision" */ | |
806 | lldpctl_k_chassis_med_inventory_fw, /**< `(S,W)` LLDP MED inventory "Firmware Revision" */ | |
807 | lldpctl_k_chassis_med_inventory_sn, /**< `(S,W)` LLDP MED inventory "Serial Number" */ | |
808 | lldpctl_k_chassis_med_inventory_manuf, /**< `(S,W)` LLDP MED inventory "Manufacturer" */ | |
809 | lldpctl_k_chassis_med_inventory_model, /**< `(S,W)` LLDP MED inventory "Model" */ | |
810 | lldpctl_k_chassis_med_inventory_asset, /**< `(S,W)` LLDP MED inventory "Asset ID" */ | |
b1eceab6 | 811 | |
d1dc456f | 812 | lldpctl_k_port_med_policies = 2000, /**< `(AL,WO)` MED policies attached to a port. */ |
b1eceab6 VB |
813 | lldpctl_k_med_policy_type, /**< `(IS,W)` MED policy app type. See `LLDP_MED_APPTYPE_*`. 0 if a policy is not defined. */ |
814 | lldpctl_k_med_policy_unknown, /**< `(I,W)` Is MED policy defined? */ | |
815 | lldpctl_k_med_policy_tagged, /**< `(I,W)` MED policy tagging */ | |
816 | lldpctl_k_med_policy_vid, /**< `(I,W)` MED policy VID */ | |
817 | lldpctl_k_med_policy_priority, /**< `(I,W)` MED policy priority */ | |
818 | lldpctl_k_med_policy_dscp, /**< `(I,W)` MED policy DSCP */ | |
819 | ||
d1dc456f | 820 | lldpctl_k_port_med_locations = 2100, /**< `(AL,WO)` MED locations attached to a port. */ |
b1eceab6 VB |
821 | lldpctl_k_med_location_format, /**< `(IS,W)` MED location format. See |
822 | * `LLDP_MED_LOCFORMAT_*`. 0 if this | |
4b292b55 VB |
823 | * location is not defined. When written, |
824 | * the following fields will be zeroed | |
825 | * out. */ | |
b1eceab6 VB |
826 | lldpctl_k_med_location_geoid, /**< `(IS,W)` MED geoid. See `LLDP_MED_LOCATION_GEOID_*`. Only if format is COORD. */ |
827 | lldpctl_k_med_location_latitude, /**< `(S,W)` MED latitude. Only if format is COORD. */ | |
828 | lldpctl_k_med_location_longitude, /**< `(S,W)` MED longitude. Only if format is COORD. */ | |
829 | lldpctl_k_med_location_altitude, /**< `(S,W)` MED altitude. Only if format is COORD. */ | |
830 | lldpctl_k_med_location_altitude_unit, /**< `(S,W)` MED altitude unit. See `LLDP_MED_LOCATION_ALTITUDE_UNIT_*`. | |
4b292b55 VB |
831 | * Only if format is COORD. */ |
832 | ||
d1dc456f | 833 | lldpctl_k_med_location_country = 2200, /**< `(S,W)` MED country. Only if format is CIVIC. */ |
b1eceab6 | 834 | lldpctl_k_med_location_elin, /**< `(S,W)` MED ELIN. Only if format is ELIN. */ |
4b292b55 | 835 | |
d1dc456f | 836 | lldpctl_k_med_location_ca_elements = 2300, /**< `(AL,WC)` MED civic address elements. Only if format is CIVIC */ |
b1eceab6 VB |
837 | lldpctl_k_med_civicaddress_type, /**< `(IS,W)` MED civic address type. */ |
838 | lldpctl_k_med_civicaddress_value, /**< `(S,W)` MED civic address value. */ | |
4b292b55 | 839 | |
d1dc456f | 840 | lldpctl_k_port_med_power = 2400, /**< `(A,WO)` LLDP-MED power related stuff. */ |
b1eceab6 VB |
841 | lldpctl_k_med_power_type, /**< `(IS,W)` LLDP MED power device type. See `LLDP_MED_POW_TYPE_*` */ |
842 | lldpctl_k_med_power_source, /**< `(IS,W)` LLDP MED power source. See `LLDP_MED_POW_SOURCE_*` */ | |
843 | lldpctl_k_med_power_priority, /**< `(IS,W)` LLDP MED power priority. See `LLDP_MED_POW_PRIO_*` */ | |
844 | lldpctl_k_med_power_val, /**< `(I,W)` LLDP MED power value */ | |
4b292b55 | 845 | |
d1dc456f | 846 | lldpctl_k_mgmt_ip = 3000, /**< `(S)` IP address */ |
d319b0de | 847 | lldpctl_k_mgmt_iface_index = 30001, /**< `(I)` Interface index */ |
78356144 | 848 | |
d1dc456f | 849 | lldpctl_k_tx_cnt = 4000, /**< `(I)` tx cnt. Only works for a local port. */ |
78356144 | 850 | lldpctl_k_rx_cnt, /**< `(I)` rx cnt. Only works for a local port. */ |
851 | lldpctl_k_rx_discarded_cnt, /**< `(I)` discarded cnt. Only works for a local port. */ | |
852 | lldpctl_k_rx_unrecognized_cnt, /**< `(I)` unrecognized cnt. Only works for a local port. */ | |
853 | lldpctl_k_ageout_cnt, /**< `(I)` ageout cnt. Only works for a local port. */ | |
854 | lldpctl_k_insert_cnt, /**< `(I)` insert cnt. Only works for a local port. */ | |
855 | lldpctl_k_delete_cnt, /**< `(I)` delete cnt. Only works for a local port. */ | |
c10302a3 | 856 | lldpctl_k_config_tx_hold, /**< `(I,WO)` Transmit hold interval. */ |
dfbd7185 | 857 | lldpctl_k_config_bond_slave_src_mac_type, /**< `(I,WO)` bond slave src mac type. */ |
8fbd3195 | 858 | lldpctl_k_config_lldp_portid_type, /**< `(I,WO)` LLDP PortID TLV Subtype */ |
1eadc9a1 | 859 | lldpctl_k_config_lldp_agent_type, /**< `(I,WO)` LLDP agent type */ |
ba1bdf6a | 860 | lldpctl_k_config_max_neighbors, /**< `(I,WO)`Maximum number of neighbors per port. */ |
c576fd21 AA |
861 | |
862 | lldpctl_k_custom_tlvs = 5000, /**< `(AL)` custom TLVs */ | |
7064f06b VB |
863 | lldpctl_k_custom_tlvs_clear, /**< `(WO)` clear list of custom TLVs */ |
864 | lldpctl_k_custom_tlv, /**< `(AL,WO)` custom TLV **/ | |
865 | lldpctl_k_custom_tlv_oui, /**< `(B,W)` custom TLV Organizationally Unique Identifier. Default is 0 (3 bytes) */ | |
866 | lldpctl_k_custom_tlv_oui_subtype, /**< `(I,W)` custom TLV subtype. Default is 0 (1 byte) */ | |
867 | lldpctl_k_custom_tlv_oui_info_string, /**< `(BS,W)` custom TLV Organizationally Unique Identifier Information String (up to 507 bytes) */ | |
868 | lldpctl_k_custom_tlv_op, /**< `(S,W)` custom TLV operation */ | |
c576fd21 | 869 | |
4b292b55 VB |
870 | } lldpctl_key_t; |
871 | ||
6fcf11ca VB |
872 | /** |
873 | * Get a map related to a key. | |
874 | * | |
875 | * Many keys expect to be written with a discrete number of values. Take for | |
876 | * example @c lldpctl_k_med_civicaddress_type, it can take any integer between 1 | |
877 | * and 128. However, each integer can be named. It can be useful for an | |
878 | * application to get a translation between the integer that can be provided and | |
879 | * a more human-readable name. This function allows to retrieve the | |
880 | * corresponding map. | |
881 | * | |
882 | * @param key The piece of information we want a map from. | |
9cac8fed | 883 | * @return The map or @c NULL if no map is available. |
6fcf11ca VB |
884 | * |
885 | * The returned map has its last element set to 0. It is also expected that the | |
886 | * string value can be used with a set operation. It will be translated to the | |
887 | * integer value. | |
888 | */ | |
889 | lldpctl_map_t *lldpctl_key_get_map(lldpctl_key_t key); | |
890 | ||
4b292b55 VB |
891 | /** |
892 | * Retrieve a bit of information as an atom. | |
893 | * | |
894 | * @param atom The atom we want to query. | |
895 | * @param key The information we want from the atom. | |
896 | * @return The atom representing the requested information or @c NULL if the | |
897 | * information is not available. | |
898 | * | |
899 | * Not every value of @c info will be available as an atom. See the | |
900 | * documentation of @c lldpctl_key_t for values accepting to be extracted as an | |
901 | * atom. Usually, this is only iterable values or values representing a complex | |
902 | * object. | |
903 | * | |
904 | * The provided atom is not a _borrowed_ reference. You need to decrement the | |
905 | * reference count when you don't need it anymore. | |
906 | * | |
907 | * As a convenience, this function will return @c NULL if the first parameter is | |
908 | * @c NULL and no error will be raised. | |
909 | */ | |
910 | lldpctl_atom_t *lldpctl_atom_get(lldpctl_atom_t *atom, lldpctl_key_t key); | |
911 | ||
912 | /** | |
913 | * Set a bit of information with an atom. | |
914 | * | |
915 | * @param atom The atom we want to write to. | |
916 | * @param key The key information we want to write. | |
917 | * @param value The value of the information we want to write. | |
918 | * @return The updated atom with the appropriate information. | |
919 | * | |
920 | * This function will return @c NULL in case of error. If the last error is @c | |
921 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
922 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
923 | * correct. | |
924 | */ | |
925 | lldpctl_atom_t *lldpctl_atom_set(lldpctl_atom_t *atom, lldpctl_key_t key, | |
926 | lldpctl_atom_t *value); | |
927 | ||
928 | /** | |
929 | * Retrieve a bit of information as a null-terminated string. | |
930 | * | |
931 | * @param atom The atom we want to query. | |
932 | * @param key The information we want from the atom. | |
933 | * @return The requested string or @c NULL if the information is not available. | |
934 | * | |
935 | * Not every value of @c info will be available as a string. See the | |
936 | * documentation of @c lldpctl_key_t for values accepting to be extracted as a | |
937 | * string. Usually, only piece of information stored as string are available in | |
938 | * this form but sometimes, you can get a nice formatted string instead of an | |
939 | * integer with this function. | |
940 | * | |
941 | * As a convenience, this function will return @c NULL if the first parameter is | |
942 | * @c NULL and no error will be raised. | |
943 | * | |
944 | * The provided string may live inside the atom providing it. If you need it | |
945 | * longer, duplicate it. | |
946 | */ | |
947 | const char *lldpctl_atom_get_str(lldpctl_atom_t *atom, lldpctl_key_t key); | |
948 | ||
949 | /** | |
950 | * Set a bit of information using a null-terminated string. | |
951 | * | |
952 | * @param atom The atom we want to write to. | |
953 | * @param key The key information we want to write. | |
954 | * @param value The value of the information we want to write. | |
955 | * @return The updated atom with the appropriate information. | |
956 | * | |
957 | * This function will return @c NULL in case of error. If the last error is @c | |
958 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
959 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
960 | * correct. | |
961 | */ | |
962 | lldpctl_atom_t *lldpctl_atom_set_str(lldpctl_atom_t *atom, lldpctl_key_t key, | |
963 | const char *value); | |
964 | ||
965 | /** | |
966 | * Retrieve a bit of information as a buffer. | |
967 | * | |
968 | * @param atom The atom we want to query. | |
969 | * @param key The information we want from the atom. | |
b1eceab6 | 970 | * @param[out] length The size of the returned buffer. |
4b292b55 VB |
971 | * @return The requested buffer or @c NULL if the information is not available. |
972 | * | |
973 | * Not every value of @c info will be available as a buffer. See the | |
974 | * documentation of @c lldpctl_key_t for values accepting to be extracted as a | |
975 | * string. Usually, only piece of information stored as buffer are available in | |
976 | * this form. | |
977 | * | |
978 | * As a convenience, this function will return @c NULL if the first parameter is | |
979 | * @c NULL and no error will be raised. If this function returns @c NULL, the | |
980 | * third parameter is set to 0. | |
981 | * | |
982 | * The provided buffer may live inside the atom providing it. If you need it | |
983 | * longer, duplicate it. | |
984 | */ | |
ae5cae02 | 985 | const uint8_t *lldpctl_atom_get_buffer(lldpctl_atom_t *atom, lldpctl_key_t key, |
4b292b55 VB |
986 | size_t *length); |
987 | ||
988 | /** | |
989 | * Set a bit of information using a buffer | |
990 | * | |
991 | * @param atom The atom we want to write to. | |
992 | * @param key The key information we want to write. | |
993 | * @param value The value of the information we want to write. | |
994 | * @param length The length of the provided buffer. | |
995 | * @return The updated atom with the appropriate information. | |
996 | * | |
997 | * This function will return @c NULL in case of error. If the last error is @c | |
998 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
999 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
1000 | * correct. | |
1001 | */ | |
1002 | lldpctl_atom_t *lldpctl_atom_set_buffer(lldpctl_atom_t *atom, lldpctl_key_t key, | |
ae5cae02 | 1003 | const uint8_t *value, size_t length); |
4b292b55 VB |
1004 | |
1005 | /** | |
1006 | * Retrieve a bit of information as an integer. | |
1007 | * | |
1008 | * @param atom The atom we want to query. | |
1009 | * @param key The information we want from the atom. | |
1010 | * @return The requested integer or -1 if the information is not available | |
1011 | * | |
1012 | * Not every value of @c info will be available as an integer. See the | |
1013 | * documentation of @c lldpctl_key_t for values accepting to be extracted as a | |
1014 | * string. Usually, only piece of information stored as an integer are available | |
1015 | * in this form. | |
1016 | * | |
1017 | * Only @c lldpctl_last_error() can tell if the returned value is an error or | |
1018 | * not. However, most values extracted from lldpd cannot be negative. | |
1019 | */ | |
1020 | long int lldpctl_atom_get_int(lldpctl_atom_t *atom, lldpctl_key_t key); | |
1021 | ||
1022 | /** | |
1023 | * Set a bit of information using an integer | |
1024 | * | |
1025 | * @param atom The atom we want to write to. | |
1026 | * @param key The key information we want to write. | |
1027 | * @param value The value of the information we want to write. | |
1028 | * @return The updated atom with the appropriate information. | |
1029 | * | |
1030 | * This function will return @c NULL in case of error. If the last error is @c | |
1031 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
1032 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
1033 | * correct. | |
1034 | */ | |
1035 | lldpctl_atom_t *lldpctl_atom_set_int(lldpctl_atom_t *atom, lldpctl_key_t key, | |
1036 | long int value); | |
1037 | ||
b1eceab6 VB |
1038 | /** |
1039 | * @defgroup liblldpctl_atom_iter Iterating over atoms | |
1040 | * | |
1041 | * Iterate over atoms (lists). | |
1042 | * | |
1043 | * @{ | |
1044 | */ | |
4b292b55 VB |
1045 | /** |
1046 | * Iterator over an iterable atom (a list of ports, a list of VLAN, ...). When | |
1047 | * an atom is a list, it can be iterated over to extract the appropriate values. | |
1048 | * | |
1049 | * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(), lldpctl_atom_iter_value() | |
1050 | */ | |
1051 | typedef struct lldpctl_atom_iter_t lldpctl_atom_iter_t; | |
1052 | ||
1053 | /** | |
1054 | * Return an iterator over a given atom. | |
1055 | * | |
1056 | * If an atom is iterable (if it is a list, like a list of ports, a list of | |
1057 | * VLAN, a list of neighbors), it is possible to iterate over it. First use this | |
1058 | * function to get an iterator then use @c lldpctl_atom_iter_next() to get the | |
1059 | * next item and @c lldpctl_atom_iter_value() to the actuel item. | |
1060 | * | |
1061 | * @param atom The atom we want to create an iterator from. | |
1062 | * @return The iterator or @c NULL if an error happened or if the atom is empty | |
1063 | * (check with @c lldpctl_last_error()). | |
1064 | * | |
1065 | * As a convenience, if the provided atom is @c NULL, this function will return | |
1066 | * @c NULL and no error will be raised. | |
1067 | */ | |
1068 | lldpctl_atom_iter_t *lldpctl_atom_iter(lldpctl_atom_t *atom); | |
1069 | ||
1070 | /** | |
1071 | * Return the next element of an iterator. | |
1072 | * | |
1073 | * @param atom The atom we are currently iterating. | |
1074 | * @param iter The iterator we want the next element from. | |
1075 | * @return An iterator starting on the next element or @c NULL if we have no | |
1076 | * more elements | |
1077 | * | |
1078 | * @see lldpctl_atom_iter(), lldpctl_atom_iter_value(). | |
1079 | * | |
1080 | * As a convenience, if the provided atom is @c NULL, this function will return | |
1081 | * @c NULL and no error will be raised. | |
1082 | */ | |
1083 | lldpctl_atom_iter_t *lldpctl_atom_iter_next(lldpctl_atom_t *atom, lldpctl_atom_iter_t *iter); | |
1084 | ||
1085 | /** | |
1086 | * Return the value of an iterator. | |
1087 | * | |
1088 | * @param atom The atom we are currently iterating. | |
1089 | * @param iter The iterator we want the next element from. | |
1090 | * @return The atom currently associated with the iterator. | |
1091 | * | |
1092 | * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(). | |
1093 | */ | |
1094 | lldpctl_atom_t *lldpctl_atom_iter_value(lldpctl_atom_t *atom, lldpctl_atom_iter_t *iter); | |
1095 | ||
1096 | /** | |
1097 | * Convenience macro to iter over every value of an iterable object. | |
1098 | * | |
1099 | * @param atom The atom you want to iterate on. | |
3c5634c1 | 1100 | * @param value Atom name that will be used to contain each value. |
4b292b55 | 1101 | * |
3c5634c1 VB |
1102 | * This macro behaves as a for loop. Moreover, at the end of each iteration, the |
1103 | * reference count of the provided value is decremented. If you need to use it | |
1104 | * outside of the loop, you need to increment it. | |
4b292b55 | 1105 | */ |
0ca21286 VB |
1106 | #define lldpctl_atom_foreach(atom, value) \ |
1107 | for (lldpctl_atom_iter_t *iter##_LINE_ = lldpctl_atom_iter(atom); \ | |
1108 | iter##_LINE_ && (value = lldpctl_atom_iter_value(atom, iter##_LINE_)); \ | |
1109 | iter##_LINE_ = lldpctl_atom_iter_next(atom, iter##_LINE_), \ | |
4b292b55 VB |
1110 | lldpctl_atom_dec_ref(value)) |
1111 | ||
1112 | /** | |
1113 | * Create a new value for an iterable element. | |
1114 | * | |
1115 | * The value is meant to be appended using @c lldpctl_atom_set(). Currently, | |
1116 | * there is no way to delete an element from a list. It is also not advisable to | |
1117 | * use getters on a newly created object until it is fully initialized. If its | |
1118 | * internal representation is using a buffer, it may not be initialized until | |
1119 | * the first set. | |
1120 | * | |
1121 | * @param atom The atom we want to create a new element for. | |
1122 | * @return The new element. | |
1123 | */ | |
1124 | lldpctl_atom_t *lldpctl_atom_create(lldpctl_atom_t *atom); | |
b1eceab6 VB |
1125 | /**@}*/ |
1126 | /**@}*/ | |
4b292b55 VB |
1127 | |
1128 | #ifdef __cplusplus | |
1129 | } | |
1130 | #endif | |
1131 | ||
b1eceab6 VB |
1132 | /**@}*/ |
1133 | ||
4b292b55 | 1134 | #endif |