Initial vendor import of ldns-1.6.4 into contrib.
[dragonfly.git] / contrib / ldns / ldns / host2str.h
1 /**
2  * host2str.h -  txt presentation of RRs
3  *
4  * a Net::DNS like library for C
5  *
6  * (c) NLnet Labs, 2005-2006
7  *
8  * See the file LICENSE for the license
9  */
10
11 /**
12  * \file
13  *
14  * Contains functions to translate the main structures to their text
15  * representation, as well as functions to print them.
16  */
17
18 #ifndef LDNS_HOST2STR_H
19 #define LDNS_HOST2STR_H
20
21 #include <ldns/common.h>
22 #include <ldns/error.h>
23 #include <ldns/rr.h>
24 #include <ldns/rdata.h>
25 #include <ldns/packet.h>
26 #include <ldns/buffer.h>
27 #include <ldns/resolver.h>
28 #include <ldns/zone.h>
29 #include <ctype.h>
30
31 #include "ldns/util.h"
32
33 #define LDNS_APL_IP4            1
34 #define LDNS_APL_IP6            2
35 #define LDNS_APL_MASK           0x7f
36 #define LDNS_APL_NEGATION       0x80
37
38 /**
39  * Converts an ldns packet opcode value to its mnemonic, and adds that
40  * to the output buffer
41  * \param[in] *output the buffer to add the data to
42  * \param[in] opcode to find the string representation of
43  * \return LDNS_STATUS_OK on success, or a buffer failure mode on error
44  */
45 ldns_status
46 ldns_pkt_opcode2buffer_str(ldns_buffer *output, ldns_pkt_opcode opcode);
47
48 /**
49  * Converts an ldns packet rcode value to its mnemonic, and adds that
50  * to the output buffer
51  * \param[in] *output the buffer to add the data to
52  * \param[in] rcode to find the string representation of
53  * \return LDNS_STATUS_OK on success, or a buffer failure mode on error
54  */
55 ldns_status
56 ldns_pkt_rcode2buffer_str(ldns_buffer *output, ldns_pkt_rcode rcode);
57
58 /**
59  * Converts an ldns algorithm type to its mnemonic, and adds that
60  * to the output buffer
61  * \param[in] *output the buffer to add the data to
62  * \param[in] algorithm to find the string representation of
63  * \return LDNS_STATUS_OK on success, or a buffer failure mode on error
64  */
65 ldns_status
66 ldns_algorithm2buffer_str(ldns_buffer *output,
67                           ldns_algorithm algorithm);
68
69 /**
70  * Converts an ldns certificate algorithm type to its mnemonic, 
71  * and adds that to the output buffer
72  * \param[in] *output the buffer to add the data to
73  * \param[in] cert_algorithm to find the string representation of
74  * \return LDNS_STATUS_OK on success, or a buffer failure mode on error
75  */
76 ldns_status
77 ldns_cert_algorithm2buffer_str(ldns_buffer *output,
78                                ldns_cert_algorithm cert_algorithm);
79
80
81 /**
82  * Converts a packet opcode to its mnemonic and returns that as
83  * an allocated null-terminated string.
84  * Remember to free it.
85  *
86  * \param[in] opcode the opcode to convert to text
87  * \return null terminated char * data, or NULL on error
88  */
89 char *ldns_pkt_opcode2str(ldns_pkt_opcode opcode);
90
91 /**
92  * Converts a packet rcode to its mnemonic and returns that as
93  * an allocated null-terminated string.
94  * Remember to free it.
95  *
96  * \param[in] rcode the rcode to convert to text
97  * \return null terminated char * data, or NULL on error
98  */
99 char *ldns_pkt_rcode2str(ldns_pkt_rcode rcode);
100
101 /**
102  * Converts a signing algorithms to its mnemonic and returns that as
103  * an allocated null-terminated string.
104  * Remember to free it.
105  *
106  * \param[in] algorithm the algorithm to convert to text
107  * \return null terminated char * data, or NULL on error
108  */
109 char *ldns_pkt_algorithm2str(ldns_algorithm algorithm);
110
111 /**
112  * Converts a cert algorithm to its mnemonic and returns that as
113  * an allocated null-terminated string.
114  * Remember to free it.
115  *
116  * \param[in] cert_algorithm to convert to text
117  * \return null terminated char * data, or NULL on error
118  */
119 char *ldns_pkt_cert_algorithm2str(ldns_cert_algorithm cert_algorithm);
120
121 /** 
122  * Converts an LDNS_RDF_TYPE_A rdata element to string format and adds it to the output buffer 
123  * \param[in] *rdf The rdata to convert
124  * \param[in] *output The buffer to add the data to
125  * \return LDNS_STATUS_OK on success, and error status on failure
126  */
127 ldns_status ldns_rdf2buffer_str_a(ldns_buffer *output, const ldns_rdf *rdf);
128
129 /** 
130  * Converts an LDNS_RDF_TYPE_AAAA rdata element to string format and adds it to the output buffer 
131  * \param[in] *rdf The rdata to convert
132  * \param[in] *output The buffer to add the data to
133  * \return LDNS_STATUS_OK on success, and error status on failure
134  */
135 ldns_status ldns_rdf2buffer_str_aaaa(ldns_buffer *output, const ldns_rdf *rdf);
136
137 /** 
138  * Converts an LDNS_RDF_TYPE_STR rdata element to string format and adds it to the output buffer 
139  * \param[in] *rdf The rdata to convert
140  * \param[in] *output The buffer to add the data to
141  * \return LDNS_STATUS_OK on success, and error status on failure
142  */
143 ldns_status ldns_rdf2buffer_str_str(ldns_buffer *output, const ldns_rdf *rdf);
144
145 /** 
146  * Converts an LDNS_RDF_TYPE_B64 rdata element to string format and adds it to the output buffer 
147  * \param[in] *rdf The rdata to convert
148  * \param[in] *output The buffer to add the data to
149  * \return LDNS_STATUS_OK on success, and error status on failure
150  */
151 ldns_status ldns_rdf2buffer_str_b64(ldns_buffer *output, const ldns_rdf *rdf);
152
153 /** 
154  * Converts an LDNS_RDF_TYPE_HEX rdata element to string format and adds it to the output buffer 
155  * \param[in] *rdf The rdata to convert
156  * \param[in] *output The buffer to add the data to
157  * \return LDNS_STATUS_OK on success, and error status on failure
158  */
159 ldns_status ldns_rdf2buffer_str_hex(ldns_buffer *output, const ldns_rdf *rdf);
160
161 /** 
162  * Converts an LDNS_RDF_TYPE_TYPE rdata element to string format and adds it to the output buffer 
163  * \param[in] *rdf The rdata to convert
164  * \param[in] *output The buffer to add the data to
165  * \return LDNS_STATUS_OK on success, and error status on failure
166  */
167 ldns_status ldns_rdf2buffer_str_type(ldns_buffer *output, const ldns_rdf *rdf);
168
169 /** 
170  * Converts an LDNS_RDF_TYPE_CLASS rdata element to string format and adds it to the output buffer 
171  * \param[in] *rdf The rdata to convert
172  * \param[in] *output The buffer to add the data to
173  * \return LDNS_STATUS_OK on success, and error status on failure
174  */
175 ldns_status ldns_rdf2buffer_str_class(ldns_buffer *output, const ldns_rdf *rdf);
176
177 /** 
178  * Converts an LDNS_RDF_TYPE_ALG rdata element to string format and adds it to the output buffer 
179  * \param[in] *rdf The rdata to convert
180  * \param[in] *output The buffer to add the data to
181  * \return LDNS_STATUS_OK on success, and error status on failure
182  */
183 ldns_status ldns_rdf2buffer_str_alg(ldns_buffer *output, const ldns_rdf *rdf);
184
185 /**
186  * Converts an ldns_rr_type value to its string representation,
187  * and places it in the given buffer
188  * \param[in] *output The buffer to add the data to
189  * \param[in] type the ldns_rr_type to convert
190  * \return LDNS_STATUS_OK on success, and error status on failure
191  */
192 ldns_status ldns_rr_type2buffer_str(ldns_buffer *output,
193                                     const ldns_rr_type type);
194
195 /**
196  * Converts an ldns_rr_type value to its string representation,
197  * and returns that string. For unknown types, the string
198  * "TYPE<id>" is returned. This function allocates data that must be
199  * freed by the caller
200  * \param[in] type the ldns_rr_type to convert
201  * \return a newly allocated string
202  */
203 char *ldns_rr_type2str(const ldns_rr_type type);
204
205 /**
206  * Converts an ldns_rr_class value to its string representation,
207  * and places it in the given buffer
208  * \param[in] *output The buffer to add the data to
209  * \param[in] klass the ldns_rr_class to convert
210  * \return LDNS_STATUS_OK on success, and error status on failure
211  */
212 ldns_status ldns_rr_class2buffer_str(ldns_buffer *output,
213                                      const ldns_rr_class klass);
214
215 /**
216  * Converts an ldns_rr_class value to its string representation,
217  * and returns that string. For unknown types, the string
218  * "CLASS<id>" is returned. This function allocates data that must be
219  * freed by the caller
220  * \param[in] klass the ldns_rr_class to convert
221  * \return a newly allocated string
222  */
223 char *ldns_rr_class2str(const ldns_rr_class klass);
224
225
226 /** 
227  * Converts an LDNS_RDF_TYPE_CERT rdata element to string format and adds it to the output buffer 
228  * \param[in] *rdf The rdata to convert
229  * \param[in] *output The buffer to add the data to
230  * \return LDNS_STATUS_OK on success, and error status on failure
231  */
232 ldns_status ldns_rdf2buffer_str_cert_alg(ldns_buffer *output, const ldns_rdf *rdf);
233
234 /** 
235  * Converts an LDNS_RDF_TYPE_LOC rdata element to string format and adds it to the output buffer 
236  * \param[in] *rdf The rdata to convert
237  * \param[in] *output The buffer to add the data to
238  * \return LDNS_STATUS_OK on success, and error status on failure
239  */
240 ldns_status ldns_rdf2buffer_str_loc(ldns_buffer *output, const ldns_rdf *rdf);
241
242 /** 
243  * Converts an LDNS_RDF_TYPE_UNKNOWN rdata element to string format and adds it to the output buffer 
244  * \param[in] *rdf The rdata to convert
245  * \param[in] *output The buffer to add the data to
246  * \return LDNS_STATUS_OK on success, and error status on failure
247  */
248 ldns_status ldns_rdf2buffer_str_unknown(ldns_buffer *output, const ldns_rdf *rdf);
249
250 /** 
251  * Converts an LDNS_RDF_TYPE_NSAP rdata element to string format and adds it to the output buffer 
252  * \param[in] *rdf The rdata to convert
253  * \param[in] *output The buffer to add the data to
254  * \return LDNS_STATUS_OK on success, and error status on failure
255  */
256 ldns_status ldns_rdf2buffer_str_nsap(ldns_buffer *output, const ldns_rdf *rdf);
257
258 /** 
259  * Converts an LDNS_RDF_TYPE_WKS rdata element to string format and adds it to the output buffer 
260  * \param[in] *rdf The rdata to convert
261  * \param[in] *output The buffer to add the data to
262  * \return LDNS_STATUS_OK on success, and error status on failure
263  */
264 ldns_status ldns_rdf2buffer_str_wks(ldns_buffer *output, const ldns_rdf *rdf);
265
266 /** 
267  * Converts an LDNS_RDF_TYPE_NSEC rdata element to string format and adds it to the output buffer 
268  * \param[in] *rdf The rdata to convert
269  * \param[in] *output The buffer to add the data to
270  * \return LDNS_STATUS_OK on success, and error status on failure
271  */
272 ldns_status ldns_rdf2buffer_str_nsec(ldns_buffer *output, const ldns_rdf *rdf);
273
274 /** 
275  * Converts an LDNS_RDF_TYPE_PERIOD rdata element to string format and adds it to the output buffer 
276  * \param[in] *rdf The rdata to convert
277  * \param[in] *output The buffer to add the data to
278  * \return LDNS_STATUS_OK on success, and error status on failure
279  */
280 ldns_status ldns_rdf2buffer_str_period(ldns_buffer *output, const ldns_rdf *rdf);
281
282 /** 
283  * Converts an LDNS_RDF_TYPE_TSIGTIME rdata element to string format and adds it to the output buffer 
284  * \param[in] *rdf The rdata to convert
285  * \param[in] *output The buffer to add the data to
286  * \return LDNS_STATUS_OK on success, and error status on failure
287  */
288 ldns_status ldns_rdf2buffer_str_tsigtime(ldns_buffer *output, const ldns_rdf *rdf);
289
290 /** 
291  * Converts an LDNS_RDF_TYPE_APL rdata element to string format and adds it to the output buffer 
292  * \param[in] *rdf The rdata to convert
293  * \param[in] *output The buffer to add the data to
294  * \return LDNS_STATUS_OK on success, and error status on failure
295  */
296 ldns_status ldns_rdf2buffer_str_apl(ldns_buffer *output, const ldns_rdf *rdf);
297
298 /** 
299  * Converts an LDNS_RDF_TYPE_INT16_DATA rdata element to string format and adds it to the output buffer 
300  * \param[in] *rdf The rdata to convert
301  * \param[in] *output The buffer to add the data to
302  * \return LDNS_STATUS_OK on success, and error status on failure
303  */
304 ldns_status ldns_rdf2buffer_str_int16_data(ldns_buffer *output, const ldns_rdf *rdf);
305
306 /** 
307  * Converts an LDNS_RDF_TYPE_IPSECKEY rdata element to string format and adds it to the output buffer 
308  * \param[in] *rdf The rdata to convert
309  * \param[in] *output The buffer to add the data to
310  * \return LDNS_STATUS_OK on success, and error status on failure
311  */
312 ldns_status ldns_rdf2buffer_str_ipseckey(ldns_buffer *output, const ldns_rdf *rdf);
313
314 /** 
315  * Converts an LDNS_RDF_TYPE_TSIG rdata element to string format and adds it to the output buffer 
316  * \param[in] *rdf The rdata to convert
317  * \param[in] *output The buffer to add the data to
318  * \return LDNS_STATUS_OK on success, and error status on failure
319  */
320 ldns_status ldns_rdf2buffer_str_tsig(ldns_buffer *output, const ldns_rdf *rdf);
321
322
323 /**
324  * Converts the data in the rdata field to presentation
325  * format (as char *) and appends it to the given buffer
326  *
327  * \param[in] output pointer to the buffer to append the data to
328  * \param[in] rdf the pointer to the rdafa field containing the data
329  * \return status
330  */
331 ldns_status ldns_rdf2buffer_str(ldns_buffer *output, const ldns_rdf *rdf);
332
333 /**
334  * Converts the data in the resource record to presentation
335  * format (as char *) and appends it to the given buffer
336  *
337  * \param[in] output pointer to the buffer to append the data to
338  * \param[in] rr the pointer to the rr field to convert
339  * \return status
340  */
341 ldns_status ldns_rr2buffer_str(ldns_buffer *output, const ldns_rr *rr);
342
343 /**
344  * Converts the data in the DNS packet to presentation
345  * format (as char *) and appends it to the given buffer
346  *
347  * \param[in] output pointer to the buffer to append the data to
348  * \param[in] pkt the pointer to the packet to convert
349  * \return status
350  */
351 ldns_status ldns_pkt2buffer_str(ldns_buffer *output, const ldns_pkt *pkt);
352
353 /**
354  * Converts the data in the DNS packet to presentation
355  * format (as char *) and appends it to the given buffer
356  *
357  * \param[in] output pointer to the buffer to append the data to
358  * \param[in] k the pointer to the private key to convert
359  * \return status
360  */
361 ldns_status ldns_key2buffer_str(ldns_buffer *output, const ldns_key *k);
362
363 /**
364  * Converts the data in the int16 typed rdata field to presentation
365  * format (as char *) and appends it to the given buffer
366  *
367  * \param[in] output pointer to the buffer to append the data to
368  * \param[in] rdf the pointer to the rdafa field containing the data
369  * \return status
370  */
371 ldns_status ldns_rdf2buffer_str_int16(ldns_buffer *output, const ldns_rdf *rdf);
372
373 /**
374  * Converts the data in the rdata field to presentation format and
375  * returns that as a char *.
376  * Remember to free it.
377  *
378  * \param[in] rdf The rdata field to convert
379  * \return null terminated char * data, or NULL on error
380  */
381 char *ldns_rdf2str(const ldns_rdf *rdf);
382
383 /**
384  * Converts the data in the resource record to presentation format and
385  * returns that as a char *.
386  * Remember to free it.
387  *
388  * \param[in] rr The rdata field to convert
389  * \return null terminated char * data, or NULL on error
390  */
391 char *ldns_rr2str(const ldns_rr *rr);
392
393 /**
394  * Converts the data in the DNS packet to presentation format and
395  * returns that as a char *.
396  * Remember to free it.
397  *
398  * \param[in] pkt The rdata field to convert
399  * \return null terminated char * data, or NULL on error
400  */
401 char *ldns_pkt2str(const ldns_pkt *pkt);
402
403 /**
404  * Converts a private key to the test presentation fmt and
405  * returns that as a char *.
406  * Remember to free it.
407  *
408  * \param[in] k the key to convert to text
409  * \return null terminated char * data, or NULL on error
410  */
411 char *ldns_key2str(const ldns_key *k);
412
413 /**
414  * Converts a list of resource records to presentation format
415  * and returns that as a char *.
416  * Remember to free it.
417  *
418  * \param[in] rr_list the rr_list to convert to text
419  * \return null terminated char * data, or NULL on error
420  */
421 char *ldns_rr_list2str(const ldns_rr_list *rr_list);
422
423 /**
424  * Returns the data in the buffer as a null terminated char * string
425  * Buffer data must be char * type, and must be freed by the caller
426  *
427  * \param[in] buffer buffer containing char * data
428  * \return null terminated char * data, or NULL on error
429  */
430 char *ldns_buffer2str(ldns_buffer *buffer);
431
432 /**
433  * Prints the data in the rdata field to the given file stream
434  * (in presentation format)
435  *
436  * \param[in] output the file stream to print to
437  * \param[in] rdf the rdata field to print
438  * \return void
439  */
440 void ldns_rdf_print(FILE *output, const ldns_rdf *rdf);
441
442 /**
443  * Prints the data in the resource record to the given file stream
444  * (in presentation format)
445  *
446  * \param[in] output the file stream to print to
447  * \param[in] rr the resource record to print
448  * \return void
449  */
450 void ldns_rr_print(FILE *output, const ldns_rr *rr);
451
452 /**
453  * Prints the data in the DNS packet to the given file stream
454  * (in presentation format)
455  *
456  * \param[in] output the file stream to print to
457  * \param[in] pkt the packet to print
458  * \return void
459  */
460 void ldns_pkt_print(FILE *output, const ldns_pkt *pkt);
461
462 /**
463  * Converts a rr_list to presentation format and appends it to
464  * the output buffer
465  * \param[in] output the buffer to append output to
466  * \param[in] list the ldns_rr_list to print
467  * \return ldns_status
468  */
469 ldns_status ldns_rr_list2buffer_str(ldns_buffer *output, const ldns_rr_list *list);
470
471 /**
472  * Converts the header of a packet to presentation format and appends it to
473  * the output buffer
474  * \param[in] output the buffer to append output to
475  * \param[in] pkt the packet to convert the header of
476  * \return ldns_status
477  */
478 ldns_status ldns_pktheader2buffer_str(ldns_buffer *output, const ldns_pkt *pkt);
479
480 /**
481  * print a rr_list to output
482  * param[in] output the fd to print to
483  * param[in] list the rr_list to print
484  */
485 void ldns_rr_list_print(FILE *output, const ldns_rr_list *list);
486
487 /**
488  * Print a resolver (in sofar that is possible) state
489  * to output.
490  * \param[in] output the fd to print to
491  * \param[in] r the resolver to print
492  */
493 void ldns_resolver_print(FILE *output, const ldns_resolver *r);
494
495 /**
496  * Print a zone structure * to output. Note the SOA record
497  * is included in this output
498  * \param[in] output the fd to print to
499  * \param[in] z the zone to print
500  */
501 void ldns_zone_print(FILE *output, const ldns_zone *z);
502
503 /**
504  * Print the ldns_rdf containing a dname to the buffer
505  * \param[in] output the buffer to print to
506  * \param[in] dname the dname to print
507  * \return ldns_status message if the printing succeeded
508  */
509 ldns_status ldns_rdf2buffer_str_dname(ldns_buffer *output, const ldns_rdf *dname);
510
511
512 #endif /* LDNS_HOST2STR_H */