/ 
Net-Doveadm-0.01-TRIAL1
River stage zero No dependents
/ Net::Doveadm

NAME

Net::Doveadm - Dovecot’s administrative interface protocol

SYNOPSIS

my $doveadm = Net::Doveadm->new(
    io => $io_object,

    # Required for authentication,
    # but we warn if the server doesn’t ask for them.
    username => $username,
    password => $password,
);

$doveadm->send(
    username => $cmd_username,
    command => [ $cmd, @args ],
);

my $result_ar;

{
    # If using non-blocking I/O …
    # $io_object->flush_write_queue();

    last if $result_ar = $doveadm->receive();

    # If using non-blocking I/O, put a select(), poll(),
    # or similar call here.

    redo;
}

DESCRIPTION

This module implements client logic for the Doveadm protocol, which facilitates administrative communication with a Dovecot server via TCP or a local socket.

I/O

This module is designed to use IO::Framed as an abstraction over the transmission medium. It is expected that most implementors will use this module; however, if so desired, a compatible interface can be substituted. In particular, the object must implement the write() and read_until() methods of that class.

If you use IO::Framed, you should not enable its allow_empty_read() mode. The Doveadm protocol is strictly RPC-oriented, which means the only successful end to a session is one that the client terminates.

Note that blocking and non-blocking I/O work nearly the same way; the SYNOPSIS above demonstrates the difference. A particular feature of this setup is that it’s possible to send multiple successive requests before reading responses to those requests.

METHODS

CLASS-new( %OPTS )

Instantiates this class. %OPTS are:

  • io - An instance of IO::Framed or a compatible interface.

  • username - The username to use in authentication. Required if the server asks for it; if given and the server does not ask for it, a warning is given.

  • password - As with username.

Note that no I/O happens in this method.

OBJ->send( %OPTS )

Send (or enqueue the sending of) a command. %OPTS are:

  • username - The username to send in the command.

  • command - An array reference whose contents are (in order) the command name and all arguments to the command.

Note that, if the server handshake is not yet complete, this will attempt to finish that before actually sending a message.

$RESULT = OBJ->receive()

Looks for a response to a previously-sent command. If such a response is ready, it will be returned as an array reference; otherwise, undef is returned.

Note that, if the server handshake is not yet complete, this will attempt to finish that before actually trying to retrieve a message.

REPOSITORY

https://github.com/FGasper/p5-Net-Doveadm

AUTHOR

Felipe Gasper (FELIPE)

COPYRIGHT

Copyright 2018 by Gasper Software Consulting

LICENSE

This distribution is released under the same license as Perl.