1    <refentry id="refopts">
2
3      <refmeta>
4	<refentrytitle>ne_set_useragent</refentrytitle>
5	<manvolnum>3</manvolnum>
6      </refmeta>
7
8      <refnamediv>
9	<refname id="ne_set_useragent">ne_set_useragent</refname>
10	<refname id="ne_set_read_timeout">ne_set_read_timeout</refname>
11	<refname id="ne_set_connect_timeout">ne_set_connect_timeout</refname>
12	<refname id="ne_get_scheme">ne_get_scheme</refname>
13	<refname id="ne_get_server_hostport">ne_get_server_hostport</refname>
14	<refpurpose>common properties for HTTP sessions</refpurpose>
15      </refnamediv>
16      
17      <refsynopsisdiv>
18	
19	<funcsynopsis>
20
21	  <funcsynopsisinfo>#include &lt;ne_session.h&gt;</funcsynopsisinfo>
22
23	  <funcprototype>
24	    <funcdef>void <function>ne_set_useragent</function></funcdef>
25	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
26	    <paramdef>const char *<parameter>product</parameter></paramdef>
27	  </funcprototype>
28
29	  <funcprototype>
30	    <funcdef>void <function>ne_set_read_timeout</function></funcdef>
31	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
32	    <paramdef>int <parameter>timeout</parameter></paramdef>
33	  </funcprototype>
34
35	  <funcprototype>
36	    <funcdef>void <function>ne_set_connect_timeout</function></funcdef>
37	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
38	    <paramdef>int <parameter>timeout</parameter></paramdef>
39	  </funcprototype>
40
41	  <funcprototype>
42	    <funcdef>const char *<function>ne_get_scheme</function></funcdef>
43	    <paramdef>ne_sesssion *<parameter>session</parameter></paramdef>
44	  </funcprototype>
45
46	  <funcprototype>
47	    <funcdef>const char *<function>ne_get_server_hostport</function></funcdef>
48	    <paramdef>ne_sesssion *<parameter>session</parameter></paramdef>
49	  </funcprototype>
50
51	</funcsynopsis>
52	
53      </refsynopsisdiv>
54
55      <refsect1>
56	<title>Description</title>
57	
58	<para>The <literal>User-Agent</literal> request header is used
59to identify the software which generated the request for statistical
60or debugging purposes.  neon does not send a
61<literal>User-Agent</literal> header unless a call is made to the
62<function>ne_set_useragent</function>.
63<function>ne_set_useragent</function> must be passed a product string
64conforming to RFC2616's product token grammar; of the form
65<literal>"Product/Version"</literal>.</para>
66
67	<para>When neon reads from a socket, by default the read
68operation will time out after 60 seconds, and the request will fail
69giving an <errorcode>NE_TIMEOUT</errorcode> error.  To configure this
70timeout interval, call <function>ne_set_read_timeout</function> giving
71the desired number of seconds as the <parameter>timeout</parameter>
72parameter.</para>
73
74	<para>When a connection is being established to a server,
75	normally only the system's TCP timeout handling will apply.
76	To configure a specific (and probably shorter) timeout, the
77	<function>ne_set_connect_timeout</function> can be used,
78	giving the desired number of seconds as the
79	<parameter>timeout</parameter> parameter.  If
80	<literal>0</literal> is passed, then the default behaviour of
81	using the system TCP timeout will be used.</para>
82
83         <para>The scheme used to initially create the session will be
84         returned by <function>ne_get_scheme</function>.</para>
85
86         <para>The hostport pair with which the session is associated
87         will be returned by the
88         <function>ne_get_server_hostport</function>; for example
89         <literal>www.example.com:8080</literal>.  Note that the
90         <literal>:port</literal> will be omitted if the default port
91         for the scheme is used.</para>
92
93      </refsect1>      
94
95      <refsect1>
96	<title>Examples</title>
97	<para>Set a user-agent string:</para>
98	<programlisting>&egsess;
99ne_set_useragent(sess, "MyApplication/2.1");</programlisting>
100
101	<para>Set a 30 second read timeout:</para>
102	<programlisting>&egsess;
103ne_set_read_timeout(sess, 30);</programlisting>
104
105      </refsect1>
106
107      <refsect1>
108	<title>See also</title>
109	
110	<para><xref linkend="ne_session_create"/>, <xref
111	linkend="ne_set_session_flag"/>.</para>
112      </refsect1>
113
114    </refentry>
115