<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<book id="index">
  <bookinfo>
    <title>libdfu Reference Manual</title>
    <releaseinfo>
      for libdfu [VERSION].
      The latest version of this documentation can be found on-line at
      <ulink role="online-location" url="http://[SERVER]/libdfu/index.html">http://[SERVER]/libdfu/</ulink>.
    </releaseinfo>
  </bookinfo>

  <reference id="intro">
    <title>About libdfu</title>
    <partintro>
      <para>
        libdfu is a library for updating firmware on DFU-capable devices.
        <ulink url="https://en.wikipedia.org/wiki/USB#DFU">DFU</ulink>
        is a standardised protocol used on many millions of devices
        to safely update device firmware by the user.
        Is is designed to be easy to implement in device bootloaders and
        also easy to support in native host drivers.
        Flashing firmware using DFU is supported in Windows, Linux and OS-X.
      </para>
      <para>
        Updating firmware on a device is typically done using
        <ulink url="http://www.fwupd.org/">fwupd</ulink> or by a session
        application like GNOME Software.
        You can also use <ulink url="http://dfu-util.sourceforge.net/">dfu-util</ulink>
        which may support mode device types than <command>dfu-tool</command>
        supplied by fwupd.
      </para>
      <para>
        <command>libdfu</command> provides a medium-level API which is
        available for all languages that support GObject Introspection.
        It supports cancellation using <varname>GCancellable</varname>
        and erro reporting using <varname>GError</varname>.
        To download a device using the API it is as simple as getting
        a <varname>GUsbDevice</varname> and then doing something like
        this:
      </para>
<programlisting>
dfu_firmware = dfu_firmware_new ();
if (!dfu_firmware_parse_data (dfu_firmware, blob_fw,
                              DFU_FIRMWARE_PARSE_FLAG_NONE, error))
        return FALSE;
dfu_device = dfu_device_new (dev);
if (!dfu_device_download (dfu_device, dfu_firmware,
                          DFU_TARGET_TRANSFER_FLAG_DETACH |
                          DFU_TARGET_TRANSFER_FLAG_VERIFY |
                          DFU_TARGET_TRANSFER_FLAG_BOOT_RUNTIME,
                          cancelleable,
                          _progress_cb, userdata,
                          error))
        return FALSE;
</programlisting>
      <para>
        You can read more about DFU in the <ulink url="http://www.usb.org/developers/docs/devclass_docs/DFU_1.1.pdf">official specification</ulink>.
      </para>
    </partintro>
  </reference>

  <chapter id="object-tree">
    <title>Object Hierarchy</title>
    <xi:include href="xml/tree_index.sgml"/>
  </chapter>

  <reference id="libdfu">
    <title>libdfu</title>
    <partintro>
      <para>
        Functionality exported by libdfu.
      </para>
    </partintro>
    <xi:include href="xml/dfu-context.xml"/>
    <xi:include href="xml/dfu-device.xml"/>
    <xi:include href="xml/dfu-firmware.xml"/>
    <xi:include href="xml/dfu-image.xml"/>
    <xi:include href="xml/dfu-element.xml"/>
    <xi:include href="xml/dfu-sector.xml"/>
    <xi:include href="xml/dfu-target.xml"/>
    <xi:include href="xml/dfu-common.xml"/>
    <xi:include href="xml/dfu-error.xml"/>
  </reference>

  <index id="api-index-full">
    <title>API Index</title>
    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
    <xi:include href="xml/api-index-0.5.4.xml"/>
  </index>

  <index id="deprecated-api-index" role="deprecated">
    <title>Index of deprecated API</title>
    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
  </index>
  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
