[people/ms/strongswan.git] / src / libfreeswan / liblwres / man / lwres_noop.html

<!--
 - Copyright (C) 2000, 2001  Internet Software Consortium.
 - 
 - Permission to use, copy, modify, and distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 - 
 - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
 - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
 - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
 - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
 - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->
<HTML
><HEAD
><TITLE
>lwres_noop</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
>lwres_noop</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8"
></A
><H2
>Name</H2
>lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free&nbsp;--&nbsp;lightweight resolver no-op message handling</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN16"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN17"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;lwres/lwres.h&gt;</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_result_t
lwres_nooprequest_render</CODE
>(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_result_t
lwres_noopresponse_render</CODE
>(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_result_t
lwres_nooprequest_parse</CODE
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_result_t
lwres_noopresponse_parse</CODE
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_noopresponse_free</CODE
>(lwres_context_t *ctx, lwres_noopresponse_t **structp);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_nooprequest_free</CODE
>(lwres_context_t *ctx, lwres_nooprequest_t **structp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN57"
></A
><H2
>DESCRIPTION</H2
><P
>These are low-level routines for creating and parsing
lightweight resolver no-op request and response messages.</P
><P
>The no-op message is analogous to a <B
CLASS="COMMAND"
>ping</B
> packet: 
a packet is sent to the resolver daemon and is simply echoed back.
The opcode is intended to allow a client to determine if the server is
operational or not.</P
><P
>There are four main functions for the no-op opcode.
One render function converts a no-op request structure &mdash;
<SPAN
CLASS="TYPE"
>lwres_nooprequest_t</SPAN
> &mdash;
to the lighweight resolver's canonical format.
It is complemented by a parse function that converts a packet in this
canonical format to a no-op request structure.
Another render function converts the no-op response structure &mdash;
<SPAN
CLASS="TYPE"
>lwres_noopresponse_t</SPAN
>
to the canonical format.
This is complemented by a parse function which converts a packet in
canonical format to a no-op response structure.</P
><P
>These structures are defined in
<TT
CLASS="FILENAME"
>lwres/lwres.h</TT
>.

They are shown below.
<PRE
CLASS="PROGRAMLISTING"
>#define LWRES_OPCODE_NOOP       0x00000000U

typedef struct {
        lwres_uint16_t  datalength;
        unsigned char   *data;
} lwres_nooprequest_t;

typedef struct {
        lwres_uint16_t  datalength;
        unsigned char   *data;
} lwres_noopresponse_t;</PRE
>
Although the structures have different types, they are identical.
This is because the no-op opcode simply echos whatever data was sent:
the response is therefore identical to the request.</P
><P
><TT
CLASS="FUNCTION"
>lwres_nooprequest_render()</TT
> uses resolver
context <TT
CLASS="PARAMETER"
><I
>ctx</I
></TT
> to convert no-op request structure
<TT
CLASS="PARAMETER"
><I
>req</I
></TT
> to canonical format.  The packet header
structure <TT
CLASS="PARAMETER"
><I
>pkt</I
></TT
> is initialised and transferred to
buffer <TT
CLASS="PARAMETER"
><I
>b</I
></TT
>.  The contents of
<TT
CLASS="PARAMETER"
><I
>*req</I
></TT
> are then appended to the buffer in
canonical format.  <TT
CLASS="FUNCTION"
>lwres_noopresponse_render()</TT
>
performs the same task, except it converts a no-op response structure
<SPAN
CLASS="TYPE"
>lwres_noopresponse_t</SPAN
> to the lightweight resolver's
canonical format.</P
><P
><TT
CLASS="FUNCTION"
>lwres_nooprequest_parse()</TT
> uses context
<TT
CLASS="PARAMETER"
><I
>ctx</I
></TT
> to convert the contents of packet
<TT
CLASS="PARAMETER"
><I
>pkt</I
></TT
> to a <SPAN
CLASS="TYPE"
>lwres_nooprequest_t</SPAN
>
structure.  Buffer <TT
CLASS="PARAMETER"
><I
>b</I
></TT
> provides space to be used
for storing this structure.  When the function succeeds, the resulting
<SPAN
CLASS="TYPE"
>lwres_nooprequest_t</SPAN
> is made available through
<TT
CLASS="PARAMETER"
><I
>*structp</I
></TT
>.
<TT
CLASS="FUNCTION"
>lwres_noopresponse_parse()</TT
> offers the same
semantics as <TT
CLASS="FUNCTION"
>lwres_nooprequest_parse()</TT
> except it
yields a <SPAN
CLASS="TYPE"
>lwres_noopresponse_t</SPAN
> structure.</P
><P
><TT
CLASS="FUNCTION"
>lwres_noopresponse_free()</TT
> and
<TT
CLASS="FUNCTION"
>lwres_nooprequest_free()</TT
> release the memory in
resolver context <TT
CLASS="PARAMETER"
><I
>ctx</I
></TT
> that was allocated to the
<SPAN
CLASS="TYPE"
>lwres_noopresponse_t</SPAN
> or <SPAN
CLASS="TYPE"
>lwres_nooprequest_t</SPAN
>
structures referenced via <TT
CLASS="PARAMETER"
><I
>structp</I
></TT
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN95"
></A
><H2
>RETURN VALUES</H2
><P
>The no-op opcode functions
<TT
CLASS="FUNCTION"
>lwres_nooprequest_render()</TT
>,

<TT
CLASS="FUNCTION"
>lwres_noopresponse_render()</TT
>
<TT
CLASS="FUNCTION"
>lwres_nooprequest_parse()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_noopresponse_parse()</TT
>
all return
<SPAN
CLASS="ERRORCODE"
>LWRES_R_SUCCESS</SPAN
>
on success.
They return
<SPAN
CLASS="ERRORCODE"
>LWRES_R_NOMEMORY</SPAN
>
if memory allocation fails.
<SPAN
CLASS="ERRORCODE"
>LWRES_R_UNEXPECTEDEND</SPAN
>
is returned if the available space in the buffer
<TT
CLASS="PARAMETER"
><I
>b</I
></TT
>
is too small to accommodate the packet header or the
<SPAN
CLASS="TYPE"
>lwres_nooprequest_t</SPAN
>
and
<SPAN
CLASS="TYPE"
>lwres_noopresponse_t</SPAN
>
structures.
<TT
CLASS="FUNCTION"
>lwres_nooprequest_parse()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_noopresponse_parse()</TT
>
will return
<SPAN
CLASS="ERRORCODE"
>LWRES_R_UNEXPECTEDEND</SPAN
>
if the buffer is not empty after decoding the received packet.
These functions will return
<SPAN
CLASS="ERRORCODE"
>LWRES_R_FAILURE</SPAN
>
if
<TT
CLASS="CONSTANT"
>pktflags</TT
>
in the packet header structure
<SPAN
CLASS="TYPE"
>lwres_lwpacket_t</SPAN
>
indicate that the packet is not a response to an earlier query.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN114"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_packet</SPAN
>(3)</SPAN
></P
></DIV
></BODY
></HTML
>
Commit	Line	Data
997358a6 MW	1	<!--
	2	- Copyright (C) 2000, 2001 Internet Software Consortium.
	3	-
	4	- Permission to use, copy, modify, and distribute this software for any
	5	- purpose with or without fee is hereby granted, provided that the above
	6	- copyright notice and this permission notice appear in all copies.
	7	-
	8	- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
	9	- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
	10	- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
	11	- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
	12	- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
	13	- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
	14	- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
	15	- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	16	-->
	17	<HTML
	18	><HEAD
	19	><TITLE
	20	>lwres_noop</TITLE
	21	><META
	22	NAME="GENERATOR"
	23	CONTENT="Modular DocBook HTML Stylesheet Version 1.61
	24	"></HEAD
	25	><BODY
	26	CLASS="REFENTRY"
	27	BGCOLOR="#FFFFFF"
	28	TEXT="#000000"
	29	LINK="#0000FF"
	30	VLINK="#840084"
	31	ALINK="#0000FF"
	32	><H1
	33	><A
	34	NAME="AEN1"
	35	>lwres_noop</A
	36	></H1
	37	><DIV
	38	CLASS="REFNAMEDIV"
	39	><A
	40	NAME="AEN8"
	41	></A
	42	><H2
	43	>Name</H2
	44	>lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free -- lightweight resolver no-op message handling</DIV
	45	><DIV
	46	CLASS="REFSYNOPSISDIV"
	47	><A
	48	NAME="AEN16"
	49	></A
	50	><H2
	51	>Synopsis</H2
	52	><DIV
	53	CLASS="FUNCSYNOPSIS"
	54	><A
	55	NAME="AEN17"
	56	></A
	57	><P
	58	></P
	59	><PRE
	60	CLASS="FUNCSYNOPSISINFO"
	61	>#include <lwres/lwres.h></PRE
	62	><P
	63	><CODE
	64	><CODE
65	CLASS="FUNCDEF"
66	>lwres_result_t
67	lwres_nooprequest_render</CODE
68	>(lwres_context_t ctx, lwres_nooprequest_t req, lwres_lwpacket_t pkt, lwres_buffer_t b);</CODE
69	></P
70	><P
71	><CODE
72	><CODE
73	CLASS="FUNCDEF"
74	>lwres_result_t
75	lwres_noopresponse_render</CODE
76	>(lwres_context_t ctx, lwres_noopresponse_t req, lwres_lwpacket_t pkt, lwres_buffer_t b);</CODE
77	></P
78	><P
79	><CODE
80	><CODE
81	CLASS="FUNCDEF"
82	>lwres_result_t
83	lwres_nooprequest_parse</CODE
84	>(lwres_context_t ctx, lwres_buffer_t b, lwres_lwpacket_t pkt, lwres_nooprequest_t *structp);</CODE
85	></P
86	><P
87	><CODE
88	><CODE
89	CLASS="FUNCDEF"
90	>lwres_result_t
91	lwres_noopresponse_parse</CODE
92	>(lwres_context_t ctx, lwres_buffer_t b, lwres_lwpacket_t pkt, lwres_noopresponse_t *structp);</CODE
93	></P
94	><P
95	><CODE
96	><CODE
97	CLASS="FUNCDEF"
98	>void
99	lwres_noopresponse_free</CODE
100	>(lwres_context_t ctx, lwres_noopresponse_t *structp);</CODE
101	></P
102	><P
103	><CODE
104	><CODE
105	CLASS="FUNCDEF"
106	>void
107	lwres_nooprequest_free</CODE
108	>(lwres_context_t ctx, lwres_nooprequest_t *structp);</CODE
109	></P
110	><P
111	></P
112	></DIV
113	></DIV
114	><DIV
115	CLASS="REFSECT1"
116	><A
117	NAME="AEN57"
118	></A
119	><H2
120	>DESCRIPTION</H2
121	><P
122	>These are low-level routines for creating and parsing
123	lightweight resolver no-op request and response messages.</P
124	><P
125	>The no-op message is analogous to a <B
126	CLASS="COMMAND"
127	>ping</B
128	> packet:
129	a packet is sent to the resolver daemon and is simply echoed back.
130	The opcode is intended to allow a client to determine if the server is
131	operational or not.</P
132	><P
133	>There are four main functions for the no-op opcode.
134	One render function converts a no-op request structure —
135	<SPAN
136	CLASS="TYPE"
137	>lwres_nooprequest_t</SPAN
138	> —
139	to the lighweight resolver's canonical format.
140	It is complemented by a parse function that converts a packet in this
141	canonical format to a no-op request structure.
142	Another render function converts the no-op response structure —
143	<SPAN
144	CLASS="TYPE"
145	>lwres_noopresponse_t</SPAN
146	>
147	to the canonical format.
148	This is complemented by a parse function which converts a packet in
149	canonical format to a no-op response structure.</P
150	><P
151	>These structures are defined in
152	<TT
153	CLASS="FILENAME"
154	>lwres/lwres.h</TT
155	>.
156
157	They are shown below.
158	<PRE
159	CLASS="PROGRAMLISTING"
160	>#define LWRES_OPCODE_NOOP 0x00000000U
161
162	typedef struct {
163	lwres_uint16_t datalength;
164	unsigned char *data;
165	} lwres_nooprequest_t;
166
167	typedef struct {
168	lwres_uint16_t datalength;
169	unsigned char *data;
170	} lwres_noopresponse_t;</PRE
171	>
172	Although the structures have different types, they are identical.
173	This is because the no-op opcode simply echos whatever data was sent:
174	the response is therefore identical to the request.</P
175	><P
176	><TT
177	CLASS="FUNCTION"
178	>lwres_nooprequest_render()</TT
179	> uses resolver
180	context <TT
181	CLASS="PARAMETER"
182	><I
183	>ctx</I
184	></TT
185	> to convert no-op request structure
186	<TT
187	CLASS="PARAMETER"
188	><I
189	>req</I
190	></TT
191	> to canonical format. The packet header
192	structure <TT
193	CLASS="PARAMETER"
194	><I
195	>pkt</I
196	></TT
197	> is initialised and transferred to
198	buffer <TT
199	CLASS="PARAMETER"
200	><I
201	>b</I
202	></TT
203	>. The contents of
204	<TT
205	CLASS="PARAMETER"
206	><I
207	>*req</I
208	></TT
209	> are then appended to the buffer in
210	canonical format. <TT
211	CLASS="FUNCTION"
212	>lwres_noopresponse_render()</TT
213	>
214	performs the same task, except it converts a no-op response structure
215	<SPAN
216	CLASS="TYPE"
217	>lwres_noopresponse_t</SPAN
218	> to the lightweight resolver's
219	canonical format.</P
220	><P
221	><TT
222	CLASS="FUNCTION"
223	>lwres_nooprequest_parse()</TT
224	> uses context
225	<TT
226	CLASS="PARAMETER"
227	><I
228	>ctx</I
229	></TT
230	> to convert the contents of packet
231	<TT
232	CLASS="PARAMETER"
233	><I
234	>pkt</I
235	></TT
236	> to a <SPAN
237	CLASS="TYPE"
238	>lwres_nooprequest_t</SPAN
239	>
240	structure. Buffer <TT
241	CLASS="PARAMETER"
242	><I
243	>b</I
244	></TT
245	> provides space to be used
246	for storing this structure. When the function succeeds, the resulting
247	<SPAN
248	CLASS="TYPE"
249	>lwres_nooprequest_t</SPAN
250	> is made available through
251	<TT
252	CLASS="PARAMETER"
253	><I
254	>*structp</I
255	></TT
256	>.
257	<TT
258	CLASS="FUNCTION"
259	>lwres_noopresponse_parse()</TT
260	> offers the same
261	semantics as <TT
262	CLASS="FUNCTION"
263	>lwres_nooprequest_parse()</TT
264	> except it
265	yields a <SPAN
266	CLASS="TYPE"
267	>lwres_noopresponse_t</SPAN
268	> structure.</P
269	><P
270	><TT
271	CLASS="FUNCTION"
272	>lwres_noopresponse_free()</TT
273	> and
274	<TT
275	CLASS="FUNCTION"
276	>lwres_nooprequest_free()</TT
277	> release the memory in
278	resolver context <TT
279	CLASS="PARAMETER"
280	><I
281	>ctx</I
282	></TT
283	> that was allocated to the
284	<SPAN
285	CLASS="TYPE"
286	>lwres_noopresponse_t</SPAN
287	> or <SPAN
288	CLASS="TYPE"
289	>lwres_nooprequest_t</SPAN
290	>
291	structures referenced via <TT
292	CLASS="PARAMETER"
293	><I
294	>structp</I
295	></TT
296	>.</P
297	></DIV
298	><DIV
299	CLASS="REFSECT1"
300	><A
301	NAME="AEN95"
302	></A
303	><H2
304	>RETURN VALUES</H2
305	><P
306	>The no-op opcode functions
307	<TT
308	CLASS="FUNCTION"
309	>lwres_nooprequest_render()</TT
310	>,
311
312	<TT
313	CLASS="FUNCTION"
314	>lwres_noopresponse_render()</TT
315	>
316	<TT
317	CLASS="FUNCTION"
318	>lwres_nooprequest_parse()</TT
319	>
320	and
321	<TT
322	CLASS="FUNCTION"
323	>lwres_noopresponse_parse()</TT
324	>
325	all return
326	<SPAN
327	CLASS="ERRORCODE"
328	>LWRES_R_SUCCESS</SPAN
329	>
330	on success.
331	They return
332	<SPAN
333	CLASS="ERRORCODE"
334	>LWRES_R_NOMEMORY</SPAN
335	>
336	if memory allocation fails.
337	<SPAN
338	CLASS="ERRORCODE"
339	>LWRES_R_UNEXPECTEDEND</SPAN
340	>
341	is returned if the available space in the buffer
342	<TT
343	CLASS="PARAMETER"
344	><I
345	>b</I
346	></TT
347	>
348	is too small to accommodate the packet header or the
349	<SPAN
350	CLASS="TYPE"
351	>lwres_nooprequest_t</SPAN
352	>
353	and
354	<SPAN
355	CLASS="TYPE"
356	>lwres_noopresponse_t</SPAN
357	>
358	structures.
359	<TT
360	CLASS="FUNCTION"
361	>lwres_nooprequest_parse()</TT
362	>
363	and
364	<TT
365	CLASS="FUNCTION"
366	>lwres_noopresponse_parse()</TT
367	>
368	will return
369	<SPAN
370	CLASS="ERRORCODE"
371	>LWRES_R_UNEXPECTEDEND</SPAN
372	>
373	if the buffer is not empty after decoding the received packet.
374	These functions will return
375	<SPAN
376	CLASS="ERRORCODE"
377	>LWRES_R_FAILURE</SPAN
378	>
379	if
380	<TT
381	CLASS="CONSTANT"
382	>pktflags</TT
383	>
384	in the packet header structure
385	<SPAN
386	CLASS="TYPE"
387	>lwres_lwpacket_t</SPAN
388	>
389	indicate that the packet is not a response to an earlier query.</P
390	></DIV
391	><DIV
392	CLASS="REFSECT1"
393	><A
394	NAME="AEN114"
395	></A
396	><H2
397	>SEE ALSO</H2
398	><P
399	><SPAN
400	CLASS="CITEREFENTRY"
401	><SPAN
402	CLASS="REFENTRYTITLE"
403	>lwres_packet</SPAN
404	>(3)</SPAN
405	></P
406	></DIV
407	></BODY
408	></HTML
409	>