lib/silccore/silcprotocol.h

   1 /*
   2
   3   silcprotocol.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2000 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 /****h* silccore/silcprotocol.h
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementation of the protocol handling routines for SILC applications.
  26  * These routines allow execution of arbitrary protocols in the application.
  27  * New protocols may be registered by type and allocated later by that
  28  * type for the execution. The protocols implements a state machine style
  29  * execution where each state is executed one after the other. The
  30  * application controls these states and their order of execution.
  31  *
  32  * After the protocol has been executed, an final callback is called
  33  * which the application may use to do post-protocol work or to start
  34  * perhaps other protocols. These routines are generic and the actual
  35  * protocols, their types, callback and final callbacks functions must
  36  * be implemented in the application.
  37  *
  38  ***/
  39
  40 #ifndef SILCPROTOCOL_H
  41 #define SILCPROTOCOL_H
  42
  43 /****d* silccore/SilcProtocolAPI/SilcProtocolType
  44  *
  45  * NAME
  46  *
  47  *    typedef unsigned char SilcProtocolType;
  48  *
  49  * DESCRIPTION
  50  *
  51  *    Protocol type definition. The protocol types are application
  52  *    specific and this is just a generic type for them.
  53  *
  54  ***/
  55 typedef unsigned char SilcProtocolType;
  56
  57 /****d* silccore/SilcProtocolAPI/SilcProtocolState
  58  *
  59  * NAME
  60  *
  61  *    typedef unsigned char SilcProtocolState;
  62  *
  63  * DESCRIPTION
  64  *
  65  *    Protocol state definition and the defined protocol states. These
  66  *    states are the generic states. However, each protocol actually
  67  *    implements the states. The state after SILC_PROTOCOL_STATE_START
  68  *    would be state 2 in the application. These states can be easily
  69  *    used for example inside switch() statement.
  70  *
  71  * EXAMPLE
  72  *
  73  *    switch (protocol->state) {
  74  *    case SILC_PROTOCOL_STATE_START:
  75  *      protocol_starts_here();
  76  *    case 2:
  77  *      ...
  78  *    case 3:
  79  *      ...
  80  *    case SILC_PROTOCOL_STATE_END:
  81  *      protocol_ends_here();
  82  *    case SILC_PROTOCOL_STATE_FAILURE:
  83  *      remote_end_sent_failure();
  84  *    case SILC_PROTOCOL_STATE_ERROR:
  85  *      local_error_during_protocol();
  86  *    }
  87  *
  88  * SOURCE
  89  */
  90 typedef unsigned char SilcProtocolState;
  91
  92 /* Protocol states. Do NOT change the values of these states, especially
  93    the START state or you break every protocol. */
  94 #define SILC_PROTOCOL_STATE_UNKNOWN 0
  95 #define SILC_PROTOCOL_STATE_START 1
  96 #define SILC_PROTOCOL_STATE_END 252
  97 #define SILC_PROTOCOL_STATE_FAILURE 253  /* Received failure from remote */
  98 #define SILC_PROTOCOL_STATE_ERROR 254    /* Local error at our end */
  99 /***/
 100
 101 /* Type definition for authentication protocol's auth methods. */
 102 /* XXX strictly speaking this belongs to application */
 103 typedef unsigned char SilcProtocolAuthMeth;
 104
 105 /****f* silccore/SilcProtocolAPI/SilcProtocolCallback
 106  *
 107  * SYNOPSIS
 108  *
 109  *    typedef SilcTaskCallback SilcProtocolCallback;
 110  *
 111  * DESCRIPTION
 112  *
 113  *    Protocol callback. This callback is set when registering new
 114  *    protocol. The callback is called everytime the protocol is executed.
 115  *    The `context' delivered to this callback function is the SilcProtocol
 116  *    context and needs to be explicitly type casted to SilcProtocol in
 117  *    the callback function.
 118  *
 119  ***/
 120 typedef SilcTaskCallback SilcProtocolCallback;
 121
 122 /****f* silccore/SilcProtocolAPI/SilcProtocolFinalCallback
 123  *
 124  * SYNOPSIS
 125  *
 126  *    typedef SilcTaskCallback SilcProtocolFinalCallback;
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Final protocol callback. This callback is set when allocating
 131  *    protocol for execution. This is called when the protocol has ended.
 132  *    The `context' delivered to this callback function is the SilcProtocol
 133  *    context and needs to be explicitly type casted to SilcProtocol in
 134  *    the callback function.
 135  *
 136  ***/
 137 typedef SilcTaskCallback SilcProtocolFinalCallback;
 138
 139 /****s* silccore/SilcProtocolAPI/SilcProtocolObject
 140  *
 141  * NAME
 142  *
 143  *    typedef struct SilcProtocolObjectStruct { ... } SilcProtocolObject;
 144  *
 145  * DESCRIPTION
 146  *
 147  *    The object for one protocol. This hold the information of one
 148  *    registered protocol. Application must not allocate this type
 149  *    directly. It is used by the protocol routines.
 150  *
 151  *    Short description of the field following:
 152  *
 153  *    SilcProtocolType type
 154  *
 155  *      Protocol type.
 156  *
 157  *    SilcProtocolCallback callback;
 158  *
 159  *      Callback function for the protocol. This is SilcTaskCallback function
 160  *      pointer as the protocols in SILC are executed as timeout tasks.
 161  *
 162  *    struct SilcProtocolObjectStruct *next;
 163  *
 164  *      Pointer to the next protocol.
 165  *
 166  ***/
 167 typedef struct SilcProtocolObjectStruct {
 168   SilcProtocolType type;
 169   SilcProtocolCallback callback;
 170   struct SilcProtocolObjectStruct *next;
 171 } SilcProtocolObject;
 172
 173 /****s* silccore/SilcProtocolAPI/SilcProtocol
 174  *
 175  * NAME
 176  *
 177  *    typedef struct SilcProtocolStruct { ... } *SilcProtocol;
 178  *
 179  * DESCRIPTION
 180  *
 181  *    The actual protocol object. This is allocated by the silc_protocol_alloc
 182  *    and holds the information about the current protocol. Information
 183  *    such as the current state, execution callback and final callback.
 184  *    The context is freed by silc_protocol_free function.
 185  *
 186  *    Short description of the field following:
 187  *
 188  *    SilcProtocolObject *protocol
 189  *
 190  *      This is the pointer to the SilcProtocolObject and holds the
 191  *      protocol specific information.
 192  *
 193  *    SilcProtocolState state
 194  *
 195  *      Protocol state. The state of the protocol can be changed in the
 196  *      callback function.
 197  *
 198  *    void *context
 199  *
 200  *      Context to be sent for the callback function. This is usually
 201  *      object for either SILC client or server. However, this abstraction
 202  *      makes it possible that this pointer could be some other object as
 203  *      well. Note that the context is not delivered in any callback
 204  *      function. Application can access it through this context.
 205  *
 206  *    SilcProtocolFinalCallback final_callback;
 207  *
 208  *      This is a callback function that is called with timeout _after_ the
 209  *      protocol has finished or error occurs. If this is NULL, naturally
 210  *      nothing will be executed. Protocol should call this function only at
 211  *      SILC_PROTOCOL_STATE_END and SILC_PROTOCOL_STATE_ERROR states.
 212  *
 213  ***/
 214 typedef struct SilcProtocolStruct {
 215   SilcProtocolObject *protocol;
 216   SilcProtocolState state;
 217   void *context;
 218   SilcProtocolFinalCallback final_callback;
 219 } *SilcProtocol;
 220
 221 /* Prototypes */
 222
 223 /****f* silccore/SilcProtocolAPI/silc_protocol_register
 224  *
 225  * SYNOPSIS
 226  *
 227  *    void silc_protocol_register(SilcProtocolType type,
 228  *                                SilcProtocolCallback callback);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Dynamically registers new protocol. The protocol is added into protocol
 233  *    list and can be unregistered with silc_protocol_unregister. The
 234  *    `type' is the type of the protocol and is used to identify the
 235  *    protocol when allocating it with silc_protocol_alloc. The `callback'
 236  *    is the actual protocol function that is called when protocol is
 237  *    executed (and it performes the actual protocol). The protocol
 238  *    is unregistered by silc_protocol_unregister function.
 239  *
 240  ***/
 241 void silc_protocol_register(SilcProtocolType type,
 242                             SilcProtocolCallback callback);
 243
 244 /****f* silccore/SilcProtocolAPI/silc_protocol_unregister
 245  *
 246  * SYNOPSIS
 247  *
 248  *    void silc_protocol_unregister(SilcProtocolType type,
 249  *                                  SilcProtocolCallback callback);
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Unregisters protocol. The unregistering is done by both protocol type
 254  *    and the protocol callback. Every registered protocol must be
 255  *    unregistered using this function.
 256  *
 257  ***/
 258 void silc_protocol_unregister(SilcProtocolType type,
 259                               SilcProtocolCallback callback);
 260
 261 /****f* silccore/SilcProtocolAPI/silc_protocol_alloc
 262  *
 263  * SYNOPSIS
 264  *
 265  *    void silc_protocol_alloc(SilcProtocolType type,
 266  *                             SilcProtocol *new_protocol,
 267  *                             void *context,
 268  *                             SilcProtocolFinalCallback callback);
 269  *
 270  * DESCRIPTION
 271  *
 272  *    Allocates a new protocol. The new allocated and initialized
 273  *    protocol is returned to the `new_protocol' argument. The argument
 274  *    context `context' is the context to be sent as argument for the
 275  *    protocol callback function. The `callback' argument is the function
 276  *    to be called after the protocol has finished.
 277  *
 278  ***/
 279 void silc_protocol_alloc(SilcProtocolType type, SilcProtocol *new_protocol,
 280                          void *context, SilcProtocolFinalCallback callback);
 281
 282 /****f* silccore/SilcProtocolAPI/silc_protocol_free
 283  *
 284  * SYNOPSIS
 285  *
 286  *    void silc_protocol_free(SilcProtocol protocol);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Frees the protocol context. This must be called for all allocated
 291  *    protocols.
 292  *
 293  ***/
 294 void silc_protocol_free(SilcProtocol protocol);
 295
 296 /****f* silccore/SilcProtocolAPI/silc_protocol_execute
 297  *
 298  * SYNOPSIS
 299  *
 300  *    void silc_protocol_execute(SilcProtocol protocol, SilcSchedule schedule,
 301  *                               long secs, long usecs);
 302  *
 303  * DESCRIPTION
 304  *
 305  *    Executes the protocol. This calls the state that has been set.
 306  *    The state must be set before calling this function. This is then
 307  *    also used to call always the next state after changing the state
 308  *    of the protocol. The `schedule' is the application's scheduler.
 309  *    It is passed to the protocol callback functions. The `secs' and
 310  *    `usecs' are the timeout before the protocol is executed. If both
 311  *    zero the protocol is executed immediately.
 312  *
 313  ***/
 314 void silc_protocol_execute(SilcProtocol protocol, SilcSchedule schedule,
 315                            long secs, long usecs);
 316
 317 /****f* silccore/SilcProtocolAPI/silc_protocol_execute_final
 318  *
 319  * SYNOPSIS
 320  *
 321  *    void
 322  *    silc_protocol_execute_final(SilcProtocol protocol,
 323  *                               SilcSchedule schedule);
 324  *
 325  * DESCRIPTION
 326  *
 327  *    Executes the final callback for the protocol. The `schedule' is
 328  *    the application's scheduler.. It is passed to the protocol callback
 329  *    functions. The final callback is executed immediately.
 330  *
 331  ***/
 332 void silc_protocol_execute_final(SilcProtocol protocol, SilcSchedule schedule);
 333
 334 /****f* silccore/SilcProtocolAPI/silc_protocol_cancel
 335  *
 336  * SYNOPSIS
 337  *
 338  *    void silc_protocol_cancel(SilcProtocol protocol, SilcSchedule schedule);
 339  *
 340  * DESCRIPTION
 341  *
 342  *    Cancels the execution of the next state of the protocol. This has
 343  *    effect only if the silc_protocol_execute was called with timeout.
 344  *    It is guaranteed that if the protocol is cancelled before the timeout
 345  *    has elapsed the protocol callback won't be called.
 346  *
 347  ***/
 348 void silc_protocol_cancel(SilcProtocol protocol, SilcSchedule schedule);
 349
 350 #endif