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 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  42
  43 .. _v4l2-event-subscription:
  44
  45 .. flat-table:: struct v4l2_event_subscription
  46     :header-rows:  0
  47     :stub-columns: 0
  48     :widths:       1 1 2
  49
  50
  51     -  .. row 1
  52
  53        -  __u32
  54
  55        -  ``type``
  56
  57        -  Type of the event, see :ref:`event-type`.
  58
  59           .. note::
  60
  61              ``V4L2_EVENT_ALL`` can be used with
  62              :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
  63              unsubscribing all events at once.
  64
  65     -  .. row 2
  66
  67        -  __u32
  68
  69        -  ``id``
  70
  71        -  ID of the event source. If there is no ID associated with the
  72           event source, then set this to 0. Whether or not an event needs an
  73           ID depends on the event type.
  74
  75     -  .. row 3
  76
  77        -  __u32
  78
  79        -  ``flags``
  80
  81        -  Event flags, see :ref:`event-flags`.
  82
  83     -  .. row 4
  84
  85        -  __u32
  86
  87        -  ``reserved``\ [5]
  88
  89        -  Reserved for future extensions. Drivers and applications must set
  90           the array to zero.
  91
  92
  93
  94 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
  95
  96 .. _event-flags:
  97
  98 .. flat-table:: Event Flags
  99     :header-rows:  0
 100     :stub-columns: 0
 101     :widths:       3 1 4
 102
 103
 104     -  .. row 1
 105
 106        -  ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
 107
 108        -  0x0001
 109
 110        -  When this event is subscribed an initial event will be sent
 111           containing the current status. This only makes sense for events
 112           that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
 113           Other events will ignore this flag.
 114
 115     -  .. row 2
 116
 117        -  ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
 118
 119        -  0x0002
 120
 121        -  If set, then events directly caused by an ioctl will also be sent
 122           to the filehandle that called that ioctl. For example, changing a
 123           control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
 124           a V4L2_EVENT_CTRL to be sent back to that same filehandle.
 125           Normally such events are suppressed to prevent feedback loops
 126           where an application changes a control to a one value and then
 127           another, and then receives an event telling it that that control
 128           has changed to the first value.
 129
 130           Since it can't tell whether that event was caused by another
 131           application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
 132           call it is hard to decide whether to set the control to the value
 133           in the event, or ignore it.
 134
 135           Think carefully when you set this flag so you won't get into
 136           situations like that.
 137
 138
 139 Return Value
 140 ============
 141
 142 On success 0 is returned, on error -1 and the ``errno`` variable is set
 143 appropriately. The generic error codes are described at the
 144 :ref:`Generic Error Codes <gen-errors>` chapter.