Home

| Home | Mailinglist | Download | License |

| Documentation | db/suite | db/common | db/base | db/relay | db/user | db/greylist |

qpsmtpd - Plugin db/common Documentation


NAME db/common

db/common - common methods for the database plugin suite

go top


VERSION 2007.1

go top


DESCRIPTION

This is the base class of all plugins in the database plugin suite.

All other plugins inherit methods from here to connect and close the database connection, configuration validation, SQL commands, record or notes handling and managing errors or return values etc.

go top


REQUIREMENTS

db/common requires the Perl modules

 DBI
 Data::Dumper
 Date::Format
 Mail::Header
 Qpsmtpd::Address
 Qpsmtpd::Transaction
 Sys::Hostname

It's tested with qpsmtpd 0.32, exim as local queue manager and MySQL as database.

go top


CONSTANTS

Notes

The following constants are defined for use with qpsmtpd->connection->notes, please take care when defining new ones locally. They are used in upper and lower case! Hopefully they won't interfere with other note-keys.

They are only used in this package and aren't exported. Please don't set the notes directly, better use the access methods provided by this class.

Texts

These constants are only used in this package and aren't exported.

go top


CONFIGURATION

None. And no entry in /etc/qpsmtpd/plugins for db/common.

All other database plugins must follow the basic plugin db/base - e.g.:

 db/base
 db/relay
 db/user
 db/greylist

They have all there own configuration files named /etc/qpsmtpd/db_base, /etc/qpsmtpd/db_user etc.

go top


INHERITANCE

A skeleton for a plugin using the database suite looks like this:

   # File: db/myplugin
   #
   # Please note the naming convention to inhibit config interference.
   #
   # The following expects only the line
   #
   #   myplugin_required_field = some_value
   #
   # in the config file db_myplugin.

   my %CONFIG_FIELDS = map { $_ => 1 } qw(
      myplugin_required_field
      myplugin_other_field
      myplugin_emtpy_field
   );

   my %CONFIG_FIELDS_EMPTY = map { $_ => 1 } qw(
      myplugin_emtpy_field
   );

   my %CONFIG_FIELDS_DEFAULT =
   (
      myplugin_other_field   => 42
   );

   sub init
   {
      my ( $self, $qp )   = @_;

      $self->isa_plugin ( "db/common" );

      $self->db_debug;

      $self->SUPER::init ( $qp );
   }

   sub db_init_config
   {
      my ( $self, $config_fields, $config_fields_empty, $config_fields_default )   = @_;

      %$config_fields         = %CONFIG_FIELDS;
      %$config_fields_empty   = %CONFIG_FIELDS_EMPTY;
      %$config_fields_default = %CONFIG_FIELDS_DEFAULT;
   }

   sub db_valid_config
   {
      my ( $self )   = @_;

      my $config   = $self->db_config();

      if ( $config->{myplugin_other_field} != 42 )
      {
         my $text   = "Bad param: myplugin_other_field" . $self->db_dump ( $config, '*config' );

         $self->db_die ( $text );
      }

      #   more checks...
   }

   sub hook_rcpt
   {
      #   ...
   }

   sub hook_data_post
   {
      #   ...
   }

go top


CONSTRUCTOR METHODS

init

Call: $self->init ( $qp )

Called from qpsmtpd on startup.

Loads the config for the inheriting plugin, calls db_init_config and db_check_config, stores the config items and calls db_valid_config.

On errors in db_check_config or db_valid_config qpsmtpd won't start.

go top

db_init_config

ABSTRACT

Call: $self->db_init_config ( $config_fields, $config_fields_empty, $config_fields_default )

Called from init on startup before db_check_config.

Must be overwritten to provide the local config structures. See INHERITANCE, how.

go top

db_check_config

Call: $self->db_check_config ( $config, $config_fields, $config_fields_empty, $config_fields_default )

Called from init on startup after db_init_config and before db_valid_config.

Sets defaults and checks for missing, unknown or empty config parameters.

Calls db_die on errors. Do not overwrite, use db_valid_config instead.

On errors in db_check_config or db_valid_config qpsmtpd won't start.

go top

db_valid_config

Call: $self->db_valid_config ()

Called from init on startup after db_check_config.

Does nothing and can be overwritten to provide more config checks. The config is already stored and can be fetched with

        my $config      = $self->db_config();

Please follow the policy of the database plugin suite and call db_die on config errors, so that:

On errors in db_check_config or db_valid_config qpsmtpd won't start. See INHERITANCE, how.

go top


DATABASE METHODS

db_open

Call: $self->db_open ()

Opens the database connection.

Tries to get the handle from qpsmtpd->connection->notes ( DB_DBH ).

Calls db_connect, if the handle is undef and stores the result.

Returns:

the database handleon success.
undefon error.

go top

db_connect

Call: $self->db_connect ()

Connects to the database described by the config of db/base.

Returns:

the database handleon success.
undefon error, which is logged by db_error.

go top

db_close

Call: $self->db_close ()

Closes an open database connection.

Tries to get the handle from qpsmtpd->connection->notes ( DB_DBH ) to disconnect.

Returns:

1on success.
0if connection was not open.

go top

db_sql

Call: $self->db_sql ( $sql [, %param ] )

Executes the SQL statement given in $sql.

Returns:

undefif not connected to a database and on all SQL errors.
the statement resultif $param{no_fetch} is given.
all rows as possibly empty reference to an array of references to hashesif $param{all} is given.
first record as possibly emtpy reference to a hashotherwise.

Errors are logged by db_error.

go top


ACCESSOR METHODS

db_config

Call: $self->db_config ( [ $key [, $value ] ] )

Accessor for the config hash stored as object attribute.

Stores the new value if $value are given.

Returns:

a reference to the config hashif no $key is given.
the stored valueif $key is given.

go top

db_rec

Call: $self->db_rec ( [ $record ] )

Accessor for the current user hash stored in qpsmtpd->connection->notes ( DB_REC ).

Stores the new hash if $record is given.

Returns:

a reference to the old hashif no $record is given.
the new hashif $record is given.

go top

db_deferred

Call: $self->db_deferred ( [ $value ] )

Accessor for the data stored in qpsmtpd->connection->notes ( DB_DEFERRED ) separated by $self-plugin_name()>.

Calls db_notes.

go top

db_notify

db_last_error

Call: $self->db_notify ( [ $value ] )

Call: $self->db_last_error ( [ $value ] )

Accessors for the data stored in qpsmtpd->connection->notes ( DB_DEFERRED | DB_NOTIFY | DB_LAST_ERROR ).

Calls db_notes.

go top

db_notes

Call: $self->db_notes ( $key [, $value ] )

Accessor for the data stored in qpsmtpd->connection->notes ( $key ).

Stores the new value if $value are given.

Returns:

the value if $key is given.

go top


LOGGING METHODS

db_debug

Call: $self->db_debug ( [ @text ] )

Creates a line like --- caller-subname: @text

Calls Qpsmtpd::Plugin::log with the line as LOGDEBUG.

go top

db_error

Call: $self->db_error ( [ @text ] )

Creates a line like PLUGIN ERROR: Qpsmtpd::Plugin::plugin_name: @text. Uses DB_ERROR, if @text is empty.

Calls Qpsmtpd::Plugin::log with the line as LOGCRIT.

Stores the line calling db_last_error.

go top

db_log

Call: $self->db_log ( [ @text ] )

Creates a line like Plugin Qpsmtpd::Plugin::plugin_name: @text

Calls Qpsmtpd::Plugin::log with the line as LOGINFO.

go top


RETURNING METHODS

db_declined

Call: $self->db_declined ( [ $msg ] )

Returns: DECLINED along with the optional $msg.

go top

db_deny

Call: $self->db_deny ( [ $msg ] )

Returns: DENY along with the optional $msg.

go top

db_denysoft

Call: $self->db_denysoft ( [ $msg ] )

Returns: DENYSOFT along with the optional $msg or DB_LATER.

go top

db_denysoft_error

Call: $self->db_denysoft_error ( [ $msg ] )

Returns: DENYSOFT along with the optional $msg or DB_LATER.

If the call to db_notify returns an entry for notify_email, this notify address is sent an email with the error message stored in db_last_error using hook_queue.

go top


HELPER METHODS

db_die

Call: $self->db_die ( [ $msg ] )

Calls db_error and dies with the optional $msg or DB_ERROR.

go top

db_complete_field_names

Call: $self->db_complete_field_names ( $record, $table )

Prefixes all keys of $record with the $table..

Returns: a reference to a new hash.

E.g.:

        my $record     = { 'field1' => 'value1', 'field2' => 2 };
        my $new_record = $self->db_complete_field_names ( $record, 'mytable' );

        # $new_record now looks like { 'mytable.field1' => 'value1', 'mytable.field2' => 2 }
go top

db_raw_field_names

Call: $self->db_raw_field_names ( $record, $table )

Removes the prefix $table. from all keys of $record.

Returns: a reference to a new hash.

E.g.:

        my $record     = { 'mytable.field1' => 'value1', 'othertable.field2' => 2 }
        my $new_record = $self->db_raw_field_names ( $record, 'mytable' );

        # $new_record now looks like { 'field1' => 'value1', 'othertable.field2' => 2 }
go top

db_valid_email

Call: $self->db_valid_email ( $email_adr )

Checks, if $email_adr is wellformed.

Returns: (three-state)

0if $email_adr is uncomplete or contains spaces.
-1if $email_adr contains dangerous chars.
1on success.

go top

db_dump

Call: $self->db_dump ( $values [, @names ] )

Returns: a text created by a Data::Dumper object using the params.

It uses the symbol substitution provided by Data::Dumper.

Calling examples:

        my $text = $self->db_dump ( $config, qw( *config ) );

        # gives:
        #
        # %config = (
        #             'email_address' => undef,
        #             'email_enabled' => 'is_enabled',
        #             'email_table' => 'emailtable',
        #             'email_user' => 'local_part',
        #             'domain_domain' => 'domain',
        #             'email_domain' => 'domain',
        #             'email_enabled_value' => 'yes',
        #             'domain_table' => 'emailtable'
        #           );

        my $text = $self->db_dump
                    (
                       [ $user, $host, $delivery, $config ],
                       qw( user host delivery *config )
                    );

        # gives:
        #
        # $user = 'ernesto';
        # $host = 'dienstleistung-kultur.de';
        # $delivery = 'ernesto@dienstleistung-kultur.de';
        # %config = ( same as above... )

go top


HOOKS None

go top


CREDITS

Thanks to Ask Bjoern Hansen for qpsmtpd.

http://smtpd.develooper.com/

go top


COPYRIGHT

(c) Ernesto 2007, ernesto@dienstleistung-kultur.de

http://dienstleistung-kultur.de/qpsmtpd/

go top


LICENCE

As per the qpsmtpd license.

go top


This is a service of dienstleistung-kultur.de            Mailsystem QPSMTPD            Comments to Ernesto at ernesto@dienstleistung-kultur.de            Impressum