[net-next-2.6.git] / Documentation / DocBook / v4l / vidioc-g-priority.xml

<refentry id="vidioc-g-priority">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_G_PRIORITY</refname>
    <refname>VIDIOC_S_PRIORITY</refname>
    <refpurpose>Query or request the access priority associated with a
file descriptor</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Arguments</title>

    <variablelist>
      <varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	  <para>&fd;</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	  <para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para>Pointer to an enum v4l2_priority type.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>To query the current access priority
applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl
with a pointer to an enum v4l2_priority variable where the driver stores
the current priority.</para>

    <para>To request an access priority applications store the
desired priority in an enum v4l2_priority variable and call
<constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this
variable.</para>

    <table frame="none" pgwide="1" id="v4l2-priority">
      <title>enum v4l2_priority</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>V4L2_PRIORITY_UNSET</constant></entry>
	    <entry>0</entry>
	    <entry></entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry>
	    <entry>1</entry>
	    <entry>Lowest priority, usually applications running in
background, for example monitoring VBI transmissions. A proxy
application running in user space will be necessary if multiple
applications want to read from a device at this priority.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry>
	    <entry>2</entry>
	    <entry></entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry>
	    <entry>2</entry>
	    <entry>Medium priority, usually applications started and
interactively controlled by the user. For example TV viewers, Teletext
browsers, or just "panel" applications to change the channel or video
controls. This is the default priority unless an application requests
another.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_PRIORITY_RECORD</constant></entry>
	    <entry>3</entry>
	    <entry>Highest priority. Only one file descriptor can have
this priority, it blocks any other fd from changing device properties.
Usually applications which must not be interrupted, like video
recording.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The requested priority value is invalid, or the
driver does not support access priorities.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><errorcode>EBUSY</errorcode></term>
	<listitem>
	  <para>Another application already requested higher
priority.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>

<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
-->
Commit	Line	Data
8e080c2e MCC	1	<refentry id="vidioc-g-priority">
	2	<refmeta>
	3	<refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle>
	4	&manvol;
	5	</refmeta>
	6
	7	<refnamediv>
	8	<refname>VIDIOC_G_PRIORITY</refname>
	9	<refname>VIDIOC_S_PRIORITY</refname>
	10	<refpurpose>Query or request the access priority associated with a
	11	file descriptor</refpurpose>
	12	</refnamediv>
	13
	14	<refsynopsisdiv>
	15	<funcsynopsis>
	16	<funcprototype>
	17	<funcdef>int <function>ioctl</function></funcdef>
	18	<paramdef>int <parameter>fd</parameter></paramdef>
	19	<paramdef>int <parameter>request</parameter></paramdef>
	20	<paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef>
	21	</funcprototype>
	22	</funcsynopsis>
	23	<funcsynopsis>
	24	<funcprototype>
	25	<funcdef>int <function>ioctl</function></funcdef>
	26	<paramdef>int <parameter>fd</parameter></paramdef>
	27	<paramdef>int <parameter>request</parameter></paramdef>
	28	<paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef>
	29	</funcprototype>
	30	</funcsynopsis>
	31	</refsynopsisdiv>
	32
	33	<refsect1>
	34	<title>Arguments</title>
	35
	36	<variablelist>
	37	<varlistentry>
	38	<term><parameter>fd</parameter></term>
	39	<listitem>
	40	<para>&fd;</para>
	41	</listitem>
	42	</varlistentry>
	43	<varlistentry>
	44	<term><parameter>request</parameter></term>
	45	<listitem>
	46	<para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para>
	47	</listitem>
	48	</varlistentry>
	49	<varlistentry>
	50	<term><parameter>argp</parameter></term>
	51	<listitem>
	52	<para>Pointer to an enum v4l2_priority type.</para>
	53	</listitem>
	54	</varlistentry>
	55	</variablelist>
	56	</refsect1>
	57
	58	<refsect1>
	59	<title>Description</title>
	60
	61	<para>To query the current access priority
	62	applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl
	63	with a pointer to an enum v4l2_priority variable where the driver stores
	64	the current priority.</para>
65
66	<para>To request an access priority applications store the
67	desired priority in an enum v4l2_priority variable and call
68	<constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this
69	variable.</para>
70
71	<table frame="none" pgwide="1" id="v4l2-priority">
72	<title>enum v4l2_priority</title>
73	<tgroup cols="3">
74	&cs-def;
75	<tbody valign="top">
76	<row>
77	<entry><constant>V4L2_PRIORITY_UNSET</constant></entry>
78	<entry>0</entry>
79	<entry></entry>
80	</row>
81	<row>
82	<entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry>
83	<entry>1</entry>
84	<entry>Lowest priority, usually applications running in
85	background, for example monitoring VBI transmissions. A proxy
86	application running in user space will be necessary if multiple
87	applications want to read from a device at this priority.</entry>
88	</row>
89	<row>
90	<entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry>
91	<entry>2</entry>
92	<entry></entry>
93	</row>
94	<row>
95	<entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry>
96	<entry>2</entry>
97	<entry>Medium priority, usually applications started and
98	interactively controlled by the user. For example TV viewers, Teletext
99	browsers, or just "panel" applications to change the channel or video
100	controls. This is the default priority unless an application requests
101	another.</entry>
102	</row>
103	<row>
104	<entry><constant>V4L2_PRIORITY_RECORD</constant></entry>
105	<entry>3</entry>
106	<entry>Highest priority. Only one file descriptor can have
107	this priority, it blocks any other fd from changing device properties.
108	Usually applications which must not be interrupted, like video
109	recording.</entry>
110	</row>
111	</tbody>
112	</tgroup>
113	</table>
114	</refsect1>
115
116	<refsect1>
117	&return-value;
118
119	<variablelist>
120	<varlistentry>
121	<term><errorcode>EINVAL</errorcode></term>
122	<listitem>
123	<para>The requested priority value is invalid, or the
124	driver does not support access priorities.</para>
125	</listitem>
126	</varlistentry>
127	<varlistentry>
128	<term><errorcode>EBUSY</errorcode></term>
129	<listitem>
130	<para>Another application already requested higher
131	priority.</para>
132	</listitem>
133	</varlistentry>
134	</variablelist>
135	</refsect1>
136	</refentry>
137
138	<!--
139	Local Variables:
140	mode: sgml
141	sgml-parent-document: "v4l2.sgml"
142	indent-tabs-mode: nil
143	End:
144	-->