[PATCH] osmo-mgw[master]: cosmetic: client: add doxygen comments

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

dexter gerrit-no-reply at lists.osmocom.org
Sat Jan 20 00:00:09 UTC 2018 

Review at  https://gerrit.osmocom.org/5937

cosmetic: client: add doxygen comments

The client lacks doxygen apidoc comments

- Add missing doxygen apidoc comments

Change-Id: I0b8a0652e60f2b3d72ee1cedfa6e2d5547d88455
---
M src/libosmo-mgcp-client/mgcp_client.c
1 file changed, 46 insertions(+), 13 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/osmo-mgw refs/changes/37/5937/1

diff --git a/src/libosmo-mgcp-client/mgcp_client.c b/src/libosmo-mgcp-client/mgcp_client.c
index 13c6529..581c6a4 100644
--- a/src/libosmo-mgcp-client/mgcp_client.c
+++ b/src/libosmo-mgcp-client/mgcp_client.c
@@ -36,6 +36,8 @@
 #include <unistd.h>
 #include <string.h>
 
+/*! Initalize MGCP client configuration struct with default values.
+ *  \param[out] conf Client configuration.*/
 void mgcp_client_conf_init(struct mgcp_client_conf *conf)
 {
 	/* NULL and -1 default to MGCP_CLIENT_*_DEFAULT values */
@@ -62,7 +64,9 @@
 	return false;
 }
 
-/* Find and seize an unsused endpoint id */
+/*! Pick next free endpoint ID.
+ *  \param[in,out] client MGCP client descriptor.
+ *  \returns 0 on success, -EINVAL on error. */
 int mgcp_client_next_endpoint(struct mgcp_client *client)
 {
 	int i;
@@ -95,6 +99,9 @@
 	return -EINVAL;
 }
 
+/*! Release a seized endpoint ID to make it available again for other calls.
+ *  \param[in] id Endpoint ID
+ *  \param[in,out] client MGCP client descriptor. */
 /* Release a seized endpoint id to make it available again for other calls */
 void mgcp_client_release_endpoint(uint16_t id, struct mgcp_client *client)
 {
@@ -237,6 +244,9 @@
 	return NULL;
 }
 
+/*! Parse body (SDP) parameters of the MGCP response
+ *  \param[in,out] r Response data
+ *  \returns 0 on success, -EINVAL on error. */
 int mgcp_response_parse_params(struct mgcp_response *r)
 {
 	char *line;
@@ -498,6 +508,9 @@
 	return mgcp;
 }
 
+/*! Initalize client connection (opens socket only, no request is sent yet)
+ *  \param[in,out] mgcp MGCP client descriptor.
+ *  \returns 0 on success, -EINVAL on error. */
 int mgcp_client_connect(struct mgcp_client *mgcp)
 {
 	struct sockaddr_in addr;
@@ -543,17 +556,25 @@
 	return rc;
 }
 
+/*! Get the IP-Aaddress of the associated MGW as string.
+ *  \param[in] mgcp MGCP client descriptor.
+ *  \returns a pointer to the address string. */
 const char *mgcp_client_remote_addr_str(struct mgcp_client *mgcp)
 {
 	return mgcp->actual.remote_addr;
 }
 
+/*! Get the IP-Port of the associated MGW.
+ *  \param[in] mgcp MGCP client descriptor.
+ *  \returns port number. */
 uint16_t mgcp_client_remote_port(struct mgcp_client *mgcp)
 {
 	return mgcp->actual.remote_port;
 }
 
-/* Return the MGCP GW binary IPv4 address in network byte order. */
+/*! Get the IP-Aaddress of the associated MGW as its numeric representation.
+ *  \param[in] mgcp MGCP client descriptor.
+ *  \returns IP-Address as 32 bit integer (network byte order) */
 uint32_t mgcp_client_remote_addr_n(struct mgcp_client *mgcp)
 {
 	return mgcp->remote_addr;
@@ -626,29 +647,32 @@
 	return -1;
 }
 
-/* Cancel a pending transaction.
+/*! Cancel a pending transaction.
+ *  \param[in] mgcp MGCP client descriptor.
+ *  \param[in,out] trans_id Transaction id.
+ *  \returns 0 on success, -ENOENT on error.
+ *
  * Should a priv pointer passed to mgcp_client_tx() become invalid, this function must be called. In
  * practical terms, if the caller of mgcp_client_tx() wishes to tear down a transaction without having
  * received a response this function must be called. The trans_id can be obtained by calling
- * mgcp_msg_trans_id() on the msgb produced by mgcp_msg_gen().
- */
+ * mgcp_msg_trans_id() on the msgb produced by mgcp_msg_gen(). */
 int mgcp_client_cancel(struct mgcp_client *mgcp, mgcp_trans_id_t trans_id)
 {
 	struct mgcp_response_pending *pending = mgcp_client_response_pending_get(mgcp, trans_id);
 	if (!pending) {
-		/* INFO is sufficient, it is not harmful to cancel a transaction twice. */
+		/*! Note: it is not harmful to cancel a transaction twice. */
 		LOGP(DLMGCP, LOGL_INFO, "Cannot cancel, no such transaction: %u\n", trans_id);
 		return -ENOENT;
 	}
 	LOGP(DLMGCP, LOGL_INFO, "Canceled transaction %u\n", trans_id);
 	talloc_free(pending);
 	return 0;
-	/* We don't really need to clean up the wqueue: In all sane cases, the msgb has already been sent
-	 * out and is no longer in the wqueue. If it still is in the wqueue, then sending MGCP messages
-	 * per se is broken and the program should notice so by a full wqueue. Even if this was called
-	 * before we had a chance to send out the message and it is still going to be sent, we will just
-	 * ignore the reply to it later. Removing a msgb from the wqueue here would just introduce more
-	 * bug surface in terms of failing to update wqueue API's counters or some such.
+	/*! We don't really need to clean up the wqueue: In all sane cases, the msgb has already been sent
+	 *  out and is no longer in the wqueue. If it still is in the wqueue, then sending MGCP messages
+	 *  per se is broken and the program should notice so by a full wqueue. Even if this was called
+	 *  before we had a chance to send out the message and it is still going to be sent, we will just
+	 *  ignore the reply to it later. Removing a msgb from the wqueue here would just introduce more
+	 *  bug surface in terms of failing to update wqueue API's counters or some such.
 	 */
 }
 
@@ -763,6 +787,10 @@
 #define MGCP_AUEP_MANDATORY (MGCP_MSG_PRESENCE_ENDPOINT)
 #define MGCP_RSIP_MANDATORY 0	/* none */
 
+/*! Generate an MGCP message
+ *  \param[in] mgcp MGCP client descriptor.
+ *  \param[in] mgcp_msg Message description
+ *  \returns message buffer on success, NULL on error. */
 struct msgb *mgcp_msg_gen(struct mgcp_client *mgcp, struct mgcp_msg *mgcp_msg)
 {
 	mgcp_trans_id_t trans_id = mgcp_client_next_trans_id(mgcp);
@@ -881,12 +909,17 @@
 	return msg;
 }
 
-/* Retrieve the MGCP transaction ID from a msgb generated by mgcp_msg_gen() */
+/*! Retrieve the MGCP transaction ID from a msgb generated by mgcp_msg_gen()
+ *  \param[in] msg message buffer
+ *  \returns Transaction id. */
 mgcp_trans_id_t mgcp_msg_trans_id(struct msgb *msg)
 {
 	return (mgcp_trans_id_t)msg->cb[MSGB_CB_MGCP_TRANS_ID];
 }
 
+/*! Get the configuration parameters a given MGCP client instance
+ *  \param[in] mgcp MGCP client descriptor.
+ *  \returns configuration */
 struct mgcp_client_conf *mgcp_client_conf_actual(struct mgcp_client *mgcp)
 {
 	return &mgcp->actual;

-- 
To view, visit https://gerrit.osmocom.org/5937
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I0b8a0652e60f2b3d72ee1cedfa6e2d5547d88455
Gerrit-PatchSet: 1
Gerrit-Project: osmo-mgw
Gerrit-Branch: master
Gerrit-Owner: dexter <pmaier at sysmocom.de>

More information about the gerrit-log mailing list