view release on metacpan or  search on metacpan

lib/IMAP/Client.pm  view on Meta::CPAN

########## rfc2177 (IMAP4 IDLE) command ##########

=pod

=item B<idle(FIXME)>

Issue IDLE command, currently unimplemented.

=cut

sub idle {
    # This function is a little different, since instead of accumulating the response and returning it,
    # we acutally want to return the untagged responses in realtime without returning.  Impossilbe?  Nah...
    # FIXME: what to do, what to do....
    my ($self) = @_;
    return($self->throw_error("IDLE unimplemented"));
}

########## rfc2971 (IMAP4 ID extention) command ##########

=pod

=item B<id(%perams)>

Provide identifying information to the server, and have the server do the same to you.  The client can request the server's information without sharing its own by supplying an undef perams argument.  The information by both parties is useful for stat...

The perams arguemnt is a hash, since information is in a key-value format.  Keys can be anything, but must be less than 30 characters in length, and values must be less than 1024 characters in length.  There are a set keys defined by the RFC that are...

=over 4

=item * name - Name of the program

=item * version - Version number of the program

=item * os - Name of the operating system

=item * os-version - Version of the operating system

=item * vendor - Vendor of the client/server

=item * support-url - URL to contact for support

=item * address - Postal address of contact/vendor

=item * date - Date program was released, specified as a date-time in IMAP4rev1

=item * command - Command used to start the program

=item * arguments - Arguments supplied on the command line, if any

=item * environment - Description of environment, i.e., UNIX environment List all the subscriptions for the authorized user for the given mailbox from the given reference.variables or Windows registry settings

=back

None of the keys are required - if the client wishes not to supply information for a key, the key is simply omitted.  Not all clients support this extention:  Support can be identified by using the capability() command, and verifying the atom "ID" is...

=cut

sub id($%) {
    my ($self,%perams) = @_;
    my $peramlist;

    return($self->throw_error("ID not supported for ID command")) unless ($self->check_capability('ID'));

    if (%perams) {
		$peramlist = '(';
		foreach my $key (keys %perams) {
		    if (length($key) > 30) { # defined in RFC section 3.3
				return ($self->throw_error("Client key [$key] too long: ".length($key)." bytes, max 30 bytes"));
		    }
		    if (length($perams{$key}) > 1024) {# defined in RFC section 3.3
				return($self->throw_error("Client value [$perams{$key}] too long: ".length($perams{$key}).", max 1024 bytes"));
		    }
		    $peramlist .= quote_once($key).' '.quote_once($perams{$key}).' ';
		}
		chop $peramlist; # rid ourselves of the last space
		$peramlist .= ')'; #overwrite last space with )
    } else {
		$peramlist = 'NIL';
    }
    
    return($self->_imap_command("ID",$peramlist));
}

########## draft-ietf-imapext-annotate-15 ##########

=pod

=item B<getannotation($mailbox, $entry_specifier, $attribute_specifier)>

Retrieve annotations on a mailbox from the server.  If the mailbox argument is empty, it will retrieve global server annotations instead.

The entry specifier indicates which type of annotation you will retrieve.  the "*" wildcard is valid for retrieving all annotations, while the "%" wildcard will match all text except the hierarchy delimiter '/'.

As of draft-ietf-imapext-annotate-15, valid global entries are:

=over 4

=item * /comment

Defines a comment or note associated with the server

=item * /motd

Defines a "message of the day" for the server (Read-Only)

=item * /admin

Indicates a method for contacting the server administrator (Read-Only)

=item * /vendor/<vendor-token>

Defines the top-level of entries associated with the server as created by a particular product of some vendor.  Vendor tokens are registered with IANA, using the ACAP [RFC2244] vendor subtree registry.

=back

... and the mailbox entries are ...

=over 4