laforge submitted this 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.