    <refentry id="refopts">

      <refmeta>
	<refentrytitle>ne_set_useragent</refentrytitle>
	<manvolnum>3</manvolnum>
      </refmeta>

      <refnamediv>
	<refname id="ne_set_useragent">ne_set_useragent</refname>
	<refname id="ne_set_persist">ne_set_persist</refname>
	<refname id="ne_set_read_timeout">ne_set_read_timeout</refname>
	<refname id="ne_set_expect100">ne_set_expect100</refname>
	<refpurpose>common settings for HTTP sessions</refpurpose>
      </refnamediv>
      
      <refsynopsisdiv>
	
	<funcsynopsis>

	  <funcsynopsisinfo>#include &lt;ne_session.h&gt;</funcsynopsisinfo>

	  <funcprototype>
	    <funcdef>void <function>ne_set_useragent</function></funcdef>
	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
	    <paramdef>const char *<parameter>product</parameter></paramdef>
	  </funcprototype>

	  <funcprototype>
	    <funcdef>void <function>ne_set_persist</function></funcdef>
	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
	    <paramdef>int <parameter>flag</parameter></paramdef>
	  </funcprototype>

	  <funcprototype>
	    <funcdef>void <function>ne_set_read_timeout</function></funcdef>
	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
	    <paramdef>int <parameter>timeout</parameter></paramdef>
	  </funcprototype>

	  <funcprototype>
	    <funcdef>void <function>ne_set_expect100</function></funcdef>
	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
	    <paramdef>int <parameter>flag</parameter></paramdef>
	  </funcprototype>

<!--
	  <funcprototype>
	    <funcdef>const char *<function>ne_get_scheme</function></funcdef>
	    <paramdef>ne_sesssion *<parameter>session</parameter></paramdef>
	  </funcprototype>

	  <funcprototype>
	    <funcdef>const char *<function>ne_get_server_hostport</function></funcdef>
	    <paramdef>ne_sesssion *<parameter>session</parameter></paramdef>
	  </funcprototype>
-->

	</funcsynopsis>
	
      </refsynopsisdiv>

      <refsect1>
	<title>Description</title>
	
	<!-- TODO: intro para? -->

	<para>The <literal>User-Agent</literal> request header is used
to identify the software which generated the request for statistical
or debugging purposes.  neon does not send a
<literal>User-Agent</literal> header unless a call is made to the
<function>ne_set_useragent</function>.
<function>ne_set_useragent</function> must be passed a product string
conforming to RFC2616's product token grammar; of the form
<literal>"Product/Version"</literal>.</para>

	<para>By default neon will use a persistent connection
whenever possible.  For specific applications, or for debugging
purposes, it is sometimes useful to disable persistent connections.
The <function>ne_set_persist</function> function will disable
persistent connections if passed a <parameter>flag</parameter>
parameter of <literal>0</literal>, and will enable them
otherwise.</para>

	<para>When neon reads from a socket, by default the read
operation will time out after 60 seconds, and the request will fail
giving an <errorcode>NE_TIMEOUT</errorcode> error.  To configure this
timeout interval, call <function>ne_set_read_timeout</function> giving
the desired number of seconds as the <parameter>timeout</parameter>
parameter.</para>

	<para>An extension introduced in the HTTP/1.1 specification
was the use of the <literal>Expect: 100-continue</literal> header.
This header allows an HTTP client to be informed of the expected
response status before the request message body is sent: a useful
optimisation for situations where a large message body is to be sent.
The <function>ne_set_expect100</function> function can be used to
enable this feature by passing the <parameter>flag</parameter>
parameter as any non-zero integer.</para>

<warning><para>Unfortunately, if this header is sent to a server which
is not fully compliant with the HTTP/1.1 specification, a deadlock
occurs resulting in a temporarily "hung" connection.  neon will
recover gracefully from this situation, but only after a 15 second
timeout.  It is highly recommended that this option is not enabled
unless it is known that the server in use correctly implements
<literal>Expect: 100-continue</literal> support.</para></warning>

      </refsect1>      

      <refsect1>
	<title>Examples</title>
	<para>Set a user-agent string:</para>
	<programlisting>&egsess;
ne_set_useragent(sess, "MyApplication/2.1");</programlisting>

	<para>Disable use of persistent connections:</para>
	<programlisting>ne_session *sess = ne_session_create(...);
ne_set_persist(sess, 0);</programlisting>

	<para>Set a 30 second read timeout:</para>
	<programlisting>&egsess;
ne_set_read_timeout(sess, 30);</programlisting>

      </refsect1>

    </refentry>
