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

<refentry id="media-ioc-enum-entities">
  <refmeta>
    <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
    <refpurpose>Enumerate entities and their properties</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Arguments</title>

    <variablelist>
      <varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	  <para>File descriptor returned by
	  <link linkend='media-func-open'><function>open()</function></link>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	  <para>MEDIA_IOC_ENUM_ENTITIES</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>
    <para>To query the attributes of an entity, applications set the id field
    of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
    ioctl with a pointer to this structure. The driver fills the rest of the
    structure or returns an &EINVAL; when the id is invalid.</para>
    <para>Entities can be enumerated by or'ing the id with the
    <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
    information about the entity with the smallest id strictly larger than the
    requested one ('next entity'), or the &EINVAL; if there is none.</para>
    <para>Entity IDs can be non-contiguous. Applications must
    <emphasis>not</emphasis> try to enumerate entities by calling
    MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>

    <table pgwide="1" frame="none" id="media-entity-desc">
      <title>struct <structname>media_entity_desc</structname></title>
      <tgroup cols="5">
	<colspec colname="c1" />
	<colspec colname="c2" />
	<colspec colname="c3" />
	<colspec colname="c4" />
	<colspec colname="c5" />
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>id</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Entity id, set by the application. When the id is or'ed with
	    <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
	    flag and returns the first entity with a larger id.</entry>
	  </row>
	  <row>
	    <entry>char</entry>
	    <entry><structfield>name</structfield>[32]</entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>type</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>revision</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Entity revision. Always zero (obsolete)</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>flags</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>group_id</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Entity group ID. Always zero (obsolete)</entry>
	  </row>
	  <row>
	    <entry>__u16</entry>
	    <entry><structfield>pads</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Number of pads</entry>
	  </row>
	  <row>
	    <entry>__u16</entry>
	    <entry><structfield>links</structfield></entry>
	    <entry></entry>
	    <entry></entry>
	    <entry>Total number of outbound links. Inbound links are not counted
	    in this field.</entry>
	  </row>
	  <row>
	    <entry>union</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>struct</entry>
	    <entry><structfield>dev</structfield></entry>
	    <entry></entry>
	    <entry>Valid for (sub-)devices that create a single device node.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>major</structfield></entry>
	    <entry>Device node major number.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry></entry>
	    <entry>__u32</entry>
	    <entry><structfield>minor</structfield></entry>
	    <entry>Device node minor number.</entry>
	  </row>
	  <row>
	    <entry></entry>
	    <entry>__u8</entry>
	    <entry><structfield>raw</structfield>[184]</entry>
	    <entry></entry>
	    <entry></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table frame="none" pgwide="1" id="media-entity-type">
      <title>Media entity types</title>
      <tgroup cols="2">
        <colspec colname="c1"/>
        <colspec colname="c2"/>
	<tbody valign="top">
	  <row>
	    <entry><constant>MEDIA_ENT_F_UNKNOWN</constant> and <constant>MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN</constant></entry>
	    <entry>Unknown entity. That generally indicates that
	    a driver didn't initialize properly the entity, with is a Kernel bug</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_IO_V4L</constant></entry>
	    <entry>Data streaming input and/or output entity.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_IO_VBI</constant></entry>
	    <entry>V4L VBI streaming input or output entity</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_IO_SWRADIO</constant></entry>
	    <entry>V4L Software Digital Radio (SDR) streaming input or output entity</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_IO_DTV</constant></entry>
	    <entry>DVB Digital TV streaming input or output entity</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_DTV_DEMOD</constant></entry>
	    <entry>Digital TV demodulator entity.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_MPEG_TS_DEMUX</constant></entry>
	    <entry>MPEG Transport stream demux entity. Could be implemented on hardware or in Kernelspace by the Linux DVB subsystem.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_DTV_CA</constant></entry>
	    <entry>Digital TV Conditional Access module (CAM) entity</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_DTV_NET_DECAP</constant></entry>
	    <entry>Digital TV network ULE/MLE desencapsulation entity. Could be implemented on hardware or in Kernelspace</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_CONN_RF</constant></entry>
	    <entry>Connector for a Radio Frequency (RF) signal.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_CONN_SVIDEO</constant></entry>
	    <entry>Connector for a S-Video signal.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_CONN_COMPOSITE</constant></entry>
	    <entry>Connector for a RGB composite signal.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_CONN_TEST</constant></entry>
	    <entry>Connector for a test generator.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_CAM_SENSOR</constant></entry>
	    <entry>Camera video sensor entity.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_FLASH</constant></entry>
	    <entry>Flash controller entity.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_LENS</constant></entry>
	    <entry>Lens controller entity.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_ATV_DECODER</constant></entry>
	    <entry>Analog video decoder, the basic function of the video decoder
	    is to accept analogue video from a wide variety of sources such as
	    broadcast, DVD players, cameras and video cassette recorders, in
	    either NTSC, PAL, SECAM or HD format, separating the stream
	    into its component parts, luminance and chrominance, and output
	    it in some digital video standard, with appropriate timing
	    signals.</entry>
	  </row>
	  <row>
	    <entry><constant>MEDIA_ENT_F_TUNER</constant></entry>
	    <entry>Digital TV, analog TV, radio and/or software radio tuner.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table frame="none" pgwide="1" id="media-entity-flag">
      <title>Media entity flags</title>
      <tgroup cols="2">
        <colspec colname="c1"/>
        <colspec colname="c2"/>
	<tbody valign="top">
	  <row>
	    <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
	    <entry>Default entity for its type. Used to discover the default
	    audio, VBI and video devices, the default camera sensor, ...</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The &media-entity-desc; <structfield>id</structfield> references
	  a non-existing entity.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>