2 <font size="+2">Using SILC Client Library</font>
4 <br /> <br /> <br />
5 <b>1.0 Introduction</b>
8 SILC Client library is a full featured SILC Client protocol implementation.
9 The library has been designed to be complete SILC client without actual
10 user interface. The library provides the API for the appliation which
11 it can use to implement generally whatever user interface it wants. The
12 SILC Client Library recides in the lib/silcclient/ directory. It uses
13 common and core compomnent of SILC protocol from the lib/silccore, SKE
14 from lib/silcske and general utility routines from lib/silcutil.
17 The `silcapi.h' file defines the function prototypes that application
18 must implement in order to be able to create the user interface with the
19 library. The idea is that the application can implement whatever user
20 interface routines in the functions and display the data whatever way
21 it wants. The library is entirely transparent to the user interface and
22 it does not include any user interface specific issues such as window
23 handling or item handling on the screen etc. These does not interest
24 the library. The `silcapi.h' also defines the client libary interface
25 the application can call. The interface includes for example functions
26 for sending channel and private messages, client and channel retrieval
27 and other utility functions.
29 <br /> <br /> <br />
30 <b>1.0.1 Including Library Headers</b>
33 Your application must include the following includes in your sources to
34 get access all SILC Client Library routines:
38 #include "silcincludes.h"<br />
39 #include "clientlibincludes.h"
43 If you are compiling with C++ compiler then you need to include the
49 #include "silcincludes.h"<br />
50 #include "clientlibincludes.h"<br &/>
55 <br /> <br /> <br />
56 <b>1.1 Creating Client</b>
59 The client is context or entity based, so several client entitites can
60 be created in the application if needed. However, it should be noted
61 that they are completely independent from each other and can be seen
62 as different applications. Usually only one client entity is needed
66 The client object is SilcClient which is usually allocated in following
70 <tt> SilcClient client = silc_client_alloc(&ops, params, context, version);</tt>
73 `ops' is the static structure of client operations that library will call.
74 `context' can be some application specific context that will be saved into
75 the SilcClient object. It is up to the caller to free this context.
76 SilcClient is always passed to the application thus the application
77 specific context can be retrieved from the SilcClient object. See
78 `client.h' file for detailed definition of SilcClient object.
81 `ops' can be defined for example as follows:
85 SilcClientOperations ops = {<br />
86 silc_say,<br />
87 silc_channel_message,<br />
88 silc_private_message,<br />
89 silc_notify,<br />
90 silc_command,<br />
91 silc_command_reply,<br />
92 silc_connect,<br />
93 silc_disconnect,<br />
94 silc_get_auth_method,<br />
95 silc_verify_public_key,<br />
96 silc_ask_passphrase,<br />
97 silc_failure,<br />
98 silc_key_agreement,<br />
103 Please see the `client_ops_example.c' source file in lib/silcclient/
104 directory for predefined structure and stub functions for your
105 convenience. It is provided for programmers so that they can copy
106 it and use it directly in their application.
109 <br /> <br /> <br />
110 <b>1.2 Initializing the Client</b>
113 The client must be initialized before running. However, there are also
114 some other tasks that must be done before initializing the client.
115 The following pointers must be set by the application before calling
116 the initializing function:
120 client->username<br />
121 client->hostname<br />
122 client->realname<br />
123 client->pkcs<br />
124 client->public_key<br />
125 client->private_key
129 You may also set client->nickname if you want. If it is set then the
130 library will change the nickname to that one after the client is connected
131 to the server. If not set, then server will initially give the nickname
132 which is same as the username.
135 After setting the pointers one must call:
138 <tt> silc_client_init(client);</tt>
141 which then initializes the client library for the `client'. If the
142 pointers mentioned above are not initialized the silc_client_init will
143 fail. The application should check the return value of the silc_client_init
147 <br /> <br /> <br />
148 <b>1.3 Running the Client</b>
151 The client is run by calling silc_client_run. The function will call
152 the scheduler from utility library that will be run until the program is
153 ended. When silc_client_run returns the application is ended. Thus,
154 to run the client, call:
157 <tt> silc_client_run(client);</tt>
160 Usually application may do some other initializations before calling
161 this function. For example before calling this function application
162 should initialize the user interface.
165 <br /> <br /> <br />
166 <b>1.3.1 Running the Client in GUI application</b>
169 Many GUI applications has their own main loop or event loop, which they
170 would like to use or are forced to use by the underlaying system. If you
171 are developing for example GUI application on Unix system, and you are
172 using GTK+ or QT as GUI library you would probably like to use their own
173 main loop. SILC Client can be run under external main loop as well. The
174 interface provides a function silc_client_run_one which will run the
175 client library once, and returns immediately. During that running it can
176 process incoming data and send outgoing data, but it is guaranteed that it
177 will not block the calling process.
180 It is suggested that you would call this function as many times in a
181 second as possible to provide smooth action for the client library. You
182 can use an timeout task, or an idle task provided by your GUI library to
183 accomplish this. After you have initialized the client library with
184 silc_client_init, you should register the timeout task or idle task that
185 will call the silc_client_run_one periodically. In the Toolkit package
186 there is GTK-- GUI example in silcer/ directory. That example calls the
187 silc_client_run_one every 50 milliseconds, and it should be sufficient for
191 For Win32 the silc_client_run can be used instead of using the Windows's
192 own event loop. However, if you would like to use the silc_client_run_one
193 also on Win32 systems it is possible.
196 <br /> <br /> <br />
197 <b>1.3.1.1 Running Client in GTK--</b>
200 Here is a short example how to run the SILC Client libary under the
201 Gnome/GTK--'s main loop:
205 gint YourClass::silc_scheduler()<br />
207 // Run the SILC client once, and return immediately. This function<br />
208 // is called every 50 milliseconds by the Gnome main loop, to process<br />
209 // SILC stuff. This function will read data, and write data to network,<br />
210 // etc. Makes the client library tick! :)<br />
211 silc_client_run_one(silc_client);<br />
212 return 1;<br />
217 then, during initialization of the SILC Client call:
221 // Setup SILC scheduler as timeout task. This will handle the SILC<br />
222 // client library every 50 milliseconds. It will actually make the<br />
223 // SILC client work on background.<br />
224 Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);<br />
228 This will call the function silc_scheduler every 50 millisecconds, which
229 on the otherhand will call silc_client_run_one, which will make the SILC
230 Client library work on the background of the GUI application.
233 <br /> <br /> <br />
234 <b>1.4 Creating Connection to Server</b>
237 Connection to remote SILC server is done by calling:
240 <tt> silc_client_connect_to_server(client, port, hostname, context);</tt>
243 The function will create the connection asynchronously to the server, ie.
244 the function will return before the actual connection is created. After
245 the connection is created the client->ops->connect operation is called.
248 Generally speaking the connections are associated with windows' on the
249 screen. IRC is usually implemented this way, however it is not the
250 necessary way to associate the client's connections. SilcClientConnection
251 object is provided by the library (and is always passed to the application)
252 that can be used in the application to associate the connection from the
253 library. Application specific context can be saved to the
254 SilcClientConnection object which then can be retrieved in the application,
255 thus perhaps associate the connection with what ever object in
256 application (window or something else).
259 <br /> <br /> <br />
260 <b>1.4.1 Using Own Connecting</b>
263 Application might not want to use silc_client_connect_to_server function
264 if it wants to perform its own connecting for some reason. In this case
265 application must call function silc_client_start_key_exchange after it
266 has created the connection by itself. This function starts the key
267 exhange protocol between the client and server and the library takes care
268 of everything after that.
271 After connection has been created application must call:
275 SilcClientConnection conn;
278 /* Add new connection to client */<br />
279 conn = silc_client_add_connection(client, hostname, port, context);
282 /* Start key exchange and let the library handle everything<br />
283 after this point on. */<br />
284 silc_client_start_key_exchange(client, conn, sock);
288 NOTE: These calls are performed only and only if application did not call
289 silc_client_connect_to_server function, but performed the connecting
293 <br /> <br /> <br />
294 <b>1.5 Example Client</b>
297 This section includes an example SILC client implementation in pseudo-like
298 C code. It creates and initializes the client and sets up an imaginary
299 user interface. The user will use the user interface then to create
300 the connections. The SilcClientOperations are expected to be implemented.
304 #include "silcincludes.h"
309 SilcClientOperations ops = {
311 silc_channel_message,
312 silc_private_message,
318 silc_get_auth_method,
319 silc_verify_public_key,
327 /* Allocate SILC client. The `silc_version_string' is defined
328 in includes/version.h file. */
329 client = silc_client_alloc(&ops, NULL, silc_version_string);
331 /* Register default ciphers, pkcs, hash funtions and hmacs. */
332 silc_cipher_register_default();
333 silc_pkcs_register_default();
334 silc_hash_register_default();
335 silc_hmac_register_default();
337 /* Set the mandatory pointers, read public and private key from
338 files (or somewhere) and return pointers and PKCS context. */
339 client->username = silc_get_username();
340 client->hostname = silc_net_localhost();
341 client->realname = silc_get_real_name();
342 client->pkcs = get_public_and_private_key(&client->public_key,
343 &client->private_key);
345 /* If the keys does not exist, create a key pair since we must
346 provide key pair to the library. */
348 generate_key_new_key_pair(client);
350 /* Iinitialize client */
351 if (!silc_client_init(client))
352 fatal_error("Could not initialize client");
354 /* Initialize user interface. The user interface can be generally
355 initialized at any phase, including before actually allocating
356 and initializing the client, if wished. */
360 /* Start the client. This will start the scheduler. At this phase
361 the user might have the user interface in front of him already.
362 He will use the user interface to create the connection to the
363 server for example. When this function returns the program is
365 silc_client_run(client);
367 /* Client is ended */