URLMAP

Section: MidWay Programmer's Manual (3C)
Updated: DATE
Index Return to Main Contents

NAME

urlmap - Introduction to operations on an URL encoded field list

SYNOPSIS

#include <urlencode.h>

urlmap * urlmapdecode (char * list);
char * urlmapencode (urlmap * map);
int urlmapnencode (char * list, int len, urlmap * map);
void urlmapfree (urlmap * map);

int urlmapnset (urlmap * map, char * key, void * value, int len);
int urlmapset (urlmap * map, char * key, char * value);
int urlmapget (urlmap * map, char * key);

urlmap * urlmapnadd (urlmap * map, char * key, void * value, int len);
urlmap * urlmapadd (urlmap * map, char * key, char * value);
urlmap * urlmapaddi (urlmap * map, char * key, int value);
int urlmapdel (urlmap * map, char * key);

DESCRIPTION

When deciding that MidWay (7) should not have a data presentation, it was with the understanding that different applications have very diffrent need here. It would be nice however to support a simple, common way of passing data.

Some users of MidWay may choose to send C structs, but they are definitly not platform indpendent. Some may choose to use xdr or even ASN.1. More likely some may use XML, which is probably a very good idea.

HTML/HTTP has proven beyond a doubt that encoding a field list key1=value1&key2=value2 is a platform independent way of passing data. THis is formally known as MIME type application/x-url-encoded.

I came to like the HTTP URL way of encode a set of name/value pairs. It has the nice quality that you don't have to deal with fields you don't know or understand, thus eliminating any need of an IDL (interface Definition Language).

The primary reason for choosing URL encoding over XML, is that XML is not yet fully proven, and that URL is very proven. Two other reason is that XML really need a DTD, which tastes too much like a IDL.

As a side note Tuxedo(tm) has a similar library called FML (Field Manipulation Language), that DO require an IDL, and all fields must be known at compile time, and the fields are typed.

Another cool thing this way on encoding allows is nesting.

This library transforms an URL encoded list into a map. It breaks up the keys and values and unescapes nonprintable characters in the keys and values.

The urlmap structure is defines as follows:


struct urlmap{
   char * key;
   char * value;
   int valuelen;
} ;

Note that the urlmap add functions that operate on the array, may resize it by realloc().

The key and value escaping, uses % escape of all bytes containing anything other than alpha numeric. That means that the value string may contain NULL if %00 was in the list.

Note that %00 is effectivly illegal in the key in this library, so is duplicate keys.

WARNINGS

This library uses malloc() and free() to allocate the space for the map array, key and value buffers. If you assign them to fixed data or use new in C++ and call urlmapfree(), bad things will happen. Usually free causes a core dump.

EXAMPLES

for example wi have a liste like this:
firstname=Joe&lastname=Doe&age=19&address=4242%20something%20street%0aSpringfield

urlmap * map;

map = urldecode("address=4242%20something%20street%0aSpringfield");
index = urlmapget(map, "address");
printf("%*.*s", map[index].valuelen, map[index].valuelen, 
       map[index].value); 
 => 4242 something street
    Springfield
urlmapfree(map);

BUGS

NOTES

The urlencode library is not within the MidWay namespace, nor is it neccessary to include the library when compiling a MidWay client or server. It is provided since many of these functions are used in the MidWay libraries, and are used extensivly within MidWay to implement the SRB protocol.

STANDARDS

NONE

This document was created by man2html, using the manual pages.
Time: 11:18:50 GMT, October 24, 2000