Dicop::Request::Pattern -- an object containing one request pattern

	use Dicop::Request::Pattern

	push @patterns, Dicop::Request::Pattern->new (
		match => 'cmd_status;type_main',
		req => 'id',
		opt => 'style',
		output => 'html',
		type => 'status',
		tpl => 'main.txt',
		auth => 0,
		class => 'admin',
		throw => 'error message',
	);

	# automatically checks the new Request against all the patterns
	# and selects the one fitting it (or generates an error in the
	# Request)
	$request = new Dicop::Request (
          id => 'req0001',
          data => 'req_0000=cmd_status;type_main',
	  patterns => \@patterns,
          );

	if ($request->error() ne '')
	  {
	  # error, no pattern matched
	  die ($request->error());
	  }

	  print "The request '", $request->as_request_string(), "' is valid.\n";
	  print "We should output ", $match->output($request), " with the title '",
		$match->title($request),"'\n";
	  print "We should read the template ", $match->template($request), "\n";
	  }

perl5.8, Dicop::Base, Dicop::Item, Dicop::Event

Exports nothing.

Class to represent a pattern that represents a valid request. All requests can be checked against this pattern to determine whether they are valid or not. In praxis a list of all valid patterns would be maintained and each request checked against each pattern.

A request in Dicop is simple a message passed between machines like the server, clients or a proxy.

Pattern descriptions are stored in a flat file in text format and are read by the code at startup.

	{
	match = "cmd_status;type_test"
	nonempty = "start end description jobtype charset"
	req = "id"
	opt = "style"
	output = "html"
	tpl = "test.txt"
	title = "Test Status Page"
	type = "status"
	class = "status"
	auth = 1
	}

Below follows a detailed description on the possible pattern properties and their meaning:

match

	match = "cmd_status;type_test"

The patterns is valid for all requests that match this pattern. The order is not important, so type_test;cmd_status would work as well. All params must match exactly - otherwise the request pattern doesn't match this request. It is possible to enter regular expressions for the values, e.g.

	match = "cmd_status;type_/^(test|work)$"

Note the closing "/" is missing and the regexp must come last.

nonempty

	nonempty = "start end description jobtype charset"

These params must be non-empty (and also present). Default is "".

req

	req = "id"

These params must be present, but can be empty unless they are listed in nonempty. Default is "". Any params in 'match' and "nonempty" are automatically added to 'required' so you don't need to list them twice.

opt

	opt = "style"

These params are optional (and can be empty if they are not listed in nonempty). Default is "style". If you don't want "style" to be optional, set opt = "".

output

	output = "html-table"

The type of output sent when this pattern matches. Valid are "html", "html-table" or "text". Default is "html".

tpl

	tpl = "test.txt"

Name of the template file to reply if this pattern matches. Optional and only neccessary if type = "html" or "html-table". If left empty, and type is "html", the vaue will be "TYPE.tpl" where TYPE is the value of the type-param of the request, e.g. for cmd_status;type_test it would be "test". This if course works only if "type" is an allowed, nonempty param.

title

	title = "Test Status Page"

The title string, only necc. if output is "html" or "html-table".

type

	type = "status"

The type of the request. Types: "status", "info", "auth", "request", "other". Default is "status". This is used to keep statistics about request types.

class

	class = "status"

The class of the request. This is used to deny/allow requests based on IPs and nets. Other then that, the class is not used. Possible are "admin", "stats", "status" and "work". Default is "admin".

auth

	auth = 1

Set this to 1 to require user authentication (e.g. password and username) for this request.

sort

	sort = "down"

The sort oder for output "html-table". Possible are "up", "upstr", "down" and "downstr". The default is "up". The variants "upstr" and "downstr" sort strings, while "up" and "down" are for numerical fields.

See also sort_by.

sort_by

    	sort_by = "id"

Which field to sort the output by. Default is "id", and can be any field of the objects to list. Only works for output of "html-table" or if the output contains a list of objects. See also sort.

carry

	carry = "job_id"

List of fields that need to be carried over for forms. These will be added as hidden params to the form.

throw

	throw = "some error message"

If this request matched without an error, throw this error message and bail out. Used to catch specific forbidden requests.

Get/set error message. Returns empty string in case of no error.

	($match, $error) = $pattern->check ( $request );

Check the given request of whether it matches this pattern (with or without error) or not. Will return $match = undef for no match, and $match = $pattern for a match. Upon $match beeing equal to $pattern, $error will indicate whether there was an error or not.

	$output_type = $pattern->output($request);

Returns the defined output for the request matching this pattern, or the empty string for none.

	$tpl = $pattern->template_name();

Returns the defined name of the template for this pattern, or the empty string for none. This will only be set if output_type() equals 'html'.

	$type = $pattern->type($request);

Returns the type of the request matching this pattern.

	$title = $pattern->title($request);

Returns the title of the request matching this pattern.

	($sort_order, $sort_by) = $pattern->sort_order();

Return the sort order ('up', or 'down') and the name of the field to sort on. The default is ('up', 'id').

	$auth = $pattern->auth();

Returns a flag indicating whether we need user authentication (e.g. pwd and username) for matching requests or not.

	$class = $pattern->class();

Returns the class of the request matching this pattern.

        my $carry = $pattern->carry();

Return a list of fields that the form must include to carry over.

None known yet.

(c) Bundesamt fuer Sicherheit in der Informationstechnik 1998-2008

DiCoP is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

See http://www.bsi.de/ for more information.