Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

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_theader_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)->lines)
 

#define HEADER_SIZE  )     ((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'.


Generated on Sun Feb 12 10:50:03 2006 for Gtk-Gnutella by doxygen 1.3.6