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