The protocol class implementing IMAP4rev1.
IMAPConnection
public IMAPConnection(String host,
int port,
int connectionTimeout,
int timeout,
boolean debug)
throws UnknownHostException,
IOException
Creates a new connection.
host
- the name of the host to connect toport
- the port to connect to, or -1 for the defaultconnectionTimeout
- the socket connection timeouttimeout
- the socket timeoutdebug
- log debugging information
IMAPConnection
public IMAPConnection(String host,
int port,
int connectionTimeout,
int timeout,
boolean secure,
TrustManager tm,
boolean debug)
throws UnknownHostException,
IOException
Creates a new connection.
host
- the name of the host to connect toport
- the port to connect to, or -1 for the defaultconnectionTimeout
- the socket connection timeouttimeout
- the socket timeoutsecure
- if an IMAP-SSL connection should be madetm
- a trust manager used to check SSL certificates, or null to
use the defaultdebug
- log debugging information
IMAPConnection
public IMAPConnection(String host,
int port,
TrustManager tm)
throws UnknownHostException,
IOException
Creates a new secure connection using the specified trust manager.
host
- the name of the host to connect toport
- the port to connect to, or -1 for the defaulttm
- a trust manager used to check SSL certificates, or null to
use the default
alertsPending
public boolean alertsPending()
Indicates if there are alerts pending for the user-agent.
append
public boolean append(String mailbox,
String[] flags,
byte[] content)
throws IOException
Append a message to the specified mailbox.
This method returns an OutputStream to which the message should be
written and then closed.
mailbox
- the mailbox nameflags
- optional list of flags to specify for the messagecontent
- the message body(including headers)
- true if successful, false if error in flags/text
authenticate
public boolean authenticate(String mechanism,
String username,
String password)
throws IOException
Authenticates the connection using the specified SASL mechanism,
username, and password.
mechanism
- a SASL authentication mechanism, e.g. LOGIN, PLAIN,
CRAM-MD5, GSSAPIusername
- the authentication principalpassword
- the authentication credentials
- true if authentication was successful, false otherwise
check
public void check()
throws IOException
Request a checkpoint of the currently selected mailbox.
close
public boolean close()
throws IOException
Permanently remove all messages that have the \Deleted flags set,
and close the mailbox.
- true if successful, false if no mailbox was selected
copy
public boolean copy(int[] messages,
String mailbox)
throws IOException
Copies the specified messages to the end of the destination mailbox.
messages
- the message numbersmailbox
- the destination mailbox
create
public boolean create(String mailbox)
throws IOException
Creates a mailbox with the specified name.
mailbox
- the mailbox name
- true if the mailbox was successfully created, false otherwise
delete
public boolean delete(String mailbox)
throws IOException
Deletes the mailbox with the specified name.
mailbox
- the mailbox name
- true if the mailbox was successfully deleted, false otherwise
deleteacl
public boolean deleteacl(String mailbox,
String principal)
throws IOException
Removes any access rights for the given authentication principal on the
specified mailbox.
mailbox
- the mailbox nameprincipal
- the authentication identifier
examine
public MailboxStatus examine(String mailbox)
throws IOException
Selects the specified mailbox.
The mailbox is identified as read-only.
mailbox
- the mailbox name
- a MailboxStatus containing the state of the selected mailbox
expunge
public int[] expunge()
throws IOException
Permanently removes all messages that have the \Delete flag set.
- the numbers of the messages expunged
fetch
public MessageStatus[] fetch(int start,
int end,
String[] fetchCommands)
throws IOException
Retrieves data associated with the specified range of messages in
the mailbox.
start
- the message number of the first messageend
- the message number of the last messagefetchCommands
- the fetch commands, e.g. FLAGS
fetch
public MessageStatus fetch(int message,
String[] fetchCommands)
throws IOException
Retrieves data associated with the specified message in the mailbox.
message
- the message numberfetchCommands
- the fetch commands, e.g. FLAGS
fetch
public MessageStatus[] fetch(int[] messages,
String[] fetchCommands)
throws IOException
Retrieves data associated with messages in the mailbox.
messages
- the message numbersfetchCommands
- the fetch commands, e.g. FLAGS
getAlerts
public String[] getAlerts()
Returns the pending alerts for the user-agent as an array.
getacl
public Map getacl(String mailbox)
throws IOException
Returns the access control list for the specified mailbox.
The returned rights are a logical OR of RIGHTS_* bits.
mailbox
- the mailbox name
- a map of principal names to Integer rights
getquota
public Quota getquota(String quotaRoot)
throws IOException
Returns the specified quota root's resource usage and limits.
quotaRoot
- the quota root
invokeSimpleCommand
protected boolean invokeSimpleCommand(String command)
throws IOException
Sends the specified IMAP command.
command
- the command
- true if OK was received, or false if NO was received
IOException
- if BAD was received or an I/O error occurred
list
public ListEntry[] list(String reference,
String mailbox)
throws IOException
Returns a subset of names from the compete set of names available to
the client.
reference
- the context relative to which mailbox names are
definedmailbox
- a mailbox name, possibly including IMAP wildcards
listrights
public int listrights(String mailbox,
String principal)
throws IOException
Returns the rights for the given principal for the specified mailbox.
The returned rights are a logical OR of RIGHTS_* bits.
mailbox
- the mailbox nameprincipal
- the authentication identity
login
public boolean login(String username,
String password)
throws IOException
Login to the connection using the username and password method.
username
- the authentication principalpassword
- the authentication credentials
- true if authentication was successful, false otherwise
logout
public void logout()
throws IOException
Logout this connection.
Underlying network resources will be freed.
myrights
public int myrights(String mailbox)
throws IOException
Returns the rights for the current principal for the specified mailbox.
The returned rights are a logical OR of RIGHTS_* bits.
mailbox
- the mailbox name
newTag
protected String newTag()
Returns a new tag for a command.
noop
public MailboxStatus noop()
throws IOException
Ping the server.
If a change in mailbox state is detected, a new mailbox status is
returned, otherwise this method returns null.
readResponse
protected IMAPResponse readResponse()
throws IOException
Reads an IMAP response from the server.
The response will consist of
either:
- A tagged response corresponding to a pending command
- An untagged error response
- A continuation response
rename
public boolean rename(String source,
String target)
throws IOException
Renames the source mailbox to the specified name.
source
- the source mailbox nametarget
- the target mailbox name
- true if the mailbox was successfully renamed, false otherwise
search
public int[] search(String charset,
String[] criteria)
throws IOException
Searches the currently selected mailbox for messages matching the
specified criteria.
select
public MailboxStatus select(String mailbox)
throws IOException
Selects the specified mailbox.
The mailbox is identified as read-write if writes are permitted.
mailbox
- the mailbox name
- a MailboxStatus containing the state of the selected mailbox
setAnsiDebug
public void setAnsiDebug(boolean flag)
Sets whether debugging output should use ANSI colour escape sequences.
setacl
public boolean setacl(String mailbox,
String principal,
int rights)
throws IOException
Changes the access rights on the specified mailbox such that the
authentication principal is granted the specified permissions.
mailbox
- the mailbox nameprincipal
- the authentication identifierrights
- the rights to assign
setquota
public Quota setquota(String quotaRoot,
Quota.Resource resources)
throws IOException
Sets the quota for the specified quota root.
quotaRoot
- the quota rootresources
- the list of resources and associated limits to set
- the new quota, or
null
if the operation failed
starttls
public boolean starttls()
throws IOException
Attempts to start TLS on the specified connection.
See RFC 2595 for details.
- true if successful, false otherwise
starttls
public boolean starttls(TrustManager tm)
throws IOException
Attempts to start TLS on the specified connection.
See RFC 2595 for details.
tm
- the custom trust manager to use
- true if successful, false otherwise
store
public MessageStatus[] store(int start,
int end,
String flagCommand,
String[] flags)
throws IOException
Alters data associated with the specified range of messages in the
mailbox.
start
- the message number of the first messageend
- the message number of the last messageflagCommand
- FLAGS, +FLAGS, -FLAGS(or .SILENT versions)flags
- message flags to set
- a list of message-number to current flags
store
public MessageStatus store(int message,
String flagCommand,
String[] flags)
throws IOException
Alters data associated with the specified message in the mailbox.
message
- the message numberflagCommand
- FLAGS, +FLAGS, -FLAGS(or .SILENT versions)flags
- message flags to set
- the message status
store
public MessageStatus[] store(int[] messages,
String flagCommand,
String[] flags)
throws IOException
Alters data associated with messages in the mailbox.
messages
- the message numbersflagCommand
- FLAGS, +FLAGS, -FLAGS(or .SILENT versions)flags
- message flags to set
- a list of message-number to current flags
subscribe
public boolean subscribe(String mailbox)
throws IOException
Adds the specified mailbox to the set of subscribed mailboxes as
returned by the LSUB command.
mailbox
- the mailbox name
- true if the mailbox was successfully subscribed, false otherwise
uidFetch
public MessageStatus uidFetch(long uid,
String[] fetchCommands)
throws IOException
Retrieves data associated with the specified message in the mailbox.
uid
- the message UIDfetchCommands
- the fetch commands, e.g. FLAGS
uidFetch
public MessageStatus[] uidFetch(long start,
long end,
String[] fetchCommands)
throws IOException
Retrieves data associated with the specified range of messages in
the mailbox.
start
- the message number of the first messageend
- the message number of the last messagefetchCommands
- the fetch commands, e.g. FLAGS
uidFetch
public MessageStatus[] uidFetch(long[] uids,
String[] fetchCommands)
throws IOException
Retrieves data associated with messages in the mailbox.
uids
- the message UIDsfetchCommands
- the fetch commands, e.g. FLAGS
uidStore
public MessageStatus uidStore(long uid,
String flagCommand,
String[] flags)
throws IOException
Alters data associated with the specified message in the mailbox.
uid
- the message UIDflagCommand
- FLAGS, +FLAGS, -FLAGS(or .SILENT versions)flags
- message flags to set
- the message status
uidStore
public MessageStatus[] uidStore(long start,
long end,
String flagCommand,
String[] flags)
throws IOException
Alters data associated with the specified range of messages in the
mailbox.
start
- the UID of the first messageend
- the UID of the last messageflagCommand
- FLAGS, +FLAGS, -FLAGS(or .SILENT versions)flags
- message flags to set
- a list of message-number to current flags
uidStore
public MessageStatus[] uidStore(long[] uids,
String flagCommand,
String[] flags)
throws IOException
Alters data associated with messages in the mailbox.
uids
- the message UIDsflagCommand
- FLAGS, +FLAGS, -FLAGS(or .SILENT versions)flags
- message flags to set
- a list of message-number to current flags
unsubscribe
public boolean unsubscribe(String mailbox)
throws IOException
Removes the specified mailbox from the set of subscribed mailboxes as
returned by the LSUB command.
mailbox
- the mailbox name
- true if the mailbox was successfully unsubscribed, false otherwise
* IMAPConnection.java
* Copyright (C) 2003,2004 The Free Software Foundation
*
* This file is part of GNU inetlib, a library.
*
* GNU inetlib is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* GNU inetlib is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Linking this library statically or dynamically with other modules is
* making a combined work based on this library. Thus, the terms and
* conditions of the GNU General Public License cover the whole
* combination.
*
* As a special exception, the copyright holders of this library give you
* permission to link this library with independent modules to produce an
* executable, regardless of the license terms of these independent
* modules, and to copy and distribute the resulting executable under
* terms of your choice, provided that you also meet, for each linked
* independent module, the terms and conditions of the license of that
* module. An independent module is a module which is not derived from
* or based on this library. If you modify this library, you may extend
* this exception to your version of the library, but you are not
* obliged to do so. If you do not wish to do so, delete this
* exception statement from your version.