1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _VIDIOC_SUBSCRIBE_EVENT:
11.. _VIDIOC_UNSUBSCRIBE_EVENT:
12
13******************************************************
14ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
15******************************************************
16
17Name
18====
19
20VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
21
22
23Synopsis
24========
25
26.. c:function:: int ioctl( int fd, VIDIOC_SUBSCRIBE_EVENT, struct v4l2_event_subscription *argp )
27    :name: VIDIOC_SUBSCRIBE_EVENT
28
29.. c:function:: int ioctl( int fd, VIDIOC_UNSUBSCRIBE_EVENT, struct v4l2_event_subscription *argp )
30    :name: VIDIOC_UNSUBSCRIBE_EVENT
31
32
33Arguments
34=========
35
36``fd``
37    File descriptor returned by :ref:`open() <func-open>`.
38
39``argp``
40    Pointer to struct :c:type:`v4l2_event_subscription`.
41
42
43Description
44===========
45
46Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
47using the :ref:`VIDIOC_DQEVENT` ioctl.
48
49
50.. tabularcolumns:: |p{4.6cm}|p{4.4cm}|p{8.7cm}|
51
52.. c:type:: v4l2_event_subscription
53
54.. flat-table:: struct v4l2_event_subscription
55    :header-rows:  0
56    :stub-columns: 0
57    :widths:       1 1 2
58
59    * - __u32
60      - ``type``
61      - Type of the event, see :ref:`event-type`.
62
63	.. note::
64
65	   ``V4L2_EVENT_ALL`` can be used with
66	   :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for
67	   unsubscribing all events at once.
68    * - __u32
69      - ``id``
70      - ID of the event source. If there is no ID associated with the
71	event source, then set this to 0. Whether or not an event needs an
72	ID depends on the event type.
73    * - __u32
74      - ``flags``
75      - Event flags, see :ref:`event-flags`.
76    * - __u32
77      - ``reserved``\ [5]
78      - Reserved for future extensions. Drivers and applications must set
79	the array to zero.
80
81
82
83.. tabularcolumns:: |p{6.8cm}|p{2.2cm}|p{8.5cm}|
84
85.. _event-flags:
86
87.. flat-table:: Event Flags
88    :header-rows:  0
89    :stub-columns: 0
90    :widths:       3 1 4
91
92    * - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
93      - 0x0001
94      - When this event is subscribed an initial event will be sent
95	containing the current status. This only makes sense for events
96	that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
97	Other events will ignore this flag.
98    * - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
99      - 0x0002
100      - If set, then events directly caused by an ioctl will also be sent
101	to the filehandle that called that ioctl. For example, changing a
102	control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
103	a V4L2_EVENT_CTRL to be sent back to that same filehandle.
104	Normally such events are suppressed to prevent feedback loops
105	where an application changes a control to a one value and then
106	another, and then receives an event telling it that that control
107	has changed to the first value.
108
109	Since it can't tell whether that event was caused by another
110	application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
111	call it is hard to decide whether to set the control to the value
112	in the event, or ignore it.
113
114	Think carefully when you set this flag so you won't get into
115	situations like that.
116
117
118Return Value
119============
120
121On success 0 is returned, on error -1 and the ``errno`` variable is set
122appropriately. The generic error codes are described at the
123:ref:`Generic Error Codes <gen-errors>` chapter.
124