diff options
author | Laurent Pinchart <laurent.pinchart@ideasonboard.com> | 2012-07-30 16:40:42 +0200 |
---|---|---|
committer | Laurent Pinchart <laurent.pinchart@ideasonboard.com> | 2013-10-23 14:25:31 +0200 |
commit | 67cc5f8c2cdc361204cb5d71fc4a48c344fe95f1 (patch) | |
tree | 768e1b619569636e5985da9385cbee8cf6d7c15c /media-enumerate.h |
Initial version of the libmediadev library
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Diffstat (limited to 'media-enumerate.h')
-rw-r--r-- | media-enumerate.h | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/media-enumerate.h b/media-enumerate.h new file mode 100644 index 0000000..ecd6b3d --- /dev/null +++ b/media-enumerate.h @@ -0,0 +1,114 @@ +/* + * Media device discovery library + * + * Copyright (C) 2012 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 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 Lesser General Public License for more details. + * + * 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_ENUMERATE_H__ +#define __MEDIA_ENUMERATE_H__ + +struct media_enumerate; + +/** + * @brief Create a new media device enumeration context. + * + * Media device enumeration contexts are used to enumerate media devices. They + * store all context information required by enumeration and cache the + * enumeration results for later access. Enumeration itself is performed by the + * separate media_enumerate_scan() function. + * + * Enumeration contexts are reference-counted, see media_enumerate_ref() and + * media_enumerate_unref() for more information. + * + * @return A pointer to the new media device enumeration context or NULL if + * memory cannot be allocated. + */ +struct media_enumerate *media_enumerate_new(void); + +/** + * @brief Take a reference to the enumeration context. + * @param media_enum - enumeration context instance. + * + * Media device enumeration contexts are reference-counted. Taking a reference + * to an enumeration context prevents it and all the information it stores from + * being freed until all references are released. The reference count is + * initialized to 1 when the context is created. + * + * @return A pointer to @a media. + */ +struct media_enumerate *media_enumerate_ref(struct media_enumerate *media_enum); + +/** + * @brief Release a reference to the enumeration context. + * @param media_enum - enumeration context instance. + * + * Release a reference to the enumeration context. When the reference count + * reaches 0 this function frees the context, including all information it + * stores. + */ +void media_enumerate_unref(struct media_enumerate *media_enum); + +/** + * @brief Enumerate media devices in the system + * @param media_enum - enumeration context instance. + * + * Scan the system to locate all available media devices. This function must be + * called once and only once before accessing the list of enumerated devices. + * + * Devices are enumerated using libudev if available or through sysfs otherwise. + * sysfs-based enumeration requires device nodes to use the standard Linux + * device names and be numbered by the device sysfs device number. For instance + * the device node corresponding to /sys/class/video4linux/video0 must be named + * /dev/video0. libudev-based enumeration doesn't have this restriction. + * + * Media devices are enumerated by scanning media controller, V4L and ALSA + * kernel devices, in that order. Emulated media devices are created as needed + * for V4L devices that are not part of a media controller based device. ALSA + * devices without a corresponding media controller or V4L devices are skipped. + * + * @return Zero on success or a negative error code on failure. + */ +int media_enumerate_scan(struct media_enumerate *media_enum); + +/** + * @brief Get the number of media devices found during enumeration + * @param media_enum - enumeration context instance. + * + * This function returns the total number of media devices found in the system + * during enumeration. If media devices haven't been enumerated yet it will + * return 0. + * + * @return The number of media devices found in the system + */ +unsigned int media_enumerate_get_devices_count(struct media_enumerate *media_enum); + +/** + * @brief Get the media devices + * @param media_enum - enumeration context instance. + * + * This function returns a pointer to the array of enumerated media devices. If + * If media devices haven't been enumerated yet it will return NULL. + * + * The array of media devices is owned by the enumeration context and will be + * freed when the enumeration context is destroyed. + * + * @return A pointer to an array of media devices + */ +struct media_device **media_enumerate_get_devices(struct media_enumerate *media_enum); + +#endif /* __MEDIA_ENUMERATE_H__ */ |