Documentation/DocBook/media/v4l/media-ioc-setup-link.xml

   1 <refentry id="media-ioc-setup-link">
   2   <refmeta>
   3     <refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>MEDIA_IOC_SETUP_LINK</refname>
   9     <refpurpose>Modify the properties of a link</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>fd</parameter></term>
  29         <listitem>
  30           <para>File descriptor returned by
  31           <link linkend='media-func-open'><function>open()</function></link>.</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>MEDIA_IOC_SETUP_LINK</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para>To change link properties applications fill a &media-link-desc; with
  53     link identification information (source and sink pad) and the new requested
  54     link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to
  55     that structure.</para>
  56     <para>The only configurable property is the <constant>ENABLED</constant>
  57     link flag to enable/disable a link. Links marked with the
  58     <constant>IMMUTABLE</constant> link flag can not be enabled or disabled.
  59     </para>
  60     <para>Link configuration has no side effect on other links. If an enabled
  61     link at the sink pad prevents the link from being enabled, the driver
  62     returns with an &EBUSY;.</para>
  63     <para>Only links marked with the <constant>DYNAMIC</constant> link flag can
  64     be enabled/disabled while streaming media data. Attempting to enable or
  65     disable a streaming non-dynamic link will return an &EBUSY;.</para>
  66     <para>If the specified link can't be found the driver returns with an
  67     &EINVAL;.</para>
  68   </refsect1>
  69
  70   <refsect1>
  71     &return-value;
  72
  73     <variablelist>
  74       <varlistentry>
  75         <term><errorcode>EINVAL</errorcode></term>
  76         <listitem>
  77           <para>The &media-link-desc; references a non-existing link, or the
  78           link is immutable and an attempt to modify its configuration was made.
  79           </para>
  80         </listitem>
  81       </varlistentry>
  82     </variablelist>
  83   </refsect1>
  84 </refentry>