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

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