<page xmlns="http://projectmallard.org/1.0/"
      xmlns:its="http://www.w3.org/2005/11/its"
      type="topic" style="task"
      id="overview-net">
  <info>
    <link type="guide" xref="index" group="net"/>
    <revision version="0.1" date="2013-08-06" status="review"/>

    <credit type="author copyright">
      <name>David King</name>
      <email its:translate="no">davidk@gnome.org</email>
      <years>2013</years>
    </credit>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

    <desc>Client and server HTTP communication, portable socket-based networking IO, and network device management.</desc>
  </info>

<title>Low-level networking</title>

<list>
 <item>
  <p><em style="strong">Create powerful and flexible HTTP servers and clients</em></p>
 </item>
 <item>
  <p><em style="strong">Use portable socket-based APIs in a UI without blocking</em></p>
 </item>
 <item>
  <p><em style="strong">Detect and manage the network connection state</em></p>
 </item>
</list>

<p>Take advantage of the portable networking APIs for accessing network
services. Asynchronous IO keeps your application UI responsive while IO is in
progress. Detect changes in the system networking state, to make your
application respond appropriately when there is no Internet access.</p>

<!-- TODO: Add screenshot.
<media type="image" mime="image/png" src="test_comm1.png" width="65%">
 <p>IMAGE</p>
</media>
-->

<section id="what">
  <title>What can you do?</title>

  <p>To <em style="strong">asynchronously access low-level networking APIs</em>,
  use <em style="strong" xref="tech-gio-network">GIO networking</em>.
  Higher-level API is available for <em style="strong">resolving proxies and
  DNS records</em> as well as using <em style="strong">secure sockets
  (TLS)</em>.</p>

  <p>Simple monitoring of network state is available in GIO, but
  <em style="strong" xref="tech-network-manager">NetworkManager</em> provides
  <em style="strong">comprehensive support for networking devices</em> and
  network topologies.</p>

  <p><em style="strong" xref="tech-soup">Libsoup</em> provides a flexible
  interface for <em style="strong">HTTP servers and clients</em>. Both
  synchronous and asynchronous APIs are provided.</p>

</section>

<!-- TODO Add link to code examples.
<section id="samples">
 <title>Code samples</title>
 <list>
  <item><p>A sample we should write</p></item>
  <item><p><link xref="samples">More…</link></p></item>
 </list>
</section>
-->

<section id="realworld">
  <title>Real-world examples</title>

  <p>You can see lots of real-world applications of GNOME networking
  technologies in open source projects, like the examples given below.</p>
  <list>
    <item>
      <p><em style="strong">Web</em> is the GNOME browser, which uses libsoup
      to access HTTP services.</p>
      <p>( <link href="https://wiki.gnome.org/Apps/Web">Website</link> | <link href="https://gitlab.gnome.org/GNOME/epiphany/raw/master/data/screenshot.png">Screenshot</link> | <link href="https://gitlab.gnome.org/GNOME/epiphany/">Source code</link> )</p>
    </item>
    <item>
      <p><em style="strong">GNOME Shell</em> is the user-visible GNOME desktop,
      which uses NetworkManager for the network status menu, including managing
      wired, wireless, 3G modem and VPN networking systems.</p>
      <p>( <link href="https://wiki.gnome.org/Projects/GnomeShell">Website</link> | <link href="http://www.gnome.org/gnome-3/">Screenshot</link> | <link href="https://gitlab.gnome.org/GNOME/gnome-shell/">Source Code</link> )</p>
    </item>
    <!-- TODO: Add low-level GIO network IO example. -->
  </list>
</section>
</page>