Glossary Item Box
In IMAP, there are one or more mailboxes available on a server. Mailboxes are identified by name. Mailboxes can be thought of like directories in a file system, where a path name constructed using a delimiter defines the position of the directory tree. In the case of IMAP and mailboxes, that delimiter can vary from server to server, but it can be identified for the current server by accessing the Delimiter property. For example, many servers represent the hierarchy using a forward-slash ("\"), and so hierarchical names are structured along the lines of "INBOX\users\guest". Other servers, however, might use a period as a delimiter and represent the same mailbox model using the name "INBOX.users.guest". Although the IMAP protocol does not have a true hierarchical structure for mailboxes, IMAP uses this naming convention to allow applications to manipulate mailboxes in an hierarchical manner.
With the PowerTCP Imap component, the details of mailbox hierarchy are taken care of in order to allow easy access to mailboxes in a familiar fashion. The Imap component provides access to the top level of the mailbox hierarchy through the Imap.MailBoxes property. This property returns a MailboxCollection object, which contains one or more Mailbox objects. These Mailbox objects can either be indexed by position (ex. imap.Mailboxes[1]) or by name (ex. imap.Mailboxes["INBOX"]). The Imap.MailBoxes property is automatically populated when a successful login occurs if the AutoList property is set to true. By default, AutoList is set to true. If it is set to false, then the Imap.MailBoxes property can be populated by calling Imap.MailBoxes.Refresh. The Refresh method can be used at any time to refresh the list of top level mailboxes.
Each Mailbox object also has a Mailboxes property, a MailboxCollection object that represents the child or contained mailboxes in the hierarchy. When this property is first accessed, the Imap component executes an IMAP LIST command behind the scenes to determine what child mailboxes exist. Like Imap.MailBoxes, the MailBox.MailBoxes property can also be refreshed by calling MailBox.MailBoxes.Refresh.
When using these collections and traversing the hierarchy, you do not need to be concerned about names and delimiters. The PowerTCP Imap component handles this parsing for you. If you need access to the name structure, it is provided through two properties of the Mailbox object. The FullName property provides the complete IMAP name of the mailbox (ex. "INBOX\users\guest"), while the MailBox.Name property provides the name of the mailbox at its level of the hierarchy ( ex. "guest"). Both properties are read/write, so you can rename a Mailbox using either property. If the act of renaming a mailbox would position it at a new level in the hierarchy, it is necessary to call Mailbox.Mailboxes.Refresh on its new parent before it will appear in the model.
In addition to being able to access the mailboxes hierarchically through the Mailboxes property, you can also access a particular mailbox or set of mailboxes directly using the List method. The List method returns an array of Mailbox objects based on the parameters passed to it. The reference parameter can be thought of as the "parent" mailbox; the IMAP LIST command will be executed in reference to the name provided in that parameter. The searchTerm parameter is the name to be searched for, and it can contain one of two wildcards: "*", for any characters; and "%", for any characters up to an appearance of the delimiter. Using "%" allows you to perform searches at a particular level in the hierarchy, and it is this type of search that the PowerTCP Imap component uses behind the scenes to build the tree of Mailbox objects.
Send comments on this topic.
Documentation version 3.1.
© 2009 Dart Communications. All rights reserved.