[78/90] connection: Document 'set_ipv4_low_priority_default_gateway_route_cb'.

Commit Message

Grant Erickson Dec. 6, 2023, 11:50 p.m. UTC

This adds documentation to the
'set_ipv4_low_priority_default_gateway_route_cb' function.
---
 src/connection.c | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

Patch

diff --git a/src/connection.c b/src/connection.c
index 62e9f3bc07f6..a199b90802e2 100644
--- a/src/connection.c
+++ b/src/connection.c
@@ -2338,6 +2338,42 @@  static uint32_t compute_low_priority_metric(const struct gateway_data *data)
 				(data->index * metric_index_step));
 }
 
+/**
+ *  @brief
+ *    Set, or add, the IPv4 low-priority default route for the
+ *    specified gateway data and configuration using a function
+ *    utilizing a SIOCADDRT socket ioctl or a RTM_NEWROUTE Linux
+ *    Routing Netlink (rtnl) command.
+ *
+ *  This attempts to set, or add, the IPv4 low-priority (that is,
+ *  metric > 0) default route for the specified gateway data and
+ *  configuration using a function utilizing a SIOCADDRT socket ioctl
+ *  or a RTM_NEWROUTE Linux Routing Netlink (rtnl) command to modify
+ *  the Linux routing table.
+ *
+ *  @param[in,out]  data    A pointer to the mutable gateway data to
+ *                          use to set, or add, the IPv4 low-priority
+ *                          default route.
+ *  @param[in,out]  config  A pointer to the mutable gateway
+ *                          configuration to use to set, or add, the
+ *                          IPv4 low-priority default route.
+ *
+ *  @retval  0        If successful.
+ *  @retval  -EINVAL  If @a data or @a config are null; or if
+ *                    the routing information to be set, or
+ *                    added, was invalid.
+ *  @retval  -EFAULT  If the address to the routing information
+ *                    to be set, or added, was invalid.
+ *  @retval  -EPERM   If the current process does not have the
+ *                    credentials or capabilities to set, or
+ *                    add, routes.
+ *  @retval  -EEXIST  A request was made to add an existing
+ *                    routing entry.
+ *
+ *  @sa connman_inet_set_gateway_interface
+ *  @sa __connman_inet_add_default_to_table
+ *
+ */
 static int set_ipv4_low_priority_default_gateway_route_cb(
 				struct gateway_data *data,
 				struct gateway_config *config)