NAME

Dicop::Request -- an object containing one message/request/answer

SYNOPSIS

        use Dicop::Request;
        use Dicop::Request::Pattern;

        my $pattern1 = Dicop::Request::Pattern->new( ... );
        my $pattern2 = Dicop::Request::Pattern->new( ... );

        $request = new Dicop::Request (
          id => 'req0001',
          data => 'req_0000=cmd_status;client_5',
          patterns => [ $pattern1, $pattern2, ... ],
          );

        print $request->error();        # request was ok?

REQUIRES

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

EXPORTS

Exports nothing.

DESCRIPTION

Class to represent a request. A request is both something the client sends to the server as well as the return answer from the server. A more better appropriate name would be "message".

METHODS

error

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

check

        $request->check ( $data, $validator);

Applies self-check and set error string on error.

request_id

Get/set the request's id:

        $request->request_id('req0003');        # set
        print $request->request_id();           # get and print

as_request_string

Returns the request as a compact request string that can be sent as an URL parameter to the server:

        $request->as_request_string();

This will give something like:

        req0002=cmd_status;type_main

pattern

        $request->pattern();

Return the request pattern that this request matched, or undef for none (in case of errors). See Dicop::Request::Pattern.

class

        $request->class();

Return the class of the request. The type stems from the pattern this request matches and is defined in an external textfile together with the pattern. See Dicop::Request::Pattern.

type

        $request->type();

Return the type of the request. The type stems from the pattern this request matches and is defined in an external textfile together with the pattern. See Dicop::Request::Pattern.

output

        $request->output();

Return the output type of the request. The type stems from the pattern this request matches and is defined in an external textfile together with the pattern. See Dicop::Request::Pattern.

title

        $request->title();

Return the output title for requests of output() eq 'html'. The type stems from the pattern this request matches and is defined in an external textfile together with the pattern. See Dicop::Request::Pattern.

template_name

        $request->template_name();

Return the template file that should be used for this request. The template file name stems from the pattern this request matches and is defined in an external textfile together with the pattern. See Dicop::Request::Pattern.

auth

        $request->auth();

Return a flag on whether this request needs a password or not. The flag stems from the pattern this request matches and is defined in an external textfile together with the pattern. See Dicop::Request::Pattern.

field

Set a field of the request object to another value:

        $equest->field('foo';'bar');    # set $request->{foo} to 'bar'

get_as_string

Return a field of the object as an ASCII string suitable for HTML output:

        $result->get_as_string('foo');

get_as_hex

Return a field of the object as an hexified string, or as a fallback, as normal string via get_as_string. The hexify happens only for certain special fields, all other are returned as simple strings:

        $result->get_as_hex('foo');

change

Change a field's value after checking that the field can be changed (via can_change) and checking the new value. If the new value does not conform to the expected format, it will be silently modifed (f.i. invalid characters might be removed) and then the change will happen:

        $object->change('foo','bar');   # will change $object->{foo} to bar
                                        # if foo can be changed

carry

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

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

can_change

Return true if the field's value can be changed.

        die ("Can not change field $field\n") if !$object->can_change($field);

is_form(), is_auth(), is_info(), is_request()

        if ($request->is_form())
          {
          ...
          }

Returns true if the request is of the tested type (form, auth, info or request). Returns false if the request is invalid (e.g. an error occured).

sort_order()

        my ($sort_dir, $sort_by) = $request->sort_order();

Return sort direction and the field to sort on, for example 'up','id').

BUGS

None known yet.

AUTHOR

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.

CPAN RT