/ 
Net-Doveadm-0.01
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.

Note that this is the original Doveadm protocol, not the newer, HTTP-based one.

I/O

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.

ERRORS

All errors that this module throws are instances of Net::Doveadm::X::Base. At this time, further details are subject to change.

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:

  • 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.

$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.