restcgi::http_word Class Reference

List of all members.

---

Detailed Description

HTTP/1.1 specification "word", either a "token" or quoted text.

This is meant for converting strings with spaces and special chars, e.g. ';', into a single "word" for HTTP "value" type fields. When encoding words, if the string parses as a "token" it is returned as is, otherwise it is quoted, escaping any embedded '\' or '"' chars.

Note: An alternative to this is to perform a "generic" URI percent-encoding along the lines of the JavaScript encode() function, producing a "token" instead of a "quoted-string". However, the JavaScript functions will allow (i.e. not encode) some chars that are invalid as "token" chars. Depending on the context these differences may or may not cause problems.

• JavaScript encode(): allows fewer chars than "token" but conflicts by allowing forward slash and at symbol. This is frequently used to set cookie values from within the browser.
• JavaScript encodeURIComponent(): allows fewer chars than "token" but conflicts by allowing left and right parens.

There is no standard solution to the encoding problem. Applications that share data must be explicitly programmed to do so. In other words, using this class for both encoding and decoding will work, interoperability with other applications (without explicit, additional programming) is not guaranteed.

Syntax (see http_token, http_text for additional definitions):

 word          = token | quoted-string
 quoted-string = ( <"> *(qdtext | quoted-pair ) \<"> )
 qdtext        = <any TEXT except <">>
 quoted-pair   = "\" CHAR
 

Notes on quoted-string:

• '\' is used as an escape for any char (0-0x7F) that follows it, and, thus, the '\' will be removed.
• CTL chars (including HT) are not allowed, escaped or not, and will cause a return of false if encountered before the ending quote.
• The char after the ending quote is not checked in any way.
• Chars from other charsets not supported, i.e. RFC2047 is not supported.

See also:

http_token, http_text, parse(std::string::const_iterator&, std::string::const_iterator, http_word&)

http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2

Public Member Functions
	http_word ()
	http_word (const std::string &s)
	http_word (const http_token &tok)
	Construct from HTTP token.
	http_word (const http_text &txt)
	Construct from HTTP text.
bool	empty () const
const std::string &	string () const
http_word	operator+ (const std::string &rhs) const
http_word &	operator+= (const std::string &rhs)
http_word	operator+ (const http_text &rhs) const
	Append text and return result.
http_word &	operator+= (const http_text &rhs)
http_word	operator+ (const http_word &rhs) const
	Append word and return result.
http_word &	operator+= (const http_word &rhs)
std::string	encoding (bool force_quotes=false) const
Static Public Attributes
static const char	ESC_CHAR
	escape char ('\')
Friends
bool RESTCGI_API	parse (std::string::const_iterator &first, std::string::const_iterator last, http_word &v)
	Parse HTTP word.

---

Constructor & Destructor Documentation

restcgi::http_word::http_word

(

)

Construct.

restcgi::http_word::http_word

(

const std::string &

s

)

Construct from encoded string, either http_token or quoted http_text.

Exceptions:

std::invalid_argument

if string not valid word

---

Member Function Documentation

bool restcgi::http_word::empty

(

)

const [inline]

Test empty.

std::string restcgi::http_word::encoding

(

bool

force_quotes = false

)

const

Calculate the encoding for the word, returning just the string if a token, otherwise quoting and escaping.

http_word restcgi::http_word::operator+

(

const std::string &

rhs

)

const [inline]

Append (and check) text string and return result.

Exceptions:

std::invalid_argument

if string contains invalid text chars

http_word& restcgi::http_word::operator+=

(

const http_word &

rhs

)

Append word to this and return this.

http_word& restcgi::http_word::operator+=

(

const http_text &

rhs

)

Append text to this and return this.

http_word& restcgi::http_word::operator+=

(

const std::string &

rhs

)

Append (and check) text string to this and return this.

Exceptions:

std::invalid_argument

if string contains invalid text chars

const std::string& restcgi::http_word::string

(

)

const [inline]

Get (unencoded) string. This is either the token or the unquoted (unfolded) text.

---

Friends And Related Function Documentation

bool RESTCGI_API parse	(	std::string::const_iterator &	first,
		std::string::const_iterator	last,
		http_word &	v
	)			[friend]

Parse HTTP word.

Returns whether found or not and advances first and sets if found. Skips leading SP or HT chars.

---