/** @endcond */
-/** @private */
-SRD_PRIV int session_is_valid(struct srd_session *sess)
-{
-
- if (!sess || sess->session_id < 1)
- return SRD_ERR;
-
- return SRD_OK;
-}
-
/**
* Create a decoding session.
*
* output callbacks.
*
* @param sess A pointer which will hold a pointer to a newly
- * initialized session on return.
+ * initialized session on return. Must not be NULL.
*
* @return SRD_OK upon success, a (negative) error code otherwise.
*
*/
SRD_API int srd_session_new(struct srd_session **sess)
{
-
- if (!sess) {
- srd_err("Invalid session pointer.");
+ if (!sess)
return SRD_ERR_ARG;
- }
*sess = g_malloc(sizeof(struct srd_session));
(*sess)->session_id = ++max_session_id;
/* Keep a list of all sessions, so we can clean up as needed. */
sessions = g_slist_append(sessions, *sess);
- srd_dbg("Created session %d.", (*sess)->session_id);
+ srd_dbg("Creating session %d.", (*sess)->session_id);
return SRD_OK;
}
* Decoders, instances and stack must have been prepared beforehand,
* and all SRD_CONF parameters set.
*
- * @param sess The session to start.
+ * @param sess The session to start. Must not be NULL.
*
* @return SRD_OK upon success, a (negative) error code otherwise.
*
struct srd_decoder_inst *di;
int ret;
- if (session_is_valid(sess) != SRD_OK) {
- srd_err("Invalid session pointer.");
- return SRD_ERR;
- }
+ if (!sess)
+ return SRD_ERR_ARG;
- srd_dbg("Calling start() on all instances in session %d.", sess->session_id);
+ srd_dbg("Calling start() of all instances in session %d.", sess->session_id);
- /* Run the start() method on all decoders receiving frontend data. */
+ /* Run the start() method of all decoders receiving frontend data. */
ret = SRD_OK;
for (d = sess->di_list; d; d = d->next) {
di = d->data;
/**
* Set a metadata configuration key in a session.
*
- * @param sess The session to configure.
+ * @param sess The session to configure. Must not be NULL.
* @param key The configuration key (SRD_CONF_*).
* @param data The new value for the key, as a GVariant with GVariantType
* appropriate to that key. A floating reference can be passed
GSList *l;
int ret;
- if (session_is_valid(sess) != SRD_OK) {
- srd_err("Invalid session.");
+ if (!sess)
return SRD_ERR_ARG;
- }
if (!key) {
srd_err("Invalid key.");
GSList *d;
int ret;
- if (session_is_valid(sess) != SRD_OK) {
- srd_err("Invalid session.");
+ if (!sess)
return SRD_ERR_ARG;
- }
for (d = sess->di_list; d; d = d->next) {
if ((ret = srd_inst_decode(d->data, abs_start_samplenum,
return SRD_OK;
}
+/**
+ * Communicate the end of the stream of sample data to the session.
+ *
+ * @param[in] sess The session. Must not be NULL.
+ *
+ * @return SRD_OK upon success. A (negative) error code otherwise.
+ *
+ * @since 0.6.0
+ */
+SRD_API int srd_session_send_eof(struct srd_session *sess)
+{
+ GSList *d;
+ int ret;
+
+ if (!sess)
+ return SRD_ERR_ARG;
+
+ for (d = sess->di_list; d; d = d->next) {
+ ret = srd_inst_send_eof(d->data);
+ if (ret != SRD_OK)
+ return ret;
+ }
+
+ return SRD_OK;
+}
+
+/**
+ * Terminate currently executing decoders in a session, reset internal state.
+ *
+ * All decoder instances have their .wait() method terminated, which
+ * shall terminate .decode() as well. Afterwards the decoders' optional
+ * .reset() method gets executed.
+ *
+ * This routine allows callers to abort pending expensive operations,
+ * when they are no longer interested in the decoders' results. Note
+ * that the decoder state is lost and aborted work cannot resume.
+ *
+ * This routine also allows callers to re-use previously created decoder
+ * stacks to process new input data which is not related to previously
+ * processed input data. This avoids the necessity to re-construct the
+ * decoder stack.
+ *
+ * @param sess The session in which to terminate decoders. Must not be NULL.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.5.1
+ */
+SRD_API int srd_session_terminate_reset(struct srd_session *sess)
+{
+ GSList *d;
+ int ret;
+
+ if (!sess)
+ return SRD_ERR_ARG;
+
+ for (d = sess->di_list; d; d = d->next) {
+ ret = srd_inst_terminate_reset(d->data);
+ if (ret != SRD_OK)
+ return ret;
+ }
+
+ return SRD_OK;
+}
+
/**
* Destroy a decoding session.
*
* All decoder instances and output callbacks are properly released.
*
- * @param sess The session to be destroyed.
+ * @param sess The session to be destroyed. Must not be NULL.
*
* @return SRD_OK upon success, a (negative) error code otherwise.
*
{
int session_id;
- if (!sess) {
- srd_err("Invalid session.");
+ if (!sess)
return SRD_ERR_ARG;
- }
session_id = sess->session_id;
if (sess->di_list)
* stack).
*
* @param sess The output session in which to register the callback.
+ * Must not be NULL.
* @param output_type The output type this callback will receive. Only one
* callback per output type can be registered.
* @param cb The function to call. Must not be NULL.
{
struct srd_pd_callback *pd_cb;
- if (session_is_valid(sess) != SRD_OK) {
- srd_err("Invalid session.");
+ if (!sess)
return SRD_ERR_ARG;
- }
- srd_dbg("Registering new callback for output type %d.", output_type);
+ srd_dbg("Registering new callback for output type %s.",
+ output_type_name(output_type));
pd_cb = g_malloc(sizeof(struct srd_pd_callback));
pd_cb->output_type = output_type;
GSList *l;
struct srd_pd_callback *tmp, *pd_cb;
- if (session_is_valid(sess) != SRD_OK) {
- srd_err("Invalid session.");
+ if (!sess)
return NULL;
- }
pd_cb = NULL;
for (l = sess->callbacks; l; l = l->next) {