<!DOCTYPE node PUBLIC
"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/org/freedesktop/DeviceKit" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">

  <interface name="org.freedesktop.DeviceKit">
    <doc:doc>
      <doc:description>
        <doc:para>
          The DeviceKit service is available via the system message
          bus. To access the service, use
          the <doc:tt>org.freedesktop.DeviceKit</doc:tt> interface on
          the <doc:tt>/org/freedesktop/DeviceKit</doc:tt> object on
          the D-Bus system bus service with the well-known
          name <doc:tt>org.freedesktop.DeviceKit</doc:tt>.
        </doc:para>
        <doc:para>
          <doc:example language="shell" title="simple example">
            <doc:code>
$ dbus-send --system \
            --print-reply \
            --dest=org.freedesktop.DeviceKit \
            /org/freedesktop/DeviceKit \
            org.freedesktop.DeviceKit.EnumerateBySubsystem \
            array:string:mmc

method return sender=:1.175 -> dest=:1.219 reply_serial=2
   array [
      struct {
         string "mmc"
         string "/sys/devices/pci0000:00/0000:00:1e.0/0000:05:00.2/mmc_host/mmc0/mmc0:e624"
         string ""
         array [
         ]
         array [
            dict entry(
               string "UDEV_LOG"
               string "3"
            )
            dict entry(
               string "SUBSYSTEM"
               string "mmc"
            )
            dict entry(
               string "DEVPATH"
               string "/devices/pci0000:00/0000:00:1e.0/0000:05:00.2/mmc_host/mmc0/mmc0:e624"
            )
            dict entry(
               string "MMC_NAME"
               string "SD04G"
            )
            dict entry(
               string "DRIVER"
               string "mmcblk"
            )
            dict entry(
               string "MMC_TYPE"
               string "SD"
            )
         ]
      }
   ]
            </doc:code>
          </doc:example>
        </doc:para>
      </doc:description>
    </doc:doc>

    <method name="InhibitShutdown">
      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
      <arg name="cookie" direction="out" type="s">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The cookie that is used to stop inhibiting the daemon.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>

      <doc:doc>
        <doc:description>
          <doc:para>
            Keep the daemon from exiting on inactivity; this is
            useful for mechanisms that wants the daemon around for
            listening on signals.
          </doc:para>
        </doc:description>
      </doc:doc>
    </method>

    <method name="UninhibitShutdown">
      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
      <arg name="cookie" direction="in" type="s">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The cookie.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>

      <doc:doc>
        <doc:description>
          <doc:para>
            Allow the daemon to exit when it's inactive. The cookie
            parameter is the return value from <doc:ref type="method"
            to="DeviceKit.InhibitShutdown">InhibitShutdown()</doc:ref>.
          </doc:para>
        </doc:description>
      </doc:doc>
    </method>

    <method name="EnumerateBySubsystem">
      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
      <arg name="subsystems" direction="in" type="as">
        <doc:doc>
          <doc:summary>
            <doc:para>
              List of subsystems to get devices from. If an empty
              array is passed devices from all subsystems is returned.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="result" direction="out" type="a(sssasa{ss})">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The result as an array of structures containing the
              subsystem, native_path, device_file,
              device_file_symlinks and properties.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>

      <doc:doc>
        <doc:description>
          <doc:para>
            Enumerate devices on the system by subsystem. If the
            subsystems parameter is empty devices from all subsystems
            will be returned. See the <doc:ref type="signal"
            to="DeviceKit::DeviceEvent">DeviceEvent()</doc:ref>
            signal for a description of the return value.
          </doc:para>
        </doc:description>
      </doc:doc>
    </method>

    <method name="EnumerateByNativePath">
      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
      <arg name="native_paths" direction="in" type="as">
        <doc:doc>
          <doc:summary>
            <doc:para>
              List of native paths.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="result" direction="out" type="a(sssasa{ss})">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The result as an array of structures containing the
              subsystem, native_path, device_file,
              device_file_symlinks and properties.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>

      <doc:doc>
        <doc:description>
          <doc:para>
            Enumerate devices on the system given a list of native
            paths. See the <doc:ref type="signal"
            to="DeviceKit::DeviceEvent">DeviceEvent()</doc:ref> signal
            for a description of the return value.
          </doc:para>
        </doc:description>
      </doc:doc>
    </method>

    <!-- device event -->
    <signal name="DeviceEvent">
      <arg name="action" type="s">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The OS specific event.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="subsystem" type="s">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The subsystem the device belongs to.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="native_path" type="s">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The OS specific native path of the device.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="device_file" type="s">
        <doc:doc>
          <doc:summary>
            <doc:para>
              The UNIX special device file for the device.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="device_file_symlinks" type="as">
        <doc:doc>
          <doc:summary>
            <doc:para>
              A list of symlinks pointing to the UNIX special device file.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>
      <arg name="properties" type="a{ss}">
        <doc:doc>
          <doc:summary>
            <doc:para>
              A set of key/value pairs with OS specific properties for the device.
            </doc:para>
          </doc:summary>
        </doc:doc>
      </arg>

      <doc:doc>
        <doc:description>
          <doc:para>
            This signal is emitted when an event occurs on a device
            such as change, add, remove.
          </doc:para>
        </doc:description>
      </doc:doc>
    </signal>

    <!-- ************************************************************ -->

    <property name="daemon-version" type="s" access="read">
      <doc:doc><doc:description><doc:para>
            Version of the running daemon, e.g. <doc:tt>002</doc:tt>.
      </doc:para></doc:description></doc:doc>
    </property>

  </interface>

</node>
