1 .. -*- coding: utf-8; mode: rst -*-
3 .. _VIDIOC_SUBSCRIBE_EVENT:
4 .. _VIDIOC_UNSUBSCRIBE_EVENT:
6 ******************************************************
7 ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
8 ******************************************************
13 VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
19 .. c:function:: int ioctl( int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp )
20 :name: VIDIOC_SUBSCRIBE_EVENT
22 .. c:function:: int ioctl( int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp )
23 :name: VIDIOC_UNSUBSCRIBE_EVENT
30 File descriptor returned by :ref:`open() <func-open>`.
38 Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
39 using the :ref:`VIDIOC_DQEVENT` ioctl.
42 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
44 .. c:type:: v4l2_event_subscription
46 .. flat-table:: struct v4l2_event_subscription
58 - Type of the event, see :ref:`event-type`.
62 ``V4L2_EVENT_ALL`` can be used with
63 :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
64 unsubscribing all events at once.
72 - ID of the event source. If there is no ID associated with the
73 event source, then set this to 0. Whether or not an event needs an
74 ID depends on the event type.
82 - Event flags, see :ref:`event-flags`.
90 - Reserved for future extensions. Drivers and applications must set
95 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
99 .. flat-table:: Event Flags
107 - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
111 - When this event is subscribed an initial event will be sent
112 containing the current status. This only makes sense for events
113 that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
114 Other events will ignore this flag.
118 - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
122 - If set, then events directly caused by an ioctl will also be sent
123 to the filehandle that called that ioctl. For example, changing a
124 control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
125 a V4L2_EVENT_CTRL to be sent back to that same filehandle.
126 Normally such events are suppressed to prevent feedback loops
127 where an application changes a control to a one value and then
128 another, and then receives an event telling it that that control
129 has changed to the first value.
131 Since it can't tell whether that event was caused by another
132 application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
133 call it is hard to decide whether to set the control to the value
134 in the event, or ignore it.
136 Think carefully when you set this flag so you won't get into
137 situations like that.
143 On success 0 is returned, on error -1 and the ``errno`` variable is set
144 appropriately. The generic error codes are described at the
145 :ref:`Generic Error Codes <gen-errors>` chapter.