1 <big><b>Using SILC Client Library</b></big>
3 <br /> <br /> <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 component of SILC protocol from the lib/silccore, SKE
13 from lib/silcske and general utility routines from lib/silcutil.
16 The `silcclient.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 `silcclient.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.
28 <br /> <br /> <br />
29 <b>Including Library Headers</b>
32 Your application must include the following includes in your sources to
33 get access all SILC Client Library routines:
37 #include "silcincludes.h"<br />
38 #include "silcclient.h"
41 <br /> <br /> <br />
42 <b>Network Initialization on Win32</b>
45 If you are programming your SILC client application on Windows system,
46 you will need to initialize the network routines in order to be able
47 to use the client library. The network initialization is done by
48 calling the silc_net_win32_init at the start of your Windows application.
49 Usually this is done either in main() or WinMain() function, or other
50 similar place. This function should be called before calling any other
55 if (silc_net_win32_init() == FALSE)<br />
56 exit_with_error();
60 This function is available only on Win32 platforms, and on other platforms
61 the network routines are initialized automatically by the operating system.
64 <br /> <br /> <br />
65 <b>Creating Client</b>
68 The client is context or entity based, so several client entitites can
69 be created in the application if needed. However, it should be noted
70 that they are completely independent from each other and can be seen
71 as different applications. Usually only one client entity is needed
75 The client object is SilcClient which is usually allocated in following
79 <tt> SilcClient client = silc_client_alloc(&ops, params, context, silc_version_string);</tt>
82 `ops' is the static structure of client operations that library will call.
83 `context' can be some application specific context that will be saved into
84 the SilcClient object. It is up to the caller to free this context.
85 SilcClient is always passed to the application thus the application
86 specific context can be retrieved from the SilcClient object. See
87 `client.h' file for detailed definition of SilcClient object.
90 The `silc_version_string' is the current protocol version string, and you
91 can get it by including `silcversion.h' header in your source code.
94 `ops' can be defined for example as follows:
98 SilcClientOperations ops = {<br />
99 silc_say,<br />
100 silc_channel_message,<br />
101 silc_private_message,<br />
102 silc_notify,<br />
103 silc_command,<br />
104 silc_command_reply,<br />
105 silc_connect,<br />
106 silc_disconnect,<br />
107 silc_get_auth_method,<br />
108 silc_verify_public_key,<br />
109 silc_ask_passphrase,<br />
110 silc_failure,<br />
111 silc_key_agreement,<br />
116 Please see the `client_ops_example.c' source file in lib/silcclient/
117 directory for predefined structure and stub functions for your
118 convenience. It is provided for programmers so that they can copy
119 it and use it directly in their application.
122 <br /> <br /> <br />
123 <b>Initializing the Client</b>
126 The client must be initialized before running. However, there are also
127 some other tasks that must be done before initializing the client.
128 The following pointers must be set by the application before calling
129 the initializing function:
133 client->username<br />
134 client->hostname<br />
135 client->realname<br />
136 client->pkcs<br />
137 client->public_key<br />
138 client->private_key
142 You may also set client->nickname if you want. If it is set then the
143 library will change the nickname to that one after the client is connected
144 to the server. If not set, then server will initially give the nickname
145 which is same as the username.
148 After setting the pointers one must call:
151 <tt> silc_client_init(client);</tt>
154 which then initializes the client library for the `client'. If the
155 pointers mentioned above are not initialized the silc_client_init will
156 fail. The application should check the return value of the silc_client_init
160 <br /> <br /> <br />
161 <b>Running the Client</b>
164 The client is run by calling silc_client_run. The function will call
165 the scheduler from utility library that will be run until the program is
166 ended. When silc_client_run returns the application is ended. Thus,
167 to run the client, call:
170 <tt> silc_client_run(client);</tt>
173 Usually application may do some other initializations before calling
174 this function. For example before calling this function application
175 should initialize the user interface.
178 <br /> <br /> <br />
179 <b>Running the Client in GUI application</b>
182 Many GUI applications has their own main loop or event loop, which they
183 would like to use or are forced to use by the underlaying system. If you
184 are developing for example GUI application on Unix system, and you are
185 using GTK+ or QT as GUI library you would probably like to use their own
186 main loop. SILC Client can be run under external main loop as well. The
187 interface provides a function silc_client_run_one which will run the
188 client library once, and returns immediately. During that running it can
189 process incoming data and send outgoing data, but it is guaranteed that it
190 will not block the calling process.
193 It is suggested that you would call this function as many times in a
194 second as possible to provide smooth action for the client library. You
195 can use an timeout task, or an idle task provided by your GUI library to
196 accomplish this. After you have initialized the client library with
197 silc_client_init, you should register the timeout task or idle task that
198 will call the silc_client_run_one periodically. In the Toolkit package
199 there is GTK-- GUI example in silcer/ directory. That example calls the
200 silc_client_run_one every 50 milliseconds, and it should be sufficient for
204 For Win32 the silc_client_run can be used instead of using the Windows's
205 own event loop. However, if you would like to use the silc_client_run_one
206 also on Win32 systems it is possible.
209 <br /> <br /> <br />
210 <b>Running Client in GTK--</b>
213 Here is a short example how to run the SILC Client libary under the
214 Gnome/GTK--'s main loop:
218 gint YourClass::silc_scheduler()<br />
220 // Run the SILC client once, and return immediately. This function<br />
221 // is called every 50 milliseconds by the Gnome main loop, to process<br />
222 // SILC stuff. This function will read data, and write data to network,<br />
223 // etc. Makes the client library tick! :)<br />
224 silc_client_run_one(silc_client);<br />
225 return 1;<br />
230 then, during initialization of the SILC Client call:
234 // Setup SILC scheduler as timeout task. This will handle the SILC<br />
235 // client library every 50 milliseconds. It will actually make the<br />
236 // SILC client work on background.<br />
237 Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);<br />
241 This will call the function silc_scheduler every 50 millisecconds, which
242 on the otherhand will call silc_client_run_one, which will make the SILC
243 Client library work on the background of the GUI application.
246 <br /> <br /> <br />
247 <b>Creating Connection to Server</b>
250 Connection to remote SILC server is done by calling:
253 <tt> silc_client_connect_to_server(client, port, hostname, context);</tt>
256 The function will create the connection asynchronously to the server, ie.
257 the function will return before the actual connection is created. After
258 the connection is created the client->ops->connect operation is called.
261 Generally speaking the connections are associated with windows' on the
262 screen. IRC is usually implemented this way, however it is not the
263 necessary way to associate the client's connections. SilcClientConnection
264 object is provided by the library (and is always passed to the application)
265 that can be used in the application to associate the connection from the
266 library. Application specific context can be saved to the
267 SilcClientConnection object which then can be retrieved in the application,
268 thus perhaps associate the connection with what ever object in
269 application (window or something else).
272 <br /> <br /> <br />
273 <b>Using Own Connecting</b>
276 Application might not want to use silc_client_connect_to_server function
277 if it wants to perform its own connecting for some reason. In this case
278 application must call function silc_client_start_key_exchange after it
279 has created the connection by itself. This function starts the key
280 exhange protocol between the client and server and the library takes care
281 of everything after that.
284 After connection has been created application must call:
288 SilcClientConnection conn;
291 /* Add new connection to client */<br />
292 conn = silc_client_add_connection(client, hostname, port, context);
295 /* Start key exchange and let the library handle everything<br />
296 after this point on. */<br />
297 silc_client_start_key_exchange(client, conn, sock);
301 NOTE: These calls are performed only and only if application did not call
302 silc_client_connect_to_server function, but performed the connecting
306 <br /> <br /> <br />
310 Being able to debug what you have coded is important when troubles occurs
311 during coding, and they always do. SILC supports extensive debugging
312 capabilities which are also available for client library user. You should
313 have compiled the Toolkit with --enable-debug option so that run-time
314 debugging is enabled.
317 Then, to say in your application you would like to use the debugging use
318 the SILC_ENABLE_DEBUG macro. Put this macro to your main header file, or
319 some other file that needs the debugging enabled. After using this macro
320 you are able to use the debugging routines provided by the SILC Toolkit.
321 Note that, the Toolkit library must be compiled with --enable-debug for
322 this macro to have any effect.
325 To turn on the run-time debugging call function silc_log_debug with TRUE
326 value. To see packet hexdumps you can call also silc_log_debug_hexdump
327 with TRUE value. Hexdumps can create more debug log so not setting it
328 to TRUE by default is probably best. To get debug messages out of specific
329 modules you can set a debug string with silc_log_set_debug_string function.
330 The function takes regex string as argument, for example:
334 silc_log_debug(TRUE);<br />
335 silc_log_set_debug_string("*");<br />
339 This piece of code turns on the debugging and sets "*" as debug string. This
340 means that all debug messages are printed. To get debugging out of only
341 for example SILC Client Library the debug string could be "silc_client*".
342 The debug string matches to function names and filenames so it is possible
343 to get debugging out of specific files, and specific functions. Other
348 silc_log_set_debug_string("silc_client*,*socket*,*ske*");<br />
352 By default, all debug messages are printed to standard error output (stderr).
353 If you want to redirect the debug messages somewhere else you can set your
354 own debug callback with silc_log_set_debug_callbacks function:
358 silc_log_set_debug_callbacks(my_debug_callback, my_context, my_hexdump_callback, my_context);<br />
362 See the lib/silcutil/silclog.h for definition of the callbacks. See the
363 same file for other logging and debugging information.
366 You can also use SILC debugging capabilities in your own application. To
367 produce debug messages you can use SILC_LOG_DEBUG and SILC_LOG_HEXDUMP
368 macros in your application. The SILC_LOG_DEBUG can print out normal debug
369 messages with variable argument list, for example:
373 SILC_LOG_DEBUG(("Start"));<br />
374 SILC_LOG_DEBUG(("Packet length %d", packet_len));<br />
375 SILC_LOG_DEBUG(("The remote is %s on %d", sock->ip, sock->port));
379 The SILC_LOG_HEXDUMP macro can be used dump data which couldn't be printed
380 out otherwise, for example binary data.
384 SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);<br />
385 SILC_LOG_HEXDUMP(("Packet, size=%d", size), packet->data, packet->len);
389 Note that the variable arguments in SILC_LOG_HEXDUMP are before the second
390 last parenthesis, and the last two arguments are the data, and its length that
394 <br /> <br /> <br />
395 <b>Example Client</b>
398 This section includes an example SILC client implementation in pseudo-like
399 C code. It creates and initializes the client and sets up an imaginary
400 user interface. The user will use the user interface then to create
401 the connections. The SilcClientOperations are expected to be implemented.
405 #include "silcincludes.h"
406 #include "silcclient.h"
410 SilcClientOperations ops = {
412 silc_channel_message,
413 silc_private_message,
419 silc_get_auth_method,
420 silc_verify_public_key,
430 /* Allocate SILC client. The `silc_version_string' is defined
431 in includes/version.h file. */
432 client = silc_client_alloc(&ops, NULL, NULL, silc_version_string);
434 /* Set the mandatory pointers, read public and private key from
435 files (or somewhere) and return pointers and PKCS context. */
436 client->username = silc_get_username();
437 client->hostname = silc_net_localhost();
438 client->realname = silc_get_real_name();
439 client->pkcs = get_public_and_private_key(&client->public_key,
440 &client->private_key);
442 /* If the keys does not exist, create a key pair since we must
443 provide key pair to the library. */
445 generate_key_new_key_pair(client);
447 /* Iinitialize client */
448 if (!silc_client_init(client))
449 fatal_error("Could not initialize client");
451 /* Initialize user interface. The user interface can be generally
452 initialized at any phase, including before actually allocating
453 and initializing the client, if wished. */
457 /* Start the client. This will start the scheduler. At this phase
458 the user might have the user interface in front of him already.
459 He will use the user interface to create the connection to the
460 server for example. When this function returns the program is
462 silc_client_run(client);
464 /* Client is ended */