1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
=head1 NAME
Mail::Server::IMAP4::List - folder related IMAP4 answers
=head1 SYNOPSIS
my $imap = Mail::Server::IMAP4::List->new
( folders => $folders # Mail::Box::Identity
, inbox => $inbox # Mail::Box
, delimiter => '#'
);
my $imap = Mail::Server::IMAP4::List->new(user => $user);
print $imap->list(...); # for LIST command
=head1 DESCRIPTION
=head1 METHODS
=head2 Constructors
Mail::Server::IMAP4::List-E<gt>B<new>(USER)
=over 4
Create a (temporary) object to handle the LIST requests for
a certain user, based upon a set of folders. The data is kept by
L<Mail::Box::Identity|Mail::Box::Identity> and L<Mail::Box::Collection|Mail::Box::Collection> objects, which
mean that the folders will not be opened to answer these questions.
Option --Defined in --Default
delimeter '/'
folders <from user>
inbox <from user>
user <undef>
. delimeter STRING|CODE
=over 4
Either the constant delimiter, or a code reference which will get passed
a folder name and should return the delimiter string used in that name.
If that folder name is empty, the default delimiter must be reported.
See L<delimiter()|Mail::Server::IMAP4::List/"Attributes"> for an example.
=back
. folders OBJECT
=over 4
You need to specify either a set of folders explicitly or via the
user. Some L<Mail::Box::Identity|Mail::Box::Identity> OBJECT is needed.
=back
. inbox BOOLEAN
=over 4
For now, only used to see whether there is an inbox, so a truth value will
do. This may change in the future. By default, the flag is set if
C<$user->inbox> is defined.
=back
. user OBJECT
=over 4
A L<Mail::Box::Manage::User|Mail::Box::Manage::User> OBJECT, representing the user who's folders
must get reported.
=back
=back
=head2 Attributes
$obj-E<gt>B<delimiter>([FOLDERNAME])
=over 4
Returns the delimiter string. The foldername is only required when a
CODE reference was specified at initiation.
I<Example:> setting-up an IMAP4 delimeter
sub delim($)
{ my $path = shift;
my ($delim, $root)
= $path =~ m/^(#news\.)/ ? ('.', $1)
= $path =~ m!^/! ? ('/', '/')
: ('/', '');
wantarray ? ($delim, $root) : $delim;
}
my $list = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
print $list->delimiter('abc/xyz'); # returns a / (slash) and ''
print $list->delimiter('#news.feed'); # returns a . (dot) and $news.
print $list->delimiter(''); # returns default delimiter
=back
$obj-E<gt>B<folders>
=over 4
Returns the L<Mail::Box::Identity|Mail::Box::Identity> of the toplevel folder.
=back
$obj-E<gt>B<inbox>
=over 4
Returns the L<Mail::Box|Mail::Box> or filename of the INBOX.
=back
$obj-E<gt>B<user>
=over 4
Returns the L<Mail::Box::Manage::User|Mail::Box::Manage::User> object, if defined.
=back
=head2 IMAP Commands
$obj-E<gt>B<list>(BASE, PATTERN)
=over 4
IMAP's LIST command. The request must be partially decoded, the answer
will need to be encoded.
I<Example:> using IMAP list
my $imap = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
local $" = ';';
my @lines = $imap->list('', ''); # returns the default delimiter
print ">@{$lines[0]}<"; # >(\Noselect);/;<
my @lines = $imap->list('#news',''); # specific delimiter
print ">@{$lines[0]}<"; # >(\Noselect);.;<
my @lines = $imap->list('top/x/', '%');
print ">@$_<," foreach @lines; # >();/;/tmp/x/y<,>(\Marked);/;/tmp/x/z<
=back
=head1 DETAILS
See
=over 4
=item RFC2060: "Internet Message Access Protocol IMAP4v1"
sections 6.3.8 (LIST question) and 7.2.2 (LIST answer)
=back
=head1 REFERENCES
See the MailBox website at L<http://perl.overmeer.net/mailbox/> for more details.
=head1 COPYRIGHTS
Distribution version 2.068.
Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for
other contributors.
Copyright (c) 2001-2006 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
|
