This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Net/Hotline/FileInfoItem, Next: Net/Hotline/FileListItem, Prev: Net/Hotline/Client, Up: Module List File object used internally by Net::Hotline::Client *************************************************** NAME ==== Net::Hotline::FileInfoItem - File object used internally by Net::Hotline::Client SYNOPSIS ======== use Net::Hotline::FileInfoItem; $file = new Net::Hotline::FileInfoItem; $file->name("smile"); $file->comments("A happy file."); ... DESCRIPTION =========== Net::Hotline::FileInfoItem is a simple class for storing and retrieving file information, You should never have to create your own Net::Hotline::FileInfoItem objects when using Net::Hotline::Client. Getting and (to a lesser extent) setting attributes is all that should be necessary. CONSTRUCTION ============ new Creates a new Net::Hotline::FileInfoItem object with all attributes set to undef. METHODS ======= All the Net::Hotline::FileInfoItem methods are simple attribute get/set routines. If given an argument, they set an attribute. In all cases, they return the current value of the attribute. comment TEXT The file comments (as seen in the Mac OS Finder). ctime NUM The creation time of the file, given as a Mac OS native time value. Add the constant Net::Hotline::Constants::HTLC_MACOS_TO_UNIX_TIME to it to change it to seconds since the Unix epoch. creator TEXT The file creator, given as a four-letter Mac OS creator code ("TTXT", "SIT!", etc.) name TEXT The file name. icon The file icon given as a four-letter code. mtime NUM The modification time of the file, given as a Mac OS native time value. Add the constant Net::Hotline::Constants::HTLC_MACOS_TO_UNIX_TIME to it to change it to seconds since the Unix epoch. ctime NUM The creation time of the file, given as a Mac OS native time value. Add the constant Net::Hotline::Constants::HTLC_MACOS_TO_UNIX_TIME to it to change it to seconds since the Unix epoch. size NUM The size of the file in bytes. type TEXT The file type, given as a four-letter Mac OS type code ("TEXT", "PICT", etc.), Net::Hotline::Constants::HTLC_INFO_FOLDER_TYPE for folders, and Net::Hotline::Constants::HTLC_INFO_FALIAS_TYPE for folder aliases. AUTHOR ====== John C. Siracusa (siracusa@mindspring.com) COPYRIGHT ========= Copyright(c) 1999 by John Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Hotline/FileListItem, Next: Net/Hotline/PrivateChat, Prev: Net/Hotline/FileInfoItem, Up: Module List File object used internally by Net::Hotline::Client *************************************************** NAME ==== Net::Hotline::FileListItem - File object used internally by Net::Hotline::Client SYNOPSIS ======== use Net::Hotline::FileListItem; $file = new Net::Hotline::FileListItem; $file->name("foo.txt"); $file->type("TEXT"); ... DESCRIPTION =========== Net::Hotline::FileListItem is a simple class for storing and retrieving file information, You should never have to create your own Net::Hotline::FileListItem objects when using Net::Hotline::Client. Getting and (to a lesser extent) setting attributes is all that should be necessary. CONSTRUCTION ============ new Creates a new Net::Hotline::FileListItem object with all attributes set to undef (or zero for numeric attributes). METHODS ======= All the Net::Hotline::FileListItem methods are simple attribute get/set routines. If given an argument, they set an attribute. In all cases, they return the current value of the attribute. creator TEXT The file creator, given as a four-letter Mac OS creator code ("TTXT", "SIT!", etc.) name TEXT The file name. size NUM The size of the file in bytes. type TEXT The file type, given as a four-letter Mac OS type code ("TEXT", "PICT", etc.) or Net::Hotline::Constants::HTLC_FOLDER_TYPE for folders. AUTHOR ====== John C. Siracusa (siracusa@mindspring.com) COPYRIGHT ========= Copyright(c) 1999 by John Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Hotline/PrivateChat, Next: Net/Hotline/Task, Prev: Net/Hotline/FileListItem, Up: Module List Private chat object used internally by Net::Hotline::Client *********************************************************** NAME ==== Net::Hotline::PrivateChat - Private chat object used internally by Net::Hotline::Client SYNOPSIS ======== use Net::Hotline::PrivateChat; $pchat = new Net::Hotline::PrivateChat; $pchat->subject("Issue 1: Monkey beards"); $pchat->reference(0x313337); ... DESCRIPTION =========== Net::Hotline::PrivateChat is a simple class for storing and retrieving private chat information, You should never have to create your own Net::Hotline::PrivateChat objects when using Net::Hotline::Client. Getting and (to a lesser extent) setting attributes is all that should be necessary. CONSTRUCTION ============ new REF, USERLIST, SUBJECT Creates a new Net::Hotline::PrivateChat object with the reference REF, userlist USERLIST, and subject SUBJECT, where REF is a number, USERLIST is a reference to a hash of Net::Hotline::User objects keyed by socket number, and SUBJECT is a string. Any missing arguments will be set to undef. METHODS ======= All the Net::Hotline::PrivateChat methods are simple attribute get/set routines. If given an argument, they set an attribute. In all cases, they return the current value of the attribute. reference NUM The private chat reference number. subject TEXT The subject of the private chat. userlist HASHREF The list of users in the private chat. AUTHOR ====== John C. Siracusa (siracusa@mindspring.com) COPYRIGHT ========= Copyright(c) 1999 by John Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Hotline/Task, Next: Net/Hotline/TrackerListItem, Prev: Net/Hotline/PrivateChat, Up: Module List Task object used internally by Net::Hotline::Client *************************************************** NAME ==== Net::Hotline::Task - Task object used internally by Net::Hotline::Client SYNOPSIS ======== use Net::Hotline::Task; $task = new Net::Hotline::Task; $task->start(time()); $task->num($num++); ... DESCRIPTION =========== Net::Hotline::Task is a simple class for storing and retrieving task information, You should never have to create your own Net::Hotline::Task objects when using Net::Hotline::Client. Getting and (to a lesser extent) setting attributes is all that should be necessary. CONSTRUCTION ============ new NUM, TYPE, START, SOCKET, PATH With no arguments, creates a new Net::Hotline::Task object with all attributes set to undef. With three or four arguments (PATH is optional), creates a new Net::Hotline::Task object with task number NUM, task type TYPE, start time START, user socket number SOCKET, and file path PATH. METHODS ======= All the Net::Hotline::Task methods are simple attribute get/set routines. If given an argument, they set an attribute. In all cases, they return the current value of the attribute. error EXPR The error state of the task. A true value means there was an error. error_text TEXT The error message text. This only applies if error() returns a true value. finish TIME The time (in platform-native time format, i.e. seconds since the epoch on a Unix system) that a task completed. num NUMBER The unique task number. Task numbers increase sequentially. path PATH The path information associated with a task (if any). In situations where two paths may be associated with a task (a "move file" task, for example), a reference to an array containing the paths will be returned. socket NUMBER The unique user socket number associated with a task (if any). start TIME The time (in platform-native time format) that a task was started. type TASK_TYPE The HTLC_TASK_XXX constant specifying the type of task. These constants are defined in Net::Hotline::Constants, and include: HTLC_TASK_KICK Disconnect a user. HTLC_TASK_LOGIN Log into server. HTLC_TASK_NEWS Get the news. HTLC_TASK_NEWS_POST Post to news. HTLC_TASK_FILE_DELETE Delete a file. HTLC_TASK_FILE_INFO Get file information. HTLC_TASK_FILE_LIST Get a file list. HTLC_TASK_FILE_MKDIR Create a new folder. HTLC_TASK_FILE_MOVE Move a file. HTLC_TASK_SEND_MSG Send a private message. HTLC_TASK_SET_INFO Set file information. HTLC_TASK_USER_INFO Get user information. HTLC_TASK_USER_LIST Get the userlist. AUTHOR ====== John C. Siracusa (siracusa@mindspring.com) COPYRIGHT ========= Copyright(c) 1999 by John Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Hotline/TrackerListItem, Next: Net/Hotline/User, Prev: Net/Hotline/Task, Up: Module List File object used internally by Net::Hotline::Client *************************************************** NAME ==== Net::Hotline::TrackerListItem - File object used internally by Net::Hotline::Client SYNOPSIS ======== use Net::Hotline::TrackerListItem; $file = new Net::Hotline::TrackerListItem; $file->address("hotline.foo.com"); $file->port(5500); ... DESCRIPTION =========== Net::Hotline::TrackerListItem is a simple class for storing and retrieving tracked server information, You should never have to create your own Net::Hotline::TrackerListItem objects when using Net::Hotline::Client. Getting and (to a lesser extent) setting attributes is all that should be necessary. CONSTRUCTION ============ new ADDRESS, PORT, NUM_USERS, NAME, DESCRIPTION With exactly five arguments, creates a new Net::Hotline::TrackerListItem object with all attributes set. With no arguments, creates a new Net::Hotline::TrackerListItem object with all attributes set to undef. METHODS ======= All the Net::Hotline::TrackerListItem methods are simple attribute get/set routines. If given an argument, they set an attribute. In all cases, they return the current value of the attribute. address TEXT The IP address of the server. port NUM The port the server is running on. num_users NUM The (claimed) number of users connected to the server. name TEXT The server name, as set by the server administrator (i.e. "Ambrosia Software" or "Myth Central") description TEXT The server description, as set by the server administrator. AUTHOR ====== John C. Siracusa (siracusa@mindspring.com) COPYRIGHT ========= Copyright(c) 1999 by John Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/Hotline/User, Next: Net/ICB, Prev: Net/Hotline/TrackerListItem, Up: Module List User object used internally by Net::Hotline::Client *************************************************** NAME ==== Net::Hotline::User - User object used internally by Net::Hotline::Client SYNOPSIS ======== use Net::Hotline::User; $user = new Net::Hotline::User; $user->nick("joe blow"); $user->icon(128); print "Nick: ", $user->nick(), "\n"; ... DESCRIPTION =========== Net::Hotline::User is a simple class for storing and retrieving user information, You should never have to create your own Net::Hotline::User objects when using Net::Hotline::Client. Getting and setting attributes is all that should be necessary. CONSTRUCTION ============ new SOCKET, NICK, LOGIN, ICON, COLOR With no arguments, creates a new Net::Hotline::User object with all attributes set to undef. The other option is to supply exactly 5 arguments as listed above. METHODS ======= All the Net::Hotline::User methods are simple attribute get/set routines. If given an argument, they set an attribute. In all cases, they return the current value of the attribute. color NUMBER The color of the user in the userlist. Values are numbers from 0 to 3. The hash HTLC_COLORS defined in Net::Hotline::Constants contains number to name color mappings (i.e. $HTLC_COLORS{2} is "red"). Example: use Net::Hotline::Constants qw(HTLC_COLORS); ... print $user->nick(), " is ", $HTLC_COLORS{$user->color()}, "\n"; icon NUMBER The user's icon number. Negative values are accepted. info TEXT User information as a block of "pretty-formatted" text. login TEXT The user's login name. nick TEXT The user's nickname in the userlist. socket NUMBER The user's unique socket number. User's are assigned a socket number whenthey connect to a Hotline server. AUTHOR ====== John C. Siracusa (siracusa@mindspring.com) COPYRIGHT ========= Copyright(c) 1999 by John Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/ICB, Next: Net/ICQ, Prev: Net/Hotline/User, Up: Module List Object oriented interface to an fnet server. ******************************************** NAME ==== Net::ICB - Object oriented interface to an fnet server. SYNOPSIS ======== use Net::ICB qw(:client); $obj = new Net::ICB('user' => "chatter"); ($type, @msg) = $obj->readmsg(); exit unless ($type eq $M_PROTO); ($type, @msg) = $obj->readmsg(); exit unless ($type eq $M_LOGINOK); my $msg = "Hello to the group"; $obj->sendopen($msg); DESCRIPTION =========== `Net::ICB' provides an object interface to a fnet/icb style chat server. FNET or ICB is an old chat protocol dating back to 1988. The original code was written in fortran on some godforsaken machine at UKY by Sean Casey. After the server was rewritten in C, various servers sprung up and died over the years. As of 1998, approximately 4 public servers run, the most popular of which peaks at ~150 people. See http://www.icb.net/ for more information. PROTOCOL ======== The ICB protocol uses only ascii text. Packets consist of a single byte of size, followed by up to 254 bytes of data. The data block contains a leading byte describing the data type, the data itself, and a trailing null. Multiple fields in the data are delimited by \001. Turn on debugging and it'll become obvious. CLASS METHODS ============= new - create a new Net::ICB object. my $obj = Net::ICB->new( [host => $hostname,] [port => $port,] [user => $username,] [nick => $nickname,] [group => $initialgroup,] [cmd => $command,] [passwd => $password] ); Constructs a new Net::ICB object. A new object is returned on success, null on failure with a `carp()'ed' error message. If any arguments are given, then new() calls connect() to establish a connection to an ICB server. Also see connect(). Any missing parameters are taken from the *$DEF_** variables defined in Net::ICB.pm. version - return the module version number. my $ver = Net::ICB->version(); print $obj->version(); Returns the Net::ICB.pm version number. Also available as a instance method. INSTANCE METHODS ================ connect - connect to an ICB server. $obj->connect( [host => $hostname,] [port => $port,] [user => $username,] [nick => $nickname,] [group => $initialgroup,] [cmd => $command,] [passwd => $password] ); Establishes a connection to an ICB server and sends a login packet. Any missing parameters are taken from the *$DEF_** variables defined in Net::ICB.pm. Unlike new(), connect() creates a connection even in the absence of arguments. Returns null on failure, check error() for specific failure code. error - return the internal error string. die $obj->error() unless ($obj->connect()); Returns a string pertaining to the last error. This string is not cleared between operations: check the return code first. clearerr - clear the internal error string. $obj->clearerr(); Clears the internal error string. debug - set and return the internal debug level. $obj->debug(1); print "Debug: ", $obj->debug(), "\n"; With an argument, debug() sets the internal debug level and returns the new value. Without, the current debug level is returned. fd - return socket file descriptor. fileno($obj->fd()); Returns the socket associated with the currect connection. sendopen - send an open message to the current group. $obj->sendopen($msg); Sends a public message to the user's current group. Returns null on failure, check error() for details. sendpriv - send a private message to a particular user. $obj->sendpriv($nickname, $msg); $obj->sendpriv("$nickname $msg"); Sends a private message to a named user. Returns null on failure, check error() for details. sendcmd - send an arbitrary command to the server. $obj->sendcmd("beep", $username); $obj->sendcmd("g", $groupname); Sends an arbitrary command to the server. Available commands vary by server but most provide m, w, g, name. Try "/m server help" or "/s_help". Returns null on failure, check error() for details. EXAMPLES ======== Alter the default variables from a client. use Net::ICB qw(:defaults); $DEF_HOST = "myhost.com"; $DEF_GROUP = "myhost"; Check who is on a server. use Net::ICB qw(:client); my $who = Net::ICB->new(cmd => 'w'); die unless $who; while (my ($type, @packet) = $who->readmsg()) { exit if ($type eq $M_EXIT); print "@packet\n"; } AUTHOR ====== John M Vinopal, banshee@resort.com  File: pm.info, Node: Net/ICQ, Next: Net/IMAP, Prev: Net/ICB, Up: Module List Pure Perl interface to an ICQ server ************************************ NAME ==== Net::ICQ - Pure Perl interface to an ICQ server SYNOPSIS ======== use Net::ICQ; $icq = Net::ICQ->new($uin, $password); $icq->connect(); $icq->add_handler('SRV_SYS_DELIVERED_MESS', \&on_msg); $params = { 'type' => 1, 'text' => 'Hello world', 'receiver_uin' => 1234 }; $icq->send_event('CMD_SEND_MESSAGE', $params); $icq->start(); DESCRIPTION =========== `Net::ICQ' is a class implementing an ICQ client interface in pure Perl. CONSTRUCTOR =========== * new (uin, password [, server [, port]]) Creates a new Net::ICQ object. A Net::ICQ object represents a single user logged into a specific ICQ server. The UIN and password to use are specified as the first two parameters. Server and port are optional, and default to 'icq.mirabilis.com' and '4000', respectively. Also, environment variables will be checked as follows: uin - ICQ_UIN password - ICQ_PASS server - ICQ_SERVER port - ICQ_PORT Constructor parameters have the highest priority, then environment variables. The built-in defaults (for server and port only) have the lowest priority. If either a UIN or password is not provided either directly or through environment variables, new() will return undef. Note that after calling new() you must next call connect() before you can send and receive ICQ events. METHODS ======= All of the following methods are instance methods; you must call them on a Net::ICQ object (for example, $icq->start). * connect Connects the Net::ICQ object to the server. * disconnect Disconnects the Net::ICQ object from the server. * connected Returns true if the Net::ICQ object is connected to the server, and false if it is not. * start If you're writing a fairly simple application that doesn't need to interface with other event-loop-based libraries, you can just call start() to begin communicating with the server. Note that start() will not return until the Net::ICQ object is disconnected from the server, either by the server itself or by your event-handler code calling disconnect(). * do_one_loop If you don't want to (or can't) call the start() method, you must continuously call do_one_loop when your Net::ICQ object is connected to the server. It uses select() to wait for data from the server and other ICQ clients, so it won't use CPU power even if you call it in a tight loop. If you need to do other processing, you could call do_one_loop as infrequently as once every few seconds. This method does one processing loop, which involves looking for incoming data from the network, calling registered event handlers, sending acknowledgements for received packets, transmitting outgoing data over the network, and sending keepalives to the server to tell it that we are still online. If it is not called often enough, you will not be notified of incoming events in a timely fashion, or the server might even think you have disconnected and start to ignore you. * add_handler(command_number, handler_ref) Sets the handler function for a specific ICQ server event. command_number specifies the event to handle. You may use either the numeric code or the corresponding string code. See the SERVER EVENTS section below for the numeric and string codes for all the events, along with descriptions of each event's function and purpose. handler_ref is a code ref for the sub that you want to handle the event. See the HANDLERS section for how a handler works and what it needs to do. * send_event(command_number, params) Sends an event to the server. command_number specifies the event to be sent. You may use either the numeric code or the corresponding string code. See the CLIENT EVENTS section below for the numeric and string codes for all the events, along with descriptions of each event's function and purpose. params is a reference to a hash containing the parameters for the event. See the CLIENT EVENTS section for an explanation of the correct parameters for each event. CLIENT EVENTS ============= Client events are the messages an ICQ client, i.e. your code, sends to the server. They represent things such as a logon request, a message to another user, or a user search request. They are sometimes called 'commands' because they represent the 'commands' that an ICQ client can execute. When you ask Net::ICQ to send an event with send_event() (described above), you need to provide 2 things: the event name, and the parameters. Event name ---------- The event name is the first parameter to send_event(), and it specifies which event you are sending. You may either specify the string code or the numeric code. The section CLIENT EVENT LIST below describes all the events and gives the codes for each. For example: when sending a text message to a user, you may give the event name as either the string 'CMD_SEND_MESSAGE' or the number 270. The hash `%Net::ICQ::cmd_codes' maps string codes to numeric codes. `keys(%Net::ICQ::cmd_codes)' will produce a list of all the string codes. Parameters ---------- The parameters list is the second parameter to send_event(), and it specifies the data for the event. Every event has its own parameter list, but the general idea is the same. The parameters list is stored as a hashref, where the hash contains a key for each parameter. Almost all the events utilize a regular 1-level hash where the values are plain scalars, but a few events do require 2-level hash. The CLIENT EVENT LIST section lists the parameters for every client event. For example: to send a normal text message with the text 'Hello world' to UIN 1234, the parameters would look like this: { 'type' => 1, 'text' => 'Hello world', 'receiver_uin' => 1234 } A complete example ------------------ Here is the complete code using send_event() to send the message 'Hello world' to UIN 1234: $params = { 'type' => 1, 'text' => 'Hello world', 'receiver_uin' => 1234 }; $icq->send_event('CMD_SEND_MESSAGE', $params);  File: pm.info, Node: Net/IMAP, Next: Net/IMAP/Simple, Prev: Net/ICQ, Up: Module List A client interface to IMAP (Internet Message Access Protocol). ************************************************************** NAME ==== Net::IMAP - A client interface to IMAP (Internet Message Access Protocol). *WARNING: This code is in alpha release. Expect the interface to change release to release.* SYNOPSIS ======== `use Net::IMAP;' DESCRIPTION =========== `Net::IMAP' provides a perl interface to the client portion of IMAP (Internet Message Access Protocol). *add more meat - describe overall design (commands, responses, callbacks, convenience routines* METHODS ======= new $host, %options ------------------- Creates a new `Net::IMAP' object, connects to $host on port 143, performs some preliminary setup of the session, and returns a reference to the object. Once connected, it processes the connection banner sent by the server. If the considers the session to be preauthenticated, new notes the fact, allowing commands to be issued without logging in. The method also issues a capability command, and notes the result. If the server does support IMAP4rev1, the method closes the connection and returns undef. The client will use non-synchronizing literals if the server supports the `LITERAL+' extension (RFC2088) and the `NonSyncLits' options is set to 1. The following `Net::xAP' options are relevant to `Net::IMAP': `Synchronous => 1' `NonSyncLits => 0' `Debug => 0' `InternetDraft => 0' `Net::IMAP' also understands the following options, specific to the module: `EOL => 'lf'' Controls what style of end-of-line processing to presented to the end-programmer. The default, `'lf'', assumes that the programemr wants to fling messages terminated with bare LFs when invoking append, and when fetching messages. In this case, the module will map to/from CRLF accordingly. If `EOL' is set to `'crlf'', the assumption is that the programmer wants messages, or portions of messages, to be terminated with CRLF. It also assumes the programmer is providing messages terminated with the string when invoking the append method, and will not provide an EOL mapping. IMAP COMMAND METHODS ==================== There are numerous commands in the IMAP protocol. Each of these are mapped to a corresponding method in the `Net::IMAP' module. Some commands can only be issued in certain protocol states. Some commands alter the state of the session. These facts are indicated in the documentation for the individual command methods. The following list enumerates the protocol states: Non-authenticated The client has not authenticated with the server. Most commands are unavailable in this state. Authenticated The client has authenticated with the server. Selected The client has opened a mailbox on the server. noop ---- Sends a noop command to the server. It is valid in any protocol state. This method is useful for placating the auto-logout god, or for triggering pending unsolicited responses from the server. capability ---------- The capability method retrieves the capabilities the IMAP server supports. This method is valid in any protocol state. The server sends a capability response back to the client. If the response does not indicate support for the `LITERAL+' extension, the `NonSyncLits' option is forced off. logout ------ Logs off of the server. This method is valid in any protocol state. login $user, $password ---------------------- Logs into the server using a simple plaintext password. This method is only valid when the protocol is in the non-authenticated state. If the server supports RFC2221 (IMAP4 Login Referrals), the completion response could include a referral. See RFC2221 for further information about login referrals. If successful, the session state is changed to *authenticated*. authenticate $authtype, @authinfo --------------------------------- Logs into the server using the authentication mechanism specified in `$authtype'. This method is only valid when the protocol is in the non-authenticated state. The IMAP authenticate command is the same as that documented in RFC2222 (Simple Authentication and Security Layer (SASL)), despite the fact that IMAP predates SASL. If successful, the session state is changed to *authenticated*. The following authentication mechanisms are currently supported: `'login'' This is a variation on the simple login technique, except that the information is transmitted in Base64. This does not provide any additional security, but does allow clients to use authenticate. `'cram-md5'' This implements the authentication mechanism defined in RFC2195 (IMAP/POP AUTHorize Extension for Simple Challenge/Response). It uses keyed MD5 to avoid sending the password over the wire. `'anonymous'' This implements the authentication mechanism defined in RFC2245 (Anonymous SASL Mechanism). Anonymous IMAP access is intended to provide access to public mailboxes or newsgroups. The method returns undef is `$authtype' specifies an unsupported mechanism or if the server does not advertise support for the mechanism. The `has_authtype' method can be used to see whether the server supports a particular authentication mechanism. In general, if the server supports a mechanism supported by `Net::IMAP', the authenticate command should be used instead of the login method. select $mailbox --------------- Opens the specified mailbox with the intention of performing reading and writing. This method is valid only when the session is in the authenticated or selected states. If successful, the server sends several responses: flags, exists, `resent', as well as ok responses containing a `unseen', permanentflags, uidnext, and uidvalidity codes. If also changes the session state to *selected*. If server returns a no response containing a newname response code, this means `$mailbox' does not exist but the server thinks this is because the folder was renamed. In this case, try specifiying the new folder name provided with the newname response code. examine $mailbox ---------------- Opens the specified mailbox in read-only mode. This method is valid only when the session is in the authenticated or selected states. create $mailbox [, $partition] ------------------------------ Creates the specified mailbox. This method is valid only when the session is in the authenticated or selected states. The optional `$partition' argument is only valid with the Cyrus IMAP daemon. Refer to the section 'Specifying Partitions with "create"' the `doc/overview' file for that package for further information. This feature can only be used by administrators creating new mailboxes. Other servers will probably reject the command if this argument is used. The results are undefined if another server accepts a second argument. delete $mailbox --------------- Deletes the specified mailbox. Returns undef if `$mailbox' is the currently open mailbox. This method is valid only when the session is in the authenticated or selected states. rename $oldmailboxname, $newmailboxname [, $partition] ------------------------------------------------------ Renames the mailbox specified in `$oldmailbox' to the name specified in `$newmailbox'. This method is valid only when the session is in the authenticated or selected states. The optional `$partition' argument is only valid with the Cyrus IMAP daemon. Refer to the section 'Specifying Partitions with "rename"' the `doc/overview' file for that package for further information. This feature can only be used by administrators. Other servers will probably reject the command if this argument is used. The results are undefined if another server accepts a third argument. subscribe $mailbox ------------------ Subscribe to the specified `$mailbox'. Subscribing in IMAP is subscribing in Usenet News, except that the server maintains the subscription list. This method is valid only when the session is in the authenticated or selected states. unsubscribe $mailbox -------------------- Unsubscribe from the specified `$mailbox'. This method is valid only when the session is in the authenticated or selected states. list $referencename, $mailbox_pattern ------------------------------------- Send an IMAP list command to the server. This method is valid only when the session is in the authenticated or selected states. Although IMAP folders do not need to be implemented as directories, think of an IMAP reference name as a parameter given to a cd or chdir command, prior to checking for folders matching `$mailbox_pattern'. The `$mailbox_pattern' parameter allows a couple wildcard characters to list subsets of the mailboxes on the server. * Matches zero or more characters at the specified location. * % Like *, matches zero or more characters at the specified location, but does not match hierarchy delimiter characters. If the last character in `$mailbox_pattern' is a %, matching levels of hierarchy are also returned. In other words: subfolders. This method will fail, returning undef, if `$mailbox_pattern' is *. This behavior is not built into the IMAP protocol; it is wired into `Net::IMAP'. Doing otherwise could be rude to both the client and server machines. If you want to know why, imagine doing `list('#news.', '*')' on a machine with a full news feed. The % character should be used to build up a folder tree incrementally. If successful, the server sends a series of list responses. Please note that the `$referencename' is an IMAPism, not a Perl reference. Also note that the wildcards usable in `$mailbox_pattern' are specific to IMAP. Perl regexps are not usable here. lsub $referencename, $mailbox_pattern ------------------------------------- Sends an IMAP `lsub' command to the server. The `lsub' command is similar to the list command, except that the server only returns subscribed mailboxes. This method is valid only when the session is in the authenticated or selected states. The parameters are the same as those for the list method. If successful, the server sends a series of `lsub' responses. status $mailbox, @statusattrs ----------------------------- Retrieves status information for the specified `$mailbox'. This method is valid only when the session is in the authenticated or selected states. Per RFC2060, the `@statusattrs' can contain any of the following strings: * messages The number of messages in the mailbox. * recent The number of messages with the `\recent' flag set. * uidnext The UID expected to be assigned to the next mailbox appended to the mailbox. This requires some explanation. Rather than using this value for prefetching the next UID, it should be used to detect whether messages have been added to the mailbox. The value will not change until messages are appended to the mailbox. * uidvalidity The unique identifier validity value of the mailbox. * unseen The number of messages without the `\seen' flag set. This method will fail, returning undef if `$mailbox' is the currently open mailbox. If successful, the server sends one or more status responses. The status operation can be rather expensive on some folder implementations, so clients should use this method sparingly. append $mailbox, $message [, Flags => $flaglistref] [, Date => $date] --------------------------------------------------------------------- Appends the email message specified in `$message' to the mailbox specified in `$mailbox'. This method is valid only when the session is in the authenticated or selected states. In general, the email message should be a real RFC822 message, although exceptions such as draft messages are reasonable in some situations. Also note that the line terminators in `$message' need to be CRLF. The Flags option allows a set of flags to be specified for the message when it is appended. Servers are not required to honor this, but most, if not all, do so. The Date option forces the internaldate to the specified value. If `$date' is a string, the format of the string is `dd-mmm-yyyy hh:mm:ss [-+]zzzz', where dd is the day of the month (starting from 1), `mmm' is the three-character abbreviation for the month name, `yyyy' is the 4-digit year, `hh' is the hour, mm is the minutes, ss is the seconds, and `[-+]zzzz' is the numeric timezone offset. This happens to be the same format returned by the `internaldate' item from the fetch command. If `$date' is a list reference, it is expected to contain two elements: a time integer and a timezone offset string. The timezone string is expected to be formatted as `[-+]zzzz'. These two values will be used to synthesize a string in the format expected by the IMAP server. As with the Flags options, servers are not required to honor the Date option, but most, if not all, do so. Note that the options are specified at the end of the list of method arguments. This is due to the fact that it is possible to have a `$mailbox' named Flags or Date. Processing the options at the end of the argument list simplifies argument processing. The order of the arguments will be changed if enough people complain. If server returns a no response containing a `trycreate' response code, this means `$mailbox' does not exist but the server thinks the command would have succeeded if the an appropriate create command was issued. On the other hand, failure with no `trycreate' response code generally means that a create should not be attempted. check ----- Ask the server to perform a checkpoint of its data. This method is valid only when the session is in the selected state. While not always needed, this should be called if the client issues a large quantity of updates to a folder in an extended session. close ----- Close the current mailbox. This method is valid only when the session is in the selected state. If successful, the session state is changed to *authenticated*. expunge ------- Delete messages marked for deletion. This method is valid only when the session is in the selected state. If successful, the server sends a series of expunge responses. It will return undef is the mailbox is marked read-only. search [Charset => $charset,] @searchkeys ----------------------------------------- Searches the mailbox for messages matching the criteria contained in `@searchkeys'. This method is valid only when the session is in the selected state. The `@searchkeys' list contains strings matching the format described in Section 6.4.4 of RFC2060. If successful, the server send zero or more search responses. Lack of a search response means the server found no matches. Note that the server can send the results of one search in multiple responses. fetch $msgset, 'all'|'full'|'fast'|$fetchattr|@fetchattrs --------------------------------------------------------- Retrieves data about a set of messages. This method is valid only when the session is in the selected state. The `$msgset' parameter identifies the set of messages from which to retrieve the items of interest. The notation accepted is similar to that found in `.newsrc' files, except that : is used to specify ranges, instead of -. Thus, to specify messages 1, 2, 3, 5, 7, 8, 9, the following string could be used: `'1:3,5,7:9''. The character * can be used to indicate the highest message number in the mailbox. Thus, to specify the last 4 messages in an 8-message mailbox, you can use `'5-*''. The following list enumerates the items that can be retrieved with fetch. Refer to Section 6.4.5 of RFC2060 for a description of each of these items. * body[$section]<$partial> * body.peek[$section]<$partial> Important: the response item returned for a `body.peek' is body. * bodystructure * body * envelope * flags * internaldate * rfc822 * rfc822.header * rfc822.size * rfc822.text * uid Please note that the items returning messages, or portion of messages, return strings terminated with CRLF. RFC2060 also defines several items that are actually macros for other sets of items: * all A macro equivalent to `('flags', 'internaldate', 'rfc822.size', 'envelope')'. * full A macro equivalent to `('flags', 'rfc822.size', 'envelope', 'body')'. * fast A macro equivalent to `('flags', 'internaldate', 'rfc822.size')'. The all, `full', and fast items are not intended to be used with other items. If successful, the server responses with one or more fetch responses. If the completion response from a fetch command is no, the client should send a noop command, to force any pending expunge responses from the server, and retry the fetch command with `$msgset' adjusted accordingly. store $msgset, $itemname, @storeattrflags ----------------------------------------- Sets various attributes for the messages identified in `$msgset'. This method is valid only when the session is in the selected state. The `$msgset' parameter is described in the section describing fetch. The `$itemname' can be one of the following: * flags Replaces the current flags with the flags specified in `@storeattrflags'. * +flags Adds the flags specified in `@storeattrflags' to the current flags. * -flags Removes the flags specified in `@storeattrflags' from the current flags. The `$itemname' can also have `.silent' appended, which causes the server to not send back update responses for the messages. If successful, and `.silent' is used used in `$itemname', the server response with a series of fetch responses reflecting the updates to the specified messages. If the completion response from a store command is no, the client should send a noop command, to force any pending expunge responses from the server, and retry the store command with `$msgset' adjusted accordingly. The `@storeattrflags' is a list of flag strings. copy $msgset, $mailbox ---------------------- Copy the messages `$msgset' to the specified mailbox. This method is valid only when the session is in the selected state. The `$msgset' parameter is described in the section describing fetch. If server returns a no response containing a `trycreate' response code, this means `$mailbox' does not exist but the server thinks the command would have succeeded if the an appropriate create command was issued. On the other hand, failure with no `trycreate' response code generally means that a create should not be attempted. uid_copy $msgset, $mailbox -------------------------- A variant of copy that uses UIDs in `$msgset', instead of message numbers. This method is valid only when the session is in the selected state. uid_fetch $msgset, 'all'|'full'|'fast'|$fetchattr|@fetchattrs ------------------------------------------------------------- A variant of fetch that uses UIDs, instead of message numbers, in `$msgset' and fetch responses. This method is valid only when the session is in the selected state. uid_search [Charset => $charset,] @searchkeys --------------------------------------------- A variant of search that uses UIDs, instead of message numbers, in `$msgset' and search responses. This method is valid only when the session is in the selected state. uid_store $msgset, $itemname, @storeattrflags --------------------------------------------- A variant of store that uses UIDs, instead of message numbers, in `$msgset' and fetch responses. This method is valid only when the session is in the selected state. CONVENIENCE ROUTINES ==================== In addition to the core protocol methods, `Net::IMAP' provides several methods for accessing various pieces of information. is_preauth ---------- Returns a boolean valud indicating whether the IMAP session is preauthenticated. banner ------ Returns the banner string issued by the server at connect time. capabilities ------------ Returns the list of capabilities supported by the server, minus the authentication capabilities. The list is not guaranteed to be in any specific order. has_capability $capname ----------------------- Returns a boolean value indicating whether the server supports the specified capability. authtypes --------- Returns a list of authentication types supported by the server. has_authtype $authname ---------------------- Returns a boolean value indicating whether the server supports the specified authentication type. qty_messages ------------ Returns the quantity of messages in the currently selected folder. qty_recent ---------- Returns the quantity of recent messages in the currently selected folder. first_unseen ------------ Returns the message number of the first unseen messages in the currently selected folder. uidvalidity ----------- Returns the uidvalidity value for the currently selected folder. This is useful for IMAP clients that cache data in persistent storage. Cache data for a mailbox should only be considered valid if the uidvalidity is the same for both cached data and the remote mailbox. See Section 2.3.1.1 of RFC2060 for further details. uidnext ------- Returns the uidnext value for the currently selected folder. permanentflags -------------- Returns the list of permanent flags the server has identified for the currently open mailbox. If a `\*' flag is present, the server allows new persistent keywords to be created. is_permanentflag $flag ---------------------- Returns a boolean value indicating whether the server considers $flag to be a permanent flag. flags ----- Returns a list of the flags associated with the mailbox. has_flag $flag -------------- Returns a boolean value indicating whether the given $flag is defined for the mailbox. mailbox ------- Returns the name of the currently open mailbox. Returns undef if no mailbox is currently open. is_readonly ----------- Returns a boolean value indicating whether the currently open mailbox is read-only. The following methods are available if the server advertises support for RFC2342 (IMAP4 Namespace). Refer to that RFC for additional information. ************************************************************************************************************************************************** NAMESPACE EXTENSION =================== The following methods are available if the server advertises support for RFC2342 (IMAP4 Namespace). Refer to that RFC for additional information. namespace --------- Sends a namespace command to the server, if the server advertises support for the extension extension. ACCESS CONTROL EXTENSION ======================== The following methods are available if the server advertises support for RFC2086 (IMAP4 ACL Extension). Refer to that RFC for additional information. setacl $mailbox, $identifier, $modrights ---------------------------------------- Sets the access control list for $identifier on `$mailbox' according to the rights contained in `$modrights'. The $identifier typically identifies an account name, but can also specify abstract entities, such as groups. The format for `$modrights' is documented in RFC2086. getacl $mailbox --------------- Retrieves the access control list for `$mailbox'. deleteacl $mailbox, $identifier ------------------------------- Deletes all access control list entries for $identifier from `$mailbox'. listrights $mailbox, $identifier -------------------------------- List the rights available to $identifier for `$mailbox'. myrights $mailbox ----------------- List the rights the current user has for `$mailbox'. QUOTA EXTENSION =============== The following methods are available if the server advertises support for RFC2087 (IMAP4 Quota Extension). Refer to that RFC for additional information. getquota $quotaroot ------------------- Lists the resource usage and limits for `$quotaroot'. setquota $quotaroot, @setquotalist ---------------------------------- Sets the resource limits for `$quotaroot' to `@setquotalist'. Valid values for `@setquotalist' are server-dependant. getquotaroot $mailbox --------------------- Lists the quota roots for `$mailbox'. UIDPLUS EXTENSION ================= The following method is available if the server advertises support for RFC2359 (IMAP4 UIDPLUS Extension). Refer to that RFC for additional information. uid_expunge $msgset ------------------- A variant of expunge that allows the operation to be narrowed to the messages with UIDs specified in `$msgset'. The `$msgset' parameter is described in the section describing fetch. CALLBACKS ========= Many of the command methods result in the server sending back response data. `Net::IMAP' processes each response by parsing the data, packages it in an appropriate object, and optionally calls a programmer-defined callback for the response. This callback mechanism is how programmers get access to the data retrieved from the server. set_untagged_callback $item, $coderef ------------------------------------- Assigns a programmer-defined code reference to the associated untagged response. When an untagged response matching $item is received, `$coderef' is called, with the IMAP object and the associated response object passed as parameters. The default callback for the ok, `bye', `bad', and no untagged responses includes code to output the text from alert responses to stderr, using carp. If you set your own callback for these responses, be sure to code handle alert codes. Per Section 7.1 of RFC2060, clients are required to clearly display alert messages to users. RESPONSE OBJECTS ================ As mention in the previous section, responses are parsed and packaged into response objects, which are then passed to callbacks. Each type of response has a corresponding object class. This section describes the various response objects provided. All of the class names itemized below are prefixed with `Net::IMAP'. As a general rule, IMAP `nil' items are set to undef in the parsed data, and IMAP parenthetical lists are converted to list references (of one form or another). In addition, atoms, quoted strings, and literals are presented as Perl strings. The condition responses (ok, no, `bad', `bye', and `preauth') can include a response code. Refer to Section 7.1 in RFC2060 for a description of each of the standard response codes. Response ======== This is the object class for completion responses. is_tagged --------- Returns a boolean value indicating whether the response is tagged. In the case of tagged completion responses, this value is always 1. has_trycreate ------------- Returns a boolean value indicating whether the `TRYCREATE' response code is present in the response. This can be used after a failed append or copy command to determine whether the server thinks the operation would succeed if a create was issued for the associated mailbox. UntaggedResponse ================ This class is common to all untagged server responses. tag --- Returns a string containing the tag associated with the response. In the case of untagged responses, this is always *. is_tagged --------- Returns a boolean value indicating whether the response is tagged. Obviously, in the case of untagged responses, this value is always 0. parent ------ Returns a reference to the parent IMAP object. Ok == This is a container for untagged ok responses from the server. code ---- Returns a list reference containing response code elements in the response. Returns undef if no response code is present. name ---- Returns the name of the response. In the case of Ok, this returns 'ok'. This method is provided as a convenience for end-programmers wanting to write one common subroutine for one or more of the responses Ok, No, Bad, and Bye. No == This is a container for untagged no responses from the server. Bad === This is a container for untagged `bad' responses from the server. Bye === This is a container for untagged `bye' responses from the server. Expunge ======= This is a container for expunge responses from the server. The information returned by qty_messages is automatically updated when expunge responses are received. msgnum ------ Returns the message number specified in the expunge response. Capability ========== This is a container for capability responses. capabilities ------------ Returns the list of capabilities supported by the server, minus the authentication capabilities. The list is not guaranteed to be in any specific order. has_capability $capname ----------------------- Returns a boolean value indicating whether the server supports the specified capability. authtypes --------- Returns a list of authentication types supported by the server. has_authtype $authname ---------------------- Returns a boolean value indicating whether the server supports the specified authentication type. List ==== This is a container for list responses. mailbox ------- Returns the name of the mailbox contained in the object. delimiter --------- Returns the hierarchy delimiter associated with the mailbox. flags ----- Returns a list of the flags associated with the mailbox. has_flag $flag -------------- Returns a boolean value indicating whether the given $flag is defined for the mailbox. List ==== This is a container for `lsub' responses. It provides the same interface as the `Net::IMAP::List' class. Fetch ===== This is a container for fetch responses. Responses for partial fetches bear special mention. While both the starting byte and quantity of bytes are specified when doing partial fetches with the fetch command, the corresponding response will only show the starting byte. In other words, the command `$imap->fetch(1, 'body[]<0.1024>'' will, if successful, result in a fetch response item of `body[]<0>' containing a 1024 octet value. To match a given response for a partial fetch, you might need to use length to match it up with the corresponding item specified in the fetch command. msgnum ------ Returns the message number identified in the response. items ----- Returns the list of data item names contained in the response. The list is not guaranteed to be in any specific order. item $item ---------- Returns the data associated with the specified data item. The following list enumerates the data types associated with each fetch item: envelope Net::IMAP::Envelope bodystructure Net::IMAP::BodyStructure body Net::IMAP::BodyStructure flags Net::IMAP::Flags UID Integer rfc822.size Integer default String Status ====== This is a container for status responses. mailbox ------- Returns a string containing the mailbox the status information is associated with. items ----- Returns the list of status items contains in the status response. item $item ---------- Returns the value of the $item status item. Search ====== This is a container for search responses. msgnums ------- Returns the list of message numbers contained in the response. Flags ===== This is a container for flags responses. flags ----- Returns the list of flags contained in the response. has_flag $flag -------------- Returns a boolean value indicating whether the specified flag is contained in the response. As a convenience, the information from the flags response is also stored in the parent `Net::IMAP' object, and is available via `Net::IMAP' versions of the flags and `has_flags' methods. Exists ====== This is a container for exists responses. exists ------ Returns the quantity of messages in the currently selected mailbox. This is information is also available in the qty_messages method in the `Net::IMAP' class. Recent ====== This is a container for recent responses. recent ------ Returns the number of messages with the `\recent' flag set. This information is also available in the qty_recent method in the `Net::IMAP' class. Namespace ========= This is a container for namespace responses. personal [$namespace] --------------------- With no argument specified, returns a list of personal namespaces. If $namespace is specified, returns the delimiter character for the specific personal namespace. other_users [$namespace] ------------------------ With no argument specified, returns a list of other users' namespaces. If $namespace is specified, returns the delimiter character for the specific other users' namespace. shared [$namespace] ------------------- With no argument specified, returns a list of shared namespaces. If $namespace is specified, returns the delimiter character for the specific shared namespace. ACL === This is a container for `acl' responses> mailbox ------- Returns the name of the mailbox associated with the given ACL data. identifiers ----------- Returns a list of identifiers contained in the ACL data. identifier $identifier ---------------------- Listrights ========== This is a container for `listrights' responses. mailbox ------- Returns the name of the mailbox associated with the given rights. identifier ---------- Returns a string containing the identifier associated with the rights. rights ------ Returns a string containing the rights contained in the response. Myrights ======== This is a container for `myrights' responses> mailbox ------- Returns the name of the mailbox associated with the given rights. rights ------ Returns a string containing the rights contained in the response. Quota ===== This is a container for `quota' responses. quotaroot --------- Returns a string containing the name of the quota root in the response. quotas ------ Returns a list of the quotas contained in the response. usage $quota ------------ Returns the usage value associated with the given `$quota'. Returns undef is the given `$quota' is not present in the response. limit $quota ------------ Returns the usage limit associated with the given `$quota'. Returns undef is the given `$quota' is not present in the response. Quotaroot ========= This is a container for quotaroot responses. mailbox ------- Returns the name of the mailbox associated with the quotaroot data. quotaroots ---------- If called in an array context, returns the list of quotaroots associated with the mailbox. If called in a scalar context, returns a list reference. MISC FETCH OBJECTS ================== A fetch response can be relatively complicated. This section documents various classes and methods associated with the various pieces of information available in fetch responses. BodyStructure ============= This is a container for bodystructure items in fetch responses. type ---- Returns a string containing the MIME type of the message. This is the left-hand portion of a MIME media type. For example, the type of `text/plain' is text. subtype ------- Returns a string containing the MIME subtype of the message. This is the right-hand portion of a MIME media type. For example, the subtype of `text/plain' is `plain'. parameters ---------- Returns a reference to a hash containing the key/value attribute pairs in the `Content-Type' field. If, for example, the `Content-Type' field was: Content-Type: text/plain; charset=us-ascii The hash would contain one entry the a key of charset, and a value of `us-ascii'. The key is always forced to be lowercase, but the case of the value is retained from the server. disposition ----------- Returns the disposition type in the `Content-Disposition' field. Returns undef if no such field exists. disp_parameters --------------- Returns a reference to a hash containing the key/value attributer pairs in the `Content-Disposition' field. A reference to an empty hash is returned if no such field exists, or if there are no parameters in the field. language -------- Returns a reference to a list of the language tags present in the `Content-Language' field. Returns a reference to an empty hash if no such field is present. Multipart ========= This is a container for C COPYRIGHT ========= Copyright (c) 1997-1999 Kevin Johnson . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.