#

# Net::IMAP implements Internet Message Access Protocol (IMAP) client

#

# == IMAP Overview

#

# authenticated itself, there is a range of commands

# available to it. Most work with mailboxes, which may be

# arranged in an hierarchical namespace, and each of which

# within a hierarchy of directories.

#

# To work on the messages within a mailbox, the client must

# selected a mailbox, they enter _selected_ state, and that

# mailbox becomes the _current_ mailbox, on which mail-item

# related commands implicitly operate.

# be assigned in ascending (but not necessarily sequential)

# order within a mailbox; this means that if a non-IMAP client

# rearranges the order of mailitems within a mailbox, the

# rearrange message orders.

#

# == Examples of Usage

#

# == References

#

#

#

#

#

#

#

#

#

#

# [[OSSL]]

# http://www.openssl.org

# [[RSSL]]

# http://savannah.gnu.org/projects/rubypki

#

# Goldsmith, D. and Davis, M., "UTF-7: A Mail-Safe Transformation Format of

#

class IMAP < Protocol

VERSION = "0.2.1"

# )

# end

#

def id(client_id=nil)

synchronize do

send_command("ID", ClientID.new(client_id))

#

# For both of these mechanisms, there should be two +args+: username

# and (cleartext) password. A server may not support one or the other

# the form "AUTH=LOGIN" or "AUTH=CRAM-MD5".

#

# Authentication is done using the appropriate authenticator object:

# Sends a LOGIN command to identify the client and carries

# the plaintext +password+ authenticating this +user+. Note

#

# A Net::IMAP::NoResponseError is raised if authentication fails.

def login(user, password)

# number of items in that mailbox from +@responses["EXISTS"][-1]+,

# and the number of recent messages from +@responses["RECENT"][-1]+.

# Note that these values can change if new messages arrive

# detecting this event.

#

# A Net::IMAP::NoResponseError is raised if the mailbox does not

end

# Sends a EXAMINE command to select a +mailbox+ so that messages

# except that the selected +mailbox+ is identified as read-only.

#

# A Net::IMAP::NoResponseError is raised if the mailbox does not

# Sends a SUBSCRIBE command to add the specified +mailbox+ name to

# the server's set of "active" or "subscribed" mailboxes as returned

#

# A Net::IMAP::NoResponseError is raised if +mailbox+ cannot be

# subscribed to; for instance, because it does not exist.

end

end

# mailboxes, and shared mailboxes.

#

#

# But many servers are configured with the default personal namespace as

# e.g. `("INBOX." ".")`, placing all personal folders under INBOX, with "."

# imap.create(prefix + %w[path to my folder].join(delim))

# end

# end

def namespace

synchronize do

send_command("NAMESPACE")

# This command is generally available to both admin and user.

# If this mailbox exists, it returns an array containing objects of type

# Net::IMAP::MailboxQuotaRoot and Net::IMAP::MailboxQuota.

def getquotaroot(mailbox)

synchronize do

send_command("GETQUOTAROOT", mailbox)

# If this mailbox exists, then an array containing a

# Net::IMAP::MailboxQuota object is returned. This

# command is generally only available to server admin.

def getquota(mailbox)

synchronize do

send_command("GETQUOTA", mailbox)

# Sends a SETQUOTA command along with the specified +mailbox+ and

# +quota+. If +quota+ is nil, then +quota+ will be unset for that

# mailbox. Typically one needs to be logged in as a server admin

def setquota(mailbox, quota)

if quota.nil?

data = '()'

# Sends the SETACL command along with +mailbox+, +user+ and the

# +rights+ that user is to have on that mailbox. If +rights+ is nil,

# then that user will be stripped of any rights to that mailbox.

def setacl(mailbox, user, rights)

if rights.nil?

send_command("SETACL", mailbox, user, "")

# Send the GETACL command along with a specified +mailbox+.

# If this mailbox exists, an array containing objects of

# Net::IMAP::MailboxACLItem will be returned.

def getacl(mailbox)

synchronize do

send_command("GETACL", mailbox)

# Sends a LSUB command, and returns a subset of names from the set

# of names that the user has declared as being "active" or

# "subscribed." +refname+ and +mailbox+ are interpreted as

# The return value is an array of +Net::IMAP::MailboxList+.

def lsub(refname, mailbox)

synchronize do

return search_internal("SEARCH", keys, charset)

end

def uid_search(keys, charset = nil)

return search_internal("UID SEARCH", keys, charset)

end

return fetch_internal("FETCH", set, attr, mod)

end

def uid_fetch(set, attr, mod = nil)

return fetch_internal("UID FETCH", set, attr, mod)

end

return store_internal("STORE", set, attr, flags)

end

def uid_store(set, attr, flags)

return store_internal("UID STORE", set, attr, flags)

end

copy_internal("COPY", set, mailbox)

end

def uid_copy(set, mailbox)

copy_internal("UID COPY", set, mailbox)

end

# of the specified destination +mailbox+. The +set+ parameter is

# a number, an array of numbers, or a Range object. The number is

# a message sequence number.

def move(set, mailbox)

copy_internal("MOVE", set, mailbox)

end

def uid_move(set, mailbox)

copy_internal("UID MOVE", set, mailbox)

end

# p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")

# #=> [6, 7, 8, 1]

#

def sort(sort_keys, search_keys, charset)

return sort_internal("SORT", sort_keys, search_keys, charset)

end

def uid_sort(sort_keys, search_keys, charset)

return sort_internal("UID SORT", sort_keys, search_keys, charset)

end

@response_handlers.delete(handler)

end

# format, as a Net::IMAP::ThreadMember tree. The supported algorithms

# are:

#

# REFERENCES:: split into threads by parent/child relationships determined

# by which message is a reply to which.

#

# and UTF-8 are sample values.

#

def thread(algorithm, search_keys, charset)

return thread_internal("THREAD", algorithm, search_keys, charset)

end

# message sequence numbers.

def uid_thread(algorithm, search_keys, charset)

return thread_internal("UID THREAD", algorithm, search_keys, charset)

end

# Sends an IDLE command that waits for notifications of new or expunged

# messages. Yields responses from the server during the IDLE.

#

#

# If +timeout+ is given, this method returns after +timeout+ seconds passed.

# +timeout+ can be used for keep-alive. For example, the following code

module Net

class IMAP < Protocol

# Flag indicating a message has been seen.

SEEN = :Seen

# Flag indicating a message has been answered.

ANSWERED = :Answered

# Flag indicating a message has been flagged for special or urgent

# attention.

FLAGGED = :Flagged

# Flag indicating a message has been marked for deletion. This

# will occur when the mailbox is closed or expunged.

DELETED = :Deleted

# Flag indicating a message is only a draft or work-in-progress version.

DRAFT = :Draft

# Flag indicating that the message is "recent," meaning that this

# session is the first session in which the client has been notified

# of this message.

RECENT = :Recent

# Flag indicating that a mailbox context name cannot contain

# children.

NOINFERIORS = :Noinferiors

# Flag indicating that a mailbox is not selected.

NOSELECT = :Noselect

# Flag indicating that a mailbox has been marked "interesting" by

# the server; this commonly indicates that the mailbox contains

# new messages.

MARKED = :Marked

# Flag indicating that the mailbox does not contains new messages.

UNMARKED = :Unmarked

# data:: Returns the data (Net::IMAP::ResponseText).

#

# raw_data:: Returns the raw data string.

# Net::IMAP::UntaggedResponse represents untagged responses.

#

# a ((<Net::IMAP::MailboxList>)) object.

#

# raw_data:: Returns the raw data string.

# Net::IMAP::IgnoredResponse represents intentionally ignored responses.

#

# ==== Fields:

#

# raw_data:: Returns the raw data string.

# Net::IMAP::TaggedResponse represents tagged responses.

#

#

# raw_data:: Returns the raw data string.

#

# Net::IMAP::ResponseText represents texts of responses.

# The text may be prefixed by the response code.

#

# text:: Returns the text.

#

# Net::IMAP::ResponseCode represents response codes.

#

#

# data:: Returns the data, if it exists.

#

# Net::IMAP::MailboxList represents contents of the LIST response.

#

#

# name:: Returns the mailbox name.

#

# Net::IMAP::MailboxQuota represents contents of GETQUOTA response.

# This object can also be a response to GETQUOTAROOT. In the syntax

#

# quota:: Quota limit imposed on the mailbox.

#

# Net::IMAP::MailboxQuotaRoot represents part of the GETQUOTAROOT

# response. (GETQUOTAROOT can also return Net::IMAP::MailboxQuota.)

# quotaroots:: Zero or more quotaroots that affect the quota on the

# specified mailbox.

#

# Net::IMAP::MailboxACLItem represents the response from GETACL.

#

# rights:: The access rights the indicated user has to the

# mailbox.

#

# Net::IMAP::Namespace represents a single [RFC-2342] namespace.

#

# delim:: Returns nil or the hierarchy delimiter character.

# extensions:: Returns a hash of extension names to extension flag arrays.

#

# Net::IMAP::Namespaces represents the response from [RFC-2342] NAMESPACE.

#

# other:: Returns an array of Other Users' Net::IMAP::Namespace objects.

# shared:: Returns an array of Shared Net::IMAP::Namespace objects.

#

# Net::IMAP::StatusData represents the contents of the STATUS response.

#

# attr:: Returns a hash. Each key is one of "MESSAGES", "RECENT", "UIDNEXT",

# "UIDVALIDITY", "UNSEEN". Each value is a number.

#

# Net::IMAP::FetchData represents the contents of the FETCH response.

#

# [UID]

# A number expressing the unique identifier of the message.

#

# Net::IMAP::Envelope represents envelope structures of messages.

#

#

# message_id:: Returns a string that represents the message-id.

#

#

# Net::IMAP::Address represents electronic mail addresses.

# host:: nil indicates [RFC-822] group syntax.

# Otherwise, returns [RFC-822] domain name.

#

#

# Net::IMAP::ContentDisposition represents Content-Disposition fields.

# param:: Returns a hash that represents parameters of the Content-Disposition

# field.

#

# Net::IMAP::ThreadMember represents a thread-node returned

# by Net::IMAP#thread.

# children:: An array of Net::IMAP::ThreadMember objects for mail

# items that are children of this in the thread.

#

# Net::IMAP::BodyTypeBasic represents basic body structures of messages.

#