    <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_get_scheme">ne_get_scheme</refname>
	<refname id="ne_get_server_hostport">ne_get_server_hostport</refname>
	<refpurpose>common properties 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>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>
	
	<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>The scheme used to initially create the session will be
         returned by <function>ne_get_scheme</function>.</para>

         <para>The hostport pair with which the session is associated
         will be returned by the
         <function>ne_get_server_hostport</function>; for example
         <literal>www.example.com:8080</literal>.  Note that the
         <literal>:port</literal> will be omitted if the default port
         for the scheme is used.</para>

      </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>
