Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 2005 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
*
- * typedef bool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
- * bool pause_operation,
- * void *context);
+ * typedef SilcBool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
+ * SilcBool pause_operation,
+ * void *context);
*
* DESCRIPTION
*
* was (or is going to be) halted or resumed, and FALSE on error.
*
***/
-typedef bool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
- bool pause_operation,
- void *context);
+typedef SilcBool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
+ SilcBool pause_operation,
+ void *context);
/* Upper layer functions for managing asynchronous operations. Layer
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
*
- * bool silc_async_halt(SilcAsyncOperation op);
+ * SilcBool silc_async_halt(SilcAsyncOperation op);
*
* DESCRIPTION
*
* controls the asynchronous operation.
*
***/
-bool silc_async_halt(SilcAsyncOperation op);
+SilcBool silc_async_halt(SilcAsyncOperation op);
-/****f* silcutil/SilcAsyncOperationAPI/silc_async_resume
+/****f* silcutil/silc_async_resume
*
* SYNOPSIS
*
- * bool silc_async_resume(SilcAsyncOperation op);
+ * SilcBool silc_async_resume(SilcAsyncOperation op);
*
* DESCRIPTION
*
* asynchronous operation.
*
***/
-bool silc_async_resume(SilcAsyncOperation op);
+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
*
- * bool silc_async_init(SilcAsyncOperation op,
- * SilcAsyncOperationAbort abort_cb,
- * SilcAsyncOperationPause pause_cb,
- * void *context);
+ * SilcBool silc_async_init(SilcAsyncOperation op,
+ * SilcAsyncOperationAbort abort_cb,
+ * SilcAsyncOperationPause pause_cb,
+ * void *context);
*
* DESCRIPTION
*
* layer to abort the asynchronous operation, by calling the
* 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.
+ * to silc_async_alloc except this does not allocate any memory. The `op'
+ * 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
* not provided then these functions has no effect for this operation.
*
***/
-bool silc_async_init(SilcAsyncOperation op,
- SilcAsyncOperationAbort abort_cb,
- SilcAsyncOperationPause pause_cb,
- void *context);
+SilcBool silc_async_init(SilcAsyncOperation op,
+ SilcAsyncOperationAbort abort_cb,
+ 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
*