vidioc-subscribe-event.rst (3326B)
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_SUBSCRIBE_EVENT: 5.. _VIDIOC_UNSUBSCRIBE_EVENT: 6 7****************************************************** 8ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT 9****************************************************** 10 11Name 12==== 13 14VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event 15 16Synopsis 17======== 18 19.. c:macro:: VIDIOC_SUBSCRIBE_EVENT 20 21``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` 22 23.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT 24 25``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)`` 26 27Arguments 28========= 29 30``fd`` 31 File descriptor returned by :c:func:`open()`. 32 33``argp`` 34 Pointer to struct :c:type:`v4l2_event_subscription`. 35 36Description 37=========== 38 39Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by 40using the :ref:`VIDIOC_DQEVENT` ioctl. 41 42.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}| 43 44.. c:type:: v4l2_event_subscription 45 46.. flat-table:: struct v4l2_event_subscription 47 :header-rows: 0 48 :stub-columns: 0 49 :widths: 1 1 2 50 51 * - __u32 52 - ``type`` 53 - Type of the event, see :ref:`event-type`. 54 55 .. note:: 56 57 ``V4L2_EVENT_ALL`` can be used with 58 :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for 59 unsubscribing all events at once. 60 * - __u32 61 - ``id`` 62 - ID of the event source. If there is no ID associated with the 63 event source, then set this to 0. Whether or not an event needs an 64 ID depends on the event type. 65 * - __u32 66 - ``flags`` 67 - Event flags, see :ref:`event-flags`. 68 * - __u32 69 - ``reserved``\ [5] 70 - Reserved for future extensions. Drivers and applications must set 71 the array to zero. 72 73 74.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}| 75 76.. _event-flags: 77 78.. flat-table:: Event Flags 79 :header-rows: 0 80 :stub-columns: 0 81 :widths: 3 1 4 82 83 * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL`` 84 - 0x0001 85 - When this event is subscribed an initial event will be sent 86 containing the current status. This only makes sense for events 87 that are triggered by a status change such as ``V4L2_EVENT_CTRL``. 88 Other events will ignore this flag. 89 * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` 90 - 0x0002 91 - If set, then events directly caused by an ioctl will also be sent 92 to the filehandle that called that ioctl. For example, changing a 93 control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause 94 a V4L2_EVENT_CTRL to be sent back to that same filehandle. 95 Normally such events are suppressed to prevent feedback loops 96 where an application changes a control to a one value and then 97 another, and then receives an event telling it that that control 98 has changed to the first value. 99 100 Since it can't tell whether that event was caused by another 101 application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` 102 call it is hard to decide whether to set the control to the value 103 in the event, or ignore it. 104 105 Think carefully when you set this flag so you won't get into 106 situations like that. 107 108Return Value 109============ 110 111On success 0 is returned, on error -1 and the ``errno`` variable is set 112appropriately. The generic error codes are described at the 113:ref:`Generic Error Codes <gen-errors>` chapter.