From: Grant Erickson <gerickson@nuovations.com>
To: connman@lists.linux.dev
Subject: [PATCH] service: Document service compare and sort functions.
Date: Thu, 2 Nov 2023 16:10:38 -0700 [thread overview]
Message-ID: <46D3640C-0231-40BE-9192-7219A8A0502A@nuovations.com> (raw)
This adds documentation to the service compare and sort functions.
---
src/service.c | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 88 insertions(+)
diff --git a/src/service.c b/src/service.c
index 9c77be08..919621b9 100644
--- a/src/service.c
+++ b/src/service.c
@@ -5443,6 +5443,33 @@ static gint service_compare_vpn(const struct connman_service *a,
return service_compare(transport, service);
}
+/**
+ * @brief
+ * Compare two network services against the @a
+ * PreferredTechnologies priority list.
+ *
+ * This compares the two specified network services, by their
+ * technology type, against the @a PreferredTechnologies priority
+ * list.
+ *
+ * @param[in] service_a A pointer to the first immutable service
+ * to compare by its technology type with the
+ * @a PreferredTechnologies priority list.
+ * @param[in] service_b A pointer to the second immutable service
+ * to compare by its technology type with the
+ * @a PreferredTechnologies priority list.
+ *
+ * @retval 0 If the @a PreferredTechnologies configuration is empty
+ * or if neither service type matches a technology type
+ * in the @a PreferredTechnologies list.
+ * @retval -1 If @a service_a type matches a technology type
+ * in the @a PreferredTechnologies list and should sort
+ * @b before @a service_b.
+ * @retval 1 If @a service_b type matches a technology type
+ * in the @a PreferredTechnologies list and should sort
+ * @b before @a service_a.
+ *
+ */
static gint service_compare_preferred(const struct connman_service *service_a,
const struct connman_service *service_b)
{
@@ -5462,6 +5489,33 @@ static gint service_compare_preferred(const struct connman_service *service_a,
return 0;
}
+/**
+ * @brief
+ * Compare two network services against one another.
+ *
+ * This compares the two specified network services.
+ *
+ * Services are compared with the following sort criteria:
+ *
+ * 1. State
+ * 2. Favorite status
+ * 3. Type
+ * 4. Strength
+ * 5. Name
+ *
+ * @param[in] a A pointer to the first immutable service
+ * to compare.
+ * @param[in] b A pointer to the second immutable service
+ * to compare.
+ *
+ * @retval 0 If service @a a and @a b are equivalent.
+ * @retval < 0 If service @a a should sort @b before service @a b.
+ * @retval > 0 If service @a b should sort @b before service @a a.
+ *
+ * @sa service_compare_preferred
+ * @sa __connman_service_compare
+ *
+ */
static gint service_compare(gconstpointer a, gconstpointer b)
{
const struct connman_service *service_a = (const void *) a;
@@ -5570,6 +5624,20 @@ static gint service_compare(gconstpointer a, gconstpointer b)
return g_strcmp0(service_a->name, service_b->name);
}
+/**
+ * @brief
+ * Sort the network services list and schedule a "ServicesChanged"
+ * D-Bus signal.
+ *
+ * This attempts to sort, if non-null and has more than one element,
+ * the network services list. On completion of the sort, a D-Bus
+ * "ServicesChanged" signal is scheduled.
+ *
+ * @sa service_compare
+ * @sa service_compare_preferred
+ * @sa service_schedule_changed
+ *
+ */
static void service_list_sort(void)
{
if (service_list && service_list->next) {
@@ -5578,6 +5646,26 @@ static void service_list_sort(void)
}
}
+/**
+ * @brief
+ * Compare two network services against one another.
+ *
+ * This compares the two specified network services.
+ *
+ * @param[in] a A pointer to the first immutable service
+ * to compare.
+ * @param[in] b A pointer to the second immutable service
+ * to compare.
+ *
+ * @retval 0 If service @a a and @a b are equivalent.
+ * @retval < 0 If service @a a should sort @b before service @a b.
+ * @retval > 0 If service @a b should sort @b before service @a a.
+ *
+ * @sa service_compare
+ * @sa service_compare_preferred
+ * @sa service_list_sort
+ *
+ */
int __connman_service_compare(const struct connman_service *a,
const struct connman_service *b)
{
--
2.42.0
next reply other threads:[~2023-11-02 23:10 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-11-02 23:10 Grant Erickson [this message]
2023-11-07 16:06 ` [PATCH] service: Document service compare and sort functions Marcel Holtmann
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=46D3640C-0231-40BE-9192-7219A8A0502A@nuovations.com \
--to=gerickson@nuovations.com \
--cc=connman@lists.linux.dev \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).