[deliverable/linux.git] / Documentation / linux_tv / media / v4l / vidioc-subscribe-event.rst

.. -*- coding: utf-8; mode: rst -*-

.. _VIDIOC_SUBSCRIBE_EVENT:

******************************************************
ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
******************************************************

*man VIDIOC_SUBSCRIBE_EVENT(2)*

VIDIOC_UNSUBSCRIBE_EVENT
Subscribe or unsubscribe event


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event_subscription *argp )

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT

``argp``


Description
===========

Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
using the :ref:`VIDIOC_DQEVENT` ioctl.


.. _v4l2-event-subscription:

.. flat-table:: struct v4l2_event_subscription
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  __u32

       -  ``type``

       -  Type of the event, see :ref:`event-type`. Note that
	  ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for
	  unsubscribing all events at once.

    -  .. row 2

       -  __u32

       -  ``id``

       -  ID of the event source. If there is no ID associated with the
	  event source, then set this to 0. Whether or not an event needs an
	  ID depends on the event type.

    -  .. row 3

       -  __u32

       -  ``flags``

       -  Event flags, see :ref:`event-flags`.

    -  .. row 4

       -  __u32

       -  ``reserved``\ [5]

       -  Reserved for future extensions. Drivers and applications must set
	  the array to zero.


.. _event-flags:

.. flat-table:: Event Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_EVENT_SUB_FL_SEND_INITIAL``

       -  0x0001

       -  When this event is subscribed an initial event will be sent
	  containing the current status. This only makes sense for events
	  that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
	  Other events will ignore this flag.

    -  .. row 2

       -  ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``

       -  0x0002

       -  If set, then events directly caused by an ioctl will also be sent
	  to the filehandle that called that ioctl. For example, changing a
	  control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
	  a V4L2_EVENT_CTRL to be sent back to that same filehandle.
	  Normally such events are suppressed to prevent feedback loops
	  where an application changes a control to a one value and then
	  another, and then receives an event telling it that that control
	  has changed to the first value.

	  Since it can't tell whether that event was caused by another
	  application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
	  call it is hard to decide whether to set the control to the value
	  in the event, or ignore it.

	  Think carefully when you set this flag so you won't get into
	  situations like that.


Return Value
============

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