/**
* 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);
+/**
+ * Function invoked to see if there's more data to be processed in the buffer.
+ *
+ * This function should be invoked to check for notifications in the data that
+ * has already been read. Its used typically for asynchronous connections.
+ *
+ * @param conn Handle to the connection to lldpd.
+ * @return 0 to indicate maybe more data is available for processing
+ * !0 to indicate no data or insufficient data for processing
+ */
+int lldpctl_process_conn_buffer(lldpctl_conn_t *conn);
+
+
/**
* Allocate a new handler for connecting to lldpd.
*
lldpctl_conn_t *lldpctl_new(lldpctl_send_callback send,
lldpctl_recv_callback recv, void *user_data);
+/**
+ * Allocate a new handler for connecting to lldpd.
+ *
+ * @param ctlname the Unix-domain socket to connect to lldpd.
+ * @param send Callback to be used when sending new data is requested.
+ * @param recv Callback to be used when receiving new data is requested.
+ * @param user_data Data to pass to callbacks.
+ * @return An handler to be used to connect to lldpd or @c NULL in
+ * case of error. In the later case, the error is probable an
+ * out of memory condition.
+ *
+ * The allocated handler can be released with @c lldpctl_release(). If the
+ * provided parameters are both @c NULL, default synchronous callbacks will be
+ * used.
+ */
+lldpctl_conn_t *lldpctl_new_name(const char *ctlname, lldpctl_send_callback send,
+ lldpctl_recv_callback recv, void *user_data);
+
/**
* Release resources associated with a connection to lldpd.
*
*/
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)` 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)` Chassis description overriden */
- lldpctl_k_config_platform, /**< `(S)` Platform description overriden (CDP) */
+ 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_enabled, /**< `(I,WO)` Is fast start enabled */
+ 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_interface_name, /**< `(S)` The interface name. */
+ lldpctl_k_interface_name = 1000, /**< `(S)` The interface name. */
- lldpctl_k_port_name, /**< `(S)` The port name. Only works for a local port. */
+ lldpctl_k_port_name = 1100, /**< `(S)` The port name. Only works for a local port. */
lldpctl_k_port_index, /**< `(I)` The port index. Only works for a local port. */
/**
* `(AL)` The list of known neighbors for this port.
*
* A neighbor is in fact a remote port.
*/
- lldpctl_k_port_neighbors,
+ lldpctl_k_port_neighbors = 1200,
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, /**< `(I)` MFS */
+ lldpctl_k_port_dot3_mfs = 1300, /**< `(I)` MFS */
lldpctl_k_port_dot3_aggregid, /**< `(I)` Port aggregation ID */
lldpctl_k_port_dot3_autoneg_support, /**< `(I)` Autonegotiation support. */
lldpctl_k_port_dot3_autoneg_enabled, /**< `(I)` Autonegotiation enabled. */
lldpctl_k_port_dot3_autoneg_advertised, /**< `(I)` Advertised protocols. See `LLDP_DOT3_LINK_AUTONEG_*` */
lldpctl_k_port_dot3_mautype, /**< `(IS)` Current MAU type. See `LLDP_DOT3_MAU_*` */
- lldpctl_k_port_dot3_power, /**< `(A,WO)` Dot3 power related stuff. */
+ lldpctl_k_port_dot3_power = 1400, /**< `(A,WO)` Dot3 power related stuff. */
lldpctl_k_dot3_power_devicetype, /**< `(IS,W)` Device type. See `LLDP_DOT3_POWER_PSE/PD` */
lldpctl_k_dot3_power_supported, /**< `(I,W)` Is MDI power supported. */
lldpctl_k_dot3_power_enabled, /**< `(I,W)` Is MDI power enabled. */
lldpctl_k_dot3_power_allocated, /**< `(I,W)` 802.3AT power allocated */
lldpctl_k_dot3_power_requested, /**< `(I,W)` 802.3AT power requested */
- lldpctl_k_port_vlan_pvid, /**< `(I)` Primary VLAN ID */
+ lldpctl_k_port_vlan_pvid = 1500, /**< `(I)` Primary VLAN ID */
lldpctl_k_port_vlans, /**< `(AL)` List of VLAN */
lldpctl_k_vlan_id, /**< `(I)` VLAN ID */
lldpctl_k_vlan_name, /**< `(S)` VLAN name */
- lldpctl_k_port_ppvids, /**< `(AL)` List of PPVIDs */
+ lldpctl_k_port_ppvids = 1600, /**< `(AL)` List of PPVIDs */
lldpctl_k_ppvid_status, /**< `(I)` Status of PPVID (see `LLDP_PPVID_CAP_*`) */
lldpctl_k_ppvid_id, /**< `(I)` ID of PPVID */
- lldpctl_k_port_pis, /**< `(AL)` List of PIDs */
+ lldpctl_k_port_pis = 1700, /**< `(AL)` List of PIDs */
lldpctl_k_pi_id, /**< `(B)` PID value */
- lldpctl_k_chassis_index, /**< `(I)` The chassis index. */
+ lldpctl_k_chassis_index = 1800, /**< `(I)` The chassis index. */
lldpctl_k_chassis_id_subtype, /**< `(IS)` The subtype ID of this chassis. */
lldpctl_k_chassis_id, /**< `(BS)` The ID of this chassis. */
lldpctl_k_chassis_name, /**< `(S)` The name of this chassis. */
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, /**< `(IS)` Chassis MED type. See `LLDP_MED_CLASS_*` */
+ 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_chassis_med_inventory_hw, /**< `(S)` LLDP MED inventory "Hardware Revision" */
lldpctl_k_chassis_med_inventory_sw, /**< `(S)` LLDP MED inventory "Software Revision" */
lldpctl_k_chassis_med_inventory_model, /**< `(S)` LLDP MED inventory "Model" */
lldpctl_k_chassis_med_inventory_asset, /**< `(S)` LLDP MED inventory "Asset ID" */
- lldpctl_k_port_med_policies, /**< `(AL,WO)` MED policies attached to a port. */
+ lldpctl_k_port_med_policies = 2000, /**< `(AL,WO)` MED policies attached to a port. */
lldpctl_k_med_policy_type, /**< `(IS,W)` MED policy app type. See `LLDP_MED_APPTYPE_*`. 0 if a policy is not defined. */
lldpctl_k_med_policy_unknown, /**< `(I,W)` Is MED policy defined? */
lldpctl_k_med_policy_tagged, /**< `(I,W)` MED policy tagging */
lldpctl_k_med_policy_priority, /**< `(I,W)` MED policy priority */
lldpctl_k_med_policy_dscp, /**< `(I,W)` MED policy DSCP */
- lldpctl_k_port_med_locations, /**< `(AL,WO)` MED locations attached to a port. */
+ lldpctl_k_port_med_locations = 2100, /**< `(AL,WO)` MED locations attached to a port. */
lldpctl_k_med_location_format, /**< `(IS,W)` MED location format. See
* `LLDP_MED_LOCFORMAT_*`. 0 if this
* location is not defined. When written,
lldpctl_k_med_location_altitude_unit, /**< `(S,W)` MED altitude unit. See `LLDP_MED_LOCATION_ALTITUDE_UNIT_*`.
* Only if format is COORD. */
- lldpctl_k_med_location_country, /**< `(S,W)` MED country. Only if format is CIVIC. */
+ lldpctl_k_med_location_country = 2200, /**< `(S,W)` MED country. Only if format is CIVIC. */
lldpctl_k_med_location_elin, /**< `(S,W)` MED ELIN. Only if format is ELIN. */
- lldpctl_k_med_location_ca_elements, /**< `(AL,WC)` MED civic address elements. Only if format is CIVIC */
+ lldpctl_k_med_location_ca_elements = 2300, /**< `(AL,WC)` MED civic address elements. Only if format is CIVIC */
lldpctl_k_med_civicaddress_type, /**< `(IS,W)` MED civic address type. */
lldpctl_k_med_civicaddress_value, /**< `(S,W)` MED civic address value. */
- lldpctl_k_port_med_power, /**< `(A,WO)` LLDP-MED power related stuff. */
+ lldpctl_k_port_med_power = 2400, /**< `(A,WO)` LLDP-MED power related stuff. */
lldpctl_k_med_power_type, /**< `(IS,W)` LLDP MED power device type. See `LLDP_MED_POW_TYPE_*` */
lldpctl_k_med_power_source, /**< `(IS,W)` LLDP MED power source. See `LLDP_MED_POW_SOURCE_*` */
lldpctl_k_med_power_priority, /**< `(IS,W)` LLDP MED power priority. See `LLDP_MED_POW_PRIO_*` */
lldpctl_k_med_power_val, /**< `(I,W)` LLDP MED power value */
- lldpctl_k_mgmt_ip, /**< `(S)` IP address */
+ lldpctl_k_mgmt_ip = 3000, /**< `(S)` IP address */
+
+ lldpctl_k_tx_cnt = 4000, /**< `(I)` tx cnt. Only works for a local port. */
+ lldpctl_k_rx_cnt, /**< `(I)` rx cnt. Only works for a local port. */
+ lldpctl_k_rx_discarded_cnt, /**< `(I)` discarded cnt. Only works for a local port. */
+ lldpctl_k_rx_unrecognized_cnt, /**< `(I)` unrecognized cnt. Only works for a local port. */
+ lldpctl_k_ageout_cnt, /**< `(I)` ageout cnt. Only works for a local port. */
+ lldpctl_k_insert_cnt, /**< `(I)` insert cnt. Only works for a local port. */
+ lldpctl_k_delete_cnt, /**< `(I)` delete cnt. Only works for a local port. */
+ 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;
/**
* The provided buffer may live inside the atom providing it. If you need it
* longer, duplicate it.
*/
-const u_int8_t *lldpctl_atom_get_buffer(lldpctl_atom_t *atom, lldpctl_key_t key,
+const uint8_t *lldpctl_atom_get_buffer(lldpctl_atom_t *atom, lldpctl_key_t key,
size_t *length);
/**
* correct.
*/
lldpctl_atom_t *lldpctl_atom_set_buffer(lldpctl_atom_t *atom, lldpctl_key_t key,
- const u_int8_t *value, size_t length);
+ const uint8_t *value, size_t length);
/**
* Retrieve a bit of information as an integer.
* 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