11) Why such library is needed
2 ==========================
3
4Media devices can be very complex. It is not trivial how to detect what's the
5other devices associated with a video node.
6
7This API provides the capabilities of getting the associated devices with a
8video node.
9
10It is currently implemented at http://git.linuxtv.org/v4l-utils.git, at the
11utils/libmedia_dev/. After validating it, it makes sense to move it to be
12part of libv4l.
13
142) Provided functions
15 ==================
16
17The API defines a macro with its current version. Currently, it is:
18
19 #define GET_MEDIA_DEVICES_VERSION 0x0104
20
21Each device type that is known by the API is defined inside enum device_type,
22currently defined as:
23
24 enum device_type {
25 UNKNOWN = 65535,
26 NONE = 65534,
27 MEDIA_V4L_VIDEO = 0,
28 MEDIA_V4L_VBI,
29 MEDIA_DVB_FRONTEND,
30 MEDIA_DVB_DEMUX,
31 MEDIA_DVB_DVR,
32 MEDIA_DVB_NET,
33 MEDIA_DVB_CA,
34 MEDIA_SND_CARD,
35 MEDIA_SND_CAP,
36 MEDIA_SND_OUT,
37 MEDIA_SND_CONTROL,
38 MEDIA_SND_HW,
39 };
40
41The first function discovers the media devices and stores the information
42at an internal representation. Such representation should be opaque to
43the userspace applications, as it can change from version to version.
44
452.1) Device discover and release functions
46 =====================================
47
48The device discover is done by calling:
49
50 void *discover_media_devices(void);
51
52In order to release the opaque structure, a free method is provided:
53
54 void free_media_devices(void *opaque);
55
562.2) Functions to help printing the discovered devices
57 =================================================
58
59In order to allow printing the device type, a function is provided to
60convert from enum device_type into string:
61
62 char *media_device_type(enum device_type type);
63
64All discovered devices can be displayed by calling:
65
66 void display_media_devices(void *opaque);
67
682.3) Functions to get device associations
69 ====================================
70
71The API provides 3 methods to get the associated devices:
72
73a) get_associated_device: returns the next device associated with another one
74
75 char *get_associated_device(void *opaque,
76 char *last_seek,
77 enum device_type desired_type,
78 char *seek_device,
79 enum device_type seek_type);
80The parameters are:
81
82 opaque: media devices opaque descriptor
83 last_seek: last seek result. Use NULL to get the first result
84 desired_type: type of the desired device
85 seek_device: name of the device with you want to get an association.
86 seek_type: type of the seek device. Using NONE produces the same
87 result of using NULL for the seek_device.
88
89This function seeks inside the media_devices struct for the next device
90that it is associated with a seek parameter.
91It can be used to get an alsa device associated with a video device. If
92the seek_device is NULL or seek_type is NONE, it will just search for
93devices of the desired_type.
94
95
96b) fget_associated_device: returns the next device associated with another one
97
98 char *fget_associated_device(void *opaque,
99 char *last_seek,
100 enum device_type desired_type,
101 int fd_seek_device,
102 enum device_type seek_type);
103
104The parameters are:
105
106 opaque: media devices opaque descriptor
107 last_seek: last seek result. Use NULL to get the first result
108 desired_type: type of the desired device
109 fd_seek_device: file handler for the device where the association will
110 be made
111 seek_type: type of the seek device. Using NONE produces the same
112 result of using NULL for the seek_device.
113
114This function seeks inside the media_devices struct for the next device
115that it is associated with a seek parameter.
116It can be used to get an alsa device associated with an open file descriptor
117
118c) get_not_associated_device: Returns the next device not associated with
119 an specific device type.
120
121char *get_not_associated_device(void *opaque,
122 char *last_seek,
123 enum device_type desired_type,
124 enum device_type not_desired_type);
125
126The parameters are:
127
128opaque: media devices opaque descriptor
129last_seek: last seek result. Use NULL to get the first result
130desired_type: type of the desired device
131not_desired_type: type of the seek device
132
133This function seeks inside the media_devices struct for the next physical
134device that doesn't support a non_desired type.
135This method is useful for example to return the audio devices that are
136provided by the motherboard.
137
1383) Examples with typical usecases
139 ==============================
140
141a) Just displaying all media devices:
142
143 void *md = discover_media_devices();
144 display_media_devices(md);
145 free_media_devices(md);
146
147The devices will be shown at the order they appear at the computer buses.
148
149b) For video0, prints the associated alsa capture device(s):
150
151 void *md = discover_media_devices();
152 char *devname = NULL, video0 = "/dev/video0";
153 do {
154 devname = get_associated_device(md, devname, MEDIA_SND_CAP,
155 video0, MEDIA_V4L_VIDEO);
156 if (devname)
157 printf("Alsa capture: %s\n", devname);
158 } while (devname);
159 free_media_devices(md);
160
161Note: the video0 string can be declarated as "/dev/video0" or as just "video0",
162as the search functions will discard any patch on it.
163
164c) Get the alsa capture device associated with an opened file descriptor:
165
166 int fd = open("/dev/video0", O_RDWR);
167 ...
168 void *md = discover_media_devices();
169 vid = fget_associated_device(md, NULL, MEDIA_SND_CAP, fd,
170 MEDIA_V4L_VIDEO);
171 printf("\n\nAlsa device = %s\n", vid);
172 close(fd);
173 free_media_devices(md);
174
175d) Get the mainboard alsa playback devices:
176
177 char *devname = NULL;
178 void *md = discover_media_devices();
179 do {
180 devname = get_not_associated_device(md, devname, MEDIA_SND_OUT,
181 MEDIA_V4L_VIDEO);
182 if (devname)
183 printf("Alsa playback: %s\n", devname);
184 } while (devname);
185 free_media_devices(md);
186
187e) Get all video devices:
188
189 void *md = discover_media_devices();
190 char *vid = NULL;
191 do {
192 vid = get_associated_device(md, vid, MEDIA_V4L_VIDEO,
193 NULL, NONE);
194 if (!vid)
195 break;
196 printf("Video device: %s\n", vid);
197 } while (vid);
198 free_media_devices(md);
199