NAME

Mail::Postfix::Attr - encode and decode Postfix attributes

VERSION

version 0.06

SYNOPSIS

  use Mail::Postfix::Attr;

  my $pf_attr = Mail::Postfix::Attr->new( 'codec' => '0',
                                          'path' => '/tmp/postfix_sock' );


  my $pf_attr = Mail::Postfix::Attr->new( 'codec' => 'plain',
                                          'inet' => 'localhost:9999' );

  my @result_attrs = $pf_attr->send( 'foo' => 4, 'bar' => 'blah' );

  my $attr_text = $pf_attr->encode( 'foo' => 4, 'bar' => 'blah' );

  my @attrs = $pf_attr->decode( $attr_text );

DESCRIPTION

Mail::Postfix::Attr supports encoding and decoding of the three formats of attributes used in the postfix MTA. Attributes are used by postfix to communicate with various of its services such as the verify program. These formats are:

  plain - key=value\n   (a collection of attributes has an \n appended)
  0     - key\0value\0  (a collection of attributes has a \0 appended)
  64    - base64(key):base64(value)\n
                        (a collection of attributes has an \n appended)

These formats are from the specifications in the postfix source files in the src/util directory:

  attr_scan0.c
  attr_scan64.c
  attr_scan_plain.c
  attr_print0.c
  attr_print64.c
  attr_print_plain.c    

If you run 'make test' (after building postfix) in this directory it will build these programs which can be used to test this Perl module:

  attr_scan0
  attr_scan64
  attr_scan_plain
  attr_print0
  attr_print64
  attr_print_plain

For example...

  # talk to the verify(8) service available in Postfix v2.
  # 
  # perl -MMail::Postfix::Attr -le 'print for Mail::Postfix::Attr
           ->new (codec=>0, path=>"/var/spool/postfix/private/verify")
           ->send(request=>query=>address=>shift)'
          postmaster@localhost

  status
  0
  recipient_status
  0
  reason
  aliased to root

METHODS

new

        my $pf_attr = Mail::Postfix::Attr->new( 'codec' => '0',
                                          'path' => '/tmp/postfix_sock' );

The new method takes a list of key/value arguments.

        codec   => <codec_type>
        path    => <unix_socket_path>
        inet    => <host:port>

        codec_type is one of '0', '64' or 'plain'. It defaults to
        'plain' if not set or it is not in the allowed codec set.

        The <unix_socket_path> argument is the unix domain socket that
        will be used to send a message to a postfix service. The
        message will be encoded and its response decoded with the
        selected codec.

        The <inet> argument is the internet domain address that will
        be used to send a message to a postfix service. It must be in
        the form of "host:port" where host can be a hostname or IP
        address and port can be a number or a name in
        /etc/services. The message will be encoded and its response
        decoded with the selected codec.

send

The send method is passed a list of postfix attribute key/value pairs. It first connects to a postfix service using the UNIX or INET socket. It then encodes the attributes using the selected codec and writes that data to the socket. It then reads from the socket to EOF and decodes that data with the codec and returns that list of attribute key/value pairs to the caller.

  my @result_attrs = $pf_attr->send( 'foo' => 4, 'bar' => 'blah' );

encode

The encode method takes a list of key/values and encodes it according to the selected codec. It returns a single string which has the encoded text of the attribute/value pairs. Each call will create a single attribute section which is terminated by an extra separator char.

  my $attr_text = $pf_attr->encode( 'foo' => 4, 'bar' => 'blah' );

You can also call each encoder directly as a class method:

  my $attr_text = Mail::Postfix::Attr->encode_0( 'foo' => 4, 'bar' => 'blah' );
  my $attr_text = Mail::Postfix::Attr->encode_64( 'foo' => 4, 'bar' => 'blah' );
  my $attr_text = Mail::Postfix::Attr->encode_plain( 'foo' => 4, 'bar' => 'blah' );

decode

The decode method takes a single string of encoded attributes and decodes it into a list of attribute sections. Each section is decoded into a list of attribute/value pairs. It returns a list of array references, each of which has the attribute/value pairs of one attribute section.

  my @attrs = $pf_attr->decode( $attr_text );

You can also call each decoder directly as a class method:

  my @attrs = Mail::Postfix::Attr->decode_0( $attr_text );
  my @attrs = Mail::Postfix::Attr->decode_64( $attr_text );
  my @attrs = Mail::Postfix::Attr->decode_plain( $attr_text );

AUTHOR

Uri Guttman <uri@stemsystems.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2002 by Uri Guttman.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Mail::Postfix::Attr

perl -MCPAN -e shell
install Mail::Postfix::Attr