/**
* Callback function invoked to send data to lldpd.
*
- * @param lldpctl Handle to the connection to lldpd.
+ * @param conn Handle to the connection to lldpd.
* @param data Bytes to be sent.
* @param length Length of provided data.
* @param user_data Provided user data.
/**
* Callback function invoked to receive data from lldpd.
*
- * @param lldpctl Handle to the connection to lldpd.
+ * @param conn Handle to the connection to lldpd.
* @param data Buffer for receiving data
* @param length Maximum bytes we can receive
* @param user_data Provided user data.
*
* @param conn Handle to the connection to lldpd.
* @return The number of bytes processed or a negative integer if an error has
- * occured.
+ * occurred.
*/
ssize_t lldpctl_send(lldpctl_conn_t *conn);
*/
void lldpctl_log_callback(void (*cb)(int severity, const char *msg));
+/**
+ * Setup log level.
+ *
+ * By default, liblldpctl will only log warnings. The following function allows
+ * to increase verbosity. This function has no effect if callbacks are
+ * registered with the previous function.
+ *
+ * @param level Level of verbosity (1 = warnings, 2 = info, 3 = debug).
+ */
+void lldpctl_log_level(int level);
+
/**
* Possible error codes for functions that return negative integers on
* this purpose or for @c lldpctl_last_error().
* lldpctl_atom_set_int(). Unlike getters, some of those may require IO to
* achieve their goal.
*
- * An atom is reference counted. Unless documented otherwise, a function
- * returning an atom will return a new reference that should be decremented if
- * not used anymore. It is quite important to use the reference counting
- * functions correctly. Segfaults or memory leaks may occur otherwise.
+ * An atom is reference counted. The semantics are quite similar to Python and
+ * you must be careful of the ownership of a reference. It is possible to own a
+ * reference by calling @c lldpctl_atom_inc_ref(). Once the atom is not needed
+ * any more, you can abandon ownership with @c lldpctl_atom_dec_ref(). Unless
+ * documented otherwise, a function returning an atom will return a new
+ * reference (the ownership is assigned to the caller, no need to call @c
+ * lldpctl_atom_inc_ref()). Unless documented otherwise, when providing an atom
+ * to a function, the atom is usually borrowed (no change in reference
+ * counting). Currently, no function will steal ownership.
+ *
+ * It is quite important to use the reference counting functions
+ * correctly. Segfaults or memory leaks may occur otherwise. Once the reference
+ * count reaches 0, the atom is immediately freed. Reusing it will likely lead
+ * to memory corruption.
*
* @{
*/
* @param neighbor Changed neighbor.
* @param data Data provided when registering the callback.
*
- * The provided interface and neighbor atoms will have their reference count
- * decremented when the callback ends. If you want to keep a reference to it, be
- * sure to increment the reference count in the callback.
+ * The provided interface and neighbor atoms are stolen by the callback: their
+ * reference count are decremented when the callback ends. If you want to keep a
+ * reference to it, be sure to increment the reference count in the callback.
*
* @see lldpctl_watch_callback
*/
*/
lldpctl_atom_t *lldpctl_get_interfaces(lldpctl_conn_t *conn);
+/**
+ * Retrieve the information related to the local chassis.
+ *
+ * @param conn Previously allocated handler to a connection to lldpd.
+ * @return Atom related to the local chassis which may be used in subsequent functions.
+ *
+ * This function may have to do IO to get the information related to the local
+ * chassis. Depending on the IO mode, information may not be available right now
+ * and the function should be called again later. If @c NULL is returned, check
+ * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
+ * (when more data is available).
+ */
+lldpctl_atom_t *lldpctl_get_local_chassis(lldpctl_conn_t *conn);
+
/**
* Retrieve the information related to a given interface.
*
* atom retrieved from an interation on @c lldpctl_get_interfaces().
* @return Atom related to this port which may be used in subsequent functions.
*
- * This functions may have to do IO to get the information related to the given
- * port. Depending on the IO mode, information may not be available tight now
+ * This function may have to do IO to get the information related to the given
+ * port. Depending on the IO mode, information may not be available right now
* and the function should be called again later. If @c NULL is returned, check
* what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
* (when more data is available).
*/
lldpctl_atom_t *lldpctl_get_port(lldpctl_atom_t *port);
+/**
+ * Retrieve the default port information.
+ *
+ * This port contains default settings whenever a new port needs to be created.
+ *
+ * @param conn Previously allocated handler to a connection to lldpd.
+ * @return Atom of the default port which may be used in subsequent functions.
+ *
+ * This function may have to do IO to get the information related to the given
+ * port. Depending on the IO mode, information may not be available right now
+ * and the function should be called again later. If @c NULL is returned, check
+ * what the last error is. If it is @c LLDPCTL_ERR_WOULDBLOCK, try again later
+ * (when more data is available).
+ */
+lldpctl_atom_t *lldpctl_get_default_port(lldpctl_conn_t *conn);
+
/**@}*/
/**
* LLDPCTL_ERR_WOULDBLOCK, you need to try again later. Usually, changes are
* transmitted immediatly. The exception are changes that need to be grouped to
* be consistent, like a LLDP MED location. When a change is transmitted
- * immediatly, it is marked with (O).
+ * immediatly, it is marked with (O). @c lldpctl_atom_set_str() may accept a @c
+ * NULL value. This case is marked with (N) and usually reset the item to the
+ * default value or no value.
*
* Some values may also be created. They are flagged with (C). This only applies
* to elements that can be iterated (L) and written (W). The element created
typedef enum {
lldpctl_k_config_tx_interval, /**< `(I,WO)` Transmit interval. When set to -1, it is meant to transmit now. */
lldpctl_k_config_receiveonly, /**< `(I)` Receive only mode */
- lldpctl_k_config_mgmt_pattern, /**< `(S)` Pattern to choose the management address */
- lldpctl_k_config_iface_pattern, /**< `(S,WO)` Pattern of enabled interfaces */
+ lldpctl_k_config_mgmt_pattern, /**< `(S,WON)` Pattern to choose the management address */
+ lldpctl_k_config_iface_pattern, /**< `(S,WON)` Pattern of enabled interfaces */
lldpctl_k_config_cid_pattern, /**< `(S)` Interface pattern to choose the chassis ID */
- lldpctl_k_config_description, /**< `(S,WO)` Chassis description overridden */
- lldpctl_k_config_platform, /**< `(S,WO)` Platform description overridden (CDP) */
- lldpctl_k_config_hostname, /**< `(S,WO)` System name overridden */
+ lldpctl_k_config_description, /**< `(S,WON)` Chassis description overridden */
+ lldpctl_k_config_platform, /**< `(S,WON)` Platform description overridden (CDP) */
+ lldpctl_k_config_hostname, /**< `(S,WON)` System name overridden */
lldpctl_k_config_advertise_version, /**< `(I)` Advertise version */
lldpctl_k_config_lldpmed_noinventory, /**< `(I)` Disable LLDP-MED inventory */
lldpctl_k_config_paused, /**< `(I)` lldpd is paused */
lldpctl_k_config_fast_start_interval, /**< `(I,WO)` Start fast transmit interval */
lldpctl_k_config_ifdescr_update, /**< `(I,WO)` Enable or disable setting interface description */
lldpctl_k_config_iface_promisc, /**< `(I,WO)` Enable or disable promiscuous mode on interfaces */
+ lldpctl_k_config_chassis_cap_advertise, /**< `(I,WO)` Enable or disable chassis capabilities advertisement */
+ lldpctl_k_config_chassis_mgmt_advertise, /**< `(I,WO)` Enable or disable management addresses advertisement */
+ lldpctl_k_config_cid_string, /**< `(S)` User defined string for the chassis ID */
lldpctl_k_interface_name = 1000, /**< `(S)` The interface name. */
lldpctl_k_port_protocol, /**< `(IS)` The protocol that was used to retrieve this information. */
lldpctl_k_port_age, /**< `(I)` Age of information, seconds from epoch. */
lldpctl_k_port_id_subtype, /**< `(IS)` The subtype ID of this port. */
- lldpctl_k_port_id, /**< `(BS)` The ID of this port. */
- lldpctl_k_port_descr, /**< `(S)` The description of this port. */
+ lldpctl_k_port_id, /**< `(BS,WO)` The ID of this port. */
+ lldpctl_k_port_descr, /**< `(S,WO)` The description of this port. */
lldpctl_k_port_hidden, /**< `(I)` Is this port hidden (or should it be displayed?)? */
+ lldpctl_k_port_status, /**< `(IS,WO)` Operational status of this (local) port */
+ lldpctl_k_port_chassis, /**< `(A)` Chassis associated to the port */
+ lldpctl_k_port_ttl, /**< `(I)` TTL for port, 0 if info is attached to chassis */
lldpctl_k_port_dot3_mfs = 1300, /**< `(I)` MFS */
lldpctl_k_port_dot3_aggregid, /**< `(I)` Port aggregation ID */
lldpctl_k_chassis_cap_available, /**< `(I)` Available capabalities (see `LLDP_CAP_*`) */
lldpctl_k_chassis_cap_enabled, /**< `(I)` Enabled capabilities (see `LLDP_CAP_*`) */
lldpctl_k_chassis_mgmt, /**< `(AL)` List of management addresses */
+ lldpctl_k_chassis_ttl, /**< Deprecated */
lldpctl_k_chassis_med_type = 1900, /**< `(IS)` Chassis MED type. See `LLDP_MED_CLASS_*` */
lldpctl_k_chassis_med_cap, /**< `(I)` Available MED capabilitied. See `LLDP_MED_CAP_*` */
lldpctl_k_config_tx_hold, /**< `(I,WO)` Transmit hold interval. */
lldpctl_k_config_bond_slave_src_mac_type, /**< `(I,WO)` bond slave src mac type. */
lldpctl_k_config_lldp_portid_type, /**< `(I,WO)` LLDP PortID TLV Subtype */
+ lldpctl_k_config_lldp_agent_type, /**< `(I,WO)` LLDP agent type */
+
+ lldpctl_k_custom_tlvs = 5000, /**< `(AL)` custom TLVs */
+ lldpctl_k_custom_tlvs_clear, /** `(I,WO)` clear list of custom TLVs */
+ lldpctl_k_custom_tlv, /** `(AL,WO)` custom TLV **/
+ lldpctl_k_custom_tlv_oui, /**< `(I,WO)` custom TLV Organizationally Unique Identifier. Default is 0 (3 bytes) */
+ lldpctl_k_custom_tlv_oui_subtype, /**< `(I,WO)` custom TLV subtype. Default is 0 (1 byte) */
+ lldpctl_k_custom_tlv_oui_info_string, /**< `(I,WO)` custom TLV Organizationally Unique Identifier Information String (up to 507 bytes) */
+ lldpctl_k_custom_tlv_op, /**< `(I,WO)` custom TLV operation */
+
} lldpctl_key_t;
/**
* Convenience macro to iter over every value of an iterable object.
*
* @param atom The atom you want to iterate on.
- * @param value Atom that will be used to contain each value.
+ * @param value Atom name that will be used to contain each value.
*
- * This macro behaves as a for loop. Moreover, at the end of each iteration,
- * value is deallocated. Don't use it outside of the loop!
+ * This macro behaves as a for loop. Moreover, at the end of each iteration, the
+ * reference count of the provided value is decremented. If you need to use it
+ * outside of the loop, you need to increment it.
*/
#define lldpctl_atom_foreach(atom, value) \
for (lldpctl_atom_iter_t *iter = lldpctl_atom_iter(atom); \
projects / thirdparty / lldpd.git / blobdiff