new

Called by the connection to create a new command.

server

Gets or sets the Net::IMAP::Server associated with this command.

connection

Gets or sets the Net::IMAP::Server::Connection associated with this command.

validate

Called before the command is run. If it returns a false value, the command is not run; it will probably want to inspect "parsed_options". If "validate" returns a false value, it is responsible for calling "no_command" or "bad_command" to notify the client of the failure. Handily, these return a false value.

run

Does the guts of the command. The return value is ignored; the command is in charge of eventually sending one of "ok_command", "bad_command", or "no_command" to the client.

The default implementation simply always response with "bad_command".

has_literal

Analyzes the options line, and returns true if the line has literals (as defined in the RFC, a literal is of the form "{42}"). If the line has literals, installs a "pending" in Net::IMAP::Server::Connection callback to continue the parsing, and returns true.

parse_options

Parses the options, and puts the results (which may be a data structure) into parsed_options.

command_id

Returns the (arbitrary) string that the client identified the command with.

parsed_options

Returns the list of options to the command.

options_str

Returns the flat string representation of the options the client gave.

data_out DATA

Returns a string representing the most probable IMAP string that conveys the "DATA".

• Array references are converted into "parenthesized lists," and each element is recursively output.
• Scalar references are dereferenced and returned as-is.
• "undef" is output as "NIL".
• Scalar values containing special characters are output as literals
• Purely numerical scalar values are output with no change
• All other scalar values are output within quotes.

Since the IMAP specification contains nothing which is similar to a hash, hash references are treated specially; specifically, the "type" key is taken to be how the "value" key should be output. Options for "type" are "string" or "literal".

untagged_response STRING

Sends an untagged response to the client.

tagged_response

Sends a tagged response to the client.

poll_after

Returns a true value if the command should send untagged updates about the selected mailbox after the command completes. Defaults to always true.

send_untagged

Sends untagged updates about the currently selected inbox to the client using "send_untagged" in Net::IMAP::Server::Connection, but only if the command has a true "poll_after".

ok_command MESSAGE [, RESPONSECODE => STRING, ...]

Sends untagged OK responses for any "RESPONSECODE" pairs, then outputs untagged messages via "send_untagged", then sends a tagged OK with the given "MESSAGE".

ok_completed [RESPONSECODE => STRING]

Sends an "OK COMPLETED" tagged response to the client.

no_command MESSAGE [, RESPONSECODE => STRING, ...]

Sends untagged NO responses for any "RESPONSECODE" pairs, then outputs untagged messages via "send_untagged", then sends a tagged OK with the given "MESSAGE".

bad_command REASON

Sends any untagged updates to the client using "send_untagged", then sends a tagged "BAD" response with the given "REASON".

valid_mailbox NAME

Returns false and calls "bad_command" if the given "NAME" is a valid name for a mailbox. This only checks that is passes UTF-7 encoding checks, and that it contains no 8-bit characters. If the name is valid, simply returns 1.

log SEVERITY, MESSAGE

Defers to "log" in Net::IMAP::Server::Connection.

out MESSAGE

Identical to "out" in Net::IMAP::Server::Connection.