Permalink
Browse files

Work in progress on IMAP documentation.

  • Loading branch information...
1 parent ed6ba5a commit abc2b119c709a3fcea92ea1750f208b2bf47c9d5 @dinhviethoa dinhviethoa committed Apr 6, 2013
Showing with 506 additions and 68 deletions.
  1. +6 −6 build-mac/mailcore2.xcodeproj/project.pbxproj
  2. +0 −10 src/async/imap/MCIMAPFetchMessagesOperation.cc
  3. +1 −1 src/core/abstract/MCMessageConstants.h
  4. +2 −2 src/core/imap/MCIMAPSession.cc
  5. +14 −0 src/objc/abstract/MCOAbstractPart.h
  6. +79 −0 src/objc/abstract/MCOConstants.h
  7. +10 −1 src/objc/imap/MCOIMAPAppendMessageOperation.h
  8. +7 −1 src/objc/imap/MCOIMAPBaseOperation.h
  9. +8 −1 src/objc/imap/MCOIMAPCapabilityOperation.h
  10. +8 −1 src/objc/imap/MCOIMAPCopyMessagesOperation.h
  11. +10 −1 src/objc/imap/MCOIMAPFetchContentOperation.h
  12. +9 −1 src/objc/imap/MCOIMAPFetchFoldersOperation.h
  13. +1 −1 src/objc/imap/MCOIMAPFetchFoldersOperation.mm
  14. +10 −1 src/objc/imap/MCOIMAPFetchMessagesOperation.h
  15. +14 −1 src/objc/imap/MCOIMAPFetchNamespaceOperation.h
  16. +7 −0 src/objc/imap/MCOIMAPFolder.h
  17. +10 −0 src/objc/imap/MCOIMAPFolderInfo.h
  18. +10 −1 src/objc/imap/MCOIMAPFolderInfoOperation.h
  19. +8 −1 src/objc/imap/MCOIMAPIdentityOperation.h
  20. +7 −1 src/objc/imap/MCOIMAPIdleOperation.h
  21. +19 −2 src/objc/imap/MCOIMAPMessage.h
  22. +0 −10 src/objc/imap/MCOIMAPMessage.mm
  23. +4 −0 src/objc/imap/MCOIMAPMessagePart.h
  24. +4 −0 src/objc/imap/MCOIMAPMultipart.h
  25. +19 −0 src/objc/imap/MCOIMAPNamespace.h
  26. +10 −0 src/objc/imap/MCOIMAPNamespaceItem.h
  27. +6 −1 src/objc/imap/MCOIMAPOperation.h
  28. +8 −0 src/objc/imap/MCOIMAPPart.h
  29. +47 −0 src/objc/imap/MCOIMAPSearchExpression.h
  30. +7 −1 src/objc/imap/MCOIMAPSearchOperation.h
  31. +101 −1 src/objc/imap/MCOIMAPSession.h
  32. +2 −0 src/objc/imap/MCOIMAPSession.mm
  33. +7 −1 src/objc/pop/MCOPOPFetchHeaderOperation.h
  34. +6 −2 src/objc/pop/MCOPOPFetchMessageOperation.h
  35. +6 −1 src/objc/pop/MCOPOPFetchMessagesOperation.h
  36. +5 −1 src/objc/pop/MCOPOPOperation.h
  37. +4 −0 src/objc/pop/MCOPOPSession.h
  38. +6 −1 src/objc/smtp/MCOSMTPOperation.h
  39. +5 −2 src/objc/smtp/MCOSMTPSendOperation.h
  40. +2 −0 src/objc/smtp/MCOSMTPSession.h
  41. +2 −2 src/objc/utils/MCOOperation+Private.h
  42. +2 −2 src/objc/utils/MCOOperation.h
  43. +7 −7 src/objc/utils/MCOOperation.mm
  44. +1 −1 src/objc/utils/NSError+MCO.h
  45. +5 −2 src/objc/utils/NSError+MCO.mm
@@ -1830,10 +1830,6 @@
C64BB25416FD32A0000DB34C /* MCOIMAP.h */,
F8EA941416BAED6E0011AC6F /* MCOIMAPSession.h */,
C07AD057D3C8FBDC7AC95733 /* MCOIMAPSession.mm */,
- F87F190816BB62690012652F /* MCOIMAPFetchFoldersOperation.h */,
- F87F190B16BB62B00012652F /* MCOIMAPFetchFoldersOperation.mm */,
- C623C58D16FE6B45001BBEFC /* MCOIMAPOperation.h */,
- C623C58E16FE6B45001BBEFC /* MCOIMAPOperation.mm */,
C623C59116FE750D001BBEFC /* MCOIMAPFolder.h */,
C623C59216FE750E001BBEFC /* MCOIMAPFolder.mm */,
C6F5B9E016FEA1E800D9DABD /* MCOIMAPMessage.h */,
@@ -1848,10 +1844,14 @@
C6F5B9ED16FEA3C400D9DABD /* MCOIMAPNamespaceItem.mm */,
C6F5B9EF16FEA3D700D9DABD /* MCOIMAPPart.h */,
C6F5B9F016FEA3D700D9DABD /* MCOIMAPPart.mm */,
- C6F61F79170169EE0073032E /* MCOIMAPFolderInfoOperation.h */,
- C6F61F7A170169EE0073032E /* MCOIMAPFolderInfoOperation.mm */,
C6F61F9D17016EA00073032E /* MCOIMAPFolderInfo.h */,
C6F61F9E17016EA00073032E /* MCOIMAPFolderInfo.m */,
+ F87F190816BB62690012652F /* MCOIMAPFetchFoldersOperation.h */,
+ F87F190B16BB62B00012652F /* MCOIMAPFetchFoldersOperation.mm */,
+ C623C58D16FE6B45001BBEFC /* MCOIMAPOperation.h */,
+ C623C58E16FE6B45001BBEFC /* MCOIMAPOperation.mm */,
+ C6F61F79170169EE0073032E /* MCOIMAPFolderInfoOperation.h */,
+ C6F61F7A170169EE0073032E /* MCOIMAPFolderInfoOperation.mm */,
C6F61FB31702AB2A0073032E /* MCOIMAPBaseOperation.h */,
C6F61FB41702AB2F0073032E /* MCOIMAPBaseOperation.mm */,
C6F61F7C170169FB0073032E /* MCOIMAPAppendMessageOperation.h */,
@@ -17,12 +17,6 @@ using namespace mailcore;
IMAPFetchMessagesOperation::IMAPFetchMessagesOperation()
{
mFetchByUidEnabled = false;
-#if 0
- mFirst = 0;
- mLast = 0;
- mUids = NULL;
- mNumbers = NULL;
-#endif
mIndexes = NULL;
mMessages = NULL;
mVanishedMessages = NULL;
@@ -31,10 +25,6 @@ IMAPFetchMessagesOperation::IMAPFetchMessagesOperation()
IMAPFetchMessagesOperation::~IMAPFetchMessagesOperation()
{
-#if 0
- MC_SAFE_RELEASE(mNumbers);
- MC_SAFE_RELEASE(mUids);
-#endif
MC_SAFE_RELEASE(mIndexes);
MC_SAFE_RELEASE(mMessages);
MC_SAFE_RELEASE(mVanishedMessages);
@@ -108,7 +108,7 @@ namespace mailcore {
IMAPCapabilityXList,
IMAPCapabilityAuthAnonymous,
IMAPCapabilityAuthCRAMMD5,
- MAPCapabilityAuthDigestMD5,
+ IMAPCapabilityAuthDigestMD5,
IMAPCapabilityAuthExternal,
IMAPCapabilityAuthGSSAPI,
IMAPCapabilityAuthKerberosV4,
@@ -1236,7 +1236,7 @@ void IMAPSession::copyMessages(String * folder, IndexSet * uidSet, String * dest
}
setList = splitSet(set, 10);
- uidSetResult = IndexSet::indexSet();
+ uidSetResult = NULL;
for(clistiter * iter = clist_begin(setList) ; iter != NULL ; iter = clist_next(iter)) {
struct mailimap_set * current_set;
@@ -1267,7 +1267,7 @@ void IMAPSession::copyMessages(String * folder, IndexSet * uidSet, String * dest
mailimap_set_free(dest_uid);
}
}
- * pDestUIDs = (IndexSet *) uidSetResult->autorelease();
+ * pDestUIDs = uidSetResult;
* pError = ErrorNone;
release:
@@ -15,10 +15,24 @@
@class MCOAbstractMessage;
typedef enum {
+ // Used for a single part.
+ // The part will be a MCOAbstractPart.
MCOPartTypeSingle,
+
+ // Used for a message part (MIME type: message/rfc822).
+ // The part will be a MCOAbstractMessagePart.
MCOPartTypeMessage,
+
+ // Used for a multipart, multipart/mixed.
+ // The part will be a MCOAbstractMultipart.
MCOPartTypeMultipartMixed,
+
+ // Used for a multipart, multipart/related.
+ // The part will be a MCOAbstractMultipart.
MCOPartTypeMultipartRelated,
+
+ // Used for a multipart, multipart/alternative.
+ // The part will be a MCOAbstractMultipart.
MCOPartTypeMultipartAlternative,
} MCOPartType;
@@ -166,6 +166,85 @@ typedef enum {
MCOIMAPSearchKindAnd,
} MCOIMAPSearchKind;
+// Keys for the namespace dictionary.
+#define MCOIMAPNamespacePersonal @"IMAPNamespacePersonal";
+#define MCOIMAPNamespaceOther @"IMAPNamespaceOther";
+#define MCOIMAPNamespaceShared @"IMAPNamespaceShared";
+
+// This is the constants for the IMAP capabilities.
+// See corresponding RFC for more information.
+typedef enum {
+ // ACL Capability.
+ MCOIMAPCapabilityACL,
+ // BINARY Capability.
+ MCOIMAPCapabilityBinary,
+ // CATENATE Capability.
+ MCOIMAPCapabilityCatenate,
+ // CHILDREN Capability.
+ MCOIMAPCapabilityChildren,
+ // COMPRESS Capability.
+ MCOIMAPCapabilityCompressDeflate,
+ // CONDSTORE Capability.
+ MCOIMAPCapabilityCondstore,
+ // ENABLE Capability.
+ MCOIMAPCapabilityEnable,
+ // IDLE Capability.
+ MCOIMAPCapabilityIdle,
+ // ID Capability.
+ MCOIMAPCapabilityId,
+ // LITERAL+ Capability.
+ MCOIMAPCapabilityLiteralPlus,
+ // MULTIAPPEND Capability.
+ MCOIMAPCapabilityMultiAppend,
+ // NAMESPACE Capability.
+ MCOIMAPCapabilityNamespace,
+ // QRESYNC Capability.
+ MCOIMAPCapabilityQResync,
+ // QUOTE Capability.
+ MCOIMAPCapabilityQuota,
+ // SORT Capability.
+ MCOIMAPCapabilitySort,
+ // STARTTLS Capability.
+ MCOIMAPCapabilityStartTLS,
+ // THREAD=ORDEREDSUBJECT Capability.
+ MCOIMAPCapabilityThreadOrderedSubject,
+ // THREAD=REFERENCES Capability.
+ MCOIMAPCapabilityThreadReferences,
+ // UIDPLUS Capability.
+ MCOIMAPCapabilityUIDPlus,
+ // UNSELECT Capability.
+ MCOIMAPCapabilityUnselect,
+ // XLIST Capability.
+ MCOIMAPCapabilityXList,
+ // AUTH=ANONYMOUS Capability.
+ MCOIMAPCapabilityAuthAnonymous,
+ // AUTH=CRAM-MD5 Capability.
+ MCOIMAPCapabilityAuthCRAMMD5,
+ // AUTH=DIGEST-MD5 Capability.
+ MCOIMAPCapabilityAuthDigestMD5,
+ // AUTH=EXTERNAL Capability.
+ MCOIMAPCapabilityAuthExternal,
+ // AUTH=GSSAPI Capability.
+ MCOIMAPCapabilityAuthGSSAPI,
+ // AUTH=KERBEROSV4 Capability.
+ MCOIMAPCapabilityAuthKerberosV4,
+ // AUTH=LOGIN Capability.
+ MCOIMAPCapabilityAuthLogin,
+ // AUTH=NTML Capability.
+ MCOIMAPCapabilityAuthNTLM,
+ // AUTH=OTP Capability.
+ MCOIMAPCapabilityAuthOTP,
+ // AUTH=PLAIN Capability.
+ MCOIMAPCapabilityAuthPlain,
+ // AUTH=SKEY Capability.
+ MCOIMAPCapabilityAuthSKey,
+ // AUTH=SRP Capability.
+ MCOIMAPCapabilityAuthSRP,
+} MCOIMAPCapability;
+
+// Error domain for mailcore.
+#define MCOErrorDomain @"MCOErrorDomain"
+
// Here's the list of errors.
typedef enum {
// No error occurred.
@@ -10,14 +10,23 @@
#define __MAILCORE_MCOIMAPAPPENDMESSAGEOPERATION_H_
+// 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.
@property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress;
-- (void)start:(void (^)(NSError *error, uint32_t createdUID))completionBlock;
+// 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.
+- (void) start:(void (^)(NSError * error, uint32_t createdUID))completionBlock;
@end
@@ -10,15 +10,21 @@
#define __MAILCORE_MCOIMAPBASEOPERATION_H_
+// It's a generic IMAP operation with progress.
+
#import <MailCore/MCOOperation.h>
typedef void (^MCOIMAPBaseOperationProgressBlock)(unsigned int current, unsigned int maximum);
typedef void (^MCOIMAPBaseOperationItemProgressBlock)(unsigned int current);
@interface MCOIMAPBaseOperation : MCOOperation
-// to be overriden by subclasses.
+// 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;
@end
@@ -10,13 +10,20 @@
#define __MAILCORE_MCOIMAPCAPBILITYOPERATION_H_
+// This class implements an operation to query capabilities.
+
#import <MailCore/MCOIMAPBaseOperation.h>
@class MCOIndexSet;
@interface MCOIMAPCapabilityOperation : MCOIMAPBaseOperation
-- (void)start:(void (^)(NSError *error, MCOIndexSet * capabilities))completionBlock;
+// 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.
+- (void) start:(void (^)(NSError * error, MCOIndexSet * capabilities))completionBlock;
@end
@@ -12,11 +12,18 @@
#define __MAILCORE_MCOCOPYMESSAGESOPERATION_H_
+// This class implements an operation to copy messages.
+
@class MCOIndexSet;
@interface MCOIMAPCopyMessagesOperation : MCOIMAPBaseOperation
-- (void)start:(void (^)(NSError *error, MCOIndexSet * destUids))completionBlock;
+// 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.
+- (void) start:(void (^)(NSError * error, MCOIndexSet * destUids))completionBlock;
@end
@@ -10,14 +10,23 @@
#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.
+
#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.
@property (nonatomic, copy) MCOIMAPBaseOperationProgressBlock progress;
-- (void)start:(void (^)(NSError *error, NSData * data))completionBlock;
+// 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.
+- (void) start:(void (^)(NSError * error, NSData * data))completionBlock;
@end
@@ -10,10 +10,18 @@
#define __MAILCORE_MCOIMAPFETCHFOLDERSOPERATION_H_
+// This class implements an operation to fetch a list of folders.
+
#import <MailCore/MCOIMAPBaseOperation.h>
@interface MCOIMAPFetchFoldersOperation : MCOIMAPBaseOperation
-- (void)start:(void (^)(NSError *error, NSArray *folder))completionBlock;
+
+// 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.
+- (void) start:(void (^)(NSError * error, NSArray * /* MCOIMAPFolder */ folders))completionBlock;
+
@end
#endif
@@ -43,7 +43,7 @@ - (void) dealloc
[super dealloc];
}
-- (void)start:(void (^)(NSError *error, NSArray *folder))completionBlock {
+- (void)start:(void (^)(NSError *error, NSArray * /* MCOIMAPFolder */ folders))completionBlock {
_completionBlock = [completionBlock copy];
[self start];
}
@@ -13,13 +13,22 @@
#import <MailCore/MCOIMAPBaseOperation.h>
#import <MailCore/MCOConstants.h>
+// This class implements an operation to fetch a list of messages.
+
@class MCOIndexSet;
@interface MCOIMAPFetchMessagesOperation : MCOIMAPBaseOperation
+// This block will be called each time a new message information will be downloaded.
@property (nonatomic, copy) MCOIMAPBaseOperationItemProgressBlock progress;
-- (void)start:(void (^)(NSError *error, NSArray * messages, MCOIndexSet * vanishedMessages))completionBlock;
+// 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.
+- (void) start:(void (^)(NSError * error, NSArray * /* MCOIMAPMessage */ messages, MCOIndexSet * vanishedMessages))completionBlock;
@end
@@ -10,11 +10,24 @@
#define __MAILCORE_MCOIMAPFETCHNAMESPACEOPERATION_H_
+// This class implements an operation to fetch namespaces.
+
#import <MailCore/MCOIMAPBaseOperation.h>
@interface MCOIMAPFetchNamespaceOperation : MCOIMAPBaseOperation
-- (void)start:(void (^)(NSError *error, NSDictionary * namespaces))completionBlock;
+// 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.
+- (void) start:(void (^)(NSError * error, NSDictionary * namespaces))completionBlock;
@end
Oops, something went wrong.

0 comments on commit abc2b11

Please sign in to comment.