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