NAME

khttp_urlpart, khttp_urlpartx, khttp_vurlpart, khttp_vurlpartx —

URL formatting for kcgi

LIBRARY

library “libkcgi”

SYNOPSIS

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>

char *
khttp_urlpart(const char *path, const char *suffix, const char *page, ...);

char *
khttp_urlpartx(const char *path, const char *suffix, const char *page, ...);

char *
khttp_vurlpart(const char *path, const char *suffix, const char *page, va_list ap);

char *
khttp_vurlpartx(const char *path, const char *suffix, const char *page, va_list ap);

DESCRIPTION

Format a URL given the components following the domain. If the variable arguments are provided, append them as query string pairs.

path/page.suffix

path/page.suffix?key=val...

If path is NULL, the URL will be relative to page; otherwise, path will be followed by a path separator. An empty path signifies the root directory.

If the suffix is NULL or empty, or the corresponding page is NULL or empty, the URL is formatted without a suffix.

The variable key-value arguments must be terminated with NULL. khttp_urlpart() and khttp_vurlpart() accept pairs of variable arguments, the first being the query string key, the second being the value. Both are char *. A NULL query string value is rendered as an empty string. khttp_urlpartx() and khttp_vurlpartx() accept triplets. In each group, the first argument is a char * giving the key. The second argument is an enum kattrx specifying the type of the third argument: KATTRX_STRING followed by a char * string (where a NULL query string value is rendered as an empty string), KATTRX_INT followed by an int64_t signed integer, or KATTRX_DOUBLE followed by a double floating-point number. If all types are KATTRX_STRING, the invocation can be shortened to khttp_urlpart().

The page, query string keys, and query string values are URL-encoded, but the path and the suffix are not.

There are two deprecated forms of these functions: kutil_urlpart() and kutil_urlpartx(). These should no longer be used.

RETURN VALUES

Return newly-allocated strings that must be freed with free(3) or NULL if allocation fails.

EXAMPLES

The following creates a relative URL with path, page, suffix, and query string parts.

url = khttp_urlpart("/path", "html", "page",
	 "foo", "bar", "baz", "xyzzy", NULL);

This will assign the following URL:

/path/page.html?foo=bar&baz=xyzzy

For typed arguments, the extended form may be used. Integer and real literals must have the int64_t and double types, respectively.

url = khttp_urlpartx("/path", "html", "page",
	 "foo", KATTRX_INT, (int64_t)0, NULL);

This assigns the following

/path/page.html?foo=0

These may be made relative to the current page by omitting the leading slash or passing NULL for the path component entirely, such as:

url1 = khttp_urlpart("rel/path", "html", "page", NULL);
url2 = khttp_urlpart(NULL, "html", "page", NULL);

These assign the following, respectively:

rel/path/page.html

page.html

Lastly, pages and their suffixes may be omitted entirely:

url3 = khttp_urlpart("", "", "", "foo", "bar", NULL);
url4 = khttp_urlpart(NULL, "", "", "foo", "bar", NULL);

These assign the following:

/?foo=bar

?foo=bar

AUTHORS

Written by Kristaps Dzonsons <kristaps@bsd.lv>.