commit 946a8b53df1ed75145b0e5e46a6c0a26ece49dad
Author: Oswald Buddenhagen <[email protected]>
Date: Sun Apr 3 18:21:46 2011 +0200
docs & related fixes
- insert "separator comments" between driver entry points
- document driver API
- use cont()'s return code according to doc
- etc.
src/drv_imap.c | 38 +++++++++++++++++++++++++-
src/isync.h | 71 ++++++++++++++++++++++++++++++++++++++++++++---
src/sync.c | 4 ++-
3 files changed, 106 insertions(+), 7 deletions(-)
diff --git a/src/drv_imap.c b/src/drv_imap.c
index bc24c1b..294228f 100644
--- a/src/drv_imap.c
+++ b/src/drv_imap.c
@@ -143,6 +143,8 @@ struct imap_cmd {
int tag;
struct {
+ /* Will be called on each continuation request until it resets
this pointer.
+ * Needs to invoke bad_callback and return < 0 on error. */
int (*cont)( imap_store_t *ctx, struct imap_cmd *cmd, const
char *prompt );
int (*done)( imap_store_t *ctx, struct imap_cmd *cmd, int
response );
char *data;
@@ -1155,7 +1157,7 @@ get_cmd_result( imap_store_t *ctx, struct imap_cmd *tcmd )
if (n != (int)cmdp->param.data_len)
break;
} else if (cmdp->param.cont) {
- if (cmdp->param.cont( ctx, cmdp, cmd ))
+ if (cmdp->param.cont( ctx, cmdp, cmd ) < 0)
break;
} else {
error( "IMAP error: unexpected command
continuation request\n" );
@@ -1243,6 +1245,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 )
{
@@ -1264,6 +1268,8 @@ imap_cancel_store( store_t *gctx )
free( ctx );
}
+/******************* imap_disown_store & imap_own_store *******************/
+
static store_t *unowned;
static void
@@ -1288,6 +1294,8 @@ imap_own_store( store_conf_t *conf )
return 0;
}
+/******************* imap_cleanup *******************/
+
static int imap_cleanup_p2( imap_store_t *, struct imap_cmd *, int );
static void
@@ -1311,6 +1319,8 @@ imap_cleanup_p2( imap_store_t *ctx,
return 0;
}
+/******************* imap_open_store *******************/
+
#ifdef HAVE_LIBSSL
static int
start_tls( imap_store_t *ctx )
@@ -1756,6 +1766,8 @@ imap_open_store_bail( imap_store_t *ctx )
return -1;
}
+/******************* imap_prepare_paths *******************/
+
static void
imap_prepare_paths( store_t *gctx )
{
@@ -1763,12 +1775,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;
@@ -1884,6 +1900,8 @@ imap_select2_p2( imap_store_t *ctx ATTR_UNUSED, struct
imap_cmd *cmd, int respon
return 0;
}
+/******************* imap_fetch_msg *******************/
+
static int
imap_fetch_msg( store_t *ctx, message_t *msg, msg_data_t *data,
int (*cb)( int sts, void *aux ), void *aux )
@@ -1898,6 +1916,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 int imap_set_flags_p2( imap_store_t *, struct imap_cmd *, int );
static int
@@ -1975,6 +1995,8 @@ imap_set_flags_p2( imap_store_t *ctx ATTR_UNUSED, struct
imap_cmd *cmd, int resp
return 0;
}
+/******************* imap_close *******************/
+
static int
imap_close( store_t *ctx,
int (*cb)( int sts, void *aux ), void *aux )
@@ -1985,6 +2007,8 @@ imap_close( store_t *ctx,
return imap_exec( (imap_store_t *)ctx, &cmd->gen, imap_done_simple_box,
"CLOSE" );
}
+/******************* imap_trash_msg *******************/
+
static int
imap_trash_msg( store_t *gctx, message_t *msg,
int (*cb)( int sts, void *aux ), void *aux )
@@ -2000,6 +2024,8 @@ imap_trash_msg( store_t *gctx, message_t *msg,
msg->uid, ctx->prefix, gctx->conf->trash );
}
+/******************* imap_store_msg *******************/
+
static int imap_store_msg_p2( imap_store_t *, struct imap_cmd *, int );
static int
@@ -2046,6 +2072,8 @@ imap_store_msg_p2( imap_store_t *ctx ATTR_UNUSED, struct
imap_cmd *cmd, int resp
return cmdp->callback( response, cmdp->out_uid, cmdp->callback_aux );
}
+/******************* imap_find_msg *******************/
+
static int imap_find_msg_p2( imap_store_t *, struct imap_cmd *, int );
static int
@@ -2075,6 +2103,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;
int (*callback)( int sts, void *aux );
@@ -2106,6 +2136,8 @@ imap_list_p2( imap_store_t *ctx, struct imap_cmd *cmd,
int response )
return cmdp->callback( response, cmdp->callback_aux );
}
+/******************* imap_cancel *******************/
+
static void
imap_cancel( store_t *gctx,
void (*cb)( void *aux ), void *aux )
@@ -2114,12 +2146,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 ba217e7..44513ce 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,11 +184,18 @@ 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. */
+/* All memory belongs to the driver's user, unless stated otherwise. */
+
+/* A negative return value from a function or a callback indicates an error
condition
+ * which has already been handled; the shortest route out of the call stack
should be
+ * taken as a consequence. */
/*
This flag says that the driver CAN store messages with CRLFs,
@@ -199,33 +208,85 @@ 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,
int (*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. */
int (*list)( store_t *ctx,
int (*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).
+ * The driver takes ownership of the excs array. */
int (*select)( store_t *ctx, int minuid, int maxuid, int *excs, int
nexcs,
int (*cb)( int sts, void *aux ), void *aux );
+
+ /* Fetch the contents and flags of the given message from the current
mailbox. */
int (*fetch_msg)( store_t *ctx, message_t *msg, msg_data_t *data,
int (*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. */
int (*store_msg)( store_t *ctx, msg_data_t *data, int to_trash,
int (*cb)( int sts, int uid, void *aux ), void *aux );
+
+ /* Find a message by its temporary UID header to determine its real
UID. */
int (*find_msg)( store_t *ctx, const char *tuid,
int (*cb)( int sts, int uid, void *aux ), void *aux );
- int (*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. */
+ int (*set_flags)( store_t *ctx, message_t *msg, int uid, int add, int
del,
int (*cb)( int sts, void *aux ), void *aux );
- int (*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. */
+ int (*trash_msg)( store_t *ctx, message_t *msg,
int (*cb)( int sts, void *aux ), void *aux );
- int (*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. */
+ int (*close)( store_t *ctx,
int (*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. If the store is canceled before this command
completes,
+ * the callback will *not* be invoked. */
+ void (*cancel)( store_t *ctx,
void (*cb)( void *aux ), void *aux );
+
+ /* Commit any pending set_flags() commands. */
void (*commit)( store_t *ctx );
};
diff --git a/src/sync.c b/src/sync.c
index 46f192f..bba516a 100644
--- a/src/sync.c
+++ b/src/sync.c
@@ -387,7 +387,7 @@ cancel_sync( sync_vars_t *svars )
{
int t;
- /* the 1st round is guaranteed not to trash svars */
+ /* the 1st round is guaranteed not to trash svars (see ST_CANCELED) */
for (t = 0; t < 2; t++)
if (svars->ret & SYNC_BAD(t)) {
cancel_done( AUX );
@@ -1286,6 +1286,7 @@ msg_copied( int sts, int uid, copy_vars_t *vars )
break;
default:
cancel_sync( svars );
+ /* fallthrough */
case SYNC_CANCELED:
free( vars );
return -1;
@@ -1518,6 +1519,7 @@ msg_rtrashed( int sts, int uid, copy_vars_t *vars )
break;
default:
cancel_sync( svars );
+ /* fallthrough */
case SYNC_CANCELED:
free( vars );
return -1;
------------------------------------------------------------------------------
Xperia(TM) PLAY
It's a major breakthrough. An authentic gaming
smartphone on the nation's most reliable network.
And it wants your games.
http://p.sf.net/sfu/verizon-sfdev
_______________________________________________
isync-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/isync-devel
