0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_SUBSCRIBE_EVENT:
0005 .. _VIDIOC_UNSUBSCRIBE_EVENT:
0006
0007 ******************************************************
0008 ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
0009 ******************************************************
0010
0011 Name
0012 ====
0013
0014 VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
0015
0016 Synopsis
0017 ========
0018
0019 .. c:macro:: VIDIOC_SUBSCRIBE_EVENT
0020
0021 ``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
0022
0023 .. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
0024
0025 ``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
0026
0027 Arguments
0028 =========
0029
0030 ``fd``
0031 File descriptor returned by :c:func:`open()`.
0032
0033 ``argp``
0034 Pointer to struct :c:type:`v4l2_event_subscription`.
0035
0036 Description
0037 ===========
0038
0039 Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
0040 using the :ref:`VIDIOC_DQEVENT` ioctl.
0041
0042 .. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|
0043
0044 .. c:type:: v4l2_event_subscription
0045
0046 .. flat-table:: struct v4l2_event_subscription
0047 :header-rows: 0
0048 :stub-columns: 0
0049 :widths: 1 1 2
0050
0051 * - __u32
0052 - ``type``
0053 - Type of the event, see :ref:`event-type`.
0054
0055 .. note::
0056
0057 ``V4L2_EVENT_ALL`` can be used with
0058 :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
0059 unsubscribing all events at once.
0060 * - __u32
0061 - ``id``
0062 - ID of the event source. If there is no ID associated with the
0063 event source, then set this to 0. Whether or not an event needs an
0064 ID depends on the event type.
0065 * - __u32
0066 - ``flags``
0067 - Event flags, see :ref:`event-flags`.
0068 * - __u32
0069 - ``reserved``\ [5]
0070 - Reserved for future extensions. Drivers and applications must set
0071 the array to zero.
0072
0073
0074 .. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
0075
0076 .. _event-flags:
0077
0078 .. flat-table:: Event Flags
0079 :header-rows: 0
0080 :stub-columns: 0
0081 :widths: 3 1 4
0082
0083 * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
0084 - 0x0001
0085 - When this event is subscribed an initial event will be sent
0086 containing the current status. This only makes sense for events
0087 that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
0088 Other events will ignore this flag.
0089 * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
0090 - 0x0002
0091 - If set, then events directly caused by an ioctl will also be sent
0092 to the filehandle that called that ioctl. For example, changing a
0093 control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
0094 a V4L2_EVENT_CTRL to be sent back to that same filehandle.
0095 Normally such events are suppressed to prevent feedback loops
0096 where an application changes a control to a one value and then
0097 another, and then receives an event telling it that that control
0098 has changed to the first value.
0099
0100 Since it can't tell whether that event was caused by another
0101 application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
0102 call it is hard to decide whether to set the control to the value
0103 in the event, or ignore it.
0104
0105 Think carefully when you set this flag so you won't get into
0106 situations like that.
0107
0108 Return Value
0109 ============
0110
0111 On success 0 is returned, on error -1 and the ``errno`` variable is set
0112 appropriately. The generic error codes are described at the
0113 :ref:`Generic Error Codes <gen-errors>` chapter.
