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

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