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