Debian Codegraph @

deps/libneon/doc/ref/opts.xml

raw
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
59 to identify the software which generated the request for statistical
60 or 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
64 conforming 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
68 operation will time out after 60 seconds, and the request will fail
69 giving an <errorcode>NE_TIMEOUT</errorcode> error. To configure this
70 timeout interval, call <function>ne_set_read_timeout</function> giving
71 the desired number of seconds as the <parameter>timeout</parameter>
72 parameter.</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;
99 ne_set_useragent(sess, "MyApplication/2.1");</programlisting>
100
101 <para>Set a 30 second read timeout:</para>
102 <programlisting>&egsess;
103 ne_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>