[83/90] connection: Document 'unset_low_priority_default_gateway'.

Commit Message

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

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

Patch

diff --git a/src/connection.c b/src/connection.c
index 1f250a62f24c..db108ed03a19 100644
--- a/src/connection.c
+++ b/src/connection.c
@@ -2595,6 +2595,50 @@  static int unset_ipv4_low_priority_default_gateway(struct gateway_data *data,
 	return unset_default_gateway_route_common(data, config, type, cb);
 }
 
+/**
+ *  @brief
+ *    Unset the low-priority default route for the specified IP
+ *    configuration type from the provided gateway data.
+ *
+ *  This attempts to unset, or clear, the low-priority (that is,
+ *  metric > 0) default route for the specified IP configuration type
+ *  from the provided gateway data. The network interface and, by
+ *  extension, the network service with which the gateway is
+ *  associated is determined by the @a index field of @a data.
+ *
+ *  On success, the gateway configuration state specific to @a type
+ *  will be set to #CONNMAN_GATEWAY_CONFIG_STATE_REMOVED.
+ *
+ *  @param[in,out]  data  A pointer to the mutable gateway data to
+ *                        clear as the low-priority default route.
+ *  @param[in]      type  The IP configuration type for which the
+ *                        gateway, or default router, configuration
+ *                        will be selected from @a data and used to
+ *                        unset the low-priority default route.
+ *
+ *  @retval  0              If successful.
+ *  @retval  -EINVAL        If @a data is null, if @a type is invalid,
+ *                          if the gateway configuration type is not
+ *                          type
+ *                          #CONNMAN_GATEWAY_CONFIG_TYPE_LOW_PRIORITY_DEFAULT,
+ *                          or if the routing information to be unset,
+ *                          or cleared, was invalid.
+ *  @retval  -EINPROGRESS   If the state of @a config is
+ *                          #CONNMAN_GATEWAY_CONFIG_STATE_REMOVED.
+ *  @retval  -EALREADY      If the state of @a config is
+ *                          #CONNMAN_GATEWAY_CONFIG_STATE_INACTIVE.
+ *  @retval  -EFAULT        If the address to the routing information
+ *                          to be unset, or cleared, was invalid.
+ *  @retval  -EPERM         If the current process does not have the
+ *                          credentials or capabilities to unset, or
+ *                          clear, routes.
+ *  @retval  -ESRCH         A request was made to unset, or clear a
+ *                          non-existing routing entry.
+ *
+ *  @sa mutatate_default_gateway
+ *  @sa unset_ipv4_low_priority_default_gateway
+ *
+ */
 static int unset_low_priority_default_gateway(struct gateway_data *data,
 				enum connman_ipconfig_type type,
 				const char *function)