webgui/lib/WebGUI/HTTP.pm

package WebGUI::HTTP;

=head1 LEGAL

 -------------------------------------------------------------------
  WebGUI is Copyright 2001-2004 Plain Black Corporation.
 -------------------------------------------------------------------
  Please read the legal notices (docs/legal.txt) and the license
  (docs/license.txt) that came with this distribution before using
  this software.
 -------------------------------------------------------------------
  http://www.plainblack.com                     info@plainblack.com
 -------------------------------------------------------------------

=cut


use strict;
use WebGUI::International;
use WebGUI::Session;

=head1 NAME

Package WebGUI::HTTP

=head1 DESCRIPTION

This package allows the manipulation of HTTP protocol information.

=head1 SYNOPSIS

use WebGUI::HTTP;
 $header = WebGUI::HTTP::getHeader();
 WebGUI::HTTP::setRedirect($url);
 WebGUI::HTTP::setCookie($name,$value);
 WebGUI::HTTP::setNoHeader($bool);
 
=head1 METHODS

These subroutines are available from this package:

=cut



#-------------------------------------------------------------------

=head2 getHeader ( ) 

Generates an HTTP header.

=cut

sub getHeader {
	return undef if ($session{http}{noHeader});	
	my $header;
	unless (exists $session{http}{location}) {
		unless ($session{http}{charset}) {
			$session{http}{charset} = WebGUI::International::getLanguage($session{page}{languageId},"charset") || "ISO-8859-1";
		}
		unless ($session{http}{mimetype}) {
			$session{http}{mimetype} = "text/html";
		}
		if ($session{setting}{preventProxyCache}) {
       	        	$session{http}{expires} = "-1d";
       	 	}
		$header = $session{cgi}->header( 
			-type => $session{http}{mimetype},
			-charset => $session{http}{charset},
			-cookie => $session{http}{cookie}, 
			-status => $session{http}{status},
			-attachment => $session{http}{filename},
			-expires => $session{http}{expires}
			);
	} else {
		$header = $session{cgi}->header( 
			-cookie => $session{http}{cookie}, 
			-location => $session{http}{location},
			-status => $session{http}{status}
			);
	}
	return $header;
}


#-------------------------------------------------------------------

=head2 getMimeType ( ) 

Returns the current mime type of the document to be returned.

=cut

sub getMimeType {
	return $session{http}{mimetype} || "text/html";
}


#-------------------------------------------------------------------

=head2 getStatus ( ) {

Returns the current HTTP status code, if one has been set.

=cut

sub getStatus {
	return $session{http}{status} || "200 OK";
}


#-------------------------------------------------------------------

=head2 setCookie ( name, value [ , timeToLive ] ) 

Sends a cookie to the browser.

=head3 name

The name of the cookie to set. Must be unique from all other cookies from this domain or it will overwrite that cookie.

=head3 value

The value to set.

=head3 timeToLive

The time that the cookie should remain in the browser. Defaults to "+10y" (10 years from now).

=cut

sub setCookie {
        my $ttl = $_[2] || '+10y';
	my $domain;
        push @{$session{http}{cookie}}, $session{cgi}->cookie(
                -name=>$_[0],
                -value=>$_[1],
                -expires=>$ttl,
                -path=>'/',
                -domain=>$domain
                );
}


#-------------------------------------------------------------------

=head2 setFilename ( filename [, mimetype] )

Override the default filename for the document, which is usually the page url. Usually used with setMimeType().

=head3 filename

The filename to set.

=head3 mimetype

The mimetype for this file. Defaults to "application/octet-stream".

=cut

sub setFilename {
	$session{http}{filename} = shift;
	my $mimetype = shift || "application/octet-stream";
	setMimeType($mimetype);
}



#-------------------------------------------------------------------

=head2 setMimeType ( mimetype )

Override mime type for the document, which is defaultly "text/html". Also see setFilename().

B<NOTE:> By setting the mime type to something other than "text/html" WebGUI will automatically not process the normal page contents. Instead it will return only the content of your Wobject function or Operation.

=head3 mimetype

The mime type for the document.

=cut

sub setMimeType {
	$session{http}{mimetype} = shift;
}

#-------------------------------------------------------------------

=head2 setNoHeader ( boolean )

Disables the printing of a HTTP header. Useful in situations when content is not
returned to a browser (export to disk for example).

=head3 boolean 

Any value other than 0 will disable header printing.

=cut

sub setNoHeader {
        $session{http}{noHeader} = shift;
}

#-------------------------------------------------------------------

=head2 setRedirect ( url )

Sets the necessary information in the HTTP header to redirect to another URL.

=head3 url

The URL to redirect to.

=cut

sub setRedirect {
	$session{http}{location} = shift;
	setStatus("302 Redirect");
}


#-------------------------------------------------------------------

=head2 setStatus ( status )

Sets the HTTP status code.

=head3 status

An HTTP status code. It takes the form of "NNN Message" where NNN is a 3 digit status number and Message is some text explaining the status number.

=cut

sub setStatus {
	$session{http}{status} = shift;
}

1;