commit b6940b482c8ef744c74cabba410c27c515170aae Author: Oswald Buddenhagen <o...@kde.org> Date: Sun Nov 14 23:16:32 2010 +0100
docs - insert "separator comments" between driver entry points - document driver API - fix one comment src/drv_imap.c | 36 ++++++++++++++++++++++++++- src/isync.h | 63 ++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 94 insertions(+), 5 deletions(-) diff --git a/src/drv_imap.c b/src/drv_imap.c index 5f9450d..f1fea71 100644 --- a/src/drv_imap.c +++ b/src/drv_imap.c @@ -150,7 +150,7 @@ struct imap_cmd { void (*done)( imap_store_t *ctx, struct imap_cmd *cmd, int response ); char *data; int data_len; - int uid; /* to identify fetch responses */ + int uid; /* to identify fetch & search responses */ unsigned to_trash:1, /* we are storing to trash, not current. */ create:1, /* create the mailbox if we get an error ... */ @@ -1248,6 +1248,8 @@ get_cmd_result_p2( imap_store_t *ctx, struct imap_cmd *cmd, int response ) } } +/******************* imap_cancel_store *******************/ + static void imap_cancel_store( store_t *gctx ) { @@ -1274,6 +1276,8 @@ imap_cancel_store( store_t *gctx ) deref_store( ctx ); } +/******************* imap_disown_store & imap_own_store *******************/ + static store_t *unowned; static void @@ -1298,6 +1302,8 @@ imap_own_store( store_conf_t *conf ) return 0; } +/******************* imap_cleanup *******************/ + static void imap_cleanup_p2( imap_store_t *, struct imap_cmd *, int ); static void @@ -1319,6 +1325,8 @@ imap_cleanup_p2( imap_store_t *ctx, imap_cancel_store( &ctx->gen ); } +/******************* imap_open_store *******************/ + #ifdef HAVE_LIBSSL static int start_tls( imap_store_t *ctx ) @@ -1770,6 +1778,8 @@ imap_open_store_bail( imap_store_t *ctx ) cb( 0, aux ); } +/******************* imap_prepare_paths *******************/ + static void imap_prepare_paths( store_t *gctx ) { @@ -1777,12 +1787,16 @@ imap_prepare_paths( store_t *gctx ) gctx->msgs = 0; } +/******************* imap_prepare_opts *******************/ + static void imap_prepare_opts( store_t *gctx, int opts ) { gctx->opts = opts; } +/******************* imap_select *******************/ + struct imap_cmd_select { struct imap_cmd_simple gen; int minuid, maxuid, *excs, nexcs; @@ -1912,6 +1926,8 @@ imap_select2_p2( imap_store_t *ctx ATTR_UNUSED, struct imap_cmd *cmd, int respon imap_refcounted_done( sts ); } +/******************* imap_fetch_msg *******************/ + static void imap_fetch_msg( store_t *ctx, message_t *msg, msg_data_t *data, void (*cb)( int sts, void *aux ), void *aux ) @@ -1926,6 +1942,8 @@ imap_fetch_msg( store_t *ctx, message_t *msg, msg_data_t *data, msg->uid, (msg->status & M_FLAGS) ? "" : "FLAGS " ); } +/******************* imap_set_flags *******************/ + static void imap_set_flags_p2( imap_store_t *, struct imap_cmd *, int ); static int @@ -2017,6 +2035,8 @@ imap_set_flags_p2( imap_store_t *ctx ATTR_UNUSED, struct imap_cmd *cmd, int resp imap_refcounted_done( sts ); } +/******************* imap_close *******************/ + static void imap_close( store_t *ctx, void (*cb)( int sts, void *aux ), void *aux ) @@ -2027,6 +2047,8 @@ imap_close( store_t *ctx, imap_exec( (imap_store_t *)ctx, &cmd->gen, imap_done_simple_box, "CLOSE" ); } +/******************* imap_trash_msg *******************/ + static void imap_trash_msg( store_t *gctx, message_t *msg, void (*cb)( int sts, void *aux ), void *aux ) @@ -2042,6 +2064,8 @@ imap_trash_msg( store_t *gctx, message_t *msg, msg->uid, ctx->prefix, gctx->conf->trash ); } +/******************* imap_store_msg *******************/ + static void imap_store_msg_p2( imap_store_t *, struct imap_cmd *, int ); static void @@ -2088,6 +2112,8 @@ imap_store_msg_p2( imap_store_t *ctx ATTR_UNUSED, struct imap_cmd *cmd, int resp cmdp->callback( response, cmdp->out_uid, cmdp->callback_aux ); } +/******************* imap_find_msg *******************/ + static void imap_find_msg_p2( imap_store_t *, struct imap_cmd *, int ); static void @@ -2117,6 +2143,8 @@ imap_find_msg_p2( imap_store_t *ctx ATTR_UNUSED, struct imap_cmd *cmd, int respo cmdp->out_uid, cmdp->callback_aux ); } +/******************* imap_list *******************/ + struct imap_cmd_list { struct imap_cmd gen; void (*callback)( int sts, void *aux ); @@ -2148,6 +2176,8 @@ imap_list_p2( imap_store_t *ctx, struct imap_cmd *cmd, int response ) cmdp->callback( response, cmdp->callback_aux ); } +/******************* imap_cancel *******************/ + static void imap_cancel( store_t *gctx, void (*cb)( void *aux ), void *aux ) @@ -2156,12 +2186,16 @@ imap_cancel( store_t *gctx, cb( aux ); } +/******************* imap_commit *******************/ + static void imap_commit( store_t *gctx ) { (void)gctx; } +/******************* imap_parse_store *******************/ + imap_server_conf_t *servers, **serverapp = &servers; static int diff --git a/src/isync.h b/src/isync.h index b34f08c..ffeb656 100644 --- a/src/isync.h +++ b/src/isync.h @@ -168,6 +168,8 @@ typedef struct store { int recent; /* # of recent messages - don't trust this beyond the initial read */ } store_t; +/* When the callback is invoked (at most once per store), the store is fubar; + * call the driver's cancel_store() to dispose of it. */ static INLINE void set_bad_callback( store_t *ctx, void (*cb)( void *aux ), void *aux ) { @@ -182,8 +184,11 @@ typedef struct { } msg_data_t; #define DRV_OK 0 +/* Message went missing, or mailbox is full, etc. */ #define DRV_MSG_BAD 1 +/* Something is wrong with the current mailbox - probably it's somehow inaccessible. */ #define DRV_BOX_BAD 2 +/* The command has been cancel()ed or cancel_store()d. */ #define DRV_CANCELED 3 /* All memory belongs to the driver's user. */ @@ -199,33 +204,83 @@ typedef struct { struct driver { int flags; + + /* Parse configuration. */ int (*parse_store)( conffile_t *cfg, store_conf_t **storep, int *err ); + + /* Close remaining server connections. All stores must be disowned first. */ void (*cleanup)( void ); + + /* Open a store with the given configuration. This may recycle existing + * server connections. Upon failure, a null store is passed to the callback. */ void (*open_store)( store_conf_t *conf, void (*cb)( store_t *ctx, void *aux ), void *aux ); + + /* Mark the store as available for recycling. Server connection may be kept alive. */ void (*disown_store)( store_t *ctx ); + + /* Try to recycle a store with the given configuration. */ store_t *(*own_store)( store_conf_t *conf ); + + /* Discard the store after a bad_callback. The server connections will be closed. + * Pending commands will have their callbacks synchronously invoked with DRV_CANCELED. */ void (*cancel_store)( store_t *ctx ); + + /* List the mailboxes in this store. */ void (*list)( store_t *ctx, void (*cb)( int sts, void *aux ), void *aux ); + + /* Invoked after setting ctx->name, this should resolve ctx->path if applicable. */ void (*prepare_paths)( store_t *ctx ); + + /* Invoked before select(), this informs the driver which operations (OP_*) + * will be performed on the mailbox. The driver may extend the set by implicitly + * needed or available operations. */ void (*prepare_opts)( store_t *ctx, int opts ); + + /* Open the previously prepared mailbox and load the message attributes needed to + * perform the requested operations. Consider only messages with UIDs between minuid + * and maxuid (inclusive) and those named in the excs array (smaller than minuid). */ void (*select)( store_t *ctx, int minuid, int maxuid, int *excs, int nexcs, void (*cb)( int sts, void *aux ), void *aux ); + + /* Fetch the contents and flags of the given message from the current mailbox. */ void (*fetch_msg)( store_t *ctx, message_t *msg, msg_data_t *data, void (*cb)( int sts, void *aux ), void *aux ); + + /* Store the given message to either the current mailbox or the trash folder. + * If the new copy's UID can be immediately determined, return it, otherwise -1. */ void (*store_msg)( store_t *ctx, msg_data_t *data, int to_trash, void (*cb)( int sts, int uid, void *aux ), void *aux ); + + /* Find a message by its temporary UID header to determine its real UID. */ void (*find_msg)( store_t *ctx, const char *tuid, void (*cb)( int sts, int uid, void *aux ), void *aux ); - void (*set_flags)( store_t *ctx, message_t *msg, int uid, int add, int del, /* msg can be null, therefore uid as a fallback */ + + /* Add/remove the named flags to/from the given message. The message may be either + * a pre-fetched one (in which case the in-memory representation is updated), + * or it may be identifed by UID only. The operation may be delayed until commit() + * is called. */ + void (*set_flags)( store_t *ctx, message_t *msg, int uid, int add, int del, void (*cb)( int sts, void *aux ), void *aux ); - void (*trash_msg)( store_t *ctx, message_t *msg, /* This may expunge the original message immediately, but it needn't to */ + + /* Move the given message from the current mailbox to the trash folder. + * This may expunge the original message immediately, but it needn't to. */ + void (*trash_msg)( store_t *ctx, message_t *msg, void (*cb)( int sts, void *aux ), void *aux ); - void (*close)( store_t *ctx, /* IMAP-style: expunge inclusive */ + + /* Expunge deleted messages from the current mailbox and close it. + * There is no need to explicitly close a mailbox if no expunge is needed. */ + void (*close)( store_t *ctx, void (*cb)( int sts, void *aux ), void *aux ); - void (*cancel)( store_t *ctx, /* only not yet sent commands */ + + /* Cancel queued commands which are not in flight yet. They will have their + * callbacks invoked with DRV_CANCELED. Afterwards, wait for the completion of + * the in-flight commands. */ + void (*cancel)( store_t *ctx, void (*cb)( void *aux ), void *aux ); + + /* Commit any pending set_flags() commands. */ void (*commit)( store_t *ctx ); }; ------------------------------------------------------------------------------ Colocation vs. Managed Hosting A question and answer guide to determining the best fit for your organization - today and in the future. http://p.sf.net/sfu/internap-sfd2d _______________________________________________ isync-devel mailing list isync-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/isync-devel