Documentation/media/uapi/v4l/vidioc-subscribe-event.rst

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