5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2005 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; version 2 of the License.
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.
20 /****h* silccore/SILC Protocol Interface
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.
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.
39 #ifndef SILCPROTOCOL_H
40 #define SILCPROTOCOL_H
42 /****d* silccore/SilcProtocolAPI/SilcProtocolType
46 * typedef unsigned char SilcProtocolType;
50 * Protocol type definition. The protocol types are application
51 * specific and this is just a generic type for them.
54 typedef unsigned char SilcProtocolType;
56 /****d* silccore/SilcProtocolAPI/SilcProtocolState
60 * typedef unsigned char SilcProtocolState;
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.
72 * switch (protocol->state) {
73 * case SILC_PROTOCOL_STATE_START:
74 * protocol_starts_here();
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();
89 typedef unsigned char SilcProtocolState;
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 */
100 /* Type definition for authentication protocol's auth methods. */
101 /* XXX strictly speaking this belongs to application */
102 typedef unsigned char SilcProtocolAuthMeth;
104 /****f* silccore/SilcProtocolAPI/SilcProtocolCallback
108 * typedef SilcTaskCallback SilcProtocolCallback;
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.
119 typedef SilcTaskCallback SilcProtocolCallback;
121 /****f* silccore/SilcProtocolAPI/SilcProtocolFinalCallback
125 * typedef SilcTaskCallback SilcProtocolFinalCallback;
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.
136 typedef SilcTaskCallback SilcProtocolFinalCallback;
138 /****s* silccore/SilcProtocolAPI/SilcProtocolObject
142 * typedef struct SilcProtocolObjectStruct { ... } SilcProtocolObject;
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.
150 * Short description of the field following:
152 * SilcProtocolType type
156 * SilcProtocolCallback callback;
158 * Callback function for the protocol. This is SilcTaskCallback function
159 * pointer as the protocols in SILC are executed as timeout tasks.
161 * struct SilcProtocolObjectStruct *next;
163 * Pointer to the next protocol.
166 typedef struct SilcProtocolObjectStruct {
167 SilcProtocolType type;
168 SilcProtocolCallback callback;
169 struct SilcProtocolObjectStruct *next;
170 } SilcProtocolObject;
172 /****s* silccore/SilcProtocolAPI/SilcProtocol
176 * typedef struct SilcProtocolStruct { ... } *SilcProtocol;
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.
185 * Short description of the field following:
187 * SilcProtocolObject *protocol
189 * This is the pointer to the SilcProtocolObject and holds the
190 * protocol specific information.
192 * SilcProtocolState state
194 * Protocol state. The state of the protocol can be changed in the
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.
205 * SilcProtocolFinalCallback final_callback;
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.
213 typedef struct SilcProtocolStruct {
214 SilcProtocolObject *protocol;
215 SilcProtocolState state;
217 SilcProtocolFinalCallback final_callback;
222 /****f* silccore/SilcProtocolAPI/silc_protocol_register
226 * void silc_protocol_register(SilcProtocolType type,
227 * SilcProtocolCallback callback);
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.
240 void silc_protocol_register(SilcProtocolType type,
241 SilcProtocolCallback callback);
243 /****f* silccore/SilcProtocolAPI/silc_protocol_unregister
247 * void silc_protocol_unregister(SilcProtocolType type,
248 * SilcProtocolCallback callback);
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.
257 void silc_protocol_unregister(SilcProtocolType type,
258 SilcProtocolCallback callback);
260 /****f* silccore/SilcProtocolAPI/silc_protocol_alloc
264 * void silc_protocol_alloc(SilcProtocolType type,
265 * SilcProtocol *new_protocol,
267 * SilcProtocolFinalCallback callback);
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.
278 void silc_protocol_alloc(SilcProtocolType type, SilcProtocol *new_protocol,
279 void *context, SilcProtocolFinalCallback callback);
281 /****f* silccore/SilcProtocolAPI/silc_protocol_free
285 * void silc_protocol_free(SilcProtocol protocol);
289 * Frees the protocol context. This must be called for all allocated
293 void silc_protocol_free(SilcProtocol protocol);
295 /****f* silccore/SilcProtocolAPI/silc_protocol_execute
299 * void silc_protocol_execute(SilcProtocol protocol, SilcSchedule schedule,
300 * long secs, long usecs);
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.
313 void silc_protocol_execute(SilcProtocol protocol, SilcSchedule schedule,
314 long secs, long usecs);
316 /****f* silccore/SilcProtocolAPI/silc_protocol_execute_final
321 * silc_protocol_execute_final(SilcProtocol protocol,
322 * SilcSchedule schedule);
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.
331 void silc_protocol_execute_final(SilcProtocol protocol, SilcSchedule schedule);
333 /****f* silccore/SilcProtocolAPI/silc_protocol_cancel
337 * void silc_protocol_cancel(SilcProtocol protocol, SilcSchedule schedule);
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.
347 void silc_protocol_cancel(SilcProtocol protocol, SilcSchedule schedule);