5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2000 Pekka Riikonen
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.
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.
21 /****h* silccore/SILC Protocol Interface
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.
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.
40 #ifndef SILCPROTOCOL_H
41 #define SILCPROTOCOL_H
43 /****d* silccore/SilcProtocolAPI/SilcProtocolType
47 * typedef unsigned char SilcProtocolType;
51 * Protocol type definition. The protocol types are application
52 * specific and this is just a generic type for them.
55 typedef unsigned char SilcProtocolType;
57 /****d* silccore/SilcProtocolAPI/SilcProtocolState
61 * typedef unsigned char SilcProtocolState;
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.
73 * switch (protocol->state) {
74 * case SILC_PROTOCOL_STATE_START:
75 * protocol_starts_here();
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();
90 typedef unsigned char SilcProtocolState;
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 */
101 /* Type definition for authentication protocol's auth methods. */
102 /* XXX strictly speaking this belongs to application */
103 typedef unsigned char SilcProtocolAuthMeth;
105 /****f* silccore/SilcProtocolAPI/SilcProtocolCallback
109 * typedef SilcTaskCallback SilcProtocolCallback;
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.
120 typedef SilcTaskCallback SilcProtocolCallback;
122 /****f* silccore/SilcProtocolAPI/SilcProtocolFinalCallback
126 * typedef SilcTaskCallback SilcProtocolFinalCallback;
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.
137 typedef SilcTaskCallback SilcProtocolFinalCallback;
139 /****s* silccore/SilcProtocolAPI/SilcProtocolObject
143 * typedef struct SilcProtocolObjectStruct { ... } SilcProtocolObject;
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.
151 * Short description of the field following:
153 * SilcProtocolType type
157 * SilcProtocolCallback callback;
159 * Callback function for the protocol. This is SilcTaskCallback function
160 * pointer as the protocols in SILC are executed as timeout tasks.
162 * struct SilcProtocolObjectStruct *next;
164 * Pointer to the next protocol.
167 typedef struct SilcProtocolObjectStruct {
168 SilcProtocolType type;
169 SilcProtocolCallback callback;
170 struct SilcProtocolObjectStruct *next;
171 } SilcProtocolObject;
173 /****s* silccore/SilcProtocolAPI/SilcProtocol
177 * typedef struct SilcProtocolStruct { ... } *SilcProtocol;
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.
186 * Short description of the field following:
188 * SilcProtocolObject *protocol
190 * This is the pointer to the SilcProtocolObject and holds the
191 * protocol specific information.
193 * SilcProtocolState state
195 * Protocol state. The state of the protocol can be changed in the
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.
206 * SilcProtocolFinalCallback final_callback;
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.
214 typedef struct SilcProtocolStruct {
215 SilcProtocolObject *protocol;
216 SilcProtocolState state;
218 SilcProtocolFinalCallback final_callback;
223 /****f* silccore/SilcProtocolAPI/silc_protocol_register
227 * void silc_protocol_register(SilcProtocolType type,
228 * SilcProtocolCallback callback);
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.
241 void silc_protocol_register(SilcProtocolType type,
242 SilcProtocolCallback callback);
244 /****f* silccore/SilcProtocolAPI/silc_protocol_unregister
248 * void silc_protocol_unregister(SilcProtocolType type,
249 * SilcProtocolCallback callback);
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.
258 void silc_protocol_unregister(SilcProtocolType type,
259 SilcProtocolCallback callback);
261 /****f* silccore/SilcProtocolAPI/silc_protocol_alloc
265 * void silc_protocol_alloc(SilcProtocolType type,
266 * SilcProtocol *new_protocol,
268 * SilcProtocolFinalCallback callback);
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.
279 void silc_protocol_alloc(SilcProtocolType type, SilcProtocol *new_protocol,
280 void *context, SilcProtocolFinalCallback callback);
282 /****f* silccore/SilcProtocolAPI/silc_protocol_free
286 * void silc_protocol_free(SilcProtocol protocol);
290 * Frees the protocol context. This must be called for all allocated
294 void silc_protocol_free(SilcProtocol protocol);
296 /****f* silccore/SilcProtocolAPI/silc_protocol_execute
300 * void silc_protocol_execute(SilcProtocol protocol, SilcSchedule schedule,
301 * long secs, long usecs);
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.
314 void silc_protocol_execute(SilcProtocol protocol, SilcSchedule schedule,
315 long secs, long usecs);
317 /****f* silccore/SilcProtocolAPI/silc_protocol_execute_final
322 * silc_protocol_execute_final(SilcProtocol protocol,
323 * SilcSchedule schedule);
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.
332 void silc_protocol_execute_final(SilcProtocol protocol, SilcSchedule schedule);
334 /****f* silccore/SilcProtocolAPI/silc_protocol_cancel
338 * void silc_protocol_cancel(SilcProtocol protocol, SilcSchedule schedule);
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.
348 void silc_protocol_cancel(SilcProtocol protocol, SilcSchedule schedule);