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