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