updates.
[silc.git] / lib / doc / silcclient_using.html
1 <big><b>Using SILC Client Library</b></big>
2
3 <br />&nbsp;<br />&nbsp;<br />
4 <b>Introduction</b>
5
6 <br />&nbsp;<br />
7 SILC Client library is a full featured SILC Client protocol implementation.
8 The library has been designed to be complete SILC client without actual
9 user interface.  The library provides the API for the appliation which
10 it can use to implement generally whatever user interface it wants.  The
11 SILC Client Library recides in the lib/silcclient/ directory.  It uses
12 common and core compomnent of SILC protocol from the lib/silccore, SKE
13 from lib/silcske and general utility routines from lib/silcutil.
14
15 <br />&nbsp;<br />
16 The `silcapi.h' file defines the function prototypes that application
17 must implement in order to be able to create the user interface with the
18 library.  The idea is that the application can implement whatever user
19 interface routines in the functions and display the data whatever way
20 it wants.  The library is entirely transparent to the user interface and
21 it does not include any user interface specific issues such as window
22 handling or item handling on the screen etc.  These does not interest
23 the library.  The `silcapi.h' also defines the client libary interface
24 the application can call.  The interface includes for example functions
25 for sending channel and private messages, client and channel retrieval
26 and other utility functions.
27
28 <br />&nbsp;<br />&nbsp;<br />
29 <b>Including Library Headers</b>
30
31 <br />&nbsp;<br />
32 Your application must include the following includes in your sources to 
33 get access all SILC Client Library routines:
34
35 <br />&nbsp;<br />
36 <tt>
37 #include "silcincludes.h"<br />
38 #include "clientlibincludes.h"
39 </tt>
40
41 <br />&nbsp;<br />
42 If you are compiling with C++ compiler then you need to include the 
43 headers as follows:
44
45 <br />&nbsp;<br />
46 <tt>
47 extern "C" {<br />
48 #include "silcincludes.h"<br />
49 #include "clientlibincludes.h"<br &/>
50 }
51 </tt>
52
53
54 <br />&nbsp;<br />&nbsp;<br />
55 <b>Creating Client</b>
56
57 <br />&nbsp;<br />
58 The client is context or entity based, so several client entitites can
59 be created in the application if needed.  However, it should be noted
60 that they are completely independent from each other and can be seen
61 as different applications.  Usually only one client entity is needed
62 per application.
63
64 <br />&nbsp;<br />
65 The client object is SilcClient which is usually allocated in following
66 manner:
67
68 <br />&nbsp;<br />
69 <tt>&nbsp;&nbsp;SilcClient client = silc_client_alloc(&ops, params, context, version);</tt>
70
71 <br />&nbsp;<br />
72 `ops' is the static structure of client operations that library will call.
73 `context' can be some application specific context that will be saved into
74 the SilcClient object.  It is up to the caller to free this context.
75 SilcClient is always passed to the application thus the application
76 specific context can be retrieved from the SilcClient object.  See 
77 `client.h' file for detailed definition of SilcClient object.
78
79 <br />&nbsp;<br />
80 `ops' can be defined for example as follows:
81
82 <br />&nbsp;<br />
83 <tt>
84 SilcClientOperations ops = {<br />
85 &nbsp;&nbsp;  silc_say,<br />
86 &nbsp;&nbsp;  silc_channel_message,<br />
87 &nbsp;&nbsp;  silc_private_message,<br />
88 &nbsp;&nbsp;  silc_notify,<br />
89 &nbsp;&nbsp;  silc_command,<br />
90 &nbsp;&nbsp;  silc_command_reply,<br />
91 &nbsp;&nbsp;  silc_connect,<br />
92 &nbsp;&nbsp;  silc_disconnect,<br />
93 &nbsp;&nbsp;  silc_get_auth_method,<br />
94 &nbsp;&nbsp;  silc_verify_public_key,<br />
95 &nbsp;&nbsp;  silc_ask_passphrase,<br />
96 &nbsp;&nbsp;  silc_failure,<br />
97 &nbsp;&nbsp;  silc_key_agreement,<br />
98 };<br />
99 </tt>
100
101 <br />&nbsp;<br />
102 Please see the `client_ops_example.c' source file in lib/silcclient/
103 directory for predefined structure and stub functions for your
104 convenience.  It is provided for programmers so that they can copy
105 it and use it directly in their application.
106
107
108 <br />&nbsp;<br />&nbsp;<br />
109 <b>Initializing the Client</b>
110
111 <br />&nbsp;<br />
112 The client must be initialized before running.  However, there are also
113 some other tasks that must be done before initializing the client.
114 The following pointers must be set by the application  before calling
115 the initializing function:
116
117 <br />&nbsp;<br />
118 <tt>
119 &nbsp;&nbsp;client->username<br />
120 &nbsp;&nbsp;client->hostname<br />
121 &nbsp;&nbsp;client->realname<br />
122 &nbsp;&nbsp;client->pkcs<br />
123 &nbsp;&nbsp;client->public_key<br />
124 &nbsp;&nbsp;client->private_key
125 </tt>
126
127 <br />&nbsp;<br />
128 You may also set client->nickname if you want.  If it is set then the
129 library will change the nickname to that one after the client is connected
130 to the server.  If not set, then server will initially give the nickname
131 which is same as the username.
132
133 <br />&nbsp;<br />
134 After setting the pointers one must call:
135
136 <br />&nbsp;<br />
137 <tt>&nbsp;&nbsp;silc_client_init(client);</tt>
138
139 <br />&nbsp;<br />
140 which then initializes the client library for the `client'.  If the
141 pointers mentioned above are not initialized the silc_client_init will
142 fail.  The application should check the return value of the silc_client_init
143 function.
144
145
146 <br />&nbsp;<br />&nbsp;<br />
147 <b>Running the Client</b>
148
149 <br />&nbsp;<br />
150 The client is run by calling silc_client_run.  The function will call
151 the scheduler from utility library that will be run until the program is
152 ended.  When silc_client_run returns the application is ended.  Thus,
153 to run the client, call:
154
155 <br />&nbsp;<br />
156 <tt>&nbsp;&nbsp;silc_client_run(client);</tt>
157
158 <br />&nbsp;<br />
159 Usually application may do some other initializations before calling
160 this function.  For example before calling this function application
161 should initialize the user interface.
162
163
164 <br />&nbsp;<br />&nbsp;<br />
165 <b>Running the Client in GUI application</b>
166
167 <br />&nbsp;<br />
168 Many GUI applications has their own main loop or event loop, which they 
169 would like to use or are forced to use by the underlaying system.  If you 
170 are developing for example GUI application on Unix system, and you are 
171 using GTK+ or QT as GUI library you would probably like to use their own 
172 main loop.  SILC Client can be run under external main loop as well.  The 
173 interface provides a function silc_client_run_one which will run the 
174 client library once, and returns immediately.  During that running it can 
175 process incoming data and send outgoing data, but it is guaranteed that it 
176 will not block the calling process.
177
178 <br />&nbsp;<br />
179 It is suggested that you would call this function as many times in a 
180 second as possible to provide smooth action for the client library.  You 
181 can use an timeout task, or an idle task provided by your GUI library to 
182 accomplish this.  After you have initialized the client library with 
183 silc_client_init, you should register the timeout task or idle task that 
184 will call the silc_client_run_one periodically.  In the Toolkit package 
185 there is GTK-- GUI example in silcer/ directory.  That example calls the 
186 silc_client_run_one every 50 milliseconds, and it should be sufficient for 
187 smooth working.
188
189 <br />&nbsp;<br />
190 For Win32 the silc_client_run can be used instead of using the Windows's 
191 own event loop.  However, if you would like to use the silc_client_run_one 
192 also on Win32 systems it is possible.
193
194
195 <br />&nbsp;<br />&nbsp;<br />
196 <b>Running Client in GTK--</b>
197
198 <br />&nbsp;<br />
199 Here is a short example how to run the SILC Client libary under the 
200 Gnome/GTK--'s main loop:
201
202 <br />&nbsp;<br />
203 <tt>
204 gint YourClass::silc_scheduler()<br />
205 {<br />
206 &nbsp;&nbsp;  // Run the SILC client once, and return immediately.  This function<br />
207 &nbsp;&nbsp;  // is called every 50 milliseconds by the Gnome main loop, to process<br />
208 &nbsp;&nbsp;  // SILC stuff.  This function will read data, and write data to network,<br />
209 &nbsp;&nbsp;  // etc.  Makes the client library tick! :)<br />
210 &nbsp;&nbsp;  silc_client_run_one(silc_client);<br />
211 &nbsp;&nbsp;  return 1;<br />
212 }<br />
213 </tt>
214
215 <br />&nbsp;<br />
216 then, during initialization of the SILC Client call:
217
218 <br />&nbsp;<br />
219 <tt>
220 // Setup SILC scheduler as timeout task. This will handle the SILC<br />
221 // client library every 50 milliseconds.  It will actually make the<br />
222 // SILC client work on background.<br />
223 Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);<br />
224 </tt>
225
226 <br />&nbsp;<br />
227 This will call the function silc_scheduler every 50 millisecconds, which 
228 on the otherhand will call silc_client_run_one, which will make the SILC 
229 Client library work on the background of the GUI application.
230
231
232 <br />&nbsp;<br />&nbsp;<br />
233 <b>Creating Connection to Server</b>
234
235 <br />&nbsp;<br />
236 Connection to remote SILC server is done by calling:
237
238 <br />&nbsp;<br />
239 <tt>&nbsp;&nbsp;silc_client_connect_to_server(client, port, hostname, context);</tt>
240
241 <br />&nbsp;<br />
242 The function will create the connection asynchronously to the server, ie.
243 the function will return before the actual connection is created.  After
244 the connection is created the client->ops->connect operation is called.
245
246 <br />&nbsp;<br />
247 Generally speaking the connections are associated with windows' on the
248 screen.  IRC is usually implemented this way, however it is not the
249 necessary way to associate the client's connections.  SilcClientConnection
250 object is provided by the library (and is always passed to the application)
251 that can be used in the application to associate the connection from the
252 library.  Application specific context can be saved to the 
253 SilcClientConnection object which then can be retrieved in the application,
254 thus perhaps associate the connection with what ever object in 
255 application (window or something else).
256
257
258 <br />&nbsp;<br />&nbsp;<br />
259 <b>Using Own Connecting</b>
260
261 <br />&nbsp;<br />
262 Application might not want to use silc_client_connect_to_server function
263 if it wants to perform its own connecting for some reason.  In this case
264 application must call function silc_client_start_key_exchange after it
265 has created the connection by itself.  This function starts the key
266 exhange protocol between the client and server and the library takes care
267 of everything after that.
268
269 <br />&nbsp;<br />
270 After connection has been created application must call:
271
272 <br />&nbsp;<br />
273 <tt>
274 &nbsp;&nbsp;SilcClientConnection conn;
275
276 <br />&nbsp;<br />
277 &nbsp;&nbsp;/* Add new connection to client */<br />
278 &nbsp;&nbsp;conn = silc_client_add_connection(client, hostname, port, context);
279
280 <br />&nbsp;<br />
281 &nbsp;&nbsp;/* Start key exchange and let the library handle everything<br />
282 &nbsp;&nbsp;   after this point on. */<br />
283 &nbsp;&nbsp;silc_client_start_key_exchange(client, conn, sock);
284 </tt>
285
286 <br />&nbsp;<br />
287 NOTE: These calls are performed only and only if application did not call
288 silc_client_connect_to_server function, but performed the connecting 
289 process manually.
290
291
292 <br />&nbsp;<br />&nbsp;<br />
293 <b>Example Client</b>
294
295 <br />&nbsp;<br />
296 This section includes an example SILC client implementation in pseudo-like
297 C code.  It creates and initializes the client and sets up an imaginary
298 user interface.  The user will use the user interface then to create
299 the connections.  The SilcClientOperations are expected to be implemented.
300
301 <br />&nbsp;<br />
302 <pre>
303 #include "silcincludes.h"
304 #include "silcapi.h"
305
306 int main()
307 {
308         SilcClientOperations ops = {
309           silc_say,
310           silc_channel_message,
311           silc_private_message,
312           silc_notify,
313           silc_command,
314           silc_command_reply,
315           silc_connect,
316           silc_disconnect,
317           silc_get_auth_method,
318           silc_verify_public_key,
319           silc_ask_passphrase,
320           silc_failure,
321           silc_key_agreement,
322         };
323
324         SilcClient client;
325
326         /* Allocate SILC client. The `silc_version_string' is defined
327            in includes/version.h file. */
328         client = silc_client_alloc(&ops, NULL, silc_version_string);
329
330         /* Register default ciphers, pkcs, hash funtions and hmacs. */
331         silc_cipher_register_default();
332         silc_pkcs_register_default();
333         silc_hash_register_default();
334         silc_hmac_register_default();
335
336         /* Set the mandatory pointers, read public and private key from
337            files (or somewhere) and return pointers and PKCS context. */
338         client->username = silc_get_username();
339         client->hostname = silc_net_localhost();
340         client->realname = silc_get_real_name();
341         client->pkcs = get_public_and_private_key(&client->public_key,
342                                                   &client->private_key);
343
344         /* If the keys does not exist, create a key pair since we must
345            provide key pair to the library. */
346         if (!client->pkcs)
347           generate_key_new_key_pair(client);
348
349         /* Iinitialize client */
350         if (!silc_client_init(client))
351           fatal_error("Could not initialize client");
352
353         /* Initialize user interface. The user interface can be generally
354            initialized at any phase, including before actually allocating
355            and initializing the client, if wished. */
356         InitUserInterface();
357         DoCoolThings();
358
359         /* Start the client. This will start the scheduler. At this phase
360            the user might have the user interface in front of him already.
361            He will use the user interface to create the connection to the
362            server for example. When this function returns the program is 
363           ended. */
364         silc_client_run(client);
365
366         /* Client is ended */
367         return 0;
368 }
369 </pre>