Expose default devices
[media-ctl.git] / src / mediactl.h
index cddf272..b74be0b 100644 (file)
@@ -1,20 +1,22 @@
 /*
  * Media controller interface library
  *
- * Copyright (C) 2010 Ideas on board SPRL <laurent.pinchart@ideasonboard.com>
+ * Copyright (C) 2010-2011 Ideas on board SPRL
+ *
+ * Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
  *
  * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; either version 2.1 of the License, or
  * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * GNU Lesser General Public License for more details.
  *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef __MEDIA_H__
@@ -37,30 +39,46 @@ struct media_pad {
        __u32 padding[3];
 };
 
-struct media_entity {
-       struct media_device *media;
-       struct media_entity_desc info;
-       struct media_pad *pads;
-       struct media_link *links;
-       unsigned int max_links;
-       unsigned int num_links;
-
-       char devname[32];
-       int fd;
-       __u32 padding[6];
-};
+struct media_device;
+struct media_entity;
 
-struct media_device {
-       int fd;
-       struct media_entity *entities;
-       unsigned int entities_count;
-       void (*debug_handler)(void *, ...);
-       void *debug_priv;
-       __u32 padding[6];
-};
+/**
+ * @brief Create a new media device.
+ * @param devnode - device node path.
+ *
+ * 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.
+ */
+struct media_device *media_device_new(const char *devnode);
+
+/**
+ * @brief Take a reference to the device.
+ * @param media - device instance.
+ *
+ * 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 media.
+ */
+struct media_device *media_device_ref(struct media_device *media);
 
-#define media_dbg(media, ...) \
-       (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
+/**
+ * @brief Release a reference to the device.
+ * @param media - device instance.
+ *
+ * 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.
@@ -77,60 +95,88 @@ void media_debug_set_handler(
        void *debug_priv);
 
 /**
- * @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
+ * @brief Enumerate the device topology
+ * @param media - device instance.
  *
- * Open the media device referenced by @a name and enumerate entities, pads and
- * links.
+ * Enumerate the media device entities, pads and links. Calling this function is
+ * mandatory before accessing the media device contents.
  *
- * 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().
+ * @return Zero on success or a negative error code on failure.
+ */
+int media_device_enumerate(struct media_device *media);
+
+/**
+ * @brief Locate the pad at the other end of a link.
+ * @param pad - sink pad at one end of the link.
  *
- * @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.
+ * Locate the source pad connected to @a pad through an enabled link. As only one
+ * link connected to a sink pad can be enabled at a time, the connected source
+ * pad is guaranteed to be unique.
+ *
+ * @return A pointer to the connected source pad, or NULL if all links connected
+ * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
  */
-struct media_device *media_open_debug(
-       const char *name, void (*debug_handler)(void *, ...),
-       void *debug_priv);
+struct media_pad *media_entity_remote_source(struct media_pad *pad);
 
 /**
- * @brief Open a media device.
- * @param name - name (including path) of the device node.
+ * @brief Get information about a media entity
+ * @param entity - media entity.
  *
- * Open the media device referenced by @a name and enumerate entities, pads and
- * links.
+ * The information structure is owned by the media entity object and will be
+ * freed when the object is destroyed.
  *
- * @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 the media entity information
  */
-struct media_device *media_open(const char *name);
+const struct media_entity_desc *media_entity_get_info(struct media_entity *entity);
 
 /**
- * @brief Close a media device.
- * @param media - device instance.
+ * @brief Get an entity pad
+ * @param entity - media entity.
+ * @param index - pad index.
+ *
+ * This function returns a pointer to the pad object identified by its index
+ * for the given entity. If the pad index is out of bounds it will return NULL.
  *
- * Close the @a media device instance and free allocated resources. Access to the
- * device instance is forbidden after this function returns.
+ * @return A pointer to the pad
  */
-void media_close(struct media_device *media);
+const struct media_pad *media_entity_get_pad(struct media_entity *entity,
+                                            unsigned int index);
 
 /**
- * @brief Locate the pad at the other end of a link.
- * @param pad - sink pad at one end of the link.
+ * @brief Get the number of links
+ * @param entity - media entity.
  *
- * Locate the source pad connected to @a pad through an enabled link. As only one
- * link connected to a sink pad can be enabled at a time, the connected source
- * pad is guaranteed to be unique.
+ * This function returns the total number of links that originate from or arrive
+ * at the the media entity.
  *
- * @return A pointer to the connected source pad, or NULL if all links connected
- * to @a pad are disabled. Return NULL also if @a pad is not a sink pad.
+ * @return The number of links for the entity
  */
-struct media_pad *media_entity_remote_source(struct media_pad *pad);
+unsigned int media_entity_get_links_count(struct media_entity *entity);
+
+/**
+ * @brief Get an entity link
+ * @param entity - media entity.
+ * @param index - link index.
+ *
+ * This function returns a pointer to the link object identified by its index
+ * for the given entity. If the link index is out of bounds it will return NULL.
+ *
+ * @return A pointer to the link
+ */
+const struct media_link *media_entity_get_link(struct media_entity *entity,
+                                              unsigned int index);
+
+/**
+ * @brief Get the device node name for an entity
+ * @param entity - media entity.
+ *
+ * This function returns the full path and name to the device node corresponding
+ * to the given entity.
+ *
+ * @return A pointer to the device node name or NULL if the entity has no
+ * associated device node
+ */
+const char *media_entity_get_devname(struct media_entity *entity);
 
 /**
  * @brief Get the type of an entity.
@@ -140,7 +186,7 @@ struct media_pad *media_entity_remote_source(struct media_pad *pad);
  */
 static inline unsigned int media_entity_type(struct media_entity *entity)
 {
-       return entity->info.type & MEDIA_ENT_TYPE_MASK;
+       return media_entity_get_info(entity)->type & MEDIA_ENT_TYPE_MASK;
 }
 
 /**
@@ -161,13 +207,83 @@ struct media_entity *media_get_entity_by_name(struct media_device *media,
  * @param media - media device.
  * @param id - entity ID.
  *
- * Search for an entity with an ID equal to @a id.
+ * This function searches for an entity based on its ID using an exact match or
+ * next ID method based on the given @a id. If @a id is ORed with
+ * MEDIA_ENT_ID_FLAG_NEXT, the function will return the entity with the smallest
+ * ID larger than @a id. Otherwise it will return the entity with an ID equal to
+ * @a id.
  *
  * @return A pointer to the entity if found, or NULL otherwise.
  */
 struct media_entity *media_get_entity_by_id(struct media_device *media,
        __u32 id);
 
+/**
+ * @brief Get the number of entities
+ * @param media - media device.
+ *
+ * This function returns the total number of entities in the media device. If
+ * entities haven't been enumerated yet it will return 0.
+ *
+ * @return The number of entities in the media device
+ */
+unsigned int media_get_entities_count(struct media_device *media);
+
+/**
+ * @brief Get the entities
+ * @param media - media device.
+ *
+ * This function returns a pointer to the array of entities for the media
+ * device. If entities haven't been enumerated yet it will return NULL.
+ *
+ * The array of entities is owned by the media device object and will be freed
+ * when the media object is destroyed.
+ *
+ * @return A pointer to an array of entities
+ */
+struct media_entity *media_get_entity(struct media_device *media, unsigned int index);
+
+/**
+ * @brief Get the default entity for a given type
+ * @param media - media device.
+ * @param type - entity type.
+ *
+ * This function returns the default entity of the requested type. @a type must
+ * be one of
+ *
+ *     MEDIA_ENT_T_DEVNODE_V4L
+ *     MEDIA_ENT_T_DEVNODE_FB
+ *     MEDIA_ENT_T_DEVNODE_ALSA
+ *     MEDIA_ENT_T_DEVNODE_DVB
+ *
+ * @return A pointer to the default entity for the type if it exists, or NULL
+ * otherwise.
+ */
+struct media_entity *media_get_default_entity(struct media_device *media,
+                                             unsigned int type);
+
+/**
+ * @brief Get the media device information
+ * @param media - media device.
+ *
+ * The information structure is owned by the media device object and will be freed
+ * when the media object is destroyed.
+ *
+ * @return A pointer to the media device information
+ */
+const struct media_device_info *media_get_info(struct media_device *media);
+
+/**
+ * @brief Get the media device node name
+ * @param media - media device.
+ *
+ * The device node name string is owned by the media device object and will be
+ * freed when the media object is destroyed.
+ *
+ * @return A pointer to the media device node name
+ */
+const char *media_get_devnode(struct media_device *media);
+
 /**
  * @brief Configure a link.
  * @param media - media device.