Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst

   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 ******************************************************
   8 ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
   9 ******************************************************
  10
  11 Name
  12 ====
  13
  14 VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
  15
  16 Synopsis
  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
  27 Arguments
  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
  36 Description
  37 ===========
  38
  39 Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
  40 using 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
 108 Return Value
 109 ============
 110
 111 On success 0 is returned, on error -1 and the ``errno`` variable is set
 112 appropriately. The generic error codes are described at the
 113 :ref:`Generic Error Codes <gen-errors>` chapter.