]>
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 | /** | |
22 | * @section liblldpctl Interfacing with lldpd | |
23 | * | |
24 | * Interfacing with a running instance of lldpd can be done through liblldpctl | |
25 | * library. | |
26 | */ | |
27 | ||
28 | #ifdef __cplusplus | |
29 | extern "C" { | |
30 | #endif | |
31 | ||
32 | #include <stdlib.h> | |
33 | #include <stdint.h> | |
34 | #include <sys/types.h> | |
35 | ||
36 | /** | |
37 | * Get default transport name. | |
38 | * | |
39 | * Currently, this is the default location of the Unix socket. | |
40 | */ | |
41 | const char* lldpctl_get_default_transport(void); | |
42 | ||
43 | /** | |
44 | * Setup log handlers. | |
45 | * | |
46 | * By default, liblldpctl will log to stderr. The following function will | |
47 | * register another callback for this purpose. Messages logged through this | |
48 | * callback may be cryptic. They are targeted for the developer. Message for end | |
49 | * users should rely on return codes. | |
50 | */ | |
51 | void lldpctl_log_callback(void (*cb)(int severity, const char *msg)); | |
52 | ||
53 | /*@{*/ | |
54 | /** | |
55 | * Structure referencing a connection with lldpd. | |
56 | * | |
57 | * This structure should be handled as opaque. It can be allocated | |
58 | * with @c lldpctl_new() and the associated resources will be freed | |
59 | * with @c lldpctl_release(). | |
60 | */ | |
61 | typedef struct lldpctl_conn_t lldpctl_conn_t; | |
62 | ||
63 | /** | |
64 | * Callback function invoked to send data to lldpd. | |
65 | * | |
66 | * @param lldpctl Handle to the connection to lldpd. | |
67 | * @param data Bytes to be sent. | |
68 | * @param length Length of provided data. | |
69 | * @param user_data Provided user data. | |
70 | * @return The number of bytes really sent or either @c LLDPCTL_ERR_WOULDBLOCK | |
71 | * if no bytes can be sent without blocking or @c | |
72 | * LLDPCTL_ERR_CALLBACK_FAILURE for other errors. | |
73 | */ | |
74 | typedef ssize_t (*lldpctl_send_callback)(lldpctl_conn_t *lldpctl, | |
75 | const uint8_t *data, size_t length, void *user_data); | |
76 | ||
77 | /** | |
78 | * Callback function invoked to receive data from lldpd. | |
79 | * | |
80 | * @param lldpctl Handle to the connection to lldpd. | |
81 | * @param data Buffer for receiving data | |
82 | * @param length Maximum bytes we can receive | |
83 | * @param user_data Provided user data. | |
84 | * @return The number of bytes really received or either @c | |
85 | * LLDPCTL_ERR_WOULDBLOCK if no bytes can be received without blocking, | |
86 | * @c LLDPCTL_ERR_CALLBACK_FAILURE for other errors or @c | |
87 | * LLDPCTL_ERR_EOF if end of file was reached. | |
88 | */ | |
89 | typedef ssize_t (*lldpctl_recv_callback)(lldpctl_conn_t *lldpctl, | |
90 | const uint8_t *data, size_t length, void *user_data); | |
91 | ||
92 | /** | |
93 | * Function invoked when additional data is available from lldpd. | |
94 | * | |
95 | * This function should be invoked in case of asynchronous IO when new data is | |
96 | * available from lldpd (expected or unexpected). | |
97 | * | |
98 | * @param lldpctl Handle to the connection to lldpd. | |
99 | * @param data Data received from lldpd. | |
100 | * @param length Length of data received. | |
4e90a9e0 VB |
101 | * @return The number of bytes available or a negative integer if an error has |
102 | * occurred. 0 is not an error. It usually means that a notification has | |
103 | * been processed. | |
4b292b55 VB |
104 | */ |
105 | ssize_t lldpctl_recv(lldpctl_conn_t *lldpctl, const uint8_t *data, size_t length); | |
106 | ||
107 | /** | |
108 | * Function invoked when there is an opportunity to send data to lldpd. | |
109 | * | |
110 | * This function should be invoked in case of asynchronous IO when new data can | |
111 | * be written to lldpd. | |
112 | * | |
113 | * @param lldpctl Handle to the connection to lldpd. | |
114 | * @return The number of bytes processed or a negative integer if an error has | |
115 | * occured. | |
116 | */ | |
117 | ssize_t lldpctl_send(lldpctl_conn_t *lldpctl); | |
118 | ||
119 | /** | |
120 | * Allocate a new handler for connecting to lldpd. | |
121 | * | |
122 | * This library does not handle IO. They are delegated to a set of functions to | |
123 | * allow a user to specify exactly how IO should be done. This open the | |
124 | * possibility to query a remote lldpd through SSH for example. A user is | |
125 | * expected to provide two functions: the first one is called when the library | |
126 | * requests incoming data, the other one when it requests outgoing | |
127 | * data. Moreover, the user is also expected to call the appropriate functions | |
128 | * when data comes back or is effectively sent (in case of asynchronous IO). | |
129 | * | |
130 | * @param send Callback to be used when sending new data is requested. | |
131 | * @param recv Callback to be used when receiving new data is requested. | |
132 | * @param user_data Data to pass to callbacks. | |
133 | * @return An handler to be used to connect to lldpd or @c NULL in | |
134 | * case of error. In the later case, the error is probable an | |
135 | * out of memory condition. | |
136 | * | |
137 | * The allocated handler can be released with @c lldpctl_release(). If the | |
138 | * provided parameters are both @c NULL, default synchronous callbacks will be | |
139 | * used. | |
140 | */ | |
141 | lldpctl_conn_t *lldpctl_new(lldpctl_send_callback send, | |
142 | lldpctl_recv_callback recv, void *user_data); | |
143 | ||
144 | /** | |
145 | * Release resources associated with a connection to lldpd. | |
146 | * | |
147 | * @param lldpctl Previously allocated handler to a connection to lldpd. | |
148 | * @return 0 on success or a negative integer | |
149 | * | |
150 | * @see lldpctl_new() | |
151 | */ | |
152 | int lldpctl_release(lldpctl_conn_t *lldpctl); | |
153 | /*@}*/ | |
154 | ||
155 | /*@{*/ | |
156 | /** | |
157 | * Possible error codes for functions that return negative integers on | |
158 | * this purpose or for @c lldpctl_last_error(). | |
159 | */ | |
160 | typedef enum { | |
161 | /** | |
162 | * No error has happened (yet). | |
163 | */ | |
164 | LLDPCTL_NO_ERROR = 0, | |
165 | /** | |
166 | * A IO related operation would block if performed. | |
167 | */ | |
168 | LLDPCTL_ERR_WOULDBLOCK = -501, | |
169 | /** | |
170 | * A IO related operation has reached a end of file condition. | |
171 | */ | |
172 | LLDPCTL_ERR_EOF = -502, | |
173 | /** | |
174 | * The requested information does not exist. For example, when | |
175 | * requesting an inexistant information from an atom. | |
176 | */ | |
177 | LLDPCTL_ERR_NOT_EXIST = -503, | |
178 | /** | |
179 | * Cannot connect to the lldpd daemon. This error only happens with | |
180 | * default synchronous handlers. | |
181 | */ | |
182 | LLDPCTL_ERR_CANNOT_CONNECT = -504, | |
183 | /** | |
184 | * Atom is of incorrect type for the requested operation. | |
185 | */ | |
186 | LLDPCTL_ERR_INCORRECT_ATOM_TYPE = -505, | |
187 | /** | |
188 | * An error occurred during serialization of message. | |
189 | */ | |
190 | LLDPCTL_ERR_SERIALIZATION = -506, | |
191 | /** | |
192 | * The requested operation cannot be performed because we have another | |
193 | * operation already running. | |
194 | */ | |
195 | LLDPCTL_ERR_INVALID_STATE = -507, | |
196 | /** | |
197 | * The provided atom cannot be iterated. | |
198 | */ | |
199 | LLDPCTL_ERR_CANNOT_ITERATE = -508, | |
200 | /** | |
201 | * The provided value is invalid. | |
202 | */ | |
203 | LLDPCTL_ERR_BAD_VALUE = -509, | |
204 | /** | |
205 | * No new element can be created for this element. | |
206 | */ | |
207 | LLDPCTL_ERR_CANNOT_CREATE = -510, | |
208 | /** | |
209 | * The library is under unexpected conditions and cannot process | |
210 | * any further data reliably. | |
211 | */ | |
212 | LLDPCTL_ERR_FATAL = -900, | |
213 | /** | |
214 | * Out of memory condition. Things may get havoc here but we | |
215 | * should be able to recover. | |
216 | */ | |
217 | LLDPCTL_ERR_NOMEM = -901, | |
218 | /** | |
219 | * An error occurred in a user provided callback. | |
220 | */ | |
221 | LLDPCTL_ERR_CALLBACK_FAILURE = -902 | |
222 | } lldpctl_error_t; | |
223 | ||
224 | /** | |
225 | * Describe a provided error code. | |
226 | * | |
227 | * @param error Error code to be described. | |
228 | * @return Statically allocated string describing the error. | |
229 | */ | |
230 | const char *lldpctl_strerror(lldpctl_error_t error); | |
231 | ||
232 | /** | |
233 | * Get the last error associated to a connection to lldpd. | |
234 | * | |
235 | * @param lldpctl Previously allocated handler to a connection to lldpd. | |
236 | * @return 0 if no error is currently registered. A negative integer | |
237 | * otherwise. | |
238 | * | |
239 | * For functions returning int, this function will return the same | |
240 | * error number. For functions returning something else, you can use | |
241 | * this function to get the appropriate error number. | |
242 | */ | |
243 | lldpctl_error_t lldpctl_last_error(lldpctl_conn_t *lldpctl); | |
244 | ||
245 | /** | |
246 | * Describe the last error associate to a connection. | |
247 | * | |
248 | * @param conn Previously allocated handler to a connection to lldpd. | |
249 | * @return Statically allocated string describing the error | |
250 | */ | |
251 | #define lldpctl_last_strerror(conn) lldpctl_strerror(lldpctl_last_error(conn)) | |
252 | /*@}*/ | |
253 | ||
254 | /*@{*/ | |
255 | /** | |
256 | * Structure representing an element (chassis, port, VLAN, ...) | |
257 | * | |
258 | * This is an opaque structure that can be passed along some functions to | |
259 | * transmit chassis, ports, VLAN and other information related to LLDP. Most | |
260 | * information are extracted using @c lldpctl_atom_get(), @c | |
261 | * lldpctl_atom_get_str(), @c lldpctl_atom_get_buffer() or @c | |
262 | * lldpctl_atom_get_int(), unless some IO with lldpd is needed to retrieve the | |
263 | * requested information. In this case, there exists an appropriate function to | |
264 | * convert the "deferred" atom into a normal one (like @c lldpctl_get_port()). | |
265 | * | |
266 | * An atom is reference counted. Unless documented otherwise, a function | |
267 | * returning an atom will return a new reference that should be decremented if | |
268 | * not used anymore. | |
269 | * | |
270 | * @see lldpctl_atom_inc_ref(), lldpctl_atom_dec_ref(). | |
271 | */ | |
272 | typedef struct lldpctl_atom_t lldpctl_atom_t; | |
273 | ||
274 | /** | |
275 | * Return the reference to connection with lldpd. | |
276 | * | |
277 | * @param atom The atom we want reference from. | |
278 | * @return The reference to the connection to lldpd. | |
279 | * | |
280 | * Each atom contains an internal reference to the corresponding connection to | |
281 | * lldpd. Use this function to get it. | |
282 | */ | |
283 | lldpctl_conn_t *lldpctl_atom_get_connection(lldpctl_atom_t *atom); | |
284 | ||
285 | /** | |
286 | * Increment reference count for an atom. | |
287 | * | |
288 | * @param atom Atom we which to increase reference count. | |
289 | */ | |
290 | void lldpctl_atom_inc_ref(lldpctl_atom_t *atom); | |
291 | ||
292 | /** | |
293 | * Decrement reference count for an atom. | |
294 | * | |
295 | * @param atom Atom we want to decrease reference count. Can be @c NULL. In this | |
296 | * case, nothing happens. | |
297 | * | |
4e90a9e0 | 298 | * When the reference count becomes 0, the atom is freed. |
4b292b55 VB |
299 | */ |
300 | void lldpctl_atom_dec_ref(lldpctl_atom_t *atom); | |
301 | ||
4e90a9e0 VB |
302 | /** |
303 | * Possible events for a change. | |
304 | */ | |
305 | typedef enum { | |
306 | lldpctl_c_deleted, /**< The neighbor has been deleted */ | |
307 | lldpctl_c_updated, /**< The neighbor has been updated */ | |
308 | lldpctl_c_added, /**< This is a new neighbor */ | |
309 | } lldpctl_change_t; | |
310 | ||
311 | /** | |
312 | * Callback function invoked when a change is detected. | |
313 | * | |
314 | * @param conn Connection with lldpd. | |
315 | * @param type Type of change detected. | |
316 | * @param interface Physical interface on which the change has happened. | |
317 | * @param neighbor Changed neighbor. | |
318 | * @param data Data provided when registering the callback. | |
319 | * | |
320 | * The provided interface and neighbor atoms will have their reference count | |
321 | * decremented when the callback ends. If you want to keep a reference to it, be | |
322 | * sure to increment the reference count in the callback. | |
323 | */ | |
324 | typedef void (*lldpctl_change_callback)(lldpctl_conn_t *conn, | |
325 | lldpctl_change_t type, | |
326 | lldpctl_atom_t *interface, | |
327 | lldpctl_atom_t *neighbor, | |
328 | void *data); | |
329 | ||
330 | /** | |
331 | * Register a callback to be called on changes. | |
332 | * | |
333 | * @param conn Connection with lldpd. | |
334 | * @param cb Replace the current callback with the provided one. | |
335 | * @param data Data that will be passed to the callback. | |
336 | * @return 0 in case of success or -1 in case of errors. | |
337 | * | |
338 | * This function will register the necessity to push neighbor changes to lldpd | |
339 | * and therefore will issue IO operations. The error code could then be @c | |
340 | * LLDPCTL_ERR_WOULDBLOCK. | |
341 | */ | |
342 | int lldpctl_watch_callback(lldpctl_conn_t *conn, | |
343 | lldpctl_change_callback cb, | |
344 | void *data); | |
345 | ||
346 | /** | |
347 | * Wait for the next change. | |
348 | * | |
349 | * @param conn Connection with lldpd. | |
350 | * @return 0 on success or a negative integer in case of error. | |
351 | * | |
352 | * This function will return once a change has been detected. It is only useful | |
353 | * as a main loop when using the builtin blocking IO mechanism. | |
354 | */ | |
355 | int lldpctl_watch(lldpctl_conn_t *conn); | |
356 | ||
4b292b55 VB |
357 | /** |
358 | * Retrieve the list of available interfaces. | |
359 | * | |
360 | * @param lldpctl Previously allocated handler to a connection to lldpd. | |
361 | * @return The list of available ports or @c NULL if an error happened. | |
362 | * | |
363 | * This function will make IO with the daemon to get the list of | |
364 | * ports. Depending on the IO model, information may not be available right now | |
365 | * and the function should be called again later. If @c NULL is returned, check | |
366 | * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later | |
367 | * (when more data is available). | |
368 | */ | |
369 | lldpctl_atom_t *lldpctl_get_interfaces(lldpctl_conn_t *lldpctl); | |
370 | ||
371 | /** | |
372 | * Retrieve the information related to a given interface. | |
373 | * | |
374 | * @param port The port we want to retrieve information from. This port is an | |
375 | * atom retrieved from @c lldpctl_get_interfaces(). | |
376 | * @return Atom related to this port which may be used in subsequent functions. | |
377 | * | |
378 | * This functions may have to do IO to get the information related to the given | |
379 | * port. Depending on the IO mode, information may not be available tight now | |
380 | * and the function should be called again later. If @c NULL is returned, check | |
381 | * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later | |
382 | * (when more data is available). | |
383 | */ | |
384 | lldpctl_atom_t *lldpctl_get_port(lldpctl_atom_t *port); | |
385 | ||
386 | /** | |
387 | * Piece of information that can be retrieved from/written to an atom. | |
388 | * | |
389 | * Each piece of information can potentially be retrieved as an atom (A), a | |
390 | * string (S), a buffer (B) or an integer (I). Additionaly, when an information | |
391 | * can be retrieved as an atom, it is usually iterable (L). When an atom can be | |
392 | * retrieved as a string and as an additional type, the string is expected to be | |
393 | * formatted. For example, the MAC address of a local port can be retrieved as a | |
394 | * buffer and a string. As a string, you'll get something like | |
395 | * "00:11:22:33:44:55". Also, all values that can be get as an integer or a | |
396 | * buffer can be get as a string too. There is no special formatting in this | |
397 | * case. "(BS)" means that the string get a special appropriate format. | |
398 | * | |
399 | * The name of a key is an indication on the type of atom that information can | |
400 | * be extracted from. For example, @c lldpctl_k_med_policy_type can be extracted | |
401 | * from an atom you got by iterating on @c lldpctl_k_port_med_policies. On the | |
402 | * other hand, @c lldpctl_k_port_descr and @c lldpctl_k_chassis can be retrieved | |
403 | * from an atom retrieved either by iterating @c lldpctl_k_port_neighbors or | |
404 | * with @c lldpctl_get_port(). | |
405 | * | |
406 | * Some values may be written. They are marked with (W). Such a change may or | |
407 | * may not be transmitted immediatly. If they are not transmitted immediatly, | |
408 | * this means that the resulting atom should be written to another atom. For | |
409 | * example, when writting @c lldpctl_k_med_policy_tagged, you need to write the | |
410 | * resulting atom to @c lldpctl_k_port_med_policies. If the change is | |
411 | * transmitted immediatly, you need to check the error status of the connection | |
412 | * to know if it has been transmitted correctly. Notably, if you get @c | |
413 | * LLDPCTL_ERR_WOULDBLOCK, you need to try again later. Usually, changes are | |
414 | * transmitted immediatly. The exception are changes that need to be grouped to | |
415 | * be consistent, like a LLDP MED location. When a change is transmitted | |
416 | * immediatly, it is marked with (O). | |
417 | * | |
418 | * Some values may also be created. They are flagged with (C). This only applies | |
419 | * to elements that can be iterated (L) and written (W). The element created | |
420 | * still needs to be appended to the list by being written to it. The creation | |
421 | * is done with @c lldpctl_atom_create(). | |
422 | * | |
423 | * An atom marked with (S) can be retrieved as a string only. It cannot be | |
424 | * written. An atom marked with (IS) can be retrieved as an integer and features | |
425 | * an appropriate representation as a string (usually, the name of a constant) | |
426 | * which is more meaningful than just the integer. An atom marked as (I) can be | |
427 | * retrieved and as a string. In the later case, this is just a string | |
428 | * representation of the integer. An atom marked with (AL) can be retrieved as | |
429 | * an atom only and can be iterated over. This is usually a list of things. An | |
430 | * atom marked (I,W) can be read as an integer or a string and can be written as | |
431 | * an integer. The change would not be commited until the atom is written to the | |
432 | * nearest atom supporting (A,WO) operation (eventually with an indirection, i.e | |
433 | * first write to a (A,W), then to a (A,WO)). | |
434 | */ | |
435 | typedef enum { | |
436 | lldpctl_k_interface_name, /**< (S) The interface name. */ | |
437 | ||
438 | lldpctl_k_port_name, /**< (S) The port name. Only works for a local port. */ | |
439 | lldpctl_k_port_index, /**< (I) The port index. Only works for a local port. */ | |
440 | /** | |
441 | * (AL) The list of known neighbors for this port. | |
442 | * | |
443 | * A neighbor is in fact a remote port. | |
444 | */ | |
445 | lldpctl_k_port_neighbors, | |
446 | lldpctl_k_port_protocol, /**< (IS) The protocol that was used to retrieve this information. */ | |
447 | lldpctl_k_port_age, /**< (I) Age of information, seconds from epoch. */ | |
448 | lldpctl_k_port_id_subtype, /**< (IS) The subtype ID of this port. */ | |
449 | lldpctl_k_port_id, /**< (BS) The ID of this port. */ | |
450 | lldpctl_k_port_descr, /**< (S) The description of this port. */ | |
451 | lldpctl_k_port_hidden, /**< (I) Is this port hidden (or should it be displayed?)? */ | |
452 | ||
453 | lldpctl_k_port_dot3_mfs, /**< (I) MFS */ | |
454 | lldpctl_k_port_dot3_aggregid, /**< (I) Port aggregation ID */ | |
455 | lldpctl_k_port_dot3_autoneg_support, /**< (I) Autonegotiation support. */ | |
456 | lldpctl_k_port_dot3_autoneg_enabled, /**< (I) Autonegotiation enabled. */ | |
457 | lldpctl_k_port_dot3_autoneg_advertised, /**< (I) Advertised protocols. See LLDP_DOT3_LINK_AUTONEG_* */ | |
458 | lldpctl_k_port_dot3_mautype, /**< (IS) Current MAU type. See LLDP_DOT3_MAU_* */ | |
459 | ||
460 | lldpctl_k_port_dot3_power, /**< (A,WO) Dot3 power related stuff. */ | |
461 | lldpctl_k_dot3_power_devicetype, /**< (IS,W) Device type. See LLDP_DOT3_POWER_PSE/PD. */ | |
462 | lldpctl_k_dot3_power_supported, /**< (I,W) Is MDI power supported. */ | |
463 | lldpctl_k_dot3_power_enabled, /**< (I,W) Is MDI power enabled. */ | |
464 | lldpctl_k_dot3_power_paircontrol, /**< (I,W) Pair-control enabled? */ | |
465 | lldpctl_k_dot3_power_pairs, /**< (IS,W) See LLDP_DOT3_POWERPAIRS_ */ | |
466 | lldpctl_k_dot3_power_class, /**< (IS,W) Power class. */ | |
467 | lldpctl_k_dot3_power_type, /**< (I,W) 802.3AT power type */ | |
468 | lldpctl_k_dot3_power_source, /**< (IS,W) 802.3AT power source */ | |
469 | lldpctl_k_dot3_power_priority, /**< (IS,W) 802.3AT power priority */ | |
470 | lldpctl_k_dot3_power_allocated, /**< (I,W) 802.3AT power allocated */ | |
471 | lldpctl_k_dot3_power_requested, /**< (I,W) 802.3AT power requested */ | |
472 | ||
473 | lldpctl_k_port_vlan_pvid, /**< (I) Primary VLAN ID */ | |
474 | lldpctl_k_port_vlans, /**< (AL) List of VLAN */ | |
475 | lldpctl_k_vlan_id, /**< (I) VLAN ID */ | |
476 | lldpctl_k_vlan_name, /**< (S) VLAN name */ | |
477 | ||
478 | lldpctl_k_port_ppvids, /**< (AL) List of PPVIDs */ | |
479 | lldpctl_k_ppvid_status, /**< (I) Status of PPVID (see LLDP_PPVID_CAP_*) */ | |
480 | lldpctl_k_ppvid_id, /**< (I) ID of PPVID */ | |
481 | ||
482 | lldpctl_k_port_pis, /**< (AL) List of PIDs */ | |
483 | lldpctl_k_pi_id, /**< (B) PID value */ | |
484 | ||
485 | lldpctl_k_chassis_index, /**< (I) The chassis index. */ | |
486 | lldpctl_k_chassis_id_subtype, /**< (IS) The subtype ID of this chassis. */ | |
487 | lldpctl_k_chassis_id, /**< (BS) The ID of this chassis. */ | |
488 | lldpctl_k_chassis_name, /**< (S) The name of this chassis. */ | |
489 | lldpctl_k_chassis_descr, /**< (S) The description of this chassis. */ | |
490 | lldpctl_k_chassis_cap_available, /**< (I) Available capabalities (see LLDP_CAP_*) */ | |
491 | lldpctl_k_chassis_cap_enabled, /**< (I) Enabled capabilities (see LLDP_CAP_*) */ | |
492 | lldpctl_k_chassis_mgmt, /**< (AL) List of management addresses */ | |
493 | ||
494 | lldpctl_k_chassis_med_type, /**< (IS) Chassis MED type. See LLDP_MED_CLASS_* */ | |
495 | lldpctl_k_chassis_med_cap, /**< (I) Available MED capabilitied. See LLDP_MED_CAP_* */ | |
496 | lldpctl_k_chassis_med_inventory_hw, /**< (S) LLDP MED inventory "Hardware Revision" */ | |
497 | lldpctl_k_chassis_med_inventory_sw, /**< (S) LLDP MED inventory "Software Revision" */ | |
498 | lldpctl_k_chassis_med_inventory_fw, /**< (S) LLDP MED inventory "Firmware Revision" */ | |
499 | lldpctl_k_chassis_med_inventory_sn, /**< (S) LLDP MED inventory "Serial Number" */ | |
500 | lldpctl_k_chassis_med_inventory_manuf, /**< (S) LLDP MED inventory "Manufacturer" */ | |
501 | lldpctl_k_chassis_med_inventory_model, /**< (S) LLDP MED inventory "Model" */ | |
502 | lldpctl_k_chassis_med_inventory_asset, /**< (S) LLDP MED inventory "Asset ID" */ | |
503 | ||
504 | lldpctl_k_port_med_policies, /**< (AL,WO) MED policies attached to a port. */ | |
505 | lldpctl_k_med_policy_type, /**< (IS,W) MED policy app type. See LLDP_MED_APPTYPE_*. 0 if a policy is not defined. */ | |
506 | lldpctl_k_med_policy_unknown, /**< (I,W) Is MED policy defined? */ | |
507 | lldpctl_k_med_policy_tagged, /**< (I,W) MED policy tagging */ | |
508 | lldpctl_k_med_policy_vid, /**< (I,W) MED policy VID */ | |
509 | lldpctl_k_med_policy_priority, /**< (I,W) MED policy priority */ | |
510 | lldpctl_k_med_policy_dscp, /**< (I,W) MED policy DSCP */ | |
511 | ||
512 | lldpctl_k_port_med_locations, /**< (AL,WO) MED locations attached to a port. */ | |
513 | lldpctl_k_med_location_format, /**< (IS,W) MED location format. See | |
514 | * LLDP_MED_LOCFORMAT_*. 0 if this | |
515 | * location is not defined. When written, | |
516 | * the following fields will be zeroed | |
517 | * out. */ | |
518 | lldpctl_k_med_location_geoid, /**< (IS,W) MED geoid. See LLDP_MED_LOCATION_GEOID_*. Only if format is COORD. */ | |
519 | lldpctl_k_med_location_latitude, /**< (S,W) MED latitude. Only if format is COORD. */ | |
520 | lldpctl_k_med_location_longitude, /**< (S,W) MED longitude. Only if format is COORD. */ | |
521 | lldpctl_k_med_location_altitude, /**< (S,W) MED altitude. Only if format is COORD. */ | |
522 | lldpctl_k_med_location_altitude_unit, /**< (S,W) MED altitude unit. See LLDP_MED_LOCATION_ALTITUDE_UNIT_*. | |
523 | * Only if format is COORD. */ | |
524 | ||
525 | lldpctl_k_med_location_country, /**< (S,W) MED country. Only if format is CIVIC. */ | |
526 | lldpctl_k_med_location_elin, /**< (S,W) MED ELIN. Only if format is ELIN. */ | |
527 | ||
528 | lldpctl_k_med_location_ca_elements, /**< (AL,WC) MED civic address elements. Only if format is CIVIC */ | |
529 | lldpctl_k_med_civicaddress_type, /**< (IS,W) MED civic address type. */ | |
530 | lldpctl_k_med_civicaddress_value, /**< (S,W) MED civic address value. */ | |
531 | ||
532 | lldpctl_k_port_med_power, /**< (A,WO) LLDP-MED power related stuff. */ | |
533 | lldpctl_k_med_power_type, /**< (IS,W) LLDP MED power device type. See LLDP_MED_POW_TYPE_* */ | |
534 | lldpctl_k_med_power_source, /**< (IS,W) LLDP MED power source. See LLDP_MED_POW_SOURCE_* */ | |
535 | lldpctl_k_med_power_priority, /**< (IS,W) LLDP MED power priority. See LLDP_MED_POW_PRIO_* */ | |
536 | lldpctl_k_med_power_val, /**< (I,W) LLDP MED power value */ | |
537 | ||
538 | lldpctl_k_mgmt_ip, /**< (S) IP address */ | |
539 | } lldpctl_key_t; | |
540 | ||
541 | /** | |
542 | * Retrieve a bit of information as an atom. | |
543 | * | |
544 | * @param atom The atom we want to query. | |
545 | * @param key The information we want from the atom. | |
546 | * @return The atom representing the requested information or @c NULL if the | |
547 | * information is not available. | |
548 | * | |
549 | * Not every value of @c info will be available as an atom. See the | |
550 | * documentation of @c lldpctl_key_t for values accepting to be extracted as an | |
551 | * atom. Usually, this is only iterable values or values representing a complex | |
552 | * object. | |
553 | * | |
554 | * The provided atom is not a _borrowed_ reference. You need to decrement the | |
555 | * reference count when you don't need it anymore. | |
556 | * | |
557 | * As a convenience, this function will return @c NULL if the first parameter is | |
558 | * @c NULL and no error will be raised. | |
559 | */ | |
560 | lldpctl_atom_t *lldpctl_atom_get(lldpctl_atom_t *atom, lldpctl_key_t key); | |
561 | ||
562 | /** | |
563 | * Set a bit of information with an atom. | |
564 | * | |
565 | * @param atom The atom we want to write to. | |
566 | * @param key The key information we want to write. | |
567 | * @param value The value of the information we want to write. | |
568 | * @return The updated atom with the appropriate information. | |
569 | * | |
570 | * This function will return @c NULL in case of error. If the last error is @c | |
571 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
572 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
573 | * correct. | |
574 | */ | |
575 | lldpctl_atom_t *lldpctl_atom_set(lldpctl_atom_t *atom, lldpctl_key_t key, | |
576 | lldpctl_atom_t *value); | |
577 | ||
578 | /** | |
579 | * Retrieve a bit of information as a null-terminated string. | |
580 | * | |
581 | * @param atom The atom we want to query. | |
582 | * @param key The information we want from the atom. | |
583 | * @return The requested string or @c NULL if the information is not available. | |
584 | * | |
585 | * Not every value of @c info will be available as a string. See the | |
586 | * documentation of @c lldpctl_key_t for values accepting to be extracted as a | |
587 | * string. Usually, only piece of information stored as string are available in | |
588 | * this form but sometimes, you can get a nice formatted string instead of an | |
589 | * integer with this function. | |
590 | * | |
591 | * As a convenience, this function will return @c NULL if the first parameter is | |
592 | * @c NULL and no error will be raised. | |
593 | * | |
594 | * The provided string may live inside the atom providing it. If you need it | |
595 | * longer, duplicate it. | |
596 | */ | |
597 | const char *lldpctl_atom_get_str(lldpctl_atom_t *atom, lldpctl_key_t key); | |
598 | ||
599 | /** | |
600 | * Set a bit of information using a null-terminated string. | |
601 | * | |
602 | * @param atom The atom we want to write to. | |
603 | * @param key The key information we want to write. | |
604 | * @param value The value of the information we want to write. | |
605 | * @return The updated atom with the appropriate information. | |
606 | * | |
607 | * This function will return @c NULL in case of error. If the last error is @c | |
608 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
609 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
610 | * correct. | |
611 | */ | |
612 | lldpctl_atom_t *lldpctl_atom_set_str(lldpctl_atom_t *atom, lldpctl_key_t key, | |
613 | const char *value); | |
614 | ||
615 | /** | |
616 | * Retrieve a bit of information as a buffer. | |
617 | * | |
618 | * @param atom The atom we want to query. | |
619 | * @param key The information we want from the atom. | |
620 | * @param length[out] The size of the returned buffer. | |
621 | * @return The requested buffer or @c NULL if the information is not available. | |
622 | * | |
623 | * Not every value of @c info will be available as a buffer. See the | |
624 | * documentation of @c lldpctl_key_t for values accepting to be extracted as a | |
625 | * string. Usually, only piece of information stored as buffer are available in | |
626 | * this form. | |
627 | * | |
628 | * As a convenience, this function will return @c NULL if the first parameter is | |
629 | * @c NULL and no error will be raised. If this function returns @c NULL, the | |
630 | * third parameter is set to 0. | |
631 | * | |
632 | * The provided buffer may live inside the atom providing it. If you need it | |
633 | * longer, duplicate it. | |
634 | */ | |
635 | const u_int8_t *lldpctl_atom_get_buffer(lldpctl_atom_t *atom, lldpctl_key_t key, | |
636 | size_t *length); | |
637 | ||
638 | /** | |
639 | * Set a bit of information using a buffer | |
640 | * | |
641 | * @param atom The atom we want to write to. | |
642 | * @param key The key information we want to write. | |
643 | * @param value The value of the information we want to write. | |
644 | * @param length The length of the provided buffer. | |
645 | * @return The updated atom with the appropriate information. | |
646 | * | |
647 | * This function will return @c NULL in case of error. If the last error is @c | |
648 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
649 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
650 | * correct. | |
651 | */ | |
652 | lldpctl_atom_t *lldpctl_atom_set_buffer(lldpctl_atom_t *atom, lldpctl_key_t key, | |
653 | const u_int8_t *value, size_t length); | |
654 | ||
655 | /** | |
656 | * Retrieve a bit of information as an integer. | |
657 | * | |
658 | * @param atom The atom we want to query. | |
659 | * @param key The information we want from the atom. | |
660 | * @return The requested integer or -1 if the information is not available | |
661 | * | |
662 | * Not every value of @c info will be available as an integer. See the | |
663 | * documentation of @c lldpctl_key_t for values accepting to be extracted as a | |
664 | * string. Usually, only piece of information stored as an integer are available | |
665 | * in this form. | |
666 | * | |
667 | * Only @c lldpctl_last_error() can tell if the returned value is an error or | |
668 | * not. However, most values extracted from lldpd cannot be negative. | |
669 | */ | |
670 | long int lldpctl_atom_get_int(lldpctl_atom_t *atom, lldpctl_key_t key); | |
671 | ||
672 | /** | |
673 | * Set a bit of information using an integer | |
674 | * | |
675 | * @param atom The atom we want to write to. | |
676 | * @param key The key information we want to write. | |
677 | * @param value The value of the information we want to write. | |
678 | * @return The updated atom with the appropriate information. | |
679 | * | |
680 | * This function will return @c NULL in case of error. If the last error is @c | |
681 | * LLDPCTL_ERR_WOULDBLOCK, the write should be retried later with the exact same | |
682 | * parameters. LLDPCTL_ERR_BAD_VALUE is raised when the provided atom is not | |
683 | * correct. | |
684 | */ | |
685 | lldpctl_atom_t *lldpctl_atom_set_int(lldpctl_atom_t *atom, lldpctl_key_t key, | |
686 | long int value); | |
687 | ||
688 | /*@}*/ | |
689 | ||
690 | /*@{*/ | |
691 | /** | |
692 | * Iterator over an iterable atom (a list of ports, a list of VLAN, ...). When | |
693 | * an atom is a list, it can be iterated over to extract the appropriate values. | |
694 | * | |
695 | * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(), lldpctl_atom_iter_value() | |
696 | */ | |
697 | typedef struct lldpctl_atom_iter_t lldpctl_atom_iter_t; | |
698 | ||
699 | /** | |
700 | * Return an iterator over a given atom. | |
701 | * | |
702 | * If an atom is iterable (if it is a list, like a list of ports, a list of | |
703 | * VLAN, a list of neighbors), it is possible to iterate over it. First use this | |
704 | * function to get an iterator then use @c lldpctl_atom_iter_next() to get the | |
705 | * next item and @c lldpctl_atom_iter_value() to the actuel item. | |
706 | * | |
707 | * @param atom The atom we want to create an iterator from. | |
708 | * @return The iterator or @c NULL if an error happened or if the atom is empty | |
709 | * (check with @c lldpctl_last_error()). | |
710 | * | |
711 | * As a convenience, if the provided atom is @c NULL, this function will return | |
712 | * @c NULL and no error will be raised. | |
713 | */ | |
714 | lldpctl_atom_iter_t *lldpctl_atom_iter(lldpctl_atom_t *atom); | |
715 | ||
716 | /** | |
717 | * Return the next element of an iterator. | |
718 | * | |
719 | * @param atom The atom we are currently iterating. | |
720 | * @param iter The iterator we want the next element from. | |
721 | * @return An iterator starting on the next element or @c NULL if we have no | |
722 | * more elements | |
723 | * | |
724 | * @see lldpctl_atom_iter(), lldpctl_atom_iter_value(). | |
725 | * | |
726 | * As a convenience, if the provided atom is @c NULL, this function will return | |
727 | * @c NULL and no error will be raised. | |
728 | */ | |
729 | lldpctl_atom_iter_t *lldpctl_atom_iter_next(lldpctl_atom_t *atom, lldpctl_atom_iter_t *iter); | |
730 | ||
731 | /** | |
732 | * Return the value of an iterator. | |
733 | * | |
734 | * @param atom The atom we are currently iterating. | |
735 | * @param iter The iterator we want the next element from. | |
736 | * @return The atom currently associated with the iterator. | |
737 | * | |
738 | * @see lldpctl_atom_iter(), lldpctl_atom_iter_next(). | |
739 | */ | |
740 | lldpctl_atom_t *lldpctl_atom_iter_value(lldpctl_atom_t *atom, lldpctl_atom_iter_t *iter); | |
741 | ||
742 | /** | |
743 | * Convenience macro to iter over every value of an iterable object. | |
744 | * | |
745 | * @param atom The atom you want to iterate on. | |
746 | * @param value Atom that will be used to contain each value. | |
747 | * | |
748 | * This macro behaves as a for loop. Moreover, at the end of each iteration, | |
749 | * value is deallocated. Don't use it outside of the loop! | |
750 | */ | |
751 | #define lldpctl_atom_foreach(atom, value) \ | |
752 | for (lldpctl_atom_iter_t *iter = lldpctl_atom_iter(atom); \ | |
753 | iter && (value = lldpctl_atom_iter_value(atom, iter)); \ | |
754 | iter = lldpctl_atom_iter_next(atom, iter), \ | |
755 | lldpctl_atom_dec_ref(value)) | |
756 | ||
757 | /** | |
758 | * Create a new value for an iterable element. | |
759 | * | |
760 | * The value is meant to be appended using @c lldpctl_atom_set(). Currently, | |
761 | * there is no way to delete an element from a list. It is also not advisable to | |
762 | * use getters on a newly created object until it is fully initialized. If its | |
763 | * internal representation is using a buffer, it may not be initialized until | |
764 | * the first set. | |
765 | * | |
766 | * @param atom The atom we want to create a new element for. | |
767 | * @return The new element. | |
768 | */ | |
769 | lldpctl_atom_t *lldpctl_atom_create(lldpctl_atom_t *atom); | |
770 | /*@}*/ | |
771 | ||
772 | #ifdef __cplusplus | |
773 | } | |
774 | #endif | |
775 | ||
776 | #endif |