Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml

   1 <refentry id="media-ioc-enum-entities">
   2   <refmeta>
   3     <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
   9     <refpurpose>Enumerate entities and their properties</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_entity_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_ENUM_ENTITIES</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     <para>To query the attributes of an entity, applications set the id field
  52     of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
  53     ioctl with a pointer to this structure. The driver fills the rest of the
  54     structure or returns an &EINVAL; when the id is invalid.</para>
  55     <para>Entities can be enumerated by or'ing the id with the
  56     <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
  57     information about the entity with the smallest id strictly larger than the
  58     requested one ('next entity'), or the &EINVAL; if there is none.</para>
  59     <para>Entity IDs can be non-contiguous. Applications must
  60     <emphasis>not</emphasis> try to enumerate entities by calling
  61     MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
  62
  63     <table pgwide="1" frame="none" id="media-entity-desc">
  64       <title>struct <structname>media_entity_desc</structname></title>
  65       <tgroup cols="5">
  66         <colspec colname="c1" />
  67         <colspec colname="c2" />
  68         <colspec colname="c3" />
  69         <colspec colname="c4" />
  70         <colspec colname="c5" />
  71         <tbody valign="top">
  72           <row>
  73             <entry>__u32</entry>
  74             <entry><structfield>id</structfield></entry>
  75             <entry></entry>
  76             <entry></entry>
  77             <entry>Entity id, set by the application. When the id is or'ed with
  78             <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
  79             flag and returns the first entity with a larger id.</entry>
  80           </row>
  81           <row>
  82             <entry>char</entry>
  83             <entry><structfield>name</structfield>[32]</entry>
  84             <entry></entry>
  85             <entry></entry>
  86             <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
  87           </row>
  88           <row>
  89             <entry>__u32</entry>
  90             <entry><structfield>type</structfield></entry>
  91             <entry></entry>
  92             <entry></entry>
  93             <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
  94           </row>
  95           <row>
  96             <entry>__u32</entry>
  97             <entry><structfield>revision</structfield></entry>
  98             <entry></entry>
  99             <entry></entry>
 100             <entry>Entity revision. Always zero (obsolete)</entry>
 101           </row>
 102           <row>
 103             <entry>__u32</entry>
 104             <entry><structfield>flags</structfield></entry>
 105             <entry></entry>
 106             <entry></entry>
 107             <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
 108           </row>
 109           <row>
 110             <entry>__u32</entry>
 111             <entry><structfield>group_id</structfield></entry>
 112             <entry></entry>
 113             <entry></entry>
 114             <entry>Entity group ID. Always zero (obsolete)</entry>
 115           </row>
 116           <row>
 117             <entry>__u16</entry>
 118             <entry><structfield>pads</structfield></entry>
 119             <entry></entry>
 120             <entry></entry>
 121             <entry>Number of pads</entry>
 122           </row>
 123           <row>
 124             <entry>__u16</entry>
 125             <entry><structfield>links</structfield></entry>
 126             <entry></entry>
 127             <entry></entry>
 128             <entry>Total number of outbound links. Inbound links are not counted
 129             in this field.</entry>
 130           </row>
 131           <row>
 132             <entry>union</entry>
 133           </row>
 134           <row>
 135             <entry></entry>
 136             <entry>struct</entry>
 137             <entry><structfield>dev</structfield></entry>
 138             <entry></entry>
 139             <entry>Valid for (sub-)devices that create a single device node.</entry>
 140           </row>
 141           <row>
 142             <entry></entry>
 143             <entry></entry>
 144             <entry>__u32</entry>
 145             <entry><structfield>major</structfield></entry>
 146             <entry>Device node major number.</entry>
 147           </row>
 148           <row>
 149             <entry></entry>
 150             <entry></entry>
 151             <entry>__u32</entry>
 152             <entry><structfield>minor</structfield></entry>
 153             <entry>Device node minor number.</entry>
 154           </row>
 155           <row>
 156             <entry></entry>
 157             <entry>__u8</entry>
 158             <entry><structfield>raw</structfield>[184]</entry>
 159             <entry></entry>
 160             <entry></entry>
 161           </row>
 162         </tbody>
 163       </tgroup>
 164     </table>
 165   </refsect1>
 166
 167   <refsect1>
 168     &return-value;
 169
 170     <variablelist>
 171       <varlistentry>
 172         <term><errorcode>EINVAL</errorcode></term>
 173         <listitem>
 174           <para>The &media-entity-desc; <structfield>id</structfield> references
 175           a non-existing entity.</para>
 176         </listitem>
 177       </varlistentry>
 178     </variablelist>
 179   </refsect1>
 180 </refentry>