класс Net::IMAP

# File lib/net/imap.rb, line 886
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 693
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", "Subject: hello
From: shugo@ruby-lang.org
To: shugo@ruby-lang.org

hello world
".gsub(/\n/, "\r\n"), [:Seen], Time.now)

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

# File lib/net/imap.rb, line 411
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("m").gsub(/\n/, "")
      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.

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

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

Например:

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

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

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

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

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

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

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

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

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

# File lib/net/imap.rb, line 847
def copy(set, mailbox)
  copy_internal("COPY", set, mailbox)
end

Отправляет команду COPY для копирования указанного сообщения (сообщений) в конец указанного почтового ящика назначения mailbox. Параметр set — это число, массив чисел или объект Range. Число — это номер последовательности сообщений.

# File lib/net/imap.rb, line 474
def create(mailbox)
  send_command("CREATE", mailbox)
end

Отправляет команду CREATE для создания нового mailbox.

Возникает исключение Net::IMAP::NoResponseError, если почтовый ящик с таким именем не может быть создан.

# File lib/net/imap.rb, line 483
def delete(mailbox)
  send_command("DELETE", mailbox)
end

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

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

# File lib/net/imap.rb, line 315
def disconnect
  begin
    begin
      # try to call SSL::SSLSocket#io.
      @sock.io.shutdown
    rescue NoMethodError
      # @sock is not an SSL::SSLSocket.
      @sock.shutdown
    end
  rescue Errno::ENOTCONN
    # ignore `Errno::ENOTCONN: Socket is not connected' on some platforms.
  rescue Exception => e
    @receiver_thread.raise(e)
  end
  @receiver_thread.join
  synchronize do
    unless @sock.closed?
      @sock.close
    end
  end
  raise e if e
end

Отключается от сервера.

# File lib/net/imap.rb, line 339
def disconnected?
  return @sock.closed?
end

Возвращает true, если отключено от сервера.

# File lib/net/imap.rb, line 463
def examine(mailbox)
  synchronize do
    @responses.clear
    send_command("EXAMINE", mailbox)
  end
end

Отправляет команду EXAMINE для выбора mailbox, чтобы можно было получить доступ к сообщениям в mailbox. Ведет себя так же, как select(), за исключением того, что выбранный mailbox определяется как доступный только для чтения.

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

# File lib/net/imap.rb, line 720
def expunge
  synchronize do
    send_command("EXPUNGE")
    return @responses.delete("EXPUNGE")
  end
end

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

# File lib/net/imap.rb, line 811
def fetch(set, attr)
  return fetch_internal("FETCH", set, attr)
end

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

Параметр set — это число или диапазон между двумя числами или массив таких значений. Число — это номер последовательности сообщений, где -1 представляет '*' для использования в обозначении диапазона, например, 100..-1 интерпретируется как '100:*'. Имейте в виду, что свойство exclude_end? объекта Range игнорируется, и содержимое диапазона не зависит от порядка конечных точек диапазона в соответствии со спецификацией протокола, поэтому 1…5, 5..1 и 5…1 эквивалентны 1..5.

attr — это список атрибутов для извлечения; см. документацию для Net::IMAP::FetchData для списка допустимых атрибутов.

Возвращаемое значение — это массив Net::IMAP::FetchData или nil (вместо пустого массива), если нет совпадающих сообщений.

Например:

p imap.fetch(6..8, "UID")
#=> [#<Net::IMAP::FetchData seqno=6, attr={"UID"=>98}>, \\
     #<Net::IMAP::FetchData seqno=7, attr={"UID"=>99}>, \\
     #<Net::IMAP::FetchData seqno=8, attr={"UID"=>100}>]
p imap.fetch(6, "BODY[HEADER.FIELDS (SUBJECT)]")
#=> [#<Net::IMAP::FetchData seqno=6, attr={"BODY[HEADER.FIELDS (SUBJECT)]"=>"Subject: test\r\n\r\n"}>]
data = imap.uid_fetch(98, ["RFC822.SIZE", "INTERNALDATE"])[0]
p data.seqno
#=> 6
p data.attr["RFC822.SIZE"]
#=> 611
p data.attr["INTERNALDATE"]
#=> "12-Oct-2000 22:40:59 +0900"
p data.attr["UID"]
#=> 98

# File lib/net/imap.rb, line 633
def getacl(mailbox)
  synchronize do
    send_command("GETACL", mailbox)
    return @responses.delete("ACL")[-1]
  end
end

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

# File lib/net/imap.rb, line 597
def getquota(mailbox)
  synchronize do
    send_command("GETQUOTA", mailbox)
    return @responses.delete("QUOTA")
  end
end

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

# File lib/net/imap.rb, line 583
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 922
def idle(&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
      @idle_done_cond = nil
      if @receiver_thread_terminating
        raise Net::IMAP::Error, "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.

# File lib/net/imap.rb, line 952
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 540
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 434
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 367
def logout
  send_command("LOGOUT")
end

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

# File lib/net/imap.rb, line 645
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 361
def noop
  send_command("NOOP")
end

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

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

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

# File lib/net/imap.rb, line 494
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 767
def search(keys, charset = nil)
  return search_internal("SEARCH", keys, charset)
end

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

<message set>

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

BEFORE <date>

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

BODY <string>

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

CC <string>

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

FROM <string>

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

NEW

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

NOT <search-key>

отрицание следующего ключа поиска.

OR <search-key> <search-key>

«или» два ключа поиска вместе.

ON <date>

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

SINCE <date>

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

SUBJECT <string>

сообщения с <string> в теме.

TO <string>

сообщения с <string> в поле TO.

Например:

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

# File lib/net/imap.rb, line 450
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 622
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 609
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 865
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 372
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 668
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 834
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 504
def subscribe(mailbox)
  send_command("SUBSCRIBE", mailbox)
end

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

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

# File lib/net/imap.rb, line 908
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] для получения более подробной информации.

# File lib/net/imap.rb, line 852
def uid_copy(set, mailbox)
  copy_internal("UID COPY", set, mailbox)
end

Аналогично copy(), но set содержит уникальные идентификаторы.

# File lib/net/imap.rb, line 816
def uid_fetch(set, attr)
  return fetch_internal("UID FETCH", set, attr)
end

Аналогично fetch(), но set содержит уникальные идентификаторы.

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

Аналогично search(), но возвращает уникальные идентификаторы.

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

Аналогично sort(), но возвращает массив уникальных идентификаторов.

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

Аналогично store(), но set содержит уникальные идентификаторы.

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

Аналогично thread(), но возвращает уникальные идентификаторы вместо номеров последовательностей сообщений.

# File lib/net/imap.rb, line 514
def unsubscribe(mailbox)
  send_command("UNSUBSCRIBE", mailbox)
end

Отправляет команду UNSUBSCRIBE, чтобы удалить указанное имя mailbox из набора «активных» или «подписанных» почтовых ящиков сервера.

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

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

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

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

Команда XLIST похожа на команду LIST, за исключением того, что возвращаемые флаги относятся к функции папки/почтового ящика, например: :Sent

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

imap.create("foo/bar")
imap.create("foo/baz")
p imap.xlist("", "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">]