250 lines
12 KiB
Objective-C
250 lines
12 KiB
Objective-C
/*
|
|
* 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"
|
|
|
|
/*!
|
|
@class CTCoreFolder
|
|
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. All methods throw an exceptions on failure.
|
|
*/
|
|
|
|
@class CTCoreMessage, CTCoreAccount;
|
|
|
|
@interface CTCoreFolder : NSObject {
|
|
struct mailfolder *myFolder;
|
|
CTCoreAccount *myAccount;
|
|
NSString *myPath;
|
|
BOOL connected;
|
|
NSError *lastError;
|
|
}
|
|
/*!
|
|
@abstract If an error occurred (nil or return of NO) call this method to get the error
|
|
*/
|
|
@property(nonatomic, retain) NSError *lastError;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract This method terminates the connection, make sure you don't have any message
|
|
connections open from this folder before disconnecting.
|
|
*/
|
|
- (void)disconnect;
|
|
|
|
/*!
|
|
@abstract This will return the message from this folder with the UID that was passed in. If the message
|
|
can't be found, nil is returned
|
|
@result A CTMessage object is returned which can be used to get further information and perform operations
|
|
on the message.
|
|
*/
|
|
- (CTCoreMessage *)messageWithUID:(NSUInteger)uid;
|
|
|
|
/*!
|
|
@abstract 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.
|
|
@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. Pass in CTFetchAttrDefaultsOnly to fetch the minimum possible, this
|
|
includes the UID, RFC822.size, 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 etc. You can
|
|
also fetch both the envelope and body structure by passing in CTFetchAttrEnvelope | CTFetchAttrBodyStructure
|
|
@return Returns a NSArray of CTCoreMessage's. Returns nil on error
|
|
*/
|
|
- (NSArray *)messagesFromSequenceNumber:(NSUInteger)startNum to:(NSUInteger)endNum withFetchAttributes:(CTFetchAttributes)attrs;
|
|
|
|
/*!
|
|
@abstract 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.
|
|
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.
|
|
@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. Pass in CTFetchAttrDefaultsOnly to fetch the minimum possible, this
|
|
includes the UID, RFC822.size, 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 etc. You can
|
|
also fetch both the envelope and body structure by passing in CTFetchAttrEnvelope | CTFetchAttrBodyStructure
|
|
@return Returns a NSArray of CTCoreMessage's. Returns nil on error
|
|
*/
|
|
- (NSArray *)messagesFromUID:(NSUInteger)startUID to:(NSUInteger)endUID withFetchAttributes:(CTFetchAttributes)attrs;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract The folder name.
|
|
*/
|
|
- (NSString *)name;
|
|
|
|
/*!
|
|
@abstract The entire path of folder.
|
|
*/
|
|
- (NSString *)path;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@astract 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;
|
|
|
|
/*!
|
|
@abstract Copies a message to a folder
|
|
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
|
|
*/
|
|
- (BOOL)copyMessage:(CTCoreMessage *)msg toPath:(NSString *)path;
|
|
|
|
/*!
|
|
@abstract Moves a message to a folder
|
|
@return Return YES on success, NO on error. Call method lastError to get error if one occurred
|
|
*/
|
|
- (BOOL)moveMessage:(CTCoreMessage *)msg toPath:(NSString *)path;
|
|
|
|
/*!
|
|
@abstract Returns 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;
|
|
|
|
/*!
|
|
@abstract Returns 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;
|
|
|
|
/*!
|
|
@abstract 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;
|
|
|
|
/*!
|
|
@abstract 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
|