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' and `silcclient_entry.h' also defines the
24 client libary interface the application can call. The interface includes
25 for example functions for sending channel and private messages, client and
26 channel retrieval 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 "silc.h"<br />
38 #include "silcclient.h"
42 <br /> <br /> <br />
43 <b>Creating Client</b>
46 The client is context or entity based, so several client entitites can
47 be created in the application if needed. However, it should be noted
48 that they are completely independent from each other and can be seen
49 as different applications. Usually only one client entity is needed
53 The client object is SilcClient which is usually allocated in following
57 <tt> SilcClient client = silc_client_alloc(&ops, params, context, NULL);</tt>
60 `ops' is the static structure of client operations that library will call.
61 `context' can be some application specific context that will be saved into
62 the SilcClient object. It is up to the caller to free this context.
63 SilcClient is always passed to the application thus the application
64 specific context can be retrieved from the SilcClient object.
67 `ops' can be defined for example as follows:
71 SilcClientOperations ops = {<br />
72 silc_say,<br />
73 silc_channel_message,<br />
74 silc_private_message,<br />
75 silc_notify,<br />
76 silc_command,<br />
77 silc_command_reply,<br />
78 silc_get_auth_method,<br />
79 silc_verify_public_key,<br />
80 silc_ask_passphrase,<br />
81 silc_key_agreement,<br />
82 silc_file_transfer,<br />
87 Please see the `client_ops_example.c' source file in lib/silcclient/
88 directory for predefined structure and stub functions for your
89 convenience. It is provided for programmers so that they can copy
90 it and use it directly in their application.
93 <br /> <br /> <br />
94 <b>Initializing the Client</b>
97 The client must be initialized before running. The client is initialized
98 simply by calling silc_client_init function:
101 <tt> silc_client_init(client, username, hostname, realname,
102 foo_client_running, foo_ctx);</tt>
105 which then initializes the client library for the `client'. The `username'
106 and `hostname' pointers are required. The `foo_client_running' with
107 `foo_ctx' in this example will be called by the client library after the
108 client is up and running. After you receive this callback you may start
109 using other API functions, such as creating connection to remote server.
112 <br /> <br /> <br />
113 <b>Running the Client</b>
116 The client is run by calling silc_client_run. The function will call
117 the scheduler from utility library that will be run until the program is
118 ended. When silc_client_run returns the application is ended. Thus,
119 to run the client, call:
122 <tt> silc_client_run(client);</tt>
125 Usually application may do some other initializations before calling
126 this function. For example before calling this function application
127 should initialize the user interface.
130 <br /> <br /> <br />
131 <b>Running the Client in GUI application</b>
134 Many GUI applications has their own main loop or event loop, which they
135 would like to use or are forced to use by the underlaying system. If you
136 are developing for example GUI application on Unix system, and you are
137 using GTK+ or QT as GUI library you would probably like to use their own
138 main loop. SILC Client can be run under external main loop as well. The
139 interface provides a function silc_client_run_one which will run the
140 client library once, and returns immediately. During that running it can
141 process incoming data and send outgoing data, but it is guaranteed that it
142 will not block the calling process.
145 It is suggested that you would call this function as many times in a
146 second as possible to provide smooth action for the client library. You
147 can use an timeout task, or an idle task provided by your GUI library to
148 accomplish this. After you have initialized the client library with
149 silc_client_init, you should register the timeout task or idle task that
150 will call the silc_client_run_one periodically.
153 For Win32 the silc_client_run can be used instead of using the Windows's
154 own event loop. However, if you would like to use the silc_client_run_one
155 also on Win32 system it is possible.
158 <br /> <br /> <br />
159 <b>Running Client in GTK--</b>
162 Here is a short example how to run the SILC Client libary under the
163 Gnome/GTK--'s main loop:
167 gint YourClass::silc_scheduler()<br />
169 // Run the SILC client once, and return immediately. This function<br />
170 // is called every 50 milliseconds by the Gnome main loop, to process<br />
171 // SILC stuff. This function will read data, and write data to network,<br />
172 // etc. Makes the client library tick! :)<br />
173 silc_client_run_one(silc_client);<br />
174 return 1;<br />
179 then, during initialization of the SILC Client call:
183 // Setup SILC scheduler as timeout task. This will handle the SILC<br />
184 // client library every 50 milliseconds. It will actually make the<br />
185 // SILC client work on background.<br />
186 Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);<br />
190 This will call the function silc_scheduler every 50 millisecconds, which
191 on the otherhand will call silc_client_run_one, which will make the SILC
192 Client library work on the background of the GUI application.
195 <br /> <br /> <br />
196 <b>Creating Connection to Server</b>
199 After your client is up and running you may create connection to remote
200 SILC server. It is done simply by calling:
203 <tt> silc_client_connect_to_server(client, ¶ms,
204 public_key, private_key,
205 remote_host, remote_port,
206 foo_connected_cb, foo_ctx);</tt>
209 The function will create the connection asynchronously to the server, ie.
210 the function will return before the actual connection is created. The
211 `foo_connected_cb' will be called once the connection has been established.
212 The `params' may be NULL but it may be used to provide additional parameters
213 to the connecting. For example it is possible to set the initial nickname
214 you would like to use into the `params'.
217 <br /> <br /> <br />
221 Being able to debug what you have coded is important when troubles occurs
222 during coding, and they always do. SILC supports extensive debugging
223 capabilities which are also available for client library user. You should
224 have compiled the Toolkit with --enable-debug option so that run-time
225 debugging is enabled.
228 Then, to say in your application you would like to use the debugging use
229 the SILC_DEBUG macro. Put this macro to your main header file, or
230 some other file that needs the debugging enabled. After using this macro
231 you are able to use the debugging routines provided by the SILC Toolkit.
232 Note that, the Toolkit library must be compiled with --enable-debug for
233 this macro to have any effect.
236 To turn on the run-time debugging call function silc_log_debug with TRUE
237 value. To see packet hexdumps you can call also silc_log_debug_hexdump
238 with TRUE value. Hexdumps can create more debug log so not setting it
239 to TRUE by default is probably best. To get debug messages out of specific
240 modules you can set a debug string with silc_log_set_debug_string function.
241 The function takes regex string as argument, for example:
245 silc_log_debug(TRUE);<br />
246 silc_log_set_debug_string("*");<br />
250 This piece of code turns on the debugging and sets "*" as debug string. This
251 means that all debug messages are printed. To get debugging out of only
252 for example SILC Client Library the debug string could be "silc_client*".
253 The debug string matches to function names and filenames so it is possible
254 to get debugging out of specific files, and specific functions. Other
259 silc_log_set_debug_string("silc_client*,*sock*,*ske*");<br />
263 By default, all debug messages are printed to standard error output (stderr).
264 If you want to redirect the debug messages somewhere else you can set your
265 own debug callback with silc_log_set_debug_callbacks function:
269 silc_log_set_debug_callbacks(my_debug_callback, my_context, my_hexdump_callback, my_context);<br />
273 See the lib/silcutil/silclog.h for definition of the callbacks. See the
274 same file for other logging and debugging information.
277 You can also use SILC debugging capabilities in your own application. To
278 produce debug messages you can use SILC_LOG_DEBUG and SILC_LOG_HEXDUMP
279 macros in your application. The SILC_LOG_DEBUG can print out normal debug
280 messages with variable argument list, for example:
284 SILC_LOG_DEBUG(("Start"));<br />
285 SILC_LOG_DEBUG(("Packet length %d", packet_len));<br />
286 SILC_LOG_DEBUG(("The remote is %s on %d", sock->ip, sock->port));
290 The SILC_LOG_HEXDUMP macro can be used dump data which couldn't be printed
291 out otherwise, for example binary data.
295 SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);<br />
296 SILC_LOG_HEXDUMP(("Packet, size=%d", size), packet->data, packet->len);
300 Note that the variable arguments in SILC_LOG_HEXDUMP are before the second
301 last parenthesis, and the last two arguments are the data, and its length that
projects / silc.git / blob