header.h File Reference

---

Detailed Description

Header parsing routines.

Author:

Raphael Manfredi

Date:

2001-2003

#include <stdio.h>
#include <glib.h>

Go to the source code of this file.

Data Structures
struct	header
	Header parsing and holding data structures. More...
struct	header_field_t
	A header field. More...
Defines
#define	HEADER_SIZE(h)   ((h)->size)
#define	HEADER_LINES(h)   ((h)->lines)
#define	HEAD_OK   0 /**< OK */
	OK.
#define	HEAD_CONTINUATION   1 /**< Unexpected continuation line */
	Unexpected continuation line.
#define	HEAD_MALFORMED   2 /**< Malformed header line */
	Malformed header line.
#define	HEAD_BAD_CHARS   3 /**< Invalid characters in field name */
	Invalid characters in field name.
#define	HEAD_EOH_REACHED   4 /**< End of header already reached */
	End of header already reached.
#define	HEAD_SKIPPED   5 /**< Skipped continuation line */
	Skipped continuation line.
#define	HEAD_TOO_LARGE   6 /**< Header too large */
	Header too large.
#define	HEAD_MANY_LINES   7 /**< Header has too many lines */
	Header has too many lines.
#define	HEAD_EOH   8 /**< End of header reached */
	End of header reached.
#define	HEAD_MAX_LINES   128 /**< Maximum amount of header lines */
	Maximum amount of header lines.
#define	HEAD_MAX_SIZE   16384 /**< Maximum size of header data */
	Maximum size of header data.
Typedefs
typedef header	header_t
	Header parsing and holding data structures.
Functions
header_t *	header_make (void)
	Create a new header object.
void	header_free (header_t *o)
	Destroy header object.
void	header_reset (header_t *o)
	Reset header object, for new header parsing.
gint	header_append (header_t *o, const gchar *text, gint len)
	Append a new line of text at the end of the header.
void	header_dump (const header_t *o, FILE *out)
	Dump whole header on specified file.
const gchar *	header_strerror (guint errnum)
gchar *	header_get (const header_t *o, const gchar *field)
	Get field value, or NULL if not present.
gchar *	header_getdup (const header_t *o, const gchar *field)
	Get field value, or NULL if not present.
gpointer	header_fmt_make (const gchar *field, const gchar *separator, gint len_hint)
	Create a new formatting context for a header line.
void	header_fmt_free (gpointer o)
	Dispose of header formatting context.
void	header_fmt_set_line_length (gpointer o, gint maxlen)
	Set max line length.
gboolean	header_fmt_value_fits (gpointer o, gint len, gint maxlen)
	Checks whether appending `len' bytes of data to the header would fit within the `maxlen' total header size requirement in case a continuation is emitted, and using the configured separator.
void	header_fmt_append (gpointer o, const gchar *str, const gchar *separator)
	Append data `str' to the header line, atomically.
void	header_fmt_append_value (gpointer o, const gchar *str)
	Append data `str' to the header line, atomically.
gint	header_fmt_length (gpointer o)
void	header_fmt_end (gpointer o)
	Terminate header, emitting the trailing "\r\n".
gchar *	header_fmt_string (gpointer o)
gchar *	header_fmt_to_string (gpointer o)
	Convert current header to a string.

---

Define Documentation

#define HEAD_BAD_CHARS   3 /**< Invalid characters in field name */

Invalid characters in field name.

#define HEAD_CONTINUATION   1 /**< Unexpected continuation line */

Unexpected continuation line.

#define HEAD_EOH   8 /**< End of header reached */

End of header reached.

#define HEAD_EOH_REACHED   4 /**< End of header already reached */

End of header already reached.

#define HEAD_MALFORMED   2 /**< Malformed header line */

Malformed header line.

#define HEAD_MANY_LINES   7 /**< Header has too many lines */

Header has too many lines.

#define HEAD_MAX_LINES   128 /**< Maximum amount of header lines */

Maximum amount of header lines.

#define HEAD_MAX_SIZE   16384 /**< Maximum size of header data */

Maximum size of header data.

#define HEAD_OK   0 /**< OK */

OK.

#define HEAD_SKIPPED   5 /**< Skipped continuation line */

Skipped continuation line.

#define HEAD_TOO_LARGE   6 /**< Header too large */

Header too large.

#define HEADER_LINES (  h   )     ((h)->lines)

#define HEADER_SIZE (  h   )     ((h)->size)

---

Typedef Documentation

typedef struct header header_t

Header parsing and holding data structures. The `headers' field is a hash table indexed by field name (normalized). Each value (GString) holds a private copy of the string making that header, with all continuations removed (leading spaces collapsed into one), and indentical fields concatenated using ", " separators, per RFC2616. The `fields' field holds a list of all the fields, in the order they appeared. The value is a header_field_t structure. It allows one to dump the header exactly as it was read.

---

Function Documentation

gint header_append (  header_t *  o, const gchar *  text, gint  len )

Append a new line of text at the end of the header. A private copy of the text is made. Returns: an error code, or HEAD_OK if appending was successful.

void header_dump (  const header_t *  o, FILE *  out )

Dump whole header on specified file.

void header_fmt_append (  gpointer  o, const gchar *  str, const gchar *  separator )

Append data `str' to the header line, atomically. `separator' is an optional separator string that will be emitted BEFORE outputting the data, and only when nothing has been emitted already. Any trailing space will be stripped out of `separator' if emitting at the end of a line. It supersedes any separator configured at make time. To use the standard separator, use header_fmt_append_value().

void header_fmt_append_value (  gpointer  o, const gchar *  str )

Append data `str' to the header line, atomically. Values are separated using the string specified at make time, if any. If emitted before a continuation, the version with stripped trailing whitespaces is used. To supersede the default separator, use header_fmt_append().

void header_fmt_end (  gpointer  o  )

Terminate header, emitting the trailing "\r\n". Further appending is forbidden.

void header_fmt_free (  gpointer  o  )

Dispose of header formatting context.

gint header_fmt_length (  gpointer  o  )

Returns: length of currently formatted header.

gpointer header_fmt_make (  const gchar *  field, const gchar *  separator, gint  len_hint )

Create a new formatting context for a header line. Parameters: `field'  is the header field name, without trailing ':'. `separator'  is the optional default separator to emit between the values added via header_fmd_append_value(). To supersede the default separator, use header_fmd_append() and specify another separator explicitly. If set to NULL, there will be no default separator and values will be simply concatenated together. The value given must NOT be freed before the header_fmt_end() call (usually it will just be a static string). Trailing spaces in the separator will be stripped if it is emitted at the end of a line before a continuation. `len_hint'  is the expected line size, for pre-sizing purposes. (0 to guess). Returns: opaque pointer.

void header_fmt_set_line_length (  gpointer  o, gint  maxlen )

Set max line length.

gchar* header_fmt_string (  gpointer  o  )

Returns: current header string.

gchar* header_fmt_to_string (  gpointer  o  )

Convert current header to a string. Attention: NB: returns pointer to static data!

gboolean header_fmt_value_fits (  gpointer  o, gint  len, gint  maxlen )

Checks whether appending `len' bytes of data to the header would fit within the `maxlen' total header size requirement in case a continuation is emitted, and using the configured separator. Attention: NB: The `maxlen' parameter is the amount of data that can be generated for the header string, not counting the final "\r\n" + the trailing NUL byte.

void header_free (  header_t *  o  )

Destroy header object.

gchar* header_get (  const header_t *  o, const gchar *  field )

Get field value, or NULL if not present. The value returned is a pointer to the internals of the header structure, so it must not be kept around. The requested header field must be in normalized form since they are stored that way.

gchar* header_getdup (  const header_t *  o, const gchar *  field )

Get field value, or NULL if not present. The value returned is a copy of the internal value, so it may be kept around, but must be freed by the caller.

header_t* header_make (  void   )

Create a new header object.

void header_reset (  header_t *  o  )

Reset header object, for new header parsing.

const gchar* header_strerror (  guint  errnum  )

Returns: human-readable error string corresponding to error code `errnum'.

---