1[comment {-*- tcl -*-}] 2[manpage_begin pop3d::dbox n 1.0.2] 3[copyright {2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Tcl POP3 Server Package}] 5[titledesc {Simple mailbox database for pop3d}] 6[category Networking] 7[require Tcl 8.3] 8[require pop3d::dbox [opt 1.0.2]] 9[description] 10[para] 11 12The package [package pop3d::dbox] provides simple/basic mailbox 13management facilities. Each mailbox object manages a single base 14directory whose subdirectories represent the managed mailboxes. Mails 15in a mailbox are represented by files in a mailbox directory, where 16each of these files contains a single mail, both headers and body, in 17RFC 822 ([uri http://www.rfc-editor.org/rfc/rfc822.txt]) conformant 18format. 19 20[para] 21 22Any mailbox object following the interface described below can be used 23in conjunction with the pop3 server core provided by the package 24[package pop3d]. It is especially possible to directly use the objects 25created by this package in the storage callback of pop3 servers 26following the same interface as servers created by the package 27[package pop3d]. 28 29[para] 30 31[list_begin definitions] 32 33[call [cmd ::pop3d::dbox::new] [opt [arg dbName]]] 34 35This command creates a new database object with an associated global 36Tcl command whose name is [arg dbName]. 37 38[list_end] 39 40The command [cmd dbName] may be used to invoke various operations on 41the database. It has the following general form: 42 43[list_begin definitions] 44[call [cmd dbName] [arg option] [opt [arg "arg arg ..."]]] 45 46[arg Option] and the [arg arg]s determine the exact behavior of the 47command. 48 49[list_end] 50 51[para] 52 53The following commands are possible for database objects: 54 55[list_begin definitions] 56 57[call [arg dbName] [method destroy]] 58 59Destroys the mailbox database and all transient data. The directory 60associated with the object is not destroyed. 61 62[call [arg dbName] [method base] [arg base]] 63 64Defines the base directory containing the mailboxes to manage. If this 65method is not called none of the following methods will work. 66 67[call [arg dbName] [method add] [arg mbox]] 68 69Adds a mailbox of name [arg mbox] to the database. The name must be a 70valid path component. 71 72[call [arg dbName] [method remove] [arg mbox]] 73 74Removes the mailbox specified through [arg mbox], and the mails 75contained therein, from the database. This method will fail if the 76specified mailbox is locked. 77 78[call [arg dbName] [method move] [arg {old new}]] 79 80Changes the name of the mailbox [arg old] to [arg new]. 81 82[call [arg dbName] [method list]] 83 84Returns a list containing the names of all mailboxes in the directory 85associated with the database. 86 87[call [arg dbName] [method exists] [arg mbox]] 88 89Returns true if the mailbox with name [arg mbox] exists in the 90database, or false if not. 91 92[call [arg dbName] [method locked] [arg mbox]] 93 94Checks if the mailbox specified through [arg mbox] is currently locked. 95 96[call [arg dbName] [method lock] [arg mbox]] 97 98This method locks the specified mailbox for use by a single connection 99to the server. This is necessary to prevent havoc if several 100connections to the same mailbox are open. The complementary method is 101[method unlock]. The command will return true if the lock could be set 102successfully or false if not. 103 104[call [arg dbName] [method unlock] [arg mbox]] 105 106This is the complementary method to [method lock], it revokes the lock 107on the specified mailbox. 108 109[call [arg dbName] [method stat] [arg mbox]] 110 111Determines the number of messages in the specified mailbox and returns 112this number. This method fails if the mailbox [arg mbox] is not 113locked. 114 115[call [arg dbName] [method size] [arg mbox] [opt [arg msgId]]] 116 117Determines the size of the message specified through its id in 118 119[arg msgId], in bytes, and returns this number. The command will 120return the size of the whole maildrop if no message id was specified. 121 122If specified the [arg msgId] has to be in the range "1 ... [lb][arg dbName] [method stat][rb]" 123 124or this call will fail. If [method stat] was not called before this 125call, [method size] will assume that there are zero messages in the 126mailbox. 127 128 129[call [arg dbName] [method dele] [arg {mbox msgList}]] 130 131Deletes the messages whose numeric ids are contained in the 132[arg msgList] from the mailbox specified via [arg mbox]. 133 134The [arg msgList] must not be empty or this call will fail. 135 136The numeric ids in [arg msgList] have to be in the range "1 ... 137[lb][arg dbName] [method stat][rb]" or this 138call will fail. If [method stat] was not called 139before this call, [method dele] will assume 140that there are zero messages in the mailbox. 141 142 143[call [arg storageCmd] [method get] [arg mbox] [arg msgId]] 144 145Returns a handle for the specified message. This handle is a mime 146token following the interface described in the documentation of 147package [package mime]. The token is [emph read-only]. In other 148words, the caller is allowed to do anything with the token except to 149modify it. 150 151The [arg msgId] has to be in the range "1 ... 152[lb][arg dbName] [method stat][rb]" or this 153call will fail. If [method stat] was not called 154before this call, [method get] will assume 155that there are zero messages in the mailbox. 156 157 158[list_end] 159 160[section {BUGS, IDEAS, FEEDBACK}] 161 162This document, and the package it describes, will undoubtedly contain 163bugs and other problems. 164 165Please report such in the category [emph pop3d] of the 166[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 167 168Please also report any ideas for enhancements you may have for either 169package and/or documentation. 170 171 172[keywords pop3 internet network protocol {rfc 822}] 173[manpage_end] 174