lib/silcutil/silcprotocol.h

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