Xbasic

URLENCODE Function

Syntax

Output_String as C = URLENCODE(url as c [,flags as c])

Arguments

urlCharacter

A URL address. Character

flagsCharacter

Formatting flags (see examples below). Flags can be a combination of the following options:

Flag
Description
u

Use uppercase hex codes

s

Do not convert spaces

r

Do not convert legal characters: '-', '_', '.', and '~'

o

'oAuth' encoding - a special flag that is a shorthand for the combined 'sru' flags.

Returns

Output_StringCharacter

URL encoded string.

Description

URL Encodes text so that it can be safely used as part of a URL.

Discussion

URLENCODE() encodes text so that it can be safely used as Part of a URL. Many characters are not allowed within URLs so their representation must be encoded in order to use them. This function automatically handles the encoding. Many characters are not allowed within URLs, so their representation must be encoded in order to use them. URLENCODE() creates a character string by converting all illegal URL address characters in the URL_String to their escape sequences.

If you had a URL like the following, with multiple name-value pairs separated by ampersands "&", then you would have to encode each of the pairs separately.

http://zip4.usps.com/zip4/welcome.jsp?address1=3350 e marconi ave&address2=Apt 2&city=Phoenix&state=Arizona

The result would be the following.

url_to_use = urlencode("http://zip4.usps.com/zip4/welcome.jsp?address1=3350 e marconi ave") + 
"&" urlencode("address2=Apt 2") + "&" + urlencode("city=Phoenix") + "&" + urlencode("state=Arizona")

Example

Encoding an entire URL:

? urlencode("http://www.alphasoftware.com/about/default.asp")
= "http%3A%2F%2Fwww%2Ealphasoftware%2Ecom%2Fabout%2Fdefault%2Easp"

Encoding URL parameters to perform an HTTP GET request:

dim home_page as C
home_page = "/Development&Documentation/usersElarrabee/index.html"
http_get("http://www.server.com/ed.asp?home_page=" + urlencode(home_page))

Parameters to Make Signing Requests when Using oAuth Easier

The urlencode() function takes optional arguments that are useful when working with APIs that require oAuth authentication. In many APIs, the request body must be specially encoded.

Examples:

? urlencode("text-value=foo bar;")
= "text%2dvalue%3dfoo%20bar%3b"

? urlencode("text-value=foo bar;","u")
= "text%2Dvalue%3Dfoo%20bar%3B"

? urlencode("text-value=foo bar;","s")
= "text%2dvalue%3dfoo bar%3b"

? urlencode("text-value=foo bar;","r")
= "text-value%3dfoo%20bar%3b"

? urlencode("text-value=foo bar;","o")
= "text-value%3Dfoo bar%3B"

See Also