forked from MailCore/MailCore
/
CTCoreFolder.h
321 lines (265 loc) · 12.4 KB
/
CTCoreFolder.h
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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
/*
* MailCore
*
* Copyright (C) 2007 - Matt Ronge
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the MailCore project nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
#import <Foundation/Foundation.h>
#import <libetpan/libetpan.h>
#import "MailCoreTypes.h"
/**
CTCoreFolder is the class used to get and set attributes for a server side folder. It is also the
class used to get a list of messages from the server. You need to make sure and establish a connection
first by calling connect.
*/
@class CTCoreMessage, CTCoreAccount;
@interface CTCoreFolder : NSObject {
struct mailfolder *myFolder;
CTCoreAccount *myAccount;
NSString *myPath;
BOOL connected;
NSError *lastError;
BOOL idling;
int idlePipe[2];
}
/**
If an error occurred (nil or return of NO) call this method to get the error
*/
@property (nonatomic, retain) NSError *lastError;
@property (nonatomic, retain) CTCoreAccount *parentAccount;
/**
This method is used to initialize a folder. This method or the
method in CTCoreAccount folderWithPath can be used to setup a folder.
@param inAccount This parameter must be passed in so the folder can initiate it's connection.
*/
- (id)initWithPath:(NSString *)path inAccount:(CTCoreAccount *)account;
/**
This initiates the connection after the folder has been initalized.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)connect;
/**
This method terminates the connection
Make sure you don't have any message connections open from this folder before disconnecting.
*/
- (void)disconnect;
/**
This will return the message from this folder with the UID that was passed in.
A CTMessage object is returned which can be used to get further information and perform operationson the message.
@return A CTCoreMessage or if not found, nil
*/
- (CTCoreMessage *)messageWithUID:(NSUInteger)uid;
/**
Use this method to download message lists from the server.
This method take fetch attributes which configure what is fetched. Fetch attributes can be combined
so you fetch all the message data at once, or select which pieces you want for your app. You can
also fetch just the default attributes which will be as fast as possible. Pass in
CTFetchAttrDefaultsOnly to attrs fetch the minimum possible, this includes the UID and
flags. The defaults are always fetched, even when you don't pass in this flag. Use
CTFetchAttrBodyStructure to also fetch the body structure of the message. This prevents a future
round trip done by [CTCoreMessage fetchBodyStructure], if it sees you already have the body
structure it won't re-fetch it. Use CTFetchAttrEnvelope if you'd like to fetch the subject, to,
from, cc, bcc, sender, date, size, etc. You can also fetch both the envelope and body structure by passing
in CTFetchAttrEnvelope | CTFetchAttrBodyStructure
@param start The message sequence number to start from, starts with 1 and NOT 0 (IMAP starts with 1 that way, sorry)
@param end The ending message sequence number, or if you'd like to fetch to the end of the message list pass in 0
@param attrs This controls what is fetched.
@return Returns a NSArray of CTCoreMessage's. Returns nil on error
*/
- (NSArray *)messagesFromSequenceNumber:(NSUInteger)startNum to:(NSUInteger)endNum withFetchAttributes:(CTFetchAttributes)attrs;
/**
Use this method to download message lists from the server.
This method uses UID ranges to determine which messages to download, while messagesFromSequenceNumber:to:withFetchAttributes: uses sequence numbers.
@param start The message sequence number to start from, starts with 1 and NOT 0 (IMAP starts with 1 that way, sorry)
@param end The ending message sequence number, or if you'd like to fetch to the end of the message list pass in 0
@param attrs This controls what is fetched.
@return Returns a NSArray of CTCoreMessage's. Returns nil on error
@see messagesFromSequenceNumber:to:withFetchAttributes:
*/
- (NSArray *)messagesFromUID:(NSUInteger)startUID to:(NSUInteger)endUID withFetchAttributes:(CTFetchAttributes)attrs;
/**
Use this method to download message lists from the server.
This method uses sequence numbers indexset to determine which messages to download.
@param sequenceNumbers The indexset of sequence numbers to load.
@param attrs This controls what is fetched.
@return Returns a NSArray of CTCoreMessage's. Returns nil on error
@see messagesFromSequenceNumber:to:withFetchAttributes:
*/
- (NSArray *)messagesWithSequenceNumbers:(NSIndexSet *)sequenceNumbers
fetchAttributes:(CTFetchAttributes)attrs;
/**
Use this method to download message lists from the server.
This method uses uid numbers indexset to determine which messages to download.
@param uidNumbers The indexset of uid numbers to load.
@param attrs This controls what is fetched.
@return Returns a NSArray of CTCoreMessage's. Returns nil on error
@see messagesFromSequenceNumber:to:withFetchAttributes:
*/
- (NSArray *)messagesWithUIDs:(NSIndexSet *)uidNumbers
fetchAttributes:(CTFetchAttributes)attrs;
/**
Pulls the sequence number for the message with the specified uid.
It does not perform UID validation, and the sequence ID is only
valid per session.
@param The uid for the message
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)sequenceNumberForUID:(NSUInteger)uid sequenceNumber:(NSUInteger *)sequenceNumber;
/**
Perform an IMAP check command
From IMAP RFC: "The CHECK command requests a checkpoint of the currently selected mailbox.
A checkpoint refers to any implementation-dependent housekeeping associated
with the mailbox (e.g., resolving the server's in-memory state of the mailbox
with the state on its disk) that is not normally executed as part of each command."
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)check;
/**
The entire path of the folder.
*/
- (NSString *)path;
/**
This will change the path of the folder.
Use this method to rename the folder on the server or to move the folder on the server.
@param path The new path for the folder as an NSString.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)setPath:(NSString *)path;
/**
Sends the idle command to the server.
*/
- (CTIdleResult)idleWithTimeout:(NSUInteger)timeout;
- (void)cancelIdle;
@property (atomic) BOOL idling;
/**
If the folder doesn't exist on the server this method will create it. Make sure the pathname
has been set first.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)create;
/**
This method will remove the folder and any messages contained within from the server.
Be careful when using this method because there is no way to undo.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)delete;
/**
The folder will be listed as subscribed on the server.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)subscribe;
/**
The folder will be listed as unsubscribed.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)unsubscribe;
/**
Exposes the IMAP APPEND command, see the IMAP RFC 4549.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL) appendMessage: (CTCoreMessage *) msg;
/**
Retrieves the message flags. You must AND/OR using the defines constants.
Here is a list of message flags:
CTFlagNew, CTFlagSeen, CTFlagFlagged, CTFlagDeleted,
CTFlagAnswered, CTFlagForwarded.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)flagsForMessage:(CTCoreMessage *)msg flags:(NSUInteger *)flags;
/**
Sets the message's flags on the server, take a look at the
documentation for flagsForMessage:
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)setFlags:(NSUInteger)flags forMessage:(CTCoreMessage *)msg;
/**
Retrieves the message extension flags.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)extensionFlagsForMessage:(CTCoreMessage *)msg flags:(NSArray **)flags;
/**
Sets the message's extension flags on the server.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)setExtensionFlags:(NSArray *)flags forMessage:(CTCoreMessage *)msg;
/**
Retrieves the message's flags and extension flags, take a look at the
documentation for flagsForMessage:
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)flagsForMessage:(CTCoreMessage *)msg flags:(NSUInteger *)flags extensionFlags:(NSArray **)extensionFlags;
/**
Sets the message's flags and extension flags on the server.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)setFlags:(NSUInteger)flags extensionFlags:(NSArray *)extensionFlags forMessage:(CTCoreMessage *)msg;
/**
Deletes all messages contained in the folder that are marked for
deletion. Deleting messages in IMAP is a little strange, first
you need to set the message flag CTFlagDeleted to CTFlagSet, and
then when you call expunge on the folder the message is contained
in, it will be deleted.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)expunge;
/**
Copies a message to a folder
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)copyMessageWithUID:(NSUInteger)uid toPath:(NSString *)path;
/**
Moves a message to a folder
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)moveMessageWithUID:(NSUInteger)uid toPath:(NSString *)path;
/**
Pass in a pointer to a NSUInteger to get the number of unread messages. This causes a round trip to the server,
as it fetches the count for each call.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)unreadMessageCount:(NSUInteger *)unseenCount;
/**
Pass in a pointer to a NSUInteger to get the number of messages in the folder. The count was retrieved
when the folder connection was established, so to refresh the count you must disconnect and reconnect.
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
*/
- (BOOL)totalMessageCount:(NSUInteger *)totalCount;
/**
Returns the uid validity value for the folder, which can be used to determine if the
local cached UID's are still valid, or if the server has changed UID's
*/
- (NSUInteger)uidValidity;
/**
Returns the uid next value for the folder. The next message added to the mailbox
will be assigned a UID greater than or equal to uidNext
*/
- (NSUInteger)uidNext;
/* Intended for advanced use only */
- (struct mailfolder *)folderStruct;
- (mailsession *)folderSession;
- (mailimap *)imapSession;
@end