vidioc-subscribe-event.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _VIDIOC_SUBSCRIBE_EVENT:
  5.. _VIDIOC_UNSUBSCRIBE_EVENT:
  6
  7******************************************************
  8ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
  9******************************************************
 10
 11Name
 12====
 13
 14VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
 15
 16Synopsis
 17========
 18
 19.. c:macro:: VIDIOC_SUBSCRIBE_EVENT
 20
 21``int ioctl(int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
 22
 23.. c:macro:: VIDIOC_UNSUBSCRIBE_EVENT
 24
 25``int ioctl(int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp)``
 26
 27Arguments
 28=========
 29
 30``fd``
 31    File descriptor returned by :c:func:`open()`.
 32
 33``argp``
 34    Pointer to struct :c:type:`v4l2_event_subscription`.
 35
 36Description
 37===========
 38
 39Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
 40using the :ref:`VIDIOC_DQEVENT` ioctl.
 41
 42.. tabularcolumns:: |p{2.6cm}|p{4.4cm}|p{10.3cm}|
 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.. tabularcolumns:: |p{7.5cm}|p{2.0cm}|p{7.8cm}|
 75
 76.. _event-flags:
 77
 78.. flat-table:: Event Flags
 79    :header-rows:  0
 80    :stub-columns: 0
 81    :widths:       3 1 4
 82
 83    * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
 84      - 0x0001
 85      - When this event is subscribed an initial event will be sent
 86	containing the current status. This only makes sense for events
 87	that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
 88	Other events will ignore this flag.
 89    * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
 90      - 0x0002
 91      - If set, then events directly caused by an ioctl will also be sent
 92	to the filehandle that called that ioctl. For example, changing a
 93	control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
 94	a V4L2_EVENT_CTRL to be sent back to that same filehandle.
 95	Normally such events are suppressed to prevent feedback loops
 96	where an application changes a control to a one value and then
 97	another, and then receives an event telling it that that control
 98	has changed to the first value.
 99
100	Since it can't tell whether that event was caused by another
101	application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
102	call it is hard to decide whether to set the control to the value
103	in the event, or ignore it.
104
105	Think carefully when you set this flag so you won't get into
106	situations like that.
107
108Return Value
109============
110
111On success 0 is returned, on error -1 and the ``errno`` variable is set
112appropriately. The generic error codes are described at the
113:ref:`Generic Error Codes <gen-errors>` chapter.