Sometimes it is necessary to insert in a Web page content that resides on a remote server accessible only via the HTTP protocol. The Exec method of the httpPage class allows to "execute" a HTTP page described by an object of the httpPage class and can be used to send to a remote server a request for an Internet resource (a HTML page, an image, a movie, or anything else). This method has the following prototype:

httpPage Exec(string server, int port=80)
     

The server parameter specifies the server name (including the domain name) or the IP address of the server where the page we want to execute resides. The port parameter indicates the port to be used (the default value is 80). The method returns an object of the httpPage class containing the server response, i.e. the requested page in case of success.

For exemplification purposes we will now show how to implement a simple function that executes a page request to a remote server and returns a string containing the body of the server response page.

<?
	function string ExecRemote(string site_address, string resource_path)
	{
		http_header = header("GET " + resource_path + " HTTP/1.1")
		page_request = httpPage(http_header, "")
		page_response = page_request.Exec(site_address)
		
		return page_response.body
	}
?>
     

The ExecRemote function takes two strings as parameters, containing the site address and the path of the page that should be requested. The latter must always start with the / (slash) character, i.e. must be relative to the site root. Within the function a header class object is created by passing a string consisting of a request (the actual header is empty) to the class constructor. The request consists in the GET method followed by the path of the page and protocol version. On the next line an object of the httpPage class is created by passing the newly created header and an empty body to the class constructor. Then the Exec method is called on the object we just created using the site address as parameter. The function returns the body of the server response page resulting from the call to the Exec method.

An invocation of the ExecRemote function looks like the following:

<?
	result = ExecRemote("www.tabasoft.it", "/home.bfr")
?>
     

The use of this function can be very useful in practice when we have to insert content (news, search forms, marketing polls) originating from another Web site in a box on the home page of our Web site and we do not want to use frames or inline frames (the latter are not supported by all browsers). In this case the script that implements our home page can execute the remote page of interest and incorporate the result (typically HTML code) in our page. Another scenario is a site distributed across multiple remote machines. In this case the ExecRemote function is a very useful tool to exploit resources on remote computers.

The request static class allows to obtain information on the request for a Biferno script (a page with ".bfr" extension) submitted to the server.

Properties of this class allow to gather information about the requested file name (filename property), its path relative to the server or site root (filePath property), and its absolute path on disk (physicalPath property).

The physicalPath property actually contains the page path as requested by the client, which may contain unresolved aliases.

To obtain the physical page path the ResolvePath method of the file class should be used, or the curFile.basePath predefined method (no parameters) should be called (which returns the absolute path of the directory where the current script resides) and the fileName property of the request class should be appended to the string returned.

<?
	scriptPath = file.ResolvePath(request.physicalPath)
	// alternatively
	scriptPath = curFile.basePath + request.fileName
?>
     

Notice that the second expression in the above example may not return the correct result if the script has been inserted into another script using the include instruction, because the latter modifies the script's basePath, but leaves the request untouched.

Other useful properties of the request class are:

Using the request class it is also possible to access fields in the HTTP header using the GetField method, which works in a way similar to the header class method with the same name, except for the fact that it has no index parameter. In practice, the request class replicates some of the functionality of the header class. If we want to access the content of the "Host" field of the HTTP header, we can use either of the following expressions, which are perfectly equivalent:

<?
	host = request.GetField("Host")
	host = pageIn.head.GetField("Host")
?>
     

Another important functionality supported by the request class is offered by the Redirect method, which allows to redirect the request to a page other than the one currently executed. The prototype of the method is:

static string Redirect(string url)
     

The url parameter specifies the path of the page that should be requested and can either be a path relative to the current script, or a path relative to the server or site root, or a complete URL. This is shown in the following script:

<?
	request.Redirect("home.bfr")
	request.Redirect("/mysite/home.bfr")
	request.Redirect("http://www.mysite.com/home.bfr ")
?>
     

Passing a complete URL to the Redirect method the request can be redirected to a page that resides on a remote server.

The client static class allows to obtain information about the client, i.e. the user that requested a page with ".bfr" extension to the server.

By querying properties of this class it is possible to acquire the IP address of the machine that originated the connection request (ipAddress property), username and password of the user when protected areas are accessed (user and password properties), and the type of browser used for the connection (userAgent property). In the example that follows we send in output the string identifying the browser that is being used to display the result of script processing, which is contained in the userAgent property.

<?
	$client.userAgent
?>
     

The result is a string with content and format similar to the following: "Mozilla/4.0 (compatible; MSIE 5.0; Mac_PowerPC)".

Other properties of the client class are address, which in most cases has the same value as ipAddress, and fromUser, which contains the email address of the user originating the request (if sent by the client).

We will see in Chapter 21, Access Control the use of the user and password properties for the authentication of users when accessing protected applications.

Cookies are a general technique to allow a server-side application (e.g. Biferno) to store and retrieve information on the client side of the connection.

To send a cookie to the client the server side application adds one or more fields of the "Set-Cookie" type to the HTTP header of the response page resulting from processing the client request, followed by the relative attributes (typically name, value and expiration date). When the client application, i.e. the Web browser, receives the server answer, it extracts cookie-related data from the header and stores it on the client machine. With every following connection request to the same server, the client sends the stored cookies in "Cookie" type fields in the request header. Individual cookies are always sent back to the server that originated them and not to other servers.

From a practical point of view, cookies are a possible solutions to the problem of loss of state for Internet connections. Using cookies it is possible, within certain limitations, to store information on the client side in a persistent fashion and therefore to share state across multiple connections.

Cookies have many applications. The typical case is demonstrated by those sites that allow users to personalize pages by choosing e.g. the colors used for display, or the kind of content to be included. Another use of cookies is to store information about the user to avoid the inconvenience of submitting the same information again and again with every connection request. This technique is used by sites requiring a login to access certain areas or using virtual shopping carts for online shopping.

Biferno implements the mechanism of session variables to maintain state, and session variable use cookies to identify single sessions. It is important to notice that the use of session variables, regardless of their number, requires sending a single cookie (session identifier, actually two cookies if counting the checksum performed by Biferno to avoid cookie tampering), while variable values, different for each session, are always stored on the server. Using session variables is less intrusive from the client point of view than simply using cookies, because all data is stored on the server and only the session identifier (SID) is stored on the client.

As mentioned above, methods of the header class can be used to send cookies to the client and to read cookies returned by the server. A first example shows how to set a simple cookie specifying only its name and its value:

<?
	pageOut.head.AddField("Set-Cookie", "user=john")
?>
     

The one code line above adds to the HTTP header of the page sent as reply, stored in the head property of the pageOut global variable, a "Set-Cookie" field containing the string "user=john", where "user" is the name of the cookie we are setting, and "john" is its value. If the string defining the cookie value contains the characters comma, colon or space it is advisable, but not mandatory, to encode the string using the "UrlEncode" format.

The cookie format specification allows other optional attributes beyond the mandatory "name=value" pair that are appended to the content string and separated by a ";" character. To fully understand the meaning of these attributes let's realize a generic function to set a cookie that takes as parameters all attributes allowed by the cookie format specification.

<?
	function void	SetCookie(string name, string value, 
		string expireTime, string domain, string path, boolean secure)
	{
		if (!name)
			return
		
		content = name + "=" + value
		if (expireTime)
			content += "; expires=" + expireTime
		if (domain)
			content += "; domain=" + domain
		if (path)
			content += "; path=" + path
		if (secure)
			content += "; secure"

		global pageOut.head.AddField("Set-Cookie", content)
	}
?>
     

The name and value parameters correspond to the mandatory attribute "name=value". If no value is supplied corresponding to the name parameter the SetCookie function does not send a cookie.

The expireTime parameter specifies the expiration date for the cookie. After this date the cookie is removed from the client machine and no longer sent to the originating server. The string representing the expiration date has to be relative to the Greenwich mean time and expressed in the Universal Time format discussed in Chapter 14, Date and Time Functionality while illustrating the time class. The expiration date is an optional attribute. If an expiration date is not specified, the cookie is deemed to be a temporary cookie and is removed when the user session ends, i.e. when the client browser application is terminated.

The domain parameter specifies the domain or domain class where the cookie will be visible (e.g. "acme.com", "www.tabasoft.it"). Only hosts in the specified domain can receive the cookie. If the domain is not explicitly specified, the domain of the server that generated the HTTP reply is considered valid. Normally the server IP address is specified. The path parameter specifies the path (or initial path portion) within the validity domain identifying the set of Web pages (or scripts) that can receive the cookie. When a HTTP request has to be answered, if the cookie has already passed the domain check, then the URL of the page requested to the server is compared with this value. In case of a match the cookie is considered valid and is sent. If the path parameter is not specified, the path corresponding to the page requested to the server is considered valid.

The secure boolean parameter specifies if the corresponding clause should be added to the cookie. A cookie containing the secure clause is valid only if the communication channel to the server is a secure channel. At the time of this writing, this means that a secure cookie is only sent to a server that supports HTTPS (HTTP over SSL). The following script shows some examples of the use of the SetCookie function implemented in the example above.

<?
	// Setting a temporary cookie
	SetCookie("test_cookie", "test")

	// Setting a cookie with an expiration date
	expireTime = time("1-11-2001")
	SetCookie("test_cookie", "test", expireTime.GMT().UString())

	// Setting a cookie expiring after two hours
	expireTime = time()
	expireTime.hour += 2
	SetCookie("test_cookie", "test", expireTime.GMT().UString())
?>
     

Let's now see how to read information contained in the cookies sent from the client to the server. The following script reads cookie values from the HTTP header (if present) and stores them into the elements of an associative array, assigning the cookie names to the corresponding indices.

<?
	function array GetCookies(void)
	{
		arr_cookies = array()
		
		cookies = global pageIn.head.GetField("Cookie")
		if (cookies)
			{
				arr1 = cookies.ToArray("; ")
				ncookies = arr1.dim
				for (i = 1; i <= ncookies; i++)
					{
						arr2 = arr1[i].ToArray("=")
						arr_cookies.Add(arr2[2])
						arr_cookies.name[i] = arr2[1]
					}
			}
			
		return arr_cookies
	}
?>
     

If we want to use the GetCookies function to acquire the value of a certain cookie we can proceed as follows:

<?
	cookiesArray = GetCookies()
	cookieName = "test_cookie"
	if (i = cookiesArray.Index(cookieName))
		cookieValue = cookiesArray[i]
?>
     

Using the Index method of the array class we check if the cookiesArray array returned from the GetCookies function has an element with an index matching the name of the target cookie and, if this is the case, its value is assigned to the cookieValue variable.