summaryrefslogtreecommitdiff
path: root/src/mediactl.h
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart@ideasonboard.com>2012-07-31 13:10:44 +0200
committerLaurent Pinchart <laurent.pinchart@ideasonboard.com>2014-03-10 19:53:57 +0100
commitbc72e1332cfc81e166c83c90ad63b4b648f19867 (patch)
tree91285072d74f8addcd5a72e6960f37e61a7e95b4 /src/mediactl.h
parent45033a900fb0d004b9790f7b9d57045ea7510cd3 (diff)
Split media_device creation and opening
Make the media_device refcounted to manage its life time. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Hans Verkuil <hans.verkuil@cisco.com> Acked-by: Sakari Ailus <sakari.ailus@iki.fi>
Diffstat (limited to 'src/mediactl.h')
-rw-r--r--src/mediactl.h84
1 files changed, 46 insertions, 38 deletions
diff --git a/src/mediactl.h b/src/mediactl.h
index 2296fe2..34e7487 100644
--- a/src/mediactl.h
+++ b/src/mediactl.h
@@ -54,6 +54,8 @@ struct media_entity {
struct media_device {
int fd;
+ int refcount;
+ char *devnode;
struct media_device_info info;
struct media_entity *entities;
unsigned int entities_count;
@@ -66,61 +68,67 @@ struct media_device {
(media)->debug_handler((media)->debug_priv, __VA_ARGS__)
/**
- * @brief Set a handler for debug messages.
- * @param media - device instance.
- * @param debug_handler - debug message handler
- * @param debug_priv - first argument to debug message handler
+ * @brief Create a new media device.
+ * @param devnode - device node path.
*
- * Set a handler for debug messages that will be called whenever
- * debugging information is to be printed. The handler expects an
- * fprintf-like function.
+ * Create a media device instance for the given device node and return it. The
+ * device node is not accessed by this function, device node access errors will
+ * not be caught and reported here. The media device needs to be enumerated
+ * before it can be accessed, see media_device_enumerate().
+ *
+ * Media devices are reference-counted, see media_device_ref() and
+ * media_device_unref() for more information.
+ *
+ * @return A pointer to the new media device or NULL if memory cannot be
+ * allocated.
*/
-void media_debug_set_handler(
- struct media_device *media, void (*debug_handler)(void *, ...),
- void *debug_priv);
+struct media_device *media_device_new(const char *devnode);
/**
- * @brief Open a media device with debugging enabled.
- * @param name - name (including path) of the device node.
- * @param debug_handler - debug message handler
- * @param debug_priv - first argument to debug message handler
- *
- * Open the media device referenced by @a name and enumerate entities, pads and
- * links.
+ * @brief Take a reference to the device.
+ * @param media - device instance.
*
- * Calling media_open_debug() instead of media_open() is equivalent to
- * media_open() and media_debug_set_handler() except that debugging is
- * also enabled during media_open().
+ * Media devices are reference-counted. Taking a reference to a device prevents
+ * it from being freed until all references are released. The reference count is
+ * initialized to 1 when the device is created.
*
- * @return A pointer to a newly allocated media_device structure instance on
- * success and NULL on failure. The returned pointer must be freed with
- * media_close when the device isn't needed anymore.
+ * @return A pointer to @a media.
*/
-struct media_device *media_open_debug(
- const char *name, void (*debug_handler)(void *, ...),
- void *debug_priv);
+struct media_device *media_device_ref(struct media_device *media);
/**
- * @brief Open a media device.
- * @param name - name (including path) of the device node.
+ * @brief Release a reference to the device.
+ * @param media - device instance.
*
- * Open the media device referenced by @a name and enumerate entities, pads and
- * links.
+ * Release a reference to the media device. When the reference count reaches 0
+ * this function frees the device.
+ */
+void media_device_unref(struct media_device *media);
+
+/**
+ * @brief Set a handler for debug messages.
+ * @param media - device instance.
+ * @param debug_handler - debug message handler
+ * @param debug_priv - first argument to debug message handler
*
- * @return A pointer to a newly allocated media_device structure instance on
- * success and NULL on failure. The returned pointer must be freed with
- * media_close when the device isn't needed anymore.
+ * Set a handler for debug messages that will be called whenever
+ * debugging information is to be printed. The handler expects an
+ * fprintf-like function.
*/
-struct media_device *media_open(const char *name);
+void media_debug_set_handler(
+ struct media_device *media, void (*debug_handler)(void *, ...),
+ void *debug_priv);
/**
- * @brief Close a media device.
+ * @brief Enumerate the device topology
* @param media - device instance.
*
- * Close the @a media device instance and free allocated resources. Access to the
- * device instance is forbidden after this function returns.
+ * Enumerate the media device entities, pads and links. Calling this function is
+ * mandatory before accessing the media device contents.
+ *
+ * @return Zero on success or a negative error code on failure.
*/
-void media_close(struct media_device *media);
+int media_device_enumerate(struct media_device *media);
/**
* @brief Locate the pad at the other end of a link.