X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcasync.h;h=6e7469839e8ea06dfd953ee43fd89831295fdbf4;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=b60c2b97c3ab0f3f802e715e8ee5258a40d1ad68;hpb=0f0340b9fbce9704cc7171f8f0104ce9103d2de6;p=silc.git

diff --git a/lib/silcutil/silcasync.h b/lib/silcutil/silcasync.h
index b60c2b97..6e746983 100644
--- a/lib/silcutil/silcasync.h
+++ b/lib/silcutil/silcasync.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2005 Pekka Riikonen
+  Copyright (C) 2005 - 2007 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
@@ -35,6 +35,32 @@
  * 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
@@ -100,9 +126,9 @@ typedef void (*SilcAsyncOperationAbort)(SilcAsyncOperation op,
  *
  * SYNOPSIS
  *
- *    typedef bool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
- *                                            bool pause_operation,
- *                                            void *context);
+ *    typedef SilcBool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
+ *                                                SilcBool pause_operation,
+ *                                                void *context);
  *
  * DESCRIPTION
  *
@@ -116,9 +142,9 @@ typedef void (*SilcAsyncOperationAbort)(SilcAsyncOperation op,
  *    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
@@ -128,7 +154,7 @@ typedef bool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
  *
  * SYNOPSIS
  *
- *    bool silc_async_halt(SilcAsyncOperation op);
+ *    SilcBool silc_async_halt(SilcAsyncOperation op);
  *
  * DESCRIPTION
  *
@@ -141,13 +167,13 @@ typedef bool (*SilcAsyncOperationPause)(SilcAsyncOperation op,
  *    controls the asynchronous operation.
  *
  ***/
-bool silc_async_halt(SilcAsyncOperation op);
+SilcBool silc_async_halt(SilcAsyncOperation op);
 
 /****f* silcutil/SilcAsyncOperationAPI/silc_async_resume
  *
  * SYNOPSIS
  *
- *    bool silc_async_resume(SilcAsyncOperation op);
+ *    SilcBool silc_async_resume(SilcAsyncOperation op);
  *
  * DESCRIPTION
  *
@@ -159,7 +185,7 @@ bool silc_async_halt(SilcAsyncOperation op);
  *    asynchronous operation.
  *
  ***/
-bool silc_async_resume(SilcAsyncOperation op);
+SilcBool silc_async_resume(SilcAsyncOperation op);
 
 /****f* silcutil/SilcAsyncOperationAPI/silc_async_abort
  *
@@ -239,10 +265,10 @@ SilcAsyncOperation silc_async_alloc(SilcAsyncOperationAbort abort_cb,
  *
  * 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
  *
@@ -251,7 +277,8 @@ SilcAsyncOperation silc_async_alloc(SilcAsyncOperationAbort abort_cb,
  *    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
@@ -259,10 +286,10 @@ SilcAsyncOperation silc_async_alloc(SilcAsyncOperationAbort abort_cb,
  *    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
  *