event: add doxygen

include/baresip.h

@@ -1680,6 +1680,8 @@ struct ua      *bevent_get_ua(const struct bevent *event);
 const struct sip_msg *bevent_get_msg(const struct bevent *event);
 enum ua_event bevent_get_enum(const struct bevent *event);
 const char *bevent_get_text(const struct bevent *event);
+void bevent_set_error(struct bevent *event, int err);
+void bevent_stop(struct bevent *event);
 
 
 /*

src/event.c

@@ -201,6 +201,15 @@ static const char *bevent_class_name(enum ua_event ev)
 }
 
 
+/**
+ * Returns the call object of a call event, which was generated by function
+ * bevent_call_emit(). If the event was generated by another emit function
+ * then NULL is returned
+ *
+ * @param event Baresip event
+ *
+ * @return The call object, or NULL.
+ */
 struct call *bevent_get_call(const struct bevent *event)
 {
 	if (!event)
@@ -213,6 +222,15 @@ struct call *bevent_get_call(const struct bevent *event)
 }
 
 
+/**
+ * Returns the User-Agent of a UA or call event, which was generated by
+ * function bevent_ua_emit() or function bevent_call_emit(). If the event was
+ * generated by another emit function then NULL is returned
+ *
+ * @param event Baresip event
+ *
+ * @return The User-Agent, or NULL.
+ */
 struct ua *bevent_get_ua(const struct bevent *event)
 {
 	struct call *call;
@@ -231,6 +249,15 @@ struct ua *bevent_get_ua(const struct bevent *event)
 }
 
 
+/**
+ * Returns the sip_msg of a SIP message event, which was generated by function
+ * bevent_sip_msg_emit(). If the event was generated by another emit function
+ * then NULL is returned
+ *
+ * @param event Baresip event
+ *
+ * @return The SIP message, or NULL.
+ */
 const struct sip_msg *bevent_get_msg(const struct bevent *event)
 {
 	if (!event)
@@ -243,18 +270,64 @@ const struct sip_msg *bevent_get_msg(const struct bevent *event)
 }
 
 
+/**
+ * Returns the event type
+ *
+ * @param event Baresip event
+ *
+ * @return the event type
+ */
 enum ua_event bevent_get_enum(const struct bevent *event)
 {
 	return event ? event->ev : UA_EVENT_MAX;
 }
 
 
+/**
+ * Returns the event text
+ *
+ * @param event Baresip event
+ *
+ * @return the event text
+ */
 const char *bevent_get_text(const struct bevent *event)
 {
 	return event ? event->txt : "";
 }
 
 
+/**
+ * Set error code of bevent. This should be used in the event handler to inform
+ * the baresip core that an error occurred. An event with set error is not
+ * passed to further event handlers
+ *
+ * @param event  Baresip event
+ * @param err    Error code
+ */
+void bevent_set_error(struct bevent *event, int err)
+{
+	if (!event)
+		return;
+
+	event->err = err;
+}
+
+
+/**
+ * Stops event processing. This should be used in an event handler to stop
+ * passing the event to further event handlers
+ *
+ * @param event  Baresip event
+ */
+void bevent_stop(struct bevent *event)
+{
+	if (!event)
+		return;
+
+	event->stop = true;
+}
+
+
 static int add_rtcp_stats(struct odict *od_parent, const struct rtcp_stats *rs)
 {
 	struct odict *od = NULL, *tx = NULL, *rx = NULL;