класс Net::IMAP

# File lib/net/imap.rb, line 906
def add_response_handler(handler = Proc.new)
  @response_handlers.push(handler)
end

Добавляет обработчик ответов. Например, чтобы обнаружить, когда сервер отправляет новый ответ EXISTS (который обычно указывает на добавление новых сообщений в почтовый ящик), добавьте следующий обработчик после выбора почтового ящика:

imap.add_response_handler { |resp|
  if resp.kind_of?(Net::IMAP::UntaggedResponse) and resp.name == "EXISTS"
    puts "Mailbox now has #{resp.data} messages"
  end
}

# File lib/net/imap.rb, line 699
def append(mailbox, message, flags = nil, date_time = nil)
  args = []
  if flags
    args.push(flags)
  end
  args.push(date_time) if date_time
  args.push(Literal.new(message))
  send_command("APPEND", mailbox, *args)
end

Отправляет команду APPEND для добавления message в конец mailbox. Необязательный параметр flags — массив флагов, изначально передаваемых новому сообщению. Необязательный параметр date_time задаёт время создания нового сообщения; по умолчанию используется текущее время. Например:

imap.append("inbox", <<EOF.gsub(/\n/, "\r\n"), [:Seen], Time.now)
Subject: hello
From: shugo@ruby-lang.org
To: shugo@ruby-lang.org

hello world
EOF

Исключение Net::IMAP::NoResponseError генерируется, если почтовый ящик не существует (он не создаётся автоматически) или если в аргументах flags, date_time или message содержатся ошибки.

# File lib/net/imap.rb, line 417
def authenticate(auth_type, *args)
  auth_type = auth_type.upcase
  unless @@authenticators.has_key?(auth_type)
    raise ArgumentError,
      format('unknown auth type - "%s"', auth_type)
  end
  authenticator = @@authenticators[auth_type].new(*args)
  send_command("AUTHENTICATE", auth_type) do |resp|
    if resp.instance_of?(ContinuationRequest)
      data = authenticator.process(resp.data.text.unpack("m")[0])
      s = [data].pack("m0")
      send_string_data(s)
      put_string(CRLF)
    end
  end
end

Отправляет команду AUTHENTICATE для аутентификации клиента. Параметр auth_type — строка, представляющая используемый механизм аутентификации. В настоящее время Net::IMAP поддерживает следующие механизмы аутентификации:

LOGIN:: login using cleartext user and password.
CRAM-MD5:: login with cleartext user and encrypted password
           (see [RFC-2195] for a full description).  This
           mechanism requires that the server have the user's
           password stored in clear-text password.

Для обоих механизмов требуется два параметра: имя пользователя и (в открытом виде) пароль. Сервер может не поддерживать один или другой из этих механизмов; проверьте capability() на наличие возможности вида “AUTH=LOGIN” или “AUTH=CRAM-MD5”.

Аутентификация выполняется с помощью соответствующего объекта аутентификатора: см. @@authenticators для получения дополнительной информации о подключении собственного аутентификатора.

Например:

imap.authenticate('LOGIN', user, password)

Исключение Net::IMAP::NoResponseError генерируется, если аутентификация не удалась.

# File lib/net/imap.rb, line 359
def capability
  synchronize do
    send_command("CAPABILITY")
    return @responses.delete("CAPABILITY")[-1]
  end
end

Отправляет команду CAPABILITY и возвращает массив поддерживаемых сервером возможностей. Каждая возможность — строка. См. [IMAP] для списка возможных возможностей.

Обратите внимание, что класс Net::IMAP не изменяет своего поведения в зависимости от возможностей сервера; пользователю класса необходимо убедиться, что определённая возможность поддерживается сервером перед её использованием.

# File lib/net/imap.rb, line 713
def check
  send_command("CHECK")
end

Отправляет команду CHECK для запроса контрольной точки текущего выбранного почтового ящика. Это выполняет специфичные для реализации задачи по уходу; например, согласование состояния почтового ящика в памяти и на диске.

# File lib/net/imap.rb, line 720
def close
  send_command("CLOSE")
end

Отправляет команду CLOSE для закрытия текущего выбранного почтового ящика. Команда CLOSE постоянно удаляет из почтового ящика все сообщения, у которых установлен флаг Удалено.

# File lib/net/imap.rb, line 589
def getquotaroot(mailbox)
  synchronize do
    send_command("GETQUOTAROOT", mailbox)
    result = []
    result.concat(@responses.delete("QUOTAROOT"))
    result.concat(@responses.delete("QUOTA"))
    return result
  end
end

Отправляет команду GETQUOTAROOT вместе с указанным mailbox. Эта команда, как правило, доступна как администраторам, так и пользователям. Если почтовый ящик существует, возвращает массив, содержащий объекты типа Net::IMAP::MailboxQuotaRoot и Net::IMAP::MailboxQuota.

# File lib/net/imap.rb, line 952
def idle(timeout = nil, &response_handler)
  raise LocalJumpError, "no block given" unless response_handler

  response = nil

  synchronize do
    tag = Thread.current[:net_imap_tag] = generate_tag
    put_string("#{tag} IDLE#{CRLF}")

    begin
      add_response_handler(response_handler)
      @idle_done_cond = new_cond
      @idle_done_cond.wait(timeout)
      @idle_done_cond = nil
      if @receiver_thread_terminating
        raise @exception || Net::IMAP::Error.new("connection closed")
      end
    ensure
      unless @receiver_thread_terminating
        remove_response_handler(response_handler)
        put_string("DONE#{CRLF}")
        response = get_tagged_response(tag, "IDLE")
      end
    end
  end

  return response
end

Отправляет команду IDLE, которая ожидает уведомлений о новых или удалённых сообщениях. Выводит ответы сервера во время IDLE.

Используйте idle_done(), чтобы выйти из режима IDLE.

Если timeout задано, этот метод возвращает значение после того, как пройдёт timeout секунд. timeout может использоваться для поддержания соединения. Например, следующий код проверяет соединение каждые 60 секунд.

loop do
  imap.idle(60) do |res|
    ...
  end
end

# File lib/net/imap.rb, line 982
def idle_done
  synchronize do
    if @idle_done_cond.nil?
      raise Net::IMAP::Error, "not during IDLE"
    end
    @idle_done_cond.signal
  end
end

Выходит из режима IDLE.

# File lib/net/imap.rb, line 546
def list(refname, mailbox)
  synchronize do
    send_command("LIST", refname, mailbox)
    return @responses.delete("LIST")
  end
end

Отправляет команду LIST и возвращает подмножество имён из полного набора всех имён, доступных клиенту. refname предоставляет контекст (например, базовый каталог в иерархии почтовых ящиков на основе каталогов). mailbox указывает почтовый ящик или (с помощью подстановочных символов) почтовые ящики в этом контексте. В mailbox могут использоваться два подстановочных знака: «*», который соответствует всем символам, **включая** разделитель иерархии (например, «/» в иерархии почтовых ящиков на основе каталогов на сервере Unix); и «%», который соответствует всем символам, **кроме** разделителя иерархии.

Если refname пусто, mailbox используется напрямую для определения, какие почтовые ящики подходят. Если mailbox пусто, возвращается корневое имя refname и разделитель иерархии.

Возвращаемое значение — массив Net::IMAP::MailboxList. Например:

imap.create("foo/bar")
imap.create("foo/baz")
p imap.list("", "foo/%")
#=> [#<Net::IMAP::MailboxList attr=[:Noselect], delim="/", name="foo/">, \\
     #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, \\
     #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]

# File lib/net/imap.rb, line 440
def login(user, password)
  send_command("LOGIN", user, password)
end

Отправляет команду LOGIN для идентификации клиента и содержит текстовое password для аутентификации этого user. Обратите внимание, что в отличие от вызова authenticate() с auth_type «LOGIN», login() **не** использует аутентификатор входа.

Если аутентификация завершится неудачей, возникает ошибка Net::IMAP::NoResponseError.

# File lib/net/imap.rb, line 373
def logout
  send_command("LOGOUT")
end

Отправляет команду LOGOUT, чтобы сообщить серверу, что клиент завершил работу с соединением.

# File lib/net/imap.rb, line 651
def lsub(refname, mailbox)
  synchronize do
    send_command("LSUB", refname, mailbox)
    return @responses.delete("LSUB")
  end
end

Отправляет команду LSUB и возвращает подмножество имён из набора имён, которые пользователь объявил «активными» или «подписанными». refname и mailbox интерпретируются так же, как для list(). Возвращаемое значение — массив Net::IMAP::MailboxList.

# File lib/net/imap.rb, line 867
def move(set, mailbox)
  copy_internal("MOVE", set, mailbox)
end

Отправляет команду MOVE для перемещения указанных сообщений в конец указанного целевого mailbox. Параметр set — число, массив чисел или объект Range. Число — порядковый номер сообщения. Расширение MOVE протокола IMAP описано в [RFC-6851].

# File lib/net/imap.rb, line 367
def noop
  send_command("NOOP")
end

Отправляет команду NOOP на сервер. Она ничего не делает.

# File lib/net/imap.rb, line 911
def remove_response_handler(handler)
  @response_handlers.delete(handler)
end

Удаляет обработчик ответов.

# File lib/net/imap.rb, line 500
def rename(mailbox, newname)
  send_command("RENAME", mailbox, newname)
end

Отправляет команду RENAME для изменения имени mailbox на newname.

Ошибка Net::IMAP::NoResponseError возникает, если почтовый ящик с именем mailbox не может быть переименован в newname по какой-либо причине; например, потому что mailbox не существует или потому, что уже существует почтовый ящик с именем newname.

# File lib/net/imap.rb, line 773
def search(keys, charset = nil)
  return search_internal("SEARCH", keys, charset)
end

Отправляет команду SEARCH для поиска сообщений в почтовом ящике, которые соответствуют заданным критериям поиска, и возвращает порядковые номера сообщений. keys может быть либо строкой, содержащей всю строку поиска, либо одномерным массивом поисковых ключевых слов и аргументов. Ниже приведены некоторые распространённые критерии поиска; полный список см. в разделе [IMAP] 6.4.4.

<набор сообщений>

набор порядковых номеров сообщений. «,» обозначает интервал, «:» обозначает диапазон. Например, «2,10:12,15» означает «2,10,11,12,15».

BEFORE <дата>

сообщения с внутренней датой строго до <дата>. Аргумент даты имеет формат, аналогичный 8-авг-2002.

BODY <строка>

сообщения, содержащие <строка> в своём теле.

CC <строка>

сообщения, содержащие <строка> в поле CC.

FROM <строка>

сообщения, содержащие <строка> в поле FROM.

NEW

сообщения со флагом Recent, но не флагом Seen.

NOT <ключ-поиска>

отменить следующий ключ поиска.

OR <ключ-поиска> <ключ-поиска>

соединить два ключа поиска по принципу «или».

ON <дата>

сообщения с внутренней датой, точно равной <дата>, которая имеет формат, аналогичный 8-авг-2002.

SINCE <дата>

сообщения с внутренней датой на или после <дата>.

SUBJECT <строка>

сообщения с <строка> в теме.

TO <строка>

сообщения с <строка> в поле TO.

Например:

p imap.search(["SUBJECT", "hello", "NOT", "NEW"])
#=> [1, 6, 7, 8]

# File lib/net/imap.rb, line 456
def select(mailbox)
  synchronize do
    @responses.clear
    send_command("SELECT", mailbox)
  end
end

Отправляет команду SELECT для выбора mailbox, чтобы можно было получить доступ к сообщениям в этом mailbox.

После выбора почтового ящика вы можете получить количество элементов в этом почтовом ящике из @responses[-1] и количество последних сообщений из @responses[-1]. Обратите внимание, что эти значения могут измениться, если во время сессии придут новые сообщения; см. add_response_handler() для способа обнаружения этого события.

Если почтовый ящик не существует или по какой-либо причине недоступен для выбора, возникает ошибка Net::IMAP::NoResponseError.

# File lib/net/imap.rb, line 628
def setacl(mailbox, user, rights)
  if rights.nil?
    send_command("SETACL", mailbox, user, "")
  else
    send_command("SETACL", mailbox, user, rights)
  end
end

Отправляет команду SETACL вместе с mailbox, user и rights для пользователя в данном почтовом ящике. Если rights равно nil, права этого пользователя для данного почтового ящика будут удалены. Команды IMAP ACL описаны в [RFC-2086].

# File lib/net/imap.rb, line 615
def setquota(mailbox, quota)
  if quota.nil?
    data = '()'
  else
    data = '(STORAGE ' + quota.to_s + ')'
  end
  send_command("SETQUOTA", mailbox, RawData.new(data))
end

Отправляет команду SETQUOTA вместе с указанными mailbox и quota. Если quota равно nil, то quota будет снято для этой почтовой папки. Обычно для этого требуется вход под учетной записью администратора сервера. Команды квоты IMAP описаны в [RFC-2087].

# File lib/net/imap.rb, line 885
def sort(sort_keys, search_keys, charset)
  return sort_internal("SORT", sort_keys, search_keys, charset)
end

Отправляет команду SORT для сортировки сообщений в почтовой папке. Возвращает массив номеров последовательности сообщений. Например:

p imap.sort(["FROM"], ["ALL"], "US-ASCII")
#=> [1, 2, 3, 5, 6, 7, 8, 4, 9]
p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")
#=> [6, 7, 8, 1]

Дополнительные сведения см. в [SORT-THREAD-EXT].

# File lib/net/imap.rb, line 378
def starttls(options = {}, verify = true)
  send_command("STARTTLS") do |resp|
    if resp.kind_of?(TaggedResponse) && resp.name == "OK"
      begin
        # for backward compatibility
        certs = options.to_str
        options = create_ssl_params(certs, verify)
      rescue NoMethodError
      end
      start_tls_session(options)
    end
  end
end

Отправляет команду STARTTLS для начала TLS-сессии.

# File lib/net/imap.rb, line 674
def status(mailbox, attr)
  synchronize do
    send_command("STATUS", mailbox, attr)
    return @responses.delete("STATUS")[-1].attr
  end
end

Отправляет команду STATUS и возвращает состояние указанной mailbox. attr — список одной или нескольких характеристик, статус которых необходимо запросить. Поддерживаемые характеристики включают:

MESSAGES:: the number of messages in the mailbox.
RECENT:: the number of recent messages in the mailbox.
UNSEEN:: the number of unseen messages in the mailbox.

Возвращаемое значение — хеш характеристик. Например:

p imap.status("inbox", ["MESSAGES", "RECENT"])
#=> {"RECENT"=>0, "MESSAGES"=>44}

Исключение Net::IMAP::NoResponseError генерируется, если значения статуса для mailbox не могут быть возвращены; например, потому что они не существуют.

# File lib/net/imap.rb, line 840
def store(set, attr, flags)
  return store_internal("STORE", set, attr, flags)
end

Отправляет команду STORE для изменения данных, связанных с сообщениями в почтовой папке, в частности, их флагов. Параметр set — число, массив чисел или объект Range. Каждое число — номер последовательности сообщения. attr — имя элемента данных для сохранения: 'FLAGS' заменит список флагов сообщения предоставленным, '+FLAGS' добавит предоставленные флаги, а '-FLAGS' удалит их. flags — список флагов.

Возвращаемое значение — массив Net::IMAP::FetchData. Например:

p imap.store(6..8, "+FLAGS", [:Deleted])
#=> [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
     #<Net::IMAP::FetchData seqno=7, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
     #<Net::IMAP::FetchData seqno=8, attr={"FLAGS"=>[:Seen, :Deleted]}>]

# File lib/net/imap.rb, line 510
def subscribe(mailbox)
  send_command("SUBSCRIBE", mailbox)
end

Отправляет команду SUBSCRIBE для добавления указанного mailbox имени в набор «активных» или «подписанных» почтовых папок сервера, возвращаемых функцией lsub().

Исключение Net::IMAP::NoResponseError генерируется, если к mailbox невозможно подключиться; например, потому что оно не существует.

# File lib/net/imap.rb, line 928
def thread(algorithm, search_keys, charset)
  return thread_internal("THREAD", algorithm, search_keys, charset)
end

Аналогично search(), но возвращает номера последовательности сообщений в формате потоков в виде дерева Net::IMAP::ThreadMember. Поддерживаемые алгоритмы:

ORDEREDSUBJECT

разбивает на потоки по одному уровню в соответствии с темой, отсортированные по дате.

REFERENCES

разбивает на потоки по отношениям родитель/дочерний, определяющим, какое сообщение является ответом на какое.

В отличие от search(), charset является обязательным аргументом. Примеры значений — US-ASCII и UTF-8.

Дополнительные сведения см. в [SORT-THREAD-EXT].