/**
* Create a new session.
- * Currently, there can be only one session at a time within the same process.
+ *
+ * @param new_session This will contain a pointer to the newly created
+ * session if the return value is SR_OK, otherwise the value
+ * is undefined and should not be used. Must not be NULL.
*
* @retval SR_OK Success.
- * @retval SR_ERR_BUG A session exists already.
+ * @retval SR_ERR_ARG Invalid argument.
*
* @since 0.4.0
*/
{
struct sr_session *session;
+ if (!new_session)
+ return SR_ERR_ARG;
+
session = g_malloc0(sizeof(struct sr_session));
session->source_timeout = -1;
* Destroy a session.
* This frees up all memory used by the session.
*
+ * @param session The session to destroy. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid session passed.
*
* The session itself (i.e., the struct sr_session) is not free'd and still
* exists after this function returns.
*
+ * @param session The session to use. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_BUG Invalid session passed.
*
/**
* Add a device instance to a session.
*
+ * @param session The session to add to. Must not be NULL.
* @param sdi The device instance to add to a session. Must not
* be NULL. Also, sdi->driver and sdi->driver->dev_open must
* not be NULL.
/* If sdi->driver is NULL, this is a virtual device. */
if (!sdi->driver) {
- sr_dbg("%s: sdi->driver was NULL, this seems to be "
- "a virtual device; continuing", __func__);
/* Just add the device, don't run dev_open(). */
session->devs = g_slist_append(session->devs, (gpointer)sdi);
sdi->session = session;
/**
* List all device instances attached to a session.
*
+ * @param session The session to use. Must not be NULL.
* @param devlist A pointer where the device instance list will be
* stored on return. If no devices are in the session,
* this will be NULL. Each element in the list points
/**
* Remove all datafeed callbacks in a session.
*
+ * @param session The session to use. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid session passed.
*
/**
* Add a datafeed callback to a session.
*
+ * @param session The session to use. Must not be NULL.
* @param cb Function to call when a chunk of data is received.
* Must not be NULL.
* @param cb_data Opaque pointer passed in by the caller.
* but driven by another scheduler, this can be used to poll the devices
* from within that scheduler.
*
+ * @param session The session to use. Must not be NULL.
* @param block If TRUE, this call will wait for any of the session's
* sources to fire an event on the file descriptors, or
* any of their timeouts to activate. In other words, this
/**
* Start a session.
*
+ * @param session The session to use. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid session passed.
*
/**
* Run a session.
*
+ * @param session The session to use. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid session passed.
*
* This must be called from within the session thread, to prevent freeing
* resources that the session thread will try to use.
*
+ * @param session The session to use. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid session passed.
*
* to wait for the session thread to return before assuming that the session is
* completely decommissioned.
*
+ * @param session The session to use. Must not be NULL.
+ *
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid session passed.
*
/**
* Add an event source for a file descriptor.
*
+ * @param session The session to use. Must not be NULL.
* @param pollfd The GPollFD.
* @param[in] timeout Max time to wait before the callback is called,
* ignored if 0.
/**
* Add an event source for a file descriptor.
*
+ * @param session The session to use. Must not be NULL.
* @param fd The file descriptor.
* @param events Events to check for.
* @param timeout Max time to wait before the callback is called, ignored if 0.
{
GPollFD p;
- (void) session;
-
p.fd = fd;
p.events = events;
/**
* Add an event source for a GPollFD.
*
+ * @param session The session to use. Must not be NULL.
* @param pollfd The GPollFD.
* @param timeout Max time to wait before the callback is called, ignored if 0.
* @param cb Callback function to add. Must not be NULL.
GPollFD *pollfd, int timeout, sr_receive_data_callback cb,
void *cb_data)
{
- (void) session;
-
return _sr_session_source_add(session, pollfd, timeout, cb,
cb_data, (gintptr)pollfd);
}
/**
* Add an event source for a GIOChannel.
*
+ * @param session The session to use. Must not be NULL.
* @param channel The GIOChannel.
* @param events Events to poll on.
* @param timeout Max time to wait before the callback is called, ignored if 0.
{
GPollFD p;
- (void) session;
-
#ifdef _WIN32
g_io_channel_win32_make_pollfd(channel, events, &p);
#else
*
* @todo Add more error checks and logging.
*
+ * @param session The session to use. Must not be NULL.
* @param poll_object The channel for which the source should be removed.
*
* @retval SR_OK Success
/**
* Remove the source belonging to the specified file descriptor.
*
+ * @param session The session to use. Must not be NULL.
* @param fd The file descriptor for which the source should be removed.
*
* @retval SR_OK Success
*/
SR_API int sr_session_source_remove(struct sr_session *session, int fd)
{
- (void) session;
-
return _sr_session_source_remove(session, (gintptr)fd);
}
/**
* Remove the source belonging to the specified poll descriptor.
*
+ * @param session The session to use. Must not be NULL.
* @param pollfd The poll descriptor for which the source should be removed.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
SR_API int sr_session_source_remove_pollfd(struct sr_session *session,
GPollFD *pollfd)
{
- (void) session;
-
return _sr_session_source_remove(session, (gintptr)pollfd);
}
/**
* Remove the source belonging to the specified channel.
*
+ * @param session The session to use. Must not be NULL.
* @param channel The channel for which the source should be removed.
*
* @retval SR_OK Success.
SR_API int sr_session_source_remove_channel(struct sr_session *session,
GIOChannel *channel)
{
- (void) session;
-
return _sr_session_source_remove(session, (gintptr)channel);
}