| Home | Mailinglist | Download | License |
| Documentation | db/suite | db/common | db/base | db/relay | db/user | db/greylist |
db/common - common methods for the database plugin suite
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.
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.
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.
hook_rcpt until hook_data_post''.
See db_deferred.
These constants are only used in this package and aren't exported.
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.
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
{
# ...
}
Call: $self->init ( $qp )
$qpCalled 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
ABSTRACT
Call: $self->db_init_config ( $config_fields, $config_fields_empty, $config_fields_default )
$config_fields, $config_fields_empty, $config_fields_defaultCalled from init on startup before db_check_config.
Must be overwritten to provide the local config structures. See INHERITANCE, how.
go top
Call: $self->db_check_config ( $config, $config_fields, $config_fields_empty, $config_fields_default )
$config$config_fields, $config_fields_empty, $config_fields_defaultCalled 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
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.
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 handle | on success. |
undef | on error. |
Call: $self->db_connect ()
Connects to the database described by the config of db/base.
Returns:
| the database handle | on success. |
undef | on error, which is logged by db_error. |
Call: $self->db_close ()
Closes an open database connection.
Tries to get the handle from qpsmtpd->connection->notes ( DB_DBH ) to disconnect.
Returns:
| 1 | on success. |
| 0 | if connection was not open. |
Call: $self->db_sql ( $sql [, %param ] )
$sql%paramExecutes the SQL statement given in $sql.
Returns:
undef | if not connected to a database and on all SQL errors. |
| the statement result | if $param{no_fetch} is given.
|
| all rows as possibly empty reference to an array of references to hashes | if $param{all} is given.
|
| first record as possibly emtpy reference to a hash | otherwise. |
Errors are logged by db_error.
Call: $self->db_config ( [ $key [, $value ] ] )
$key$valueAccessor for the config hash stored as object attribute.
Stores the new value if $value are given.
Returns:
| a reference to the config hash | if no $key is given.
|
| the stored value | if $key is given. |
Call: $self->db_rec ( [ $record ] )
$recordAccessor 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 hash | if no $record is given.
|
| the new hash | if $record is given. |
Call: $self->db_deferred ( [ $value ] )
$valueAccessor for the data stored in qpsmtpd->connection->notes
( DB_DEFERRED ) separated by $self-plugin_name()>.
Calls db_notes.
go top
Call: $self->db_notify ( [ $value ] )
Call: $self->db_last_error ( [ $value ] )
$valueAccessors for the data stored in qpsmtpd->connection->notes
( DB_DEFERRED | DB_NOTIFY | DB_LAST_ERROR ).
Calls db_notes.
go top
Call: $self->db_notes ( $key [, $value ] )
$key$valueAccessor for the data stored in qpsmtpd->connection->notes ( $key ).
Stores the new value if $value are given.
Returns:
the value if $key is given.
Call: $self->db_debug ( [ @text ] )
@textCreates a line like --- caller-subname: @text
Calls Qpsmtpd::Plugin::log with the line as LOGDEBUG.
Call: $self->db_error ( [ @text ] )
@textCreates 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
Call: $self->db_log ( [ @text ] )
@textCreates a line like Plugin Qpsmtpd::Plugin::plugin_name: @text
Calls Qpsmtpd::Plugin::log with the line as LOGINFO.
Call: $self->db_declined ( [ $msg ] )
$msgReturns: DECLINED along with the optional $msg.
Call: $self->db_deny ( [ $msg ] )
$msgReturns: DENY along with the optional $msg.
Call: $self->db_denysoft ( [ $msg ] )
$msgReturns: DENYSOFT along with the optional $msg
or DB_LATER.
Call: $self->db_denysoft_error ( [ $msg ] )
$msgReturns: 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.
Call: $self->db_die ( [ $msg ] )
$msgCalls db_error and dies with the optional $msg
or DB_ERROR.
Call: $self->db_complete_field_names ( $record, $table )
$record$tablePrefixes 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
Call: $self->db_raw_field_names ( $record, $table )
$record$tableRemoves 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
Call: $self->db_valid_email ( $email_adr )
$email_adrChecks, if $email_adr is wellformed.
Returns: (three-state)
| 0 | if $email_adr is uncomplete or contains spaces.
|
| -1 | if $email_adr contains dangerous chars.
|
| 1 | on success. |
Call: $self->db_dump ( $values [, @names ] )
$values@namesReturns: 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... )
Thanks to Ask Bjoern Hansen for qpsmtpd.
(c) Ernesto 2007, ernesto@dienstleistung-kultur.de
http://dienstleistung-kultur.de/qpsmtpd/
As per the qpsmtpd license.