Net::Doveadm - Dovecot’s administrative interface protocol
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,
username => $cmd_username,
command => [ $cmd, @args ],
# If using non-blocking I/O …
last if $result_ar = $doveadm->receive();
# If using non-blocking I/O, put a select(), poll(),
# or similar call here.
This module implements client logic for the Doveadm protocol, which facilitates administrative communication with a Dovecot server via TCP or a local socket.
Note that this is the original Doveadm protocol, not the newer, HTTP-based one.
This module is designed, rather than to interact directly with a socket or other filehandle, to use IO::Framed as an abstraction over the transmission medium. If so desired, a compatible interface can be substituted for IO::Framed; in particular, the interface must implement IO::Framed’s write() and read_until() methods.
If you use IO::Framed, you should not enable its allow_empty_read() mode. The Doveadm protocol is strictly RPC-oriented, and 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.
All errors that this module throws are instances of Net::Doveadm::X::Base. At this time, further details are subject to change.
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.
Send (or enqueue the sending of) a command. %OPTS are:
command - An array reference whose contents are (in order) the command name and all arguments to the command. Note that some calls, e.g., mailbox list, are “compound commands” rather than a command with argument.
username - Optional, the username to send with the command.
verbosity - Optional, either 1 (“verbose”) or 2 (“debug”).
Note that, if the server handshake is not yet complete, this will attempt to finish that before actually sending a message.
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.
Felipe Gasper (FELIPE)
Copyright 2018 by Gasper Software Consulting
This distribution is released under the same license as Perl.
To install Net::Doveadm, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.