scope_trace: Add/update utilities

* Added a AST_STREAM_STATE_END sentinel
* Add ast_stream_to_str()
* Add ast_stream_state_to_str()
* Add ast_stream_get_format_count()
* Add ast_stream_topology_to_str()
* Add ast_stream_topology_get_active_count()
* Add ast_format_cap_append_names()
* Add ast_sip_session_get_name()

Change-Id: I132eb5971ea41509c660f64e9113cda8c9013b0b

include/asterisk/format_cap.h

@@ -310,6 +310,17 @@ int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_media_typ
  */
 const char *ast_format_cap_get_names(const struct ast_format_cap *cap, struct ast_str **buf);
 
+/*!
+ * \brief Append the names of codecs of a set of formats to an ast_str buffer
+ * \since 18
+ *
+ * \param cap The capabilities structure containing the formats
+ * \param buf A \c ast_str buffer to append the names of the formats to
+ *
+ * \return The contents of the buffer in \c buf
+ */
+const char *ast_format_cap_append_names(const struct ast_format_cap *cap, struct ast_str **buf);
+
 #ifndef AST_FORMAT_CAP_NAMES_LEN
 /*! Buffer size for callers of ast_format_cap_get_names to allocate. */
 #define AST_FORMAT_CAP_NAMES_LEN 384

include/asterisk/res_pjsip_session.h

@@ -912,4 +912,12 @@ int ast_sip_session_media_set_write_callback(struct ast_sip_session *session, st
  */
 struct ast_sip_session_media *ast_sip_session_media_get_transport(struct ast_sip_session *session, struct ast_sip_session_media *session_media);
 
+/*!
+ * \brief Get the channel or endpoint name associated with the session
+ *
+ * \param session
+ * \retval Channel name or endpoint name or "unknown"
+ */
+const char *ast_sip_session_get_name(const struct ast_sip_session *session);
+
 #endif /* _RES_PJSIP_SESSION_H */

include/asterisk/stream.h

@@ -75,8 +75,28 @@ enum ast_stream_state {
 	 * \brief Set when the stream is not sending OR receiving media
 	 */
 	AST_STREAM_STATE_INACTIVE,
+    /*!
+     * \brief Sentinel
+     */
+    AST_STREAM_STATE_END
 };
 
+/*!
+ * \brief Stream state enum to string map
+ * \internal
+ */
+extern const char *ast_stream_state_map[AST_STREAM_STATE_END];
+
+/*!
+ * \brief Safely get the name of a stream state
+ * \since 18
+ *
+ * \param stream_state One of enum ast_stream_state
+ * \returns A constant string with the name of the state or an empty string
+ * if an invalid value was passed in.
+ */
+#define ast_stream_state_to_str(stream_state) _stream_maps_to_str(ast_stream_state_map, stream_state)
+
 /*!
  * \brief Create a new media stream representation
  *
@@ -152,6 +172,42 @@ enum ast_media_type ast_stream_get_type(const struct ast_stream *stream);
  */
 void ast_stream_set_type(struct ast_stream *stream, enum ast_media_type type);
 
+/*!
+ * \brief Get a string representing the stream for debugging/display purposes
+ * \since 18
+ *
+ * \param stream A stream
+ * \param buf A pointer to an ast_str* used for the output.
+ *
+ * \retval "" (empty string) if either buf or *buf are NULL
+ * \retval "(null stream)" if *stream was NULL
+ * \retval <stream_representation> otherwise
+ *
+ * \warning No attempt should ever be made to free the returned
+ * char * and it should be dup'd if needed after the ast_str is freed.
+ *
+ * \details
+ *
+ * Return format:
+ * <name>:<media_type>:<stream_state> (formats)
+ *
+ * Sample return:
+ * "audio:audio:sendrecv (ulaw,g722)"
+ *
+ */
+const char *ast_stream_to_str(const struct ast_stream *stream, struct ast_str **buf);
+
+/*!
+ * \brief Get the count of the current negotiated formats of a stream
+ *
+ * \param stream The media stream
+ *
+ * \return The count of negotiated formats
+ *
+ * \since 18
+ */
+int ast_stream_get_format_count(const struct ast_stream *stream);
+
 /*!
  * \brief Get the current negotiated formats of a stream
  *
@@ -523,4 +579,35 @@ int ast_stream_get_group(const struct ast_stream *stream);
  */
 void ast_stream_set_group(struct ast_stream *stream, int group);
 
+/*!
+ * \brief Get the number of active (non-REMOVED) streams in a topology
+ *
+ * \param topology The topology of streams
+ *
+ * \return the number of active streams
+ */
+int ast_stream_topology_get_active_count(const struct ast_stream_topology *topology);
+
+/*!
+ * \brief Get a string representing the topology for debugging/display purposes
+ *
+ * \param topology A stream topology
+ * \param buf A pointer to an ast_str* used for the output.
+ *
+ * \retval "" (empty string) if either buf or *buf are NULL
+ * \retval "(null topology)" if *topology was NULL
+ * \retval <topology_representation> otherwise
+ *
+ * \warning No attempt should ever be made to free the returned
+ * char * and it should be dup'd if needed after the ast_str is freed.
+  *
+ * Return format:
+ * <stream> ...
+ *
+ * Sample return:
+ * "<audio:audio:sendrecv (ulaw,g722)> <video:video:sendonly (h264)>"
+ *
+ */
+const char *ast_stream_topology_to_str(const struct ast_stream_topology *topology, struct ast_str **buf);
+
 #endif /* _AST_STREAM_H */

main/format_cap.c

@@ -699,11 +699,19 @@ int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast
 	return internal_format_cap_identical(cap2, cap1);
 }
 
-const char *ast_format_cap_get_names(const struct ast_format_cap *cap, struct ast_str **buf)
+static const char *__ast_format_cap_get_names(const struct ast_format_cap *cap, struct ast_str **buf, int append)
 {
 	int i;
 
-	ast_str_set(buf, 0, "(");
+	if (!buf || !*buf) {
+		return "";
+	}
+
+	if (append) {
+		ast_str_append(buf, 0, "(");
+	} else {
+		ast_str_set(buf, 0, "(");
+	}
 
 	if (!cap || !AST_VECTOR_SIZE(&cap->preference_order)) {
 		ast_str_append(buf, 0, "nothing)");
@@ -725,6 +733,16 @@ const char *ast_format_cap_get_names(const struct ast_format_cap *cap, struct as
 	return ast_str_buffer(*buf);
 }
 
+const char *ast_format_cap_get_names(const struct ast_format_cap *cap, struct ast_str **buf)
+{
+	return __ast_format_cap_get_names(cap, buf, 0);
+}
+
+const char *ast_format_cap_append_names(const struct ast_format_cap *cap, struct ast_str **buf)
+{
+	return __ast_format_cap_get_names(cap, buf, 1);
+}
+
 int ast_format_cap_empty(const struct ast_format_cap *cap)
 {
 	int count = ast_format_cap_count(cap);

main/stream.c

@@ -93,6 +93,14 @@ struct ast_stream_topology {
 	AST_VECTOR(, struct ast_stream *) streams;
 };
 
+const char *ast_stream_state_map[] = {
+       [AST_STREAM_STATE_REMOVED] = "removed",
+       [AST_STREAM_STATE_SENDRECV] = "sendrecv",
+       [AST_STREAM_STATE_SENDONLY] = "sendonly",
+       [AST_STREAM_STATE_RECVONLY] = "recvonly",
+       [AST_STREAM_STATE_INACTIVE] = "inactive",
+};
+
 struct ast_stream *ast_stream_alloc(const char *name, enum ast_media_type type)
 {
 	struct ast_stream *stream;
@@ -196,6 +204,33 @@ const struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *str
 	return stream->formats;
 }
 
+const char *ast_stream_to_str(const struct ast_stream *stream, struct ast_str **buf)
+{
+       if (!buf || !*buf) {
+               return "";
+       }
+
+       if (!stream) {
+               ast_str_append(buf, 0, "(null stream)");
+               return ast_str_buffer(*buf);
+       }
+
+       ast_str_append(buf, 0, "%s:%s:%s ",
+               S_OR(stream->name, "noname"),
+               ast_codec_media_type2str(stream->type),
+               ast_stream_state_map[stream->state]);
+       ast_format_cap_append_names(stream->formats, buf);
+
+       return ast_str_buffer(*buf);
+}
+
+int ast_stream_get_format_count(const struct ast_stream *stream)
+{
+       ast_assert(stream != NULL);
+
+       return stream->formats ? ast_format_cap_count(stream->formats) : 0;
+}
+
 void ast_stream_set_formats(struct ast_stream *stream, struct ast_format_cap *caps)
 {
 	ast_assert(stream != NULL);
@@ -495,6 +530,22 @@ int ast_stream_topology_get_count(const struct ast_stream_topology *topology)
 	return AST_VECTOR_SIZE(&topology->streams);
 }
 
+int ast_stream_topology_get_active_count(const struct ast_stream_topology *topology)
+{
+       int i;
+       int count = 0;
+       ast_assert(topology != NULL);
+
+       for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
+               struct ast_stream *stream = AST_VECTOR_GET(&topology->streams, i);
+               if (stream->state != AST_STREAM_STATE_REMOVED) {
+                       count++;
+               }
+       }
+
+       return count;
+}
+
 struct ast_stream *ast_stream_topology_get_stream(
 	const struct ast_stream_topology *topology, unsigned int stream_num)
 {
@@ -631,6 +682,32 @@ struct ast_format_cap *ast_format_cap_from_stream_topology(
 	return caps;
 }
 
+const char *ast_stream_topology_to_str(const struct ast_stream_topology *topology,
+       struct ast_str **buf)
+{
+       int i;
+
+       if (!buf ||!*buf) {
+               return "";
+       }
+
+       if (!topology) {
+               ast_str_append(buf, 0, "(null topology)");
+               return ast_str_buffer(*buf);
+       }
+
+       for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
+               struct ast_stream *stream;
+
+               stream = AST_VECTOR_GET(&topology->streams, i);
+               ast_str_append(buf, 0, " <");
+               ast_stream_to_str(stream, buf);
+               ast_str_append(buf, 0, ">");
+       }
+
+       return ast_str_buffer(*buf);
+}
+
 struct ast_stream *ast_stream_topology_get_first_stream_by_type(
 	const struct ast_stream_topology *topology,
 	enum ast_media_type type)

res/res_pjsip_session.c

@@ -110,6 +110,20 @@ static int sdp_handler_list_hash(const void *obj, int flags)
 	return ast_str_hash(stream_type);
 }
 
+const char *ast_sip_session_get_name(const struct ast_sip_session *session)
+{
+	if (!session) {
+		return "(null session)";
+	}
+	if (session->channel) {
+		return ast_channel_name(session->channel);
+	} else if (session->endpoint) {
+		return ast_sorcery_object_get_id(session->endpoint);
+	} else {
+		return "unknown";
+	}
+}
+
 static int sdp_handler_list_cmp(void *obj, void *arg, int flags)
 {
 	struct sdp_handler_list *handler_list1 = obj;