Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2005 - 2007 Pekka Riikonen
+ Copyright (C) 2005 - 2008 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*/
-/****h* silcutil/SILC Async Operation Interface
+/****h* silcutil/Async Operation Interface
*
* DESCRIPTION
*
* operation, no callback function will be called back to the upper layer.
* This must be remembered when implementing the operation layer.
*
+ * EXAMPLE
+ *
+ * SilcAsyncOperation async_call(Callback callback, void *cb_context)
+ * {
+ * SilcAsyncOperation op;
+ * OpContext ctx;
+ *
+ * // Allocate async operation so that caller can control us, like abort
+ * op = silc_async_alloc(async_call_abort, NULL, ctx);
+ * ctx->callback = callback;
+ *
+ * ...
+ *
+ * // Return async operation for upper layer
+ * return op;
+ * }
+ *
+ * // This callback is called when silc_async_abort is called by upper layer.
+ * // The callback given to async_call must not be called after this.
+ * void async_call_abort(SilcAsyncOperation op, void *context)
+ * {
+ * OpContext ctx = context;
+ * ctx->aborted = TRUE;
+ * ctx->callback = NULL;
+ * }
+ *
***/
#ifndef SILCASYNC_H
#define SILCASYNC_H
-/****s* silcutil/SilcAsyncOperationAPI/SilcAsyncOperation
+/****s* silcutil/SilcAsyncOperation
*
* NAME
*
***/
typedef struct SilcAsyncOperationObject *SilcAsyncOperation;
-/****s* silcutil/SilcAsyncOperationAPI/SilcAsyncOperationStruct
+/****s* silcutil/SilcAsyncOperationStruct
*
* NAME
*
***/
typedef struct SilcAsyncOperationObject SilcAsyncOperationStruct;
-/****f* silcutil/SilcAsyncOperationAPI/SilcAsyncOperationAbort
+/****f* silcutil/SilcAsyncOperationAbort
*
* SYNOPSIS
*
typedef void (*SilcAsyncOperationAbort)(SilcAsyncOperation op,
void *context);
-/****f* silcutil/SilcAsyncOperationAPI/SilcAsyncOperationPause
+/****f* silcutil/SilcAsyncOperationPause
*
* SYNOPSIS
*
that has received SilcAsyncOperation context can control the async
operation with these functions. */
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_halt
+/****f* silcutil/silc_async_halt
*
* SYNOPSIS
*
***/
SilcBool silc_async_halt(SilcAsyncOperation op);
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_resume
+/****f* silcutil/silc_async_resume
*
* SYNOPSIS
*
***/
SilcBool silc_async_resume(SilcAsyncOperation op);
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_abort
+/****f* silcutil/silc_async_abort
*
* SYNOPSIS
*
/* The operation layer functions. The layer that performs the async
operation use these functions. */
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_alloc
+/****f* silcutil/silc_async_alloc
*
* SYNOPSIS
*
SilcAsyncOperationPause pause_cb,
void *context);
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_init
+/****f* silcutil/silc_async_init
*
* SYNOPSIS
*
* silc_async_abort. Since this use pre-allocated context, the function
* silc_async_free need not be called. This function is equivalent
* to silc_async_alloc except this does not allocate any memory. The `op'
- * needs not be uninitialized.
+ * needs not be uninitialized. This returns always TRUE.
*
* If the `pause_cb' is provided then the upper layer may also halt and
* then later resume the execution of the operation, by calling the
SilcAsyncOperationPause pause_cb,
void *context);
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_free
+/****f* silcutil/silc_async_free
*
* SYNOPSIS
*
***/
void silc_async_free(SilcAsyncOperation op);
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_get_context
+/****f* silcutil/silc_async_get_context
*
* SYNOPSIS
*