diff options
author | Matt Ronge <mronge@mronge.com> | 2013-06-02 20:41:28 -0500 |
---|---|---|
committer | Matt Ronge <mronge@mronge.com> | 2013-06-02 20:41:28 -0500 |
commit | 3ae5bf7a1d806c749c28f641be34733c85808efe (patch) | |
tree | 27513da58055e421686ace2601d37a1e23eacb28 /src/objc | |
parent | 6fbe6f212003b97860a23c254e5124f0b2578366 (diff) |
Finished formatting docs for Appledoc for IMAP and SMTP
Diffstat (limited to 'src/objc')
26 files changed, 748 insertions, 612 deletions
diff --git a/src/objc/imap/MCOIMAPAppendMessageOperation.h b/src/objc/imap/MCOIMAPAppendMessageOperation.h index 95f29f5d..c23d79a1 100644 --- a/src/objc/imap/MCOIMAPAppendMessageOperation.h +++ b/src/objc/imap/MCOIMAPAppendMessageOperation.h @@ -10,22 +10,29 @@ #define __MAILCORE_MCOIMAPAPPENDMESSAGEOPERATION_H_ -// This class implements an operation that adds a message to a folder. +/** This class implements an operation that adds a message to a folder. */ #import <MailCore/MCOIMAPBaseOperation.h> #import <MailCore/MCOConstants.h> @interface MCOIMAPAppendMessageOperation : MCOIMAPBaseOperation -// This block will be called during the progression while sending the message -// when some bytes have been sent to the network. +/** + This block will be called as bytes are sent +*/ @property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress; -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. createdUID will be the value of the UID of -// the created message is the server supports UIDPLUS or zero if not. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// createdUID will be zero. +/** + Starts the asynchronous append operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `createdUID` will be the value of the + UID of the created message if the server supports UIDPLUS or zero if not. + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in MCOConstants.h, `createdUID` will be zero. +*/ - (void) start:(void (^)(NSError * error, uint32_t createdUID))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPBaseOperation.h b/src/objc/imap/MCOIMAPBaseOperation.h index 84e03892..f5bf88af 100644 --- a/src/objc/imap/MCOIMAPBaseOperation.h +++ b/src/objc/imap/MCOIMAPBaseOperation.h @@ -10,7 +10,7 @@ #define __MAILCORE_MCOIMAPBASEOPERATION_H_ -// It's a generic IMAP operation with progress. +/** Represents a generic IMAP operation with methods that are called with progress updates */ #import <MailCore/MCOOperation.h> @@ -19,13 +19,21 @@ typedef void (^MCOIMAPBaseOperationItemProgressBlock)(unsigned int current); @interface MCOIMAPBaseOperation : MCOOperation -// those two methods can be overriden by subclasses. - -// It will be called when a send or receive of a content of a message will occur. -- (void) bodyProgress:(unsigned int)current maximum:(unsigned int)maximum; - -// It will be called when a new item is received in a list of items. -- (void) itemProgress:(unsigned int)current maximum:(unsigned int)maximum; +/* Can be overriden by subclasses */ + +/* + Will be called when a sending or receiving the contents of a message + @param current The number of bytes sent or received + @param maximum The total number of bytes expected +*/ +- (void)bodyProgress:(unsigned int)current maximum:(unsigned int)maximum; + +/* + Will be called when a new item is received in a list of items, like for example a message list + @param current The number of items downloaded + @param maximum The total number of items expected +*/ +- (void)itemProgress:(unsigned int)current maximum:(unsigned int)maximum; @end diff --git a/src/objc/imap/MCOIMAPCapabilityOperation.h b/src/objc/imap/MCOIMAPCapabilityOperation.h index 38166e0b..29b0d3be 100644 --- a/src/objc/imap/MCOIMAPCapabilityOperation.h +++ b/src/objc/imap/MCOIMAPCapabilityOperation.h @@ -10,7 +10,10 @@ #define __MAILCORE_MCOIMAPCAPBILITYOPERATION_H_ -// This class implements an operation to query capabilities. +/** + This class implements an operation to query for IMAP capabilities, + like for example the extensions UIDPLUS, IDLE, NAMESPACE, ... etc +*/ #import <MailCore/MCOIMAPBaseOperation.h> @@ -18,11 +21,18 @@ @interface MCOIMAPCapabilityOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. capabilities is a set of IMAP capabilities. -// See MCOConstants.h / MCOIMAPCapability. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// info will be nil. + +/** + Starts the asynchronous capabilities operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `capabilities` will contain a set of IMAP capabilities. + See `MCOConstants.h` under `MCOIMAPCapability` for a list of possible values. + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in MCOConstants.h, `capabilities` will be nil +*/ - (void) start:(void (^)(NSError * error, MCOIndexSet * capabilities))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPCopyMessagesOperation.h b/src/objc/imap/MCOIMAPCopyMessagesOperation.h index 0fb3c5ad..c916e1d7 100644 --- a/src/objc/imap/MCOIMAPCopyMessagesOperation.h +++ b/src/objc/imap/MCOIMAPCopyMessagesOperation.h @@ -12,17 +12,24 @@ #define __MAILCORE_MCOCOPYMESSAGESOPERATION_H_ -// This class implements an operation to copy messages. +/** Implements an operation for copying messages between folders */ @class MCOIndexSet; @interface MCOIMAPCopyMessagesOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. destUids will contain the UID of the messages -// created in the destination folder if UIDPLUS is supported. destUids will be nil if UIDPLUS is not supported. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// info will be nil. +/** + Starts the asynchronous copy operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `destUids` will contain the UIDs of the messages created + in the destination folder. If the server doesn't support UIDPLUS then `destUids` will be nil. + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `destUids` will be nil +*/ + - (void) start:(void (^)(NSError * error, MCOIndexSet * destUids))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPFetchContentOperation.h b/src/objc/imap/MCOIMAPFetchContentOperation.h index f43425bb..1886981a 100644 --- a/src/objc/imap/MCOIMAPFetchContentOperation.h +++ b/src/objc/imap/MCOIMAPFetchContentOperation.h @@ -10,22 +10,32 @@ #define __MAILCORE_MCOIMAPFETCHCONTENTOPERATION_H_ -// This class implements an operation to fetch the content of a message. -// It can be a part or a full message. +/** + This class implements an operation to fetch the content of a message. + It can be a part or a full message. +*/ #import <MailCore/MCOIMAPBaseOperation.h> #import <MailCore/MCOConstants.h> @interface MCOIMAPFetchContentOperation : MCOIMAPBaseOperation -// This block will be called during the progression while receiving the message -// when some bytes have been downloaded from the network. +/** + This block will be called as bytes are received from the network +*/ @property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress; -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. data contains the requested data of the message. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// data will be nil. +/** + Starts the asynchronous fetch operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `data` will contain the requested data + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `data` will be nil +*/ + - (void) start:(void (^)(NSError * error, NSData * data))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPFetchFoldersOperation.h b/src/objc/imap/MCOIMAPFetchFoldersOperation.h index 90feb870..e4352bd2 100644 --- a/src/objc/imap/MCOIMAPFetchFoldersOperation.h +++ b/src/objc/imap/MCOIMAPFetchFoldersOperation.h @@ -10,16 +10,22 @@ #define __MAILCORE_MCOIMAPFETCHFOLDERSOPERATION_H_ -// This class implements an operation to fetch a list of folders. +/** This class implements an operation to fetch a list of folders. */ #import <MailCore/MCOIMAPBaseOperation.h> @interface MCOIMAPFetchFoldersOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. folders will be an array of MCOIMAPFolder. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// folders will be nil. +/** + Starts the asynchronous fetch operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `folders` will contain an array of MCOIMAPFolder + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `folders` will be nil +*/ - (void) start:(void (^)(NSError * error, NSArray * /* MCOIMAPFolder */ folders))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPFetchMessagesOperation.h b/src/objc/imap/MCOIMAPFetchMessagesOperation.h index 32a3a451..659d9bca 100644 --- a/src/objc/imap/MCOIMAPFetchMessagesOperation.h +++ b/src/objc/imap/MCOIMAPFetchMessagesOperation.h @@ -13,21 +13,28 @@ #import <MailCore/MCOIMAPBaseOperation.h> #import <MailCore/MCOConstants.h> -// This class implements an operation to fetch a list of messages. +/** This class implements an operation to fetch a list of messages from a folder */ @class MCOIndexSet; @interface MCOIMAPFetchMessagesOperation : MCOIMAPBaseOperation -// This block will be called each time a new message information will be downloaded. +/** This block will be called each time a new message is downloaded. */ @property (nonatomic, copy) MCOIMAPBaseOperationItemProgressBlock progress; -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. messages will be an array of MCOIMAPMessage. -// vanishedMessages will contain the messages removed on the server if the server supports QRESYNC and if it was a sync request. -// In other case, vanishedMessages will be nil. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// messages and vanishedMessages will be nil. +/** + Starts the asynchronous fetch operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `messages` will be an array of MCOIMAPMessage. + `vanishedMessages` will contain the messages removed on the server if the server supports QRESYNC and if it was a sync request + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `messages` and `vanishedMessages` will be nil + + If you are not supporting QRESYNC you can safely ignore `vanishedMessages`. +*/ - (void) start:(void (^)(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPFetchNamespaceOperation.h b/src/objc/imap/MCOIMAPFetchNamespaceOperation.h index b7e5fb64..ce845f5e 100644 --- a/src/objc/imap/MCOIMAPFetchNamespaceOperation.h +++ b/src/objc/imap/MCOIMAPFetchNamespaceOperation.h @@ -10,23 +10,28 @@ #define __MAILCORE_MCOIMAPFETCHNAMESPACEOPERATION_H_ -// This class implements an operation to fetch namespaces. +/** This class implements an operation to fetch any IMAP namespaces. */ #import <MailCore/MCOIMAPBaseOperation.h> @interface MCOIMAPFetchNamespaceOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// -// On success, the completion block will be called with nil as error. -// namespaces is a dictionary with the following keys: -// MCOIMAPNamespacePersonal for personal namespaces, -// MCOIMAPNamespaceOther for other namespaces, -// MCOIMAPNamespaceShared for shared namespaces. -// Values are MCOIMAPNamespace. -// -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// namespaces will be nil. +/** + Starts the asynchronous namespace fetch operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `namespaces` will contain these keys: + + - `MCOIMAPNamespacePersonal` for personal namespaces, + - `MCOIMAPNamespaceOther` for other namespaces, + - `MCOIMAPNamespaceShared` for shared namespaces. + + Values of the dictionary are MCOIMAPNamespace + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `namespaces` will be nil +*/ - (void) start:(void (^)(NSError * error, NSDictionary * namespaces))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPFolder.h b/src/objc/imap/MCOIMAPFolder.h index 03858fc5..8688ef5b 100644 --- a/src/objc/imap/MCOIMAPFolder.h +++ b/src/objc/imap/MCOIMAPFolder.h @@ -10,20 +10,23 @@ #define __MAILCORE_MCOIMAPFOLDER_H_ -// This class implements an IMAP folder. +/** This class represents an IMAP folder */ #import <Foundation/Foundation.h> #import <MailCore/MCOConstants.h> @interface MCOIMAPFolder : NSObject <NSCopying> -// It's the path of the folder. +/** The folder's path, like for example INBOX.Archive */ @property (nonatomic, copy) NSString * path; -// It's the delimiter for each component of the path. +/** It's the delimiter for each component of the path. Commonly . or / */ @property (nonatomic, assign) char delimiter; -// It's the flags of the folder. See MCOIMAPFolderFlag. +/** + Any flags the folder may have, like if the folder is for Drafts, Spam, Junk, etc. Or + it could be marked with metadata like that it has no children. +*/ @property (nonatomic, assign) MCOIMAPFolderFlag flags; @end diff --git a/src/objc/imap/MCOIMAPFolderInfo.h b/src/objc/imap/MCOIMAPFolderInfo.h index cbeb64f2..39713e80 100644 --- a/src/objc/imap/MCOIMAPFolderInfo.h +++ b/src/objc/imap/MCOIMAPFolderInfo.h @@ -12,23 +12,23 @@ #import <Foundation/Foundation.h> -// This class is a cluster for some folder information. +/* This class holds IMAP folder metadata */ @interface MCOIMAPFolderInfo : NSObject -// Returns a new allocated folder info. +/** Create an empty instance */ + (MCOIMAPFolderInfo *) info; -// UIDNEXT value. +/** The folder's IMAP UIDNEXT value. Used to determine the uid for the next received message. */ @property (nonatomic, assign) uint32_t uidNext; -// UIDVALIDITY value. +/** The folders IMAP UIDVALIDITY value. Must be used to determine if the server has changed assigned UIDs */ @property (nonatomic, assign) uint32_t uidValidity; -// MODSEQ value. +/** An advanced value used for doing quick flag syncs if the server supports it. The MODSEQ value. */ @property (nonatomic, assign) uint64_t modSequenceValue; -// number of messages. +/** Total number of messages in the folder */ @property (nonatomic, assign) int messageCount; @end diff --git a/src/objc/imap/MCOIMAPFolderInfoOperation.h b/src/objc/imap/MCOIMAPFolderInfoOperation.h index 73101641..d26e47a8 100644 --- a/src/objc/imap/MCOIMAPFolderInfoOperation.h +++ b/src/objc/imap/MCOIMAPFolderInfoOperation.h @@ -12,17 +12,26 @@ #import <MailCore/MCOIMAPBaseOperation.h> -// This class implements the operation that will fetch some folder information -// (uidNext uidValidity, modSequenceValue, messageCount). +/** + The class is used to get folder metadata (like UIDVALIDITY, UIDNEXT, etc). + @see MCOIMAPFolderInfo +*/ @class MCOIMAPFolderInfo; @interface MCOIMAPFolderInfoOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. info contains the folder information. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// info will be nil. +/** + Starts the asynchronous operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `info` will contain the folder metadata + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `info` will be nil +*/ + - (void) start:(void (^)(NSError * error, MCOIMAPFolderInfo * info))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPIdentityOperation.h b/src/objc/imap/MCOIMAPIdentityOperation.h index 0a32892c..d0d5f27b 100644 --- a/src/objc/imap/MCOIMAPIdentityOperation.h +++ b/src/objc/imap/MCOIMAPIdentityOperation.h @@ -10,17 +10,28 @@ #define __MAILCORE_MCOIMAPIDENTITYOPERATION_H_ -// This class implements an operation to get/send identity. +/** + This class implements an operation to get the servers identification info or + to send the clients identification info. Useful for bug reports and usage + statistics. + @warn Not all servers support this. +*/ #import <MailCore/MCOIMAPBaseOperation.h> @interface MCOIMAPIdentityOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. serverIdentity contains the server identity information. -// See RFC 2971 for the common keys of this dictionary. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// serverIdentity will be nil. +/** + Starts the asynchronous identity operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `serverIdentity` will contain identifying server information. + See [RFC2971](http://tools.ietf.org/html/rfc2971) for commons dictionary keys. + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h`, `serverIdentity` will be nil +*/ - (void) start:(void (^)(NSError * error, NSDictionary * serverIdentity))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPIdleOperation.h b/src/objc/imap/MCOIMAPIdleOperation.h index 2da19d19..01b4f443 100644 --- a/src/objc/imap/MCOIMAPIdleOperation.h +++ b/src/objc/imap/MCOIMAPIdleOperation.h @@ -10,18 +10,29 @@ #define __MAILCORE_MCOIMAPIDLEOPERATION_H_ -// This class implements an idle operation. +/** + This class implements an IMAP IDLE. IDLE is used to keep a connection + open with the server so that new messages can be pushed to the client. + See [RFC2177](http://tools.ietf.org/html/rfc2177) +*/ #import <MailCore/MCOIMAPBaseOperation.h> @interface MCOIMAPIdleOperation : MCOIMAPBaseOperation -// Interrupts the IDLE operation. +/** Stop the current IDLE session */ - (void) interruptIdle; -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. +/** + Starts IDLE + + @param completionBlock Called when the IDLE times out, errors out or detects a change + + - On success `error` will be nil + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in `MCOConstants.h` +*/ - (void) start:(void (^)(NSError * error))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPMessage.h b/src/objc/imap/MCOIMAPMessage.h index f0a1e0ec..81dfa9f7 100644 --- a/src/objc/imap/MCOIMAPMessage.h +++ b/src/objc/imap/MCOIMAPMessage.h @@ -10,14 +10,19 @@ #define __MAILCORE_MCOIMAPMESSAGE_H_ -// This class implements an IMAP message. -// If you fetched the MIME structure of the message, you can fetch -// efficiently the content of the message by fetching only the parts -// that you need to show it. -// For example, you could fetch only the text parts to show the summary -// of the message, using -[MCOIMAPSession fetchMessageAttachmentByUIDOperationWithFolder:uid:partID:encoding:] -// You can also decide to fetch entirely the message using -// -[MCOIMAPSession fetchMessageByUIDOperationWithFolder:uid:] +/** + This represents an IMAP message. + + If you fetched the MIME structure of the message, you can fetch + efficiently the content of the message by fetching only the parts + that you need to show it. + + For example, you could fetch only the text parts to show the summary + of the message, using [MCOIMAPSession fetchMessageAttachmentByUIDOperationWithFolder:uid:partID:encoding:] + + You can also decide to fetch entirely the message using + [MCOIMAPSession fetchMessageByUIDOperationWithFolder:uid:] +*/ #import <MailCore/MCOAbstractMessage.h> #import <MailCore/MCOConstants.h> @@ -26,32 +31,36 @@ @interface MCOIMAPMessage : MCOAbstractMessage <NSCopying> -// It's the UID of the message. +/** IMAP UID of the message. */ @property (nonatomic, assign) uint32_t uid; -// It's the flags of the message. +/** Flags of the message, like if it is deleted, read, starred etc */ @property (nonatomic, assign) MCOMessageFlag flags; -// It's the flags of the message fetched from the server. +/** The contents of the message flags when it was fetched from the server */ @property (nonatomic, assign) MCOMessageFlag originalFlags; -// It's the last modification sequence value of the message synced from the server. +/** It's the last modification sequence value of the message synced from the server. See RFC4551 */ @property (nonatomic, assign) uint64_t modSeqValue; -// It's the main MIME part of the message. +/** Main MIME part of the message */ @property (nonatomic, retain) MCOAbstractPart * mainPart; -// It's the Gmail labels of the message. +/** Any Gmail labels of the message */ @property (nonatomic, copy) NSArray * gmailLabels; -// Returns the part with the given part identifier. -// A part identifier looks like 1.2.1 +/** + Returns the part with the given part identifier. + @param partID A part identifier looks like 1.2.1 +*/ - (MCOAbstractPart *) partForPartID:(NSString *)partID; -// HTML rendering of the message to be displayed in a web view. -// The delegate should implement at least -// -MCOAbstractMessage:dataForIMAPPart:folder: -// so that the complete HTML rendering can have a chance to take place. +/** + HTML rendering of the message to be displayed in a web view. + The delegate should implement at least + [MCOAbstractMessage:dataForIMAPPart:folder:] + so that the complete HTML rendering can take place. +*/ - (NSString *) htmlRenderingWithFolder:(NSString *)folder delegate:(id <MCOHTMLRendererIMAPDelegate>)delegate; diff --git a/src/objc/imap/MCOIMAPMessagePart.h b/src/objc/imap/MCOIMAPMessagePart.h index 22ce8a50..b602d93a 100644 --- a/src/objc/imap/MCOIMAPMessagePart.h +++ b/src/objc/imap/MCOIMAPMessagePart.h @@ -10,14 +10,13 @@ #define __MAILCORE_MCOIMAPMESSAGEPART_H_ -// This class implements a message part. +/** Represents a message part. */ #import <MailCore/MCOAbstractMessagePart.h> @interface MCOIMAPMessagePart : MCOAbstractMessagePart <NSCopying> -// It's the part identifier. -// A part identifier looks like 1.2.1 +/** A part identifier is of the form 1.2.1*/ @property (nonatomic, copy) NSString * partID; @end diff --git a/src/objc/imap/MCOIMAPMultipart.h b/src/objc/imap/MCOIMAPMultipart.h index d178a2ce..0e0bb0eb 100644 --- a/src/objc/imap/MCOIMAPMultipart.h +++ b/src/objc/imap/MCOIMAPMultipart.h @@ -10,14 +10,13 @@ #define __MAILCORE_MCOIMAPMULTIPART_H_ -// This class implements a multipart. +/** Represents the a multipart retrieved from IMAP */ #import <MailCore/MCOAbstractMultipart.h> @interface MCOIMAPMultipart : MCOAbstractMultipart <NSCopying> -// It's the part identifier. -// A part identifier looks like 1.2.1 +/** A part identifier looks like 1.2.1 */ @property (nonatomic, copy) NSString * partID; @end diff --git a/src/objc/imap/MCOIMAPNamespace.h b/src/objc/imap/MCOIMAPNamespace.h index 392a3d1b..f3373c64 100644 --- a/src/objc/imap/MCOIMAPNamespace.h +++ b/src/objc/imap/MCOIMAPNamespace.h @@ -10,7 +10,7 @@ #define __MAILCORE_MCOIMAPNAMESPACE_H_ -// This class implements an IMAP namespace. +/** Represents an IMAP namespace */ #import <Foundation/Foundation.h> @@ -18,31 +18,36 @@ @interface MCOIMAPNamespace : NSObject <NSCopying> -// Returns a simple namespace with only an item. -// This item will have the given prefix and the given path delimiter. +/** + Returns a simple namespace with only one item. +*/ + (MCOIMAPNamespace *) namespaceWithPrefix:(NSString *)prefix delimiter:(char)delimiter; -// Returns the prefix of the main item of this namespace. +/** Returns the prefix of the main item of this namespace. */ - (NSString *) mainPrefix; -// Returns the path delimiter of the main item of this namespace. +/** Returns the path delimiter of the main item of this namespace */ - (char) mainDelimiter; -// Returns the list of prefixes of this namespace. +/** Returns the list of prefixes of this namespace. */ - (NSArray *) prefixes; -// Returns the folder path for the given list of path components in the context -// of the main item of the namespace. +/** + Returns the folder path for the given list of path components in the context + of the main item of the namespace. +*/ - (NSString *) pathForComponents:(NSArray *)components; -// Returns the folder path for the given list of path components and a prefix. -// It will use the best item matching the prefix to compute the path. +/** + Returns the folder path for the given list of path components and a prefix. + It will use the best item matching the prefix to compute the path. +*/ - (NSString *) pathForComponents:(NSArray *)components prefix:(NSString *)prefix; -// Returns the components given a folder path. +/** Returns the components given a folder path. */ - (NSArray *) componentsFromPath:(NSString *)path; -// Returns YES if the namespace contains the given folder path. +/** Returns YES if the namespace contains the given folder path. */ - (BOOL) containsFolderPath:(NSString *)path; @end diff --git a/src/objc/imap/MCOIMAPNamespaceItem.h b/src/objc/imap/MCOIMAPNamespaceItem.h index 6171b464..b23d0dfc 100644 --- a/src/objc/imap/MCOIMAPNamespaceItem.h +++ b/src/objc/imap/MCOIMAPNamespaceItem.h @@ -10,25 +10,25 @@ #define __MAILCORE_MCOIMAPNAMESPACEITEM_H_ -// This class implements an IMAP namespace item. +/** Represents a namespace item */ #import <Foundation/Foundation.h> @interface MCOIMAPNamespaceItem : NSObject <NSCopying> -// This is the prefix for this namespace item. +/** This is the prefix for this namespace item */ @property (nonatomic, copy) NSString * prefix; -// This is the delimiter of the path for this namespace item. +/** This is the delimiter of the path for this namespace item */ @property (nonatomic, assign) char delimiter; -// Returns folder path for given path components in the context of this namespace item. +/** Returns folder path for given path components in the context of this namespace item */ - (NSString *) pathForComponents:(NSArray *)components; -// Returns components for the given path in the context of this namespace item. +/** Returns components for the given path in the context of this namespace */ - (NSArray *) componentsForPath:(NSString *)path; -// Returns YES if the namespace contains this folder path. +/** Returns YES if the namespace contains this folder path */ - (BOOL) containsFolder:(NSString *)folder; @end diff --git a/src/objc/imap/MCOIMAPOperation.h b/src/objc/imap/MCOIMAPOperation.h index 74aba70a..b8ee37e4 100644 --- a/src/objc/imap/MCOIMAPOperation.h +++ b/src/objc/imap/MCOIMAPOperation.h @@ -10,15 +10,22 @@ #define __MAILCORE_MCOIMAPOPERATION_H_ -// This class implements a generic IMAP operation. +/** This class implements a generic IMAP operation */ #import <MailCore/MCOOperation.h> @interface MCOIMAPOperation : MCOOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. +/** + Starts the asynchronous append operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in MCOConstants.h, +*/ - (void) start:(void (^)(NSError * error))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPPart.h b/src/objc/imap/MCOIMAPPart.h index 58bdfd2d..029135bf 100644 --- a/src/objc/imap/MCOIMAPPart.h +++ b/src/objc/imap/MCOIMAPPart.h @@ -14,20 +14,23 @@ #import <MailCore/MCOConstants.h> +/** Represents a single IMAP message part */ + @interface MCOIMAPPart : MCOAbstractPart <NSCopying> -// It's the part identifier. -// A part identifier looks like 1.2.1 +/** A part identifier looks like 1.2.1 */ @property (nonatomic, copy) NSString * partID; -// It's the size of the single part. +/** The size of the single part in bytes */ @property (nonatomic, nonatomic) unsigned int size; -// It's the encoding of the single part. +/** It's the encoding of the single part */ @property (nonatomic, nonatomic) MCOEncoding encoding; -// Returns the decoded size of the part. -// For example, for a part that's encoded with base64, it will return actual_size * 3/4. +/** + Returns the decoded size of the part. + For example, for a part that's encoded with base64, it will return actual_size * 3/4. +*/ - (unsigned int) decodedSize; @end diff --git a/src/objc/imap/MCOIMAPSearchExpression.h b/src/objc/imap/MCOIMAPSearchExpression.h index d0c439e9..17a7656a 100644 --- a/src/objc/imap/MCOIMAPSearchExpression.h +++ b/src/objc/imap/MCOIMAPSearchExpression.h @@ -10,64 +10,77 @@ #define __MAILCORE_MCOIMAPSEARCHEXPRESSION_H_ -// This class implements a search expression. +/** Used to construct an IMAP search query */ #import <Foundation/Foundation.h> #import <MailCore/MCOConstants.h> @interface MCOIMAPSearchExpression : NSObject +/** + Creates a search expression that matches the sender of an email. -// Creates a search expression that matches the sender of an email. -// -// Example: -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] -// + Example: + + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] +*/ + (MCOIMAPSearchExpression *) searchFrom:(NSString *)value; -// Creates a search expression that matches any recipient of an email. -// -// Example: -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchRecipient:@"ngan@etpan.org"] -// +/** + Creates a search expression that matches any recipient of an email. + + Example: + + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchRecipient:@"ngan@etpan.org"] +**/ + (MCOIMAPSearchExpression *) searchRecipient:(NSString *)value; -// Creates a search expression that matches the subject of an email. -// -// Example: -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchSubject:@"airline"] -// +/* + Creates a search expression that matches the subject of an email. + + Example: + + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchSubject:@"airline"] +**/ + (MCOIMAPSearchExpression *) searchSubject:(NSString *)value; -// Creates a search expression that matches the content of an email. -// -// Example: -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchContent:@"meeting"] -// +/** + Creates a search expression that matches the content of an email. + + Example: + + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchContent:@"meeting"] +*/ + (MCOIMAPSearchExpression *) searchContent:(NSString *)value; -// Creates a search expression that matches the content of a specific header. -// -// Example: -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchHeader:@"List-Id" value:@"shoes"] -// +/** + Creates a search expression that matches the content of a specific header. + + Example: + + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchHeader:@"List-Id" value:@"shoes"] +**/ + (MCOIMAPSearchExpression *) searchHeader:(NSString *)header value:(NSString *)value; -// Creates a search expression that's a disjunction of two search expressions. -// -// Example: -// MCOIMAPSearchExpression * exprFrom = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] -// MCOIMAPSearchExpression * exprSubject = [MCOIMAPSearchExpression searchContent:@"meeting"] -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchAnd:exprFrom other:exprSubject]; -// +/** + Creates a search expression that's a disjunction of two search expressions. + + Example: + + MCOIMAPSearchExpression * exprFrom = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] + MCOIMAPSearchExpression * exprSubject = [MCOIMAPSearchExpression searchContent:@"meeting"] + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchAnd:exprFrom other:exprSubject]; +**/ + + (MCOIMAPSearchExpression *) searchAnd:(MCOIMAPSearchExpression *)expression other:(MCOIMAPSearchExpression *)other; +/** + Creates a search expression that's a conjunction of two search expressions. -// Creates a search expression that's a conjunction of two search expressions. -// -// Example: -// MCOIMAPSearchExpression * exprFrom = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] -// MCOIMAPSearchExpression * exprOtherFrom = [MCOIMAPSearchExpression searchRecipient:@"ngan@etpan.org"] -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchOr:exprFrom exprOtherFrom]; -// + Example: + + MCOIMAPSearchExpression * exprFrom = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] + MCOIMAPSearchExpression * exprOtherFrom = [MCOIMAPSearchExpression searchRecipient:@"ngan@etpan.org"] + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchOr:exprFrom exprOtherFrom]; +*/ + (MCOIMAPSearchExpression *) searchOr:(MCOIMAPSearchExpression *)expression other:(MCOIMAPSearchExpression *)other; @end diff --git a/src/objc/imap/MCOIMAPSearchOperation.h b/src/objc/imap/MCOIMAPSearchOperation.h index 25795cfb..a178984d 100644 --- a/src/objc/imap/MCOIMAPSearchOperation.h +++ b/src/objc/imap/MCOIMAPSearchOperation.h @@ -10,7 +10,7 @@ #define __MAILCORE_MCOSEARCHOPERATION_H_ -// This class implements a search operation. +/** This class runs an IMAP search operation */ #import <MailCore/MCOIMAPBaseOperation.h> @@ -18,10 +18,17 @@ @interface MCOIMAPSearchOperation : MCOIMAPBaseOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. searchResult will contain the UID of the messages. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. -// searchResult will be nil. +/** + Starts the asynchronous search operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil and `searchResults` will contain the UIDs of any matching messages + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in MCOConstants.h, `searchResult` will be nil +*/ + - (void) start:(void (^)(NSError * error, MCOIndexSet * searchResult))completionBlock; @end diff --git a/src/objc/imap/MCOIMAPSession.h b/src/objc/imap/MCOIMAPSession.h index 344550b5..18bfc192 100644 --- a/src/objc/imap/MCOIMAPSession.h +++ b/src/objc/imap/MCOIMAPSession.h @@ -29,484 +29,462 @@ @class MCOIMAPIdentityOperation; @class MCOIMAPCapabilityOperation; -// This class implements asynchronous IMAP protocol. +/** + This is the main IMAP class from which all operations are created + + After calling a method that returns an operation you must call start: on the instance + to begin the operation. +*/ @interface MCOIMAPSession : NSObject -// This is the hostname of the POP3 server to connect to. +/** This is the hostname of the IMAP server to connect to. */ @property (nonatomic, strong) NSString *hostname; -// This is the port of the IMAP server to connect to. +/** This is the port of the IMAP server to connect to. */ @property (nonatomic, assign) unsigned int port; -// This is the username of the account. +/** This is the username of the account. */ @property (nonatomic, strong) NSString *username; -// This is the password of the account. +/** This is the password of the account. */ @property (nonatomic, strong) NSString *password; -// This is the authentication type to use to connect. -// MCOAuthTypeSASLNone means that it uses the clear-text password authentication. -// It's the default. -// Note: However, over a encrypted connection, the password will be safe. +/** + This is the authentication type to use to connect. + `MCOAuthTypeSASLNone` means that it uses the clear-text is used (and is the default). + @warning *Important*: Over an encrypted connection like TLS, the password will still be secure +*/ @property (nonatomic, assign) MCOAuthType authType; -// This is the encryption type to use. -// See MCOConnectionType for more information. +/** + This is the encryption type to use. + See MCOConnectionType for more information. +*/ @property (nonatomic, assign) MCOConnectionType connectionType; -// This is the timeout of the connection. +/** This is the timeout of the connection. *// @property (nonatomic, assign) NSTimeInterval timeout; -// When set to YES, the connection will fail if the certificate is incorrect. +/** When set to YES, the connection will fail if the certificate is incorrect. */ @property (nonatomic, assign) BOOL checkCertificateEnabled; -// When set to YES, VoIP capability will be enabled on the IMAP connection on iOS. +/** When set to YES, VoIP capability will be enabled on the IMAP connection on iOS */ @property (nonatomic, assign, getter=isVoIPEnabled) BOOL VoIPEnabled; -// The default delimiter for the folder paths. +/** The default delimiter for the folder paths */ @property (nonatomic, assign) char delimiter; -// The default namespace. +/** The default namespace. */ @property (nonatomic, strong) MCOIMAPNamespace * defaultNamespace; -// When set to YES, the session is allowed open to open several connections -// to the same folder. +/** + When set to YES, the session is allowed open to open several connections to the same folder. + @warning Some older IMAP servers don't like this +*/ @property (nonatomic, assign) BOOL allowsFolderConcurrentAccessEnabled; -// Maximum number of connections to the server allowed. +/** + Maximum number of connections to the server allowed. +*/ @property (nonatomic, assign) unsigned int maximumConnections; -// Returns a request operation for some info of the folder -// The operation needs to be started. -// (uidNext uidValidity, modSequenceValue, messageCount). -// -// { -// ... -// MCOIMAPFolderInfoOperation * op = [session folderInfoOperation:@"INBOX"]; -// [op start:^(NSError *error, MCOIMAPFolderInfo * info) { -// NSLog(@"UIDNEXT: %lu", (unsigned long) [info uidNext]); -// NSLog(@"UIDVALIDITY: %lu", (unsigned long) [info uidValidity]); -// NSLog(@"HIGHESTMODSEQ: %llu", (unsigned long long) [info modSequenceValue]); -// NSLog(@"messages count: %lu", [info messageCount]); -// }]]; -// +/** @name Folder Operations */ + +/** + Returns an operation that retrieves folder metadata (like UIDNext) + + MCOIMAPFolderInfoOperation * op = [session folderInfoOperation:@"INBOX"]; + [op start:^(NSError *error, MCOIMAPFolderInfo * info) { + NSLog(@"UIDNEXT: %lu", (unsigned long) [info uidNext]); + NSLog(@"UIDVALIDITY: %lu", (unsigned long) [info uidValidity]); + NSLog(@"HIGHESTMODSEQ: %llu", (unsigned long long) [info modSequenceValue]); + NSLog(@"messages count: %lu", [info messageCount]); + }]; +*/ + - (MCOIMAPFolderInfoOperation *) folderInfoOperation:(NSString *)folder; -// Returns an operation to fetch subscribed folders. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation]; -// [op start:^(NSError * error, NSArray * /* MCOIMAPFolder */ folders) { -// ... -// }]]; -// +/** + Returns an operation that gets the list of subscribed folders. + + MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation]; + [op start:^(NSError * error, NSArray * folders) { + ... + }]; +*/ - (MCOIMAPFetchFoldersOperation *) fetchSubscribedFoldersOperation; -// Returns an operation to fetch all folders. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation]; -// [op start:^(NSError * error, NSArray * /* MCOIMAPFolder */ folders) { -// ... -// }]]; -// +/** + Returns an operation that gets all folders + + MCOIMAPFetchFoldersOperation * op = [session fetchAllFoldersOperation]; + [op start:^(NSError * error, NSArray *folders) { + ... + }]; +*/ - (MCOIMAPFetchFoldersOperation *) fetchAllFoldersOperation; -// Returns an operation to rename a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session renameFolderOperation:@"my documents" otherName:@"Documents"]; -// [op start:^(NSError * error) { -// ... -// }]]; -// +/** + Creates an operation for renaming a folder + + MCOIMAPOperation * op = [session renameFolderOperation:@"my documents" otherName:@"Documents"]; + [op start:^(NSError * error) { + ... + }]; + +*/ - (MCOIMAPOperation *) renameFolderOperation:(NSString *)folder otherName:(NSString *)otherName; -// Returns an operation to delete a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"]; -// [op start:^(NSError * error) { -// ... -// }]]; -// +/** + Create an operation for deleting a folder + + MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"]; + [op start:^(NSError * error) { + ... + }]]; +*/ - (MCOIMAPOperation *) deleteFolderOperation:(NSString *)folder; -// Returns an operation to create a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"]; -// [op start:^(NSError * error) { -// ... -// }]; -// +/** + Returns an operation that creates a new folder + + MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"]; + [op start:^(NSError * error) { + ... + }]; +*/ - (MCOIMAPOperation *) createFolderOperation:(NSString *)folder; -// Returns an operation to subscribe a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"]; -// [op start:^(NSError * error) { -// if (error != nil) -// return; -// MCOIMAPOperation * op = [session subscribeFolderOperation:@"holidays 2013"] { -// ... -// }]; -// }]]; -// +/** + Returns an operation to subscribe to a folder. + + MCOIMAPOperation * op = [session createFolderOperation:@"holidays 2013"]; + [op start:^(NSError * error) { + if (error != nil) + return; + MCOIMAPOperation * op = [session subscribeFolderOperation:@"holidays 2013"]; + ... + }]; +*/ - (MCOIMAPOperation *) subscribeFolderOperation:(NSString *)folder; -// Returns an operation to unsubscribe a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session unsubscribeFolderOperation:@"holidays 2009"]; -// [op start:^(NSError * error) { -// if (error != nil) -// return; -// MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"] { -// ... -// }]; -// }]]; -// +/** + Returns an operation to unsubscribe from a folder. + + MCOIMAPOperation * op = [session unsubscribeFolderOperation:@"holidays 2009"]; + [op start:^(NSError * error) { + if (error != nil) + return; + MCOIMAPOperation * op = [session deleteFolderOperation:@"holidays 2009"] + ... + }]; +*/ - (MCOIMAPOperation *) unsubscribeFolderOperation:(NSString *)folder; -// Returns an operation to add a message to a folder. -// The operation needs to be started. -// { -// ... -// MCOIMAPOperation * op = [session appendMessageOperationWithFolder:@"Sent Mail" messageData:rfc822Data flags:MCOMessageFlagNone]; -// [op start:^(NSError * error, uint32_t createdUID) { -// if (error == nil) { -// NSLog(@"created message with UID %lu", (unsigned long) createdUID); -// } -// }]; -// +/** + Returns an operation to expunge a folder. + + MCOIMAPOperation * op = [session expungeOperation:@"INBOX"]; + [op start:^(NSError * error) { + ... + }]; +*/ +- (MCOIMAPOperation *) expungeOperation:(NSString *)folder; + +/** @name Message Actions */ + +/** + Returns an operation to add a message to a folder. + + MCOIMAPOperation * op = [session appendMessageOperationWithFolder:@"Sent Mail" messageData:rfc822Data flags:MCOMessageFlagNone]; + [op start:^(NSError * error, uint32_t createdUID) { + if (error == nil) { + NSLog(@"created message with UID %lu", (unsigned long) createdUID); + } + }]; +*/ - (MCOIMAPAppendMessageOperation *)appendMessageOperationWithFolder:(NSString *)folder messageData:(NSData *)messageData flags:(MCOMessageFlag)flags; -// Returns an operation to copy messages to a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPCopyMessagesOperation * op = [session copyMessagesOperationWithFolder:@"INBOX" -// uids:[MCIndexSet indexSetWithIndex:456] -// destFolder:@"Cocoa"]; -// [op start:^(NSError * error, MCOIndexSet * destUids) { -// NSLog(@"copied to folder with UID %@", destUids); -// }]; -// +/** + Returns an operation to copy messages to a folder. + + MCOIMAPCopyMessagesOperation * op = [session copyMessagesOperationWithFolder:@"INBOX" + uids:[MCIndexSet indexSetWithIndex:456] + destFolder:@"Cocoa"]; + [op start:^(NSError * error, MCOIndexSet * destUids) { + NSLog(@"copied to folder with UID %@", destUids); + }]; +*/ - (MCOIMAPCopyMessagesOperation *)copyMessagesOperationWithFolder:(NSString *)folder uids:(MCOIndexSet *)uids destFolder:(NSString *)destFolder NS_RETURNS_NOT_RETAINED; +/** + Returns an operation to change flags of messages. -// Returns an operation to expunge a folder. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session expungeOperation:@"INBOX"]; -// [op start:^(NSError * error) { -// ... -// }]; -// -- (MCOIMAPOperation *) expungeOperation:(NSString *)folder; + For example: Adds the seen flag to the message with UID 456. -// Returns an operation to fetch messages by UID. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByUIDOperationWithFolder:@"INBOX" -// requestKind:MCOIMAPMessagesRequestKindHeaders | MCOIMAPMessagesRequestKindStructure -// uids:MCORangeMake(1, UINT64_MAX)]; -// [op start:^(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages) { -// for(MCOIMAPMessage * msg in messages) { -// NSLog(@"%lu: %@", [msg uid], [msg header]); -// } -// }]; -// + MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX" + uids:[MCOIndexSet indexSetWithIndex:456] + kind:MCOIMAPStoreFlagsRequestKindAdd + flags:MCOMessageFlagSeen]; + [op start:^(NSError * error) { + ... + }]; +*/ +- (MCOIMAPOperation *) storeFlagsOperationWithFolder:(NSString *)folder + uids:(MCOIndexSet *)uids + kind:(MCOIMAPStoreFlagsRequestKind)kind + flags:(MCOMessageFlag)flags; +/** + Returns an operation to change labels of messages. Intended for Gmail + + For example: Adds the label "Home" flag to the message with UID 456. + + MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX" + uids:[MCOIndexSet indexSetWithIndex:456] + kind:MCOIMAPStoreFlagsRequestKindAdd + labels:[NSArray arrayWithObject:@"Home"]]; + [op start:^(NSError * error) { + ... + }]; +*/ +- (MCOIMAPOperation *) storeLabelsOperationWithFolder:(NSString *)folder + uids:(MCOIndexSet *)uids + kind:(MCOIMAPStoreFlagsRequestKind)kind + labels:(NSArray *)labels; + +/** @name Fetching Messages */ + +/** + Returns an operation to fetch messages by UID. + + MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByUIDOperationWithFolder:@"INBOX" + requestKind:MCOIMAPMessagesRequestKindHeaders | MCOIMAPMessagesRequestKindStructure + uids:MCORangeMake(1, UINT64_MAX)]; + [op start:^(NSError * error, NSArray * messages, MCOIndexSet * vanishedMessages) { + for(MCOIMAPMessage * msg in messages) { + NSLog(@"%lu: %@", [msg uid], [msg header]); + } + }]; +*/ - (MCOIMAPFetchMessagesOperation *) fetchMessagesByUIDOperationWithFolder:(NSString *)folder requestKind:(MCOIMAPMessagesRequestKind)requestKind uids:(MCOIndexSet *)uids; -// Returns an operation to fetch messages by number. -// The operation needs to be started. -// -// { -// ... -// // show 50 most recent uids. -// MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByNumberOperationWithFolder:@"INBOX" -// requestKind:MCOIMAPMessagesRequestKindUID -// uids:MCORangeMake(messageCount - 50, messageCount)]; -// [op start:^(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages) { -// for(MCOIMAPMessage * msg in messages) { -// NSLog(@"%lu", [msg uid]); -// } -// }]; -// +/** + Returns an operation to fetch messages by (sequence) number. + For example: show 50 most recent uids. + MCOIMAPFetchMessagesOperation * op = [session fetchMessagesByNumberOperationWithFolder:@"INBOX" + requestKind:MCOIMAPMessagesRequestKindUID + uids:MCORangeMake(messageCount - 50, messageCount)]; + [op start:^(NSError * error, NSArray * messages, MCOIndexSet * vanishedMessages) { + for(MCOIMAPMessage * msg in messages) { + NSLog(@"%lu", [msg uid]); + } + }]; +*/ - (MCOIMAPFetchMessagesOperation *) fetchMessagesByNumberOperationWithFolder:(NSString *)folder requestKind:(MCOIMAPMessagesRequestKind)requestKind numbers:(MCOIndexSet *)numbers; -// Returns an operation to sync the last changes related to the given message list given a modSeq. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPFetchMessagesOperation * op = [session syncMessagesByUIDWithFolder:@"INBOX" -// requestKind:MCOIMAPMessagesRequestKindUID -// uids:MCORangeMake(1, UINT64_MAX) -// modSeq:lastModSeq]; -// [op start:^(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages) { -// NSLog(@"added or modified messages: %@", messages); -// NSLog(@"deleted messages: %@", vanishedMessages); -// }]; -// +/** + Returns an operation to sync the last changes related to the given message list given a modSeq. + + MCOIMAPFetchMessagesOperation * op = [session syncMessagesByUIDWithFolder:@"INBOX" + requestKind:MCOIMAPMessagesRequestKindUID + uids:MCORangeMake(1, UINT64_MAX) + modSeq:lastModSeq]; + [op start:^(NSError * error, NSArray * messages, MCOIndexSet * vanishedMessages) { + NSLog(@"added or modified messages: %@", messages); + NSLog(@"deleted messages: %@", vanishedMessages); + }]; + +@warn *Important*: This is only for servers that support Conditional Store. See [RFC4551](http://tools.ietf.org/html/rfc4551) +*/ - (MCOIMAPFetchMessagesOperation *) syncMessagesByUIDWithFolder:(NSString *)folder requestKind:(MCOIMAPMessagesRequestKind)requestKind uids:(MCOIndexSet *)uids modSeq:(uint64_t)modSeq; -// Returns an operation to fetch the content of a message. -// The operation needs to be started. -// If urgent is set to YES, an additional connection to the same folder might be opened to fetch the content. -// -// { -// ... -// MCOIMAPFetchContentOperation * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456 urgent:NO]; -// [op start:^(NSError * error, NSData * messageData) { -// MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData] -// ... -// }]; -// +/** + Returns an operation to fetch the content of a message. + @param urgent is set to YES, an additional connection to the same folder might be opened to fetch the content. + + MCOIMAPFetchContentOperation * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456 urgent:NO]; + [op start:^(NSError * error, NSData * messageData) { + MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData] + ... + }]; +*/ - (MCOIMAPFetchContentOperation *) fetchMessageByUIDOperationWithFolder:(NSString *)folder uid:(uint32_t)uid urgent:(BOOL)urgent; -// Returns an operation to fetch the content of a message. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPFetchContentOperation * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456]; -// [op start:^(NSError * error, NSData * messageData) { -// MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData] -// ... -// }]; -// +/** + Returns an operation to fetch the content of a message. + + MCOIMAPFetchContentOperation * op = [session fetchMessageByUIDOperationWithFolder:@"INBOX" uid:456]; + [op start:^(NSError * error, NSData * messageData) { + MCOMessageParser * parser = [MCOMessageParser messageParserWithData:messageData] + ... + }]; +*/ - (MCOIMAPFetchContentOperation *) fetchMessageByUIDOperationWithFolder:(NSString *)folder uid:(uint32_t)uid; -// Returns an operation to fetch an attachment. -// The operation needs to be started. -// If urgent is set to YES, an additional connection to the same folder might be opened to fetch the content. -// -// { -// ... -// MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX" -// uid:456 -// partID:@"1.2" -// encoding:MCOEncodingBase64 -// urgent:YES]; -// [op start:^(NSError * error, NSData * partData) { -// ... -// }]; -// +/** @name Fetching Attachment Operations */ + +/** + Returns an operation to fetch an attachment. + @param urgent is set to YES, an additional connection to the same folder might be opened to fetch the content. + + MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX" + uid:456 + partID:@"1.2" + encoding:MCOEncodingBase64 + urgent:YES]; + [op start:^(NSError * error, NSData * partData) { + ... + }]; +*/ - (MCOIMAPFetchContentOperation *) fetchMessageAttachmentByUIDOperationWithFolder:(NSString *)folder uid:(uint32_t)uid partID:(NSString *)partID encoding:(MCOEncoding)encoding urgent:(BOOL)urgent; -// Returns an operation to fetch an attachment. -// The operation needs to be started. -// -// Example 1: -// { -// ... -// MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX" -// uid:456 -// partID:@"1.2" -// encoding:MCOEncodingBase64]; -// [op start:^(NSError * error, NSData * partData) { -// ... -// }]; -// -// Example 2: -// { -// ... -// MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX" -// uid:[message uid] -// partID:[part partID] -// encoding:[part encoding]]; -// [op start:^(NSError * error, NSData * partData) { -// ... -// }]; -// +/** + Returns an operation to fetch an attachment. + + Example 1: + + MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX" + uid:456 + partID:@"1.2" + encoding:MCOEncodingBase64]; + [op start:^(NSError * error, NSData * partData) { + ... + }]; + + Example 2: + + MCOIMAPFetchContentOperation * op = [session fetchMessageAttachmentByUIDOperationWithFolder:@"INBOX" + uid:[message uid] + partID:[part partID] + encoding:[part encoding]]; + [op start:^(NSError * error, NSData * partData) { + ... + }]; +*/ - (MCOIMAPFetchContentOperation *) fetchMessageAttachmentByUIDOperationWithFolder:(NSString *)folder uid:(uint32_t)uid partID:(NSString *)partID encoding:(MCOEncoding)encoding; -// Returns an operation to change flags of messages. -// The operation needs to be started. -// -// Adds the seen flag to the message with UID 456. -// { -// ... -// MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX" -// uids:[MCOIndexSet indexSetWithIndex:456] -// kind:MCOIMAPStoreFlagsRequestKindAdd -// flags:MCOMessageFlagSeen]; -// [op start:^(NSError * error) { -// ... -// }]; -// -- (MCOIMAPOperation *) storeFlagsOperationWithFolder:(NSString *)folder - uids:(MCOIndexSet *)uids - kind:(MCOIMAPStoreFlagsRequestKind)kind - flags:(MCOMessageFlag)flags; - -// Returns an operation to change labels of messages. -// The operation needs to be started. -// -// Adds the label "Home" flag to the message with UID 456. -// { -// ... -// MCOIMAPOperation * op = [session storeFlagsOperationWithFolder:@"INBOX" -// uids:[MCOIndexSet indexSetWithIndex:456] -// kind:MCOIMAPStoreFlagsRequestKindAdd -// labels:[NSArray arrayWithObject:@"Home"]]; -// [op start:^(NSError * error) { -// ... -// }]; -// -- (MCOIMAPOperation *) storeLabelsOperationWithFolder:(NSString *)folder - uids:(MCOIndexSet *)uids - kind:(MCOIMAPStoreFlagsRequestKind)kind - labels:(NSArray *)labels; +/** @name General IMAP Actions */ -// Returns an operation to search for messages with a simple match. -// The operation needs to be started. -// -// ... -// MCOIMAPSearchOperation * op = [session searchOperationWithFolder:@"INBOX" -// kind:MCOIMAPSearchKindFrom -// searchString:@"laura"]; -// [op start:^(NSError * error, MCOIndexSet * searchResult) { -// ... -// }]; -// -- (MCOIMAPSearchOperation *) searchOperationWithFolder:(NSString *)folder - kind:(MCOIMAPSearchKind)kind - searchString:(NSString *)searchString; +/** + Returns an operation to wait for something to happen in the folder. + See [RFC2177](http://tools.ietf.org/html/rfc2177) for me info. -// Returns an operation to search for messages. -// The operation needs to be started. -// -// ... -// MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] -// MCOIMAPSearchOperation * op = [session searchExpressionOperationWithFolder:@"INBOX" -// expression:expr]; -// [op start:^(NSError * error, MCOIndexSet * searchResult) { -// ... -// }]; -// -- (MCOIMAPSearchOperation *) searchExpressionOperationWithFolder:(NSString *)folder - expression:(MCOIMAPSearchExpression *)expression; - -// Returns an operation to wait for something to happen in the folder. -// The operation needs to be started. -// -// ... -// MCOIMAPIdleOperation * op = [session idleOperationWithFolder:@"INBOX" -// lastKnownUID:0]; -// [op start:^(NSError * error) { -// ... -// }]; -// + MCOIMAPIdleOperation * op = [session idleOperationWithFolder:@"INBOX" + lastKnownUID:0]; + [op start:^(NSError * error) { + ... + }]; +*/ - (MCOIMAPIdleOperation *) idleOperationWithFolder:(NSString *)folder lastKnownUID:(uint32_t)lastKnownUID; -// Returns an operation to fetch the list of namespaces. -// The operation needs to be started. -// -// ... -// MCOIMAPFetchNamespaceOperation * op = [session fetchNamespaceOperation]; -// [op start:^(NSError * error, NSDictionary * namespaces) { -// if (error != nil) -// return; -// MCOIMAPNamespace * ns = [namespace objectForKey:MCOIMAPNamespacePersonal]; -// NSString * path = [ns pathForComponents:[NSArray arrayWithObject:]]; -// MCOIMAPOperation * createOp = [session createFolderOperation:foobar]; -// [createOp start:^(NSError * error) { -// ... -// }]; -// }]; -// +/** + Returns an operation to fetch the list of namespaces. + + MCOIMAPFetchNamespaceOperation * op = [session fetchNamespaceOperation]; + [op start:^(NSError * error, NSDictionary * namespaces) { + if (error != nil) + return; + MCOIMAPNamespace * ns = [namespace objectForKey:MCOIMAPNamespacePersonal]; + NSString * path = [ns pathForComponents:[NSArray arrayWithObject:]]; + MCOIMAPOperation * createOp = [session createFolderOperation:foobar]; + [createOp start:^(NSError * error) { + ... + }]; + }]; +*/ - (MCOIMAPFetchNamespaceOperation *) fetchNamespaceOperation; -// Returns an operation to send/get identity. -// The operation needs to be started. -// -// ... -// MCOIMAPIdentityOperation * op = [session identityOperationWithVendor:@"Mozilla" -// name:@"Thunderbird" -// version:@"17.0.5"]; -// [op start:^(NSError * error, NSDictionary * serverIdentity) { -// ... -// }]; -// +/** + Returns an operation to send the client or get the server identity. + + MCOIMAPIdentityOperation * op = [session identityOperationWithVendor:@"Mozilla" + name:@"Thunderbird" + version:@"17.0.5"]; + [op start:^(NSError * error, NSDictionary * serverIdentity) { + ... + }]; +*/ - (MCOIMAPIdentityOperation *) identityOperationWithVendor:(NSString *)vendor name:(NSString *)name version:(NSString *)version; -// Returns an operation that will check whether the IMAP account is valid. -// The operation needs to be started. -// -// { -// ... -// MCOIMAPOperation * op = [session checkAccountOperation]; -// [op start:^(NSError * error) { -// ... -// }]]; -// + +/** + Returns an operation that will check whether the IMAP account is valid. + + MCOIMAPOperation * op = [session checkAccountOperation]; + [op start:^(NSError * error) { + ... + }]; +*/ - (MCOIMAPOperation *) checkAccountOperation; -// Returns an operation to request capabilities of the server. -// See MCOIMAPCapability for the list of capabilities. -// The operation needs to be started. -// -// { -// ... -// canIdle = NO; -// MCOIMAPCapabilityOperation * op = [session capabilityOperation]; -// [op start:^(NSError * error, MCOIndexSet * capabilities) { -// if ([capabilities containsIndex:MCOIMAPCapabilityIdle]) { -// canIdle = YES; -// } -// }]]; -// +/** + Returns an operation to request capabilities of the server. + See MCOIMAPCapability for the list of capabilities. + + canIdle = NO; + MCOIMAPCapabilityOperation * op = [session capabilityOperation]; + [op start:^(NSError * error, MCOIndexSet * capabilities) { + if ([capabilities containsIndex:MCOIMAPCapabilityIdle]) { + canIdle = YES; + } + }]; +*/ - (MCOIMAPCapabilityOperation *) capabilityOperation; +/** @name Search Operations */ + +/** + Returns an operation to search for messages with a simple match. + + MCOIMAPSearchOperation * op = [session searchOperationWithFolder:@"INBOX" + kind:MCOIMAPSearchKindFrom + searchString:@"laura"]; + [op start:^(NSError * error, MCOIndexSet * searchResult) { + ... + }]; +*/ +- (MCOIMAPSearchOperation *) searchOperationWithFolder:(NSString *)folder + kind:(MCOIMAPSearchKind)kind + searchString:(NSString *)searchString; + +/** + Returns an operation to search for messages. + + MCOIMAPSearchExpression * expr = [MCOIMAPSearchExpression searchFrom:@"laura@etpan.org"] + MCOIMAPSearchOperation * op = [session searchExpressionOperationWithFolder:@"INBOX" + expression:expr]; + [op start:^(NSError * error, MCOIndexSet * searchResult) { + ... + }]; +*/ +- (MCOIMAPSearchOperation *) searchExpressionOperationWithFolder:(NSString *)folder + expression:(MCOIMAPSearchExpression *)expression; + @end #endif diff --git a/src/objc/smtp/MCOSMTPOperation.h b/src/objc/smtp/MCOSMTPOperation.h index 32d98dc8..7e6fa3f8 100644 --- a/src/objc/smtp/MCOSMTPOperation.h +++ b/src/objc/smtp/MCOSMTPOperation.h @@ -12,13 +12,20 @@ #import <MailCore/MCOOperation.h> -// This is an asynchronous SMTP operation. +/** This is an asynchronous SMTP operation, used for sending messages. */ @interface MCOSMTPOperation : MCOOperation -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. +/** + Starts the asynchronous operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in MCOConstants.h, +*/ - (void) start:(void (^)(NSError * error))completionBlock; @end diff --git a/src/objc/smtp/MCOSMTPSendOperation.h b/src/objc/smtp/MCOSMTPSendOperation.h index e8a0f6b5..8e2dc56d 100644 --- a/src/objc/smtp/MCOSMTPSendOperation.h +++ b/src/objc/smtp/MCOSMTPSendOperation.h @@ -12,19 +12,25 @@ #import <MailCore/MCOSMTPOperation.h> -// This is an asynchronous operation that will send a message through SMTP. +/** This is an asynchronous operation that will send a message through SMTP. */ typedef void (^MCOSMTPOperationProgressBlock)(unsigned int current, unsigned int maximum); @interface MCOSMTPSendOperation : MCOSMTPOperation -// This block will be called during the progression while sending the message -// when some bytes have been sent to the network. +/** This block will be called as the message is sent */ @property (nonatomic, copy) MCOSMTPOperationProgressBlock progress; -// Starts the asynchronous operation. -// On success, the completion block will be called with nil as error. -// On failure, error will be set with MCOErrorDomain as domain and an error code available in MCOConstants.h. +/* + Starts the asynchronous operation. + + @param completionBlock Called when the operation is finished. + + - On success `error` will be nil + + - On failure, `error` will be set with `MCOErrorDomain` as domain and an + error code available in MCOConstants.h, +*/ - (void) start:(void (^)(NSError * error))completionBlock; @end diff --git a/src/objc/smtp/MCOSMTPSession.h b/src/objc/smtp/MCOSMTPSession.h index e0645eb1..08189bed 100644 --- a/src/objc/smtp/MCOSMTPSession.h +++ b/src/objc/smtp/MCOSMTPSession.h @@ -14,7 +14,12 @@ #import <MailCore/MCOConstants.h> -// This class implements asynchronous SMTP protocol. +/** + This class is used to create an SMTP connection and send messages + + After calling a method that returns an operation you must call start: on the instance + to begin the operation. +*/ @class MCOSMTPSendOperation; @class MCOSMTPOperation; @@ -22,63 +27,67 @@ @interface MCOSMTPSession : NSObject -// This is the hostname of the POP3 server to connect to. +/** This is the hostname of the SMTP server to connect to. */ @property (nonatomic, copy) NSString * hostname; -// This is the port of the POP3 server to connect to. +/** This is the port of the POP3 server to connect to. */ @property (nonatomic, assign) unsigned int port; -// This is the username of the account. +/** This is the username of the account. */ @property (nonatomic, copy) NSString * username; -// This is the password of the account. +/** This is the password of the account. */ @property (nonatomic, copy) NSString * password; -// This is the authentication type to use to connect. -// MCOAuthTypeSASLNone means that it uses the clear-text password authentication. -// It's the default. -// Note: However, over a encrypted connection, the password will be safe. +/** + This is the authentication type to use to connect. + `MCOAuthTypeSASLNone` means that it uses the clear-text is used (and is the default). + @warning *Important*: Over an encrypted connection like TLS, the password will still be secure +*/ @property (nonatomic, assign) MCOAuthType authType; -// This is the encryption type to use. -// See MCOConnectionType for more information. +/** + This is the encryption type to use. + See MCOConnectionType for more information. +*/ @property (nonatomic, assign) MCOConnectionType connectionType; -// This is the timeout of the connection. +/** This is the timeout of the connection. */ @property (nonatomic, assign) NSTimeInterval timeout; -// When set to YES, the connection will fail if the certificate is incorrect. +/** When set to YES, the connection will fail if the certificate is incorrect. */ @property (nonatomic, assign, getter=isCheckCertificateEnabled) BOOL checkCertificateEnabled; -// If set to YES, when sending the EHLO or HELO command, use IP address instead of hostname. -// Default is NO. +/** + If set to YES, when sending the EHLO or HELO command, use IP address instead of hostname. + Default is NO. +*/ @property (nonatomic, assign, getter=isUseHeloIPEnabled) BOOL useHeloIPEnabled; -// Returns an operation that will send the given message through SMTP. -// The operation needs to be started. -// It will use the recipient set in the message data (To, Cc and Bcc). -// It will also filter out Bcc from the content of the message. -// -// { -// ... -// // Generate RFC 822 data using MCOMessageBuilder -// MCOPOPOperation * op = [session sendOperationWithData:rfc822Data]; -// [op start:^(NSError * error) { -// ... -// }]; -// +/** @name Operations */ + +/** + Returns an operation that will send the given message through SMTP. + It will use the recipient set in the message data (To, Cc and Bcc). + It will also filter out Bcc from the content of the message. + + Generate RFC 822 data using MCOMessageBuilder + + MCOPOPOperation * op = [session sendOperationWithData:rfc822Data]; + [op start:^(NSError * error) { + ... + }]; +*/ - (MCOSMTPSendOperation *) sendOperationWithData:(NSData *)messageData; -// Returns an operation that will check whether the SMTP account is valid. -// The operation needs to be started. -// -// { -// ... -// MCOPOPOperation * op = [session checkAccountOperationWithFrom:[MCOAddress addressWithMailbox:@"hoa@etpan.org"]]; -// [op start:^(NSError * error) { -// ... -// }]; -// +/** + Returns an operation that will check whether the SMTP account is valid. + + MCOPOPOperation * op = [session checkAccountOperationWithFrom:[MCOAddress addressWithMailbox:@"hoa@etpan.org"]]; + [op start:^(NSError * error) { + ... + }]; +*/ - (MCOSMTPOperation *) checkAccountOperationWithFrom:(MCOAddress *)from; @end |