laforge submitted this change.

View Change

cosmetic: osmo_sccp_user_bind() clarify prim_cb msgb ownership in documentation

Change-Id: I6dcda9221aa77809fe0f10e0e159558aad07885c
---
M src/sccp_user.c
1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/src/sccp_user.c b/src/sccp_user.c
index b869dab..62ae9ed 100644
--- a/src/sccp_user.c
+++ b/src/sccp_user.c
@@ -92,9 +92,14 @@
 /*! \brief Bind a SCCP User to a given Point Code
  *  \param[in] inst SCCP Instance
  *  \param[in] name human-readable name
+ *  \param[in] prim_cb User provided callback to pass a primitive/msg up the stack
  *  \param[in] ssn Sub-System Number to bind to
  *  \param[in] pc Point Code to bind to, or OSMO_SS7_PC_INVALID if none.
- *  \returns Callee-allocated SCCP User on success; negative otherwise */
+ *  \returns Callee-allocated SCCP User on success; negative otherwise
+ *
+ * Ownership of oph->msg in prim_cb is transferred to the user of the
+ * registered callback when called.
+ */
 static struct osmo_sccp_user *
 sccp_user_bind_pc(struct osmo_sccp_instance *inst, const char *name,
 		  osmo_prim_cb prim_cb, uint16_t ssn, uint32_t pc)
@@ -127,9 +132,14 @@
 /*! \brief Bind a given SCCP User to a given SSN+PC
  *  \param[in] inst SCCP Instance
  *  \param[in] name human-readable name
+ *  \param[in] prim_cb User provided callback to pass a primitive/msg up the stack
  *  \param[in] ssn Sub-System Number to bind to
  *  \param[in] pc Point Code to bind to
- *  \returns Callee-allocated SCCP User on success; negative otherwise */
+ *  \returns Callee-allocated SCCP User on success; negative otherwise
+ *
+ * Ownership of oph->msg in prim_cb is transferred to the user of the
+ * registered callback when called.
+ */
 struct osmo_sccp_user *
 osmo_sccp_user_bind_pc(struct osmo_sccp_instance *inst, const char *name,
 		       osmo_prim_cb prim_cb, uint16_t ssn, uint32_t pc)
@@ -140,8 +150,13 @@
 /*! \brief Bind a given SCCP User to a given SSN (at any PC)
  *  \param[in] inst SCCP Instance
  *  \param[in] name human-readable name
+ *  \param[in] prim_cb User provided callback to pass a primitive/msg up the stack
  *  \param[in] ssn Sub-System Number to bind to
- *  \returns Callee-allocated SCCP User on success; negative otherwise */
+ *  \returns Callee-allocated SCCP User on success; negative otherwise
+ *
+ * Ownership of oph->msg in prim_cb is transferred to the user of the
+ * registered callback when called.
+ */
 struct osmo_sccp_user *
 osmo_sccp_user_bind(struct osmo_sccp_instance *inst, const char *name,
 		    osmo_prim_cb prim_cb, uint16_t ssn)
@@ -175,7 +190,10 @@
 /*! \brief Send a SCCP User SAP Primitive up to the User
  *  \param[in] scu SCCP User to whom to send the primitive
  *  \param[in] prim Primitive to send to the user
- *  \returns return value of the SCCP User's prim_cb() function */
+ *  \returns return value of the SCCP User's prim_cb() function
+ *
+ * Ownership of prim->oph->msg is passed to the user of the registered callback
+ */
 int sccp_user_prim_up(struct osmo_sccp_user *scu, struct osmo_scu_prim *prim)
 {
 	LOGP(DLSCCP, LOGL_DEBUG, "Delivering %s to SCCP User '%s'\n",

To view, visit change 40157. To unsubscribe, or for help writing mail filters, visit settings.