docs/toolkit/manual/silcclient_using.html

   1
   2 <html>
   3 <head>
   4  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-a" />
   5  <meta http-equiv="Content-Language" content="en" />
   6  <meta name="description" content="SILC Secure Internet Live Conferencing" />
   7  <meta name="keywords" content="SILC, secure, chat, protocol, cipher, encrypt, SKE" />
   8  <meta content="INDEX, FOLLOW" name="ROBOTS" />
   9  <style type="text/css">
  10   <!--
  11   body { color: #000000; background: #f0f0f0; font-family: Helvetica, Arial, Sans-serif; }
  12   a:link { text-decoration: none; color: #2f488f; }
  13   a:visited { text-decoration: none;color: #2f488f; }
  14   a:active { text-decoration: none; color: #2f488f; }
  15   -->
  16  </style>
  17 </head>
  18
  19 <body topmargin="0" leftmargin="0" marginheight="0" marginwidth="0">
  20
  21 <table border="0" cellspacing="0" cellpadding="6" width="100%">
  22  <tr valign="top" bgcolor="#dddddd">
  23   <td><small>Copyright &copy; 2001 - 2007 SILC Project<br />
  24     <a href="http://silcnet.org">SILC Project Website</a></small></td>
  25   <td align="right"><small>
  26    <a href="index.html">SILC Toolkit Reference Manual</a><br />
  27    <a href="toolkit_index.html">Index</a></small></td>
  28    </small></td>
  29  </tr>
  30 </table>
  31 <table border="0" cellspacing="0" cellpadding="0" width="100%">
  32 <tr bgcolor="#444444"><td><img src="space.gif" width="1" height="1"border="0" alt="" ></td></tr>
  33 </table>
  34
  35 <table cellpadding="0" cellspacing="0" border="0">
  36  <tr valign="top">
  37
  38   <td width="200" bgcolor="#f0f0f0">
  39    <img src="space.gif" width="1" height="1" border="0" alt="">
  40    <table width="100%" cellpadding="2" cellspacing="2" border="0">
  41     <tr valign="top"><td>
  42 <br />
  43 <small>
  44 <!-- Template file for the big index that appears in the Toolkit reference
  45 manual on the left side.  With this file it is possible to add other than
  46 automatically generated links to that list. -->
  47
  48 <a href="index.html"><img src="box.gif" border="0" alt="">SILC Toolkit Reference Manual</a><br />
  49
  50
  51 <a href=silccryptlib.html><img src=box.gif border=0 alt=>SILC Crypto Library</a><br />
  52 &nbsp;&nbsp;&nbsp; <a href=silcrng_intro.html><img src=box2.gif border=0 alt=>Introduction to SILC RNG</a><br />
  53 &nbsp;&nbsp;&nbsp; <a href=silcrng.html><img src=box2.gif border=0 alt=>SILC RNG Interface</a><br />
  54 &nbsp;&nbsp;&nbsp; <a href=silccipher.html><img src=box2.gif border=0 alt=>SILC Cipher API</a><br />
  55 &nbsp;&nbsp;&nbsp; <a href=silcpkcs.html><img src=box2.gif border=0 alt=>SILC PKCS API</a><br />
  56 &nbsp;&nbsp;&nbsp; <a href=silcpk.html><img src=box2.gif border=0 alt=>SILC Public Key API</a><br />
  57 &nbsp;&nbsp;&nbsp; <a href=silcpkcs1.html><img src=box2.gif border=0 alt=>SILC PKCS #1 API</a><br />
  58 &nbsp;&nbsp;&nbsp; <a href=silchash.html><img src=box2.gif border=0 alt=>SILC Hash Interface</a><br />
  59 &nbsp;&nbsp;&nbsp; <a href=silchmac.html><img src=box2.gif border=0 alt=>SILC HMAC Interface</a><br />
  60 <a href=silccorelib.html><img src=box.gif border=0 alt=>SILC Core Library</a><br />
  61 &nbsp;&nbsp;&nbsp; <a href=silcauth.html><img src=box2.gif border=0 alt=>SILC Authentication Interface</a><br />
  62 &nbsp;&nbsp;&nbsp; <a href=silcmessage.html><img src=box2.gif border=0 alt=>SILC Message Interface</a><br />
  63 &nbsp;&nbsp;&nbsp; <a href=silcchannel.html><img src=box2.gif border=0 alt=>SILC Channel Interface</a><br />
  64 &nbsp;&nbsp;&nbsp; <a href=silccommand.html><img src=box2.gif border=0 alt=>SILC Command Interface</a><br />
  65 &nbsp;&nbsp;&nbsp; <a href=silcnotify.html><img src=box2.gif border=0 alt=>SILC Notify Interface</a><br />
  66 &nbsp;&nbsp;&nbsp; <a href=silcstatus.html><img src=box2.gif border=0 alt=>SILC Status Types</a><br />
  67 &nbsp;&nbsp;&nbsp; <a href=silcmode.html><img src=box2.gif border=0 alt=>SILC Modes</a><br />
  68 &nbsp;&nbsp;&nbsp; <a href=silcid.html><img src=box2.gif border=0 alt=>SILC ID Interface</a><br />
  69 &nbsp;&nbsp;&nbsp; <a href=silcargument.html><img src=box2.gif border=0 alt=>SILC Argument Interface</a><br />
  70 &nbsp;&nbsp;&nbsp; <a href=silcattrs.html><img src=box2.gif border=0 alt=>SILC Attributes Interface</a><br />
  71 &nbsp;&nbsp;&nbsp; <a href=silcpacket.html><img src=box2.gif border=0 alt=>Packet Engine Interface</a><br />
  72 &nbsp;&nbsp;&nbsp; <a href=silcpubkey.html><img src=box2.gif border=0 alt=>SILC Public Key Payload Interface</a><br />
  73 <a href=silcskelib.html><img src=box.gif border=0 alt=>SILC Key Exchange Library</a><br />
  74 &nbsp;&nbsp;&nbsp; <a href=silcske.html><img src=box2.gif border=0 alt=>SILC SKE Interface</a><br />
  75 &nbsp;&nbsp;&nbsp; <a href=silcconnauth.html><img src=box2.gif border=0 alt=>SILC Connection Authentication Interface</a><br />
  76 <a href=silcvcardlib.html><img src=box.gif border=0 alt=>SILC VCard Library</a><br />
  77 &nbsp;&nbsp;&nbsp; <a href=silcvcard.html><img src=box2.gif border=0 alt=>SILC VCard Interface</a><br />
  78 <a href=silcmathlib.html><img src=box.gif border=0 alt=>SILC Math Library</a><br />
  79 &nbsp;&nbsp;&nbsp; <a href=silcmp.html><img src=box2.gif border=0 alt=>SILC MP Interface</a><br />
  80 &nbsp;&nbsp;&nbsp; <a href=silcmath.html><img src=box2.gif border=0 alt=>SILC Math Interface</a><br />
  81 <a href=silcclientlib.html><img src=box.gif border=0 alt=>SILC Client Library</a><br />
  82 &nbsp;&nbsp;&nbsp; <a href=silcclient_using.html><img src=box2.gif border=0 alt=>Using SILC Client Library Tutorial</a><br />
  83 &nbsp;&nbsp;&nbsp; <a href=command_reply_args.html><img src=box2.gif border=0 alt=>Arguments for <b>command_reply</b> Client Operation</a><br />
  84 &nbsp;&nbsp;&nbsp; <a href=silcstatus_args.html><img src=box2.gif border=0 alt=>SilcStatus Error Arguments in <b>command_reply</b> Client Operation</a><br />
  85 &nbsp;&nbsp;&nbsp; <a href=notifyargs.html><img src=box2.gif border=0 alt=>Arguments for <b>notify</b> Client Operation</a><br />
  86 &nbsp;&nbsp;&nbsp; <a href=silcclient_unicode.html><img src=box2.gif border=0 alt=>Unicode and UTF-8 Strings in Client Library</a><br />
  87 &nbsp;&nbsp;&nbsp; <a href=silcclient.html><img src=box2.gif border=0 alt=>Client Library Interface Reference</a><br />
  88 &nbsp;&nbsp;&nbsp; <a href=silcclient_entry.html><img src=box2.gif border=0 alt=>Client Entry Interface Reference</a><br />
  89 <a href=silcasn1lib.html><img src=box.gif border=0 alt=>SILC ASN.1 Library</a><br />
  90 &nbsp;&nbsp;&nbsp; <a href=silcasn1.html><img src=box2.gif border=0 alt=>SILC ASN.1 Interface</a><br />
  91 &nbsp;&nbsp;&nbsp; <a href=silcber.html><img src=box2.gif border=0 alt=>SILC BER interface</a><br />
  92 <a href=silchttplib.html><img src=box.gif border=0 alt=>SILC HTTP Library</a><br />
  93 &nbsp;&nbsp;&nbsp; <a href=silchttpserver.html><img src=box2.gif border=0 alt=>SILC HTTP Server Interface</a><br />
  94 &nbsp;&nbsp;&nbsp; <a href=silchttpphp.html><img src=box2.gif border=0 alt=>SILC HTTP PHP Translator</a><br />
  95 <a href=silcutillib.html><img src=box.gif border=0 alt=>SILC Utility Library</a><br />
  96 &nbsp;&nbsp;&nbsp; <a href=silctypes.html><img src=box2.gif border=0 alt=>Basic Types and Definitions</a><br />
  97 &nbsp;&nbsp;&nbsp; <a href=silcbuffer.html><img src=box2.gif border=0 alt=>Data Buffer Interface</a><br />
  98 &nbsp;&nbsp;&nbsp; <a href=silcbuffmt.html><img src=box2.gif border=0 alt=>Data Buffer Format Interface</a><br />
  99 &nbsp;&nbsp;&nbsp; <a href=silchashtable.html><img src=box2.gif border=0 alt=>Hash Table Interface</a><br />
 100 &nbsp;&nbsp;&nbsp; <a href=silcmemory.html><img src=box2.gif border=0 alt=>Memory Allocation Interface</a><br />
 101 &nbsp;&nbsp;&nbsp; <a href=silcstack.html><img src=box2.gif border=0 alt=>Data Stack (memory pool) Interface</a><br />
 102 &nbsp;&nbsp;&nbsp; <a href=silcfsm.html><img src=box2.gif border=0 alt=>Finite State Machine Interface</a><br />
 103 &nbsp;&nbsp;&nbsp; <a href=silcthread.html><img src=box2.gif border=0 alt=>Thread Interface</a><br />
 104 &nbsp;&nbsp;&nbsp; <a href=silcmutex.html><img src=box2.gif border=0 alt=>Mutual Exclusion Lock Interface</a><br />
 105 &nbsp;&nbsp;&nbsp; <a href=silccond.html><img src=box2.gif border=0 alt=>Condition Variable Interface</a><br />
 106 &nbsp;&nbsp;&nbsp; <a href=silcatomic.html><img src=box2.gif border=0 alt=>Atomic Operations Interface</a><br />
 107 &nbsp;&nbsp;&nbsp; <a href=silcnet.html><img src=box2.gif border=0 alt=>Network (TCP and UDP) Interface</a><br />
 108 &nbsp;&nbsp;&nbsp; <a href=silcschedule.html><img src=box2.gif border=0 alt=>Scheduler Interface</a><br />
 109 &nbsp;&nbsp;&nbsp; <a href=silcasync.html><img src=box2.gif border=0 alt=>Asynchronous Operation Interface</a><br />
 110 &nbsp;&nbsp;&nbsp; <a href=silcstream.html><img src=box2.gif border=0 alt=>Abstract Stream Interface</a><br />
 111 &nbsp;&nbsp;&nbsp; <a href=silcsocketstream.html><img src=box2.gif border=0 alt=>Socket Stream Interface</a><br />
 112 &nbsp;&nbsp;&nbsp; <a href=silcfdstream.html><img src=box2.gif border=0 alt=>File Descriptor Stream Interface</a><br />
 113 &nbsp;&nbsp;&nbsp; <a href=silcfileutil.html><img src=box2.gif border=0 alt=>File Utility Functions</a><br />
 114 &nbsp;&nbsp;&nbsp; <a href=silcstrutil.html><img src=box2.gif border=0 alt=>String Utility Interface</a><br />
 115 &nbsp;&nbsp;&nbsp; <a href=silcsnprintf.html><img src=box2.gif border=0 alt=>Snprintf Interface</a><br />
 116 &nbsp;&nbsp;&nbsp; <a href=silcutf8.html><img src=box2.gif border=0 alt=>UTF-8 String Interface</a><br />
 117 &nbsp;&nbsp;&nbsp; <a href=silcstringprep.html><img src=box2.gif border=0 alt=>Stringprep Interface</a><br />
 118 &nbsp;&nbsp;&nbsp; <a href=silcutil.html><img src=box2.gif border=0 alt=>Utility Functions</a><br />
 119 &nbsp;&nbsp;&nbsp; <a href=silclist.html><img src=box2.gif border=0 alt=>List Interface</a><br />
 120 &nbsp;&nbsp;&nbsp; <a href=silcdlist.html><img src=box2.gif border=0 alt=>Dynamic List Interface</a><br />
 121 &nbsp;&nbsp;&nbsp; <a href=silcmime.html><img src=box2.gif border=0 alt=>MIME Interface</a><br />
 122 &nbsp;&nbsp;&nbsp; <a href=silctime.html><img src=box2.gif border=0 alt=>Time Utility Functions</a><br />
 123 &nbsp;&nbsp;&nbsp; <a href=silclog.html><img src=box2.gif border=0 alt=>Logging Interface</a><br />
 124 &nbsp;&nbsp;&nbsp; <a href=silcconfig.html><img src=box2.gif border=0 alt=>Config File Interface</a><br />
 125 <a href=silcskrlib.html><img src=box.gif border=0 alt=>SILC Key Repository Library</a><br />
 126 &nbsp;&nbsp;&nbsp; <a href=silcskr.html><img src=box2.gif border=0 alt=>SILC SKR Interface</a><br />
 127 <a href=silcaputillib.html><img src=box.gif border=0 alt=>SILC Application Utility Library</a><br />
 128 &nbsp;&nbsp;&nbsp; <a href=silcapputil.html><img src=box2.gif border=0 alt=>SILC Application Utilities</a><br />
 129 &nbsp;&nbsp;&nbsp; <a href=silcidcache.html><img src=box2.gif border=0 alt=>SILC ID Cache Interface</a><br />
 130 <a href=silcsftplib.html><img src=box.gif border=0 alt=>SILC SFTP Library</a><br />
 131 &nbsp;&nbsp;&nbsp; <a href=silcsftp.html><img src=box2.gif border=0 alt=>SILC SFTP Interface</a><br />
 132 &nbsp;&nbsp;&nbsp; <a href=silcsftp_fs.html><img src=box2.gif border=0 alt=>SFTP Filesystems Interface</a><br />
 133
 134 <br />
 135 <b>Resource Links</b>
 136 <br />
 137 <a href="http://silcnet.org"><img src="box.gif" border="0" alt="">SILC Project Website</a><br />
 138 <a href="http://silcnet.org/support/documentation/"><img src="box.gif" border="0" alt="">SILC Protocol Documentation</a><br />
 139 <a href="http://silcnet.org/support/documentation/wp/"><img src="box.gif" border="0" alt="">SILC White Paper</a><br />
 140 <a href="http://silcnet.org/support/faq/"><img src="box.gif" border="0" alt="">SILC FAQs</a><br />
 141
 142 </small>
 143 <br /><br /><br /><br />
 144     </td></tr>
 145    </table>
 146   </td>
 147
 148   <td bgcolor="#cccccc" background="dot.gif">
 149    <img src="space.gif" width="1" height="1" border="0" alt=""></td>
 150
 151   <td width="720" bgcolor="#ffffff">
 152    <img src="space.gif" width="1" height="1" border="0" alt="">
 153    <table cellpadding="2" cellspacing="6" width="100%">
 154     <tr><td valign="top">
 155 <br />
 156 <big><b>Using SILC Client Library</b></big>
 157
 158 <br />&nbsp;<br />&nbsp;<br />
 159 <b>Introduction</b>
 160
 161 <br />&nbsp;<br />
 162 SILC Client library is a full featured SILC Client protocol implementation.
 163 The library has been designed to be complete SILC client without actual
 164 user interface.  The library provides the API for the appliation which
 165 it can use to implement generally whatever user interface it wants.  The
 166 SILC Client Library recides in the lib/silcclient/ directory.  It uses
 167 common and core component of SILC protocol from the lib/silccore, SKE
 168 from lib/silcske and general utility routines from lib/silcutil.
 169
 170 <br />&nbsp;<br />
 171 The `silcclient.h' file defines the function prototypes that application
 172 must implement in order to be able to create the user interface with the
 173 library.  The idea is that the application can implement whatever user
 174 interface routines in the functions and display the data whatever way
 175 it wants.  The library is entirely transparent to the user interface and
 176 it does not include any user interface specific issues such as window
 177 handling or item handling on the screen etc.  These does not interest
 178 the library.  The `silcclient.h' and `silcclient_entry.h' also defines the
 179 client libary interface the application can call.  The interface includes
 180 for example functions for sending channel and private messages, client and
 181 channel retrieval and other utility functions.
 182
 183 <br />&nbsp;<br />&nbsp;<br />
 184 <b>Including Library Headers</b>
 185
 186 <br />&nbsp;<br />
 187 Your application must include the following includes in your sources to
 188 get access all SILC Client Library routines:
 189
 190 <br />&nbsp;<br />
 191 <tt>
 192 #include "silc.h"<br />
 193 #include "silcclient.h"
 194 </tt>
 195
 196
 197 <br />&nbsp;<br />&nbsp;<br />
 198 <b>Creating Client</b>
 199
 200 <br />&nbsp;<br />
 201 The client is context or entity based, so several client entitites can
 202 be created in the application if needed.  However, it should be noted
 203 that they are completely independent from each other and can be seen
 204 as different applications.  Usually only one client entity is needed
 205 per application.
 206
 207 <br />&nbsp;<br />
 208 The client object is SilcClient which is usually allocated in following
 209 manner:
 210
 211 <br />&nbsp;<br />
 212 <tt>&nbsp;&nbsp;SilcClient client = silc_client_alloc(&ops, params, context, NULL);</tt>
 213
 214 <br />&nbsp;<br />
 215 `ops' is the static structure of client operations that library will call.
 216 `context' can be some application specific context that will be saved into
 217 the SilcClient object.  It is up to the caller to free this context.
 218 SilcClient is always passed to the application thus the application
 219 specific context can be retrieved from the SilcClient object.
 220
 221 <br />&nbsp;<br />
 222 `ops' can be defined for example as follows:
 223
 224 <br />&nbsp;<br />
 225 <tt>
 226 SilcClientOperations ops = {<br />
 227 &nbsp;&nbsp;  silc_say,<br />
 228 &nbsp;&nbsp;  silc_channel_message,<br />
 229 &nbsp;&nbsp;  silc_private_message,<br />
 230 &nbsp;&nbsp;  silc_notify,<br />
 231 &nbsp;&nbsp;  silc_command,<br />
 232 &nbsp;&nbsp;  silc_command_reply,<br />
 233 &nbsp;&nbsp;  silc_get_auth_method,<br />
 234 &nbsp;&nbsp;  silc_verify_public_key,<br />
 235 &nbsp;&nbsp;  silc_ask_passphrase,<br />
 236 &nbsp;&nbsp;  silc_key_agreement,<br />
 237 &nbsp;&nbsp;  silc_file_transfer,<br />
 238 };<br />
 239 </tt>
 240
 241 <br />&nbsp;<br />
 242 Please see the `client_ops_example.c' source file in lib/silcclient/
 243 directory for predefined structure and stub functions for your
 244 convenience.  It is provided for programmers so that they can copy
 245 it and use it directly in their application.
 246
 247
 248 <br />&nbsp;<br />&nbsp;<br />
 249 <b>Initializing the Client</b>
 250
 251 <br />&nbsp;<br />
 252 The client must be initialized before running.  The client is initialized
 253 simply by calling silc_client_init function:
 254
 255 <br />&nbsp;<br />
 256 <tt>&nbsp;&nbsp;silc_client_init(client, username, hostname, realname,
 257                                  foo_client_running, foo_ctx);</tt>
 258
 259 <br />&nbsp;<br />
 260 which then initializes the client library for the `client'.  The `username'
 261 and `hostname' pointers are required.  The `foo_client_running' with
 262 `foo_ctx' in this example will be called by the client library after the
 263 client is up and running.  After you receive this callback you may start
 264 using other API functions, such as creating connection to remote server.
 265
 266
 267 <br />&nbsp;<br />&nbsp;<br />
 268 <b>Running the Client</b>
 269
 270 <br />&nbsp;<br />
 271 The client is run by calling silc_client_run.  The function will call
 272 the scheduler from utility library that will be run until the program is
 273 ended.  When silc_client_run returns the application is ended.  Thus,
 274 to run the client, call:
 275
 276 <br />&nbsp;<br />
 277 <tt>&nbsp;&nbsp;silc_client_run(client);</tt>
 278
 279 <br />&nbsp;<br />
 280 Usually application may do some other initializations before calling
 281 this function.  For example before calling this function application
 282 should initialize the user interface.
 283
 284
 285 <br />&nbsp;<br />&nbsp;<br />
 286 <b>Running the Client in GUI application</b>
 287
 288 <br />&nbsp;<br />
 289 Many GUI applications has their own main loop or event loop, which they
 290 would like to use or are forced to use by the underlaying system.  If you
 291 are developing for example GUI application on Unix system, and you are
 292 using GTK+ or QT as GUI library you would probably like to use their own
 293 main loop.  SILC Client can be run under external main loop as well.  The
 294 interface provides a function silc_client_run_one which will run the
 295 client library once, and returns immediately.  During that running it can
 296 process incoming data and send outgoing data, but it is guaranteed that it
 297 will not block the calling process.
 298
 299 <br />&nbsp;<br />
 300 It is suggested that you would call this function as many times in a
 301 second as possible to provide smooth action for the client library.  You
 302 can use an timeout task, or an idle task provided by your GUI library to
 303 accomplish this.  After you have initialized the client library with
 304 silc_client_init, you should register the timeout task or idle task that
 305 will call the silc_client_run_one periodically.
 306
 307 <br />&nbsp;<br />
 308 For Win32 the silc_client_run can be used instead of using the Windows's
 309 own event loop.  However, if you would like to use the silc_client_run_one
 310 also on Win32 system it is possible.
 311
 312
 313 <br />&nbsp;<br />&nbsp;<br />
 314 <b>Running Client in GTK--</b>
 315
 316 <br />&nbsp;<br />
 317 Here is a short example how to run the SILC Client libary under the
 318 Gnome/GTK--'s main loop:
 319
 320 <br />&nbsp;<br />
 321 <tt>
 322 gint YourClass::silc_scheduler()<br />
 323 {<br />
 324 &nbsp;&nbsp;  // Run the SILC client once, and return immediately.  This function<br />
 325 &nbsp;&nbsp;  // is called every 50 milliseconds by the Gnome main loop, to process<br />
 326 &nbsp;&nbsp;  // SILC stuff.  This function will read data, and write data to network,<br />
 327 &nbsp;&nbsp;  // etc.  Makes the client library tick! :)<br />
 328 &nbsp;&nbsp;  silc_client_run_one(silc_client);<br />
 329 &nbsp;&nbsp;  return 1;<br />
 330 }<br />
 331 </tt>
 332
 333 <br />&nbsp;<br />
 334 then, during initialization of the SILC Client call:
 335
 336 <br />&nbsp;<br />
 337 <tt>
 338 // Setup SILC scheduler as timeout task. This will handle the SILC<br />
 339 // client library every 50 milliseconds.  It will actually make the<br />
 340 // SILC client work on background.<br />
 341 Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);<br />
 342 </tt>
 343
 344 <br />&nbsp;<br />
 345 This will call the function silc_scheduler every 50 millisecconds, which
 346 on the otherhand will call silc_client_run_one, which will make the SILC
 347 Client library work on the background of the GUI application.
 348
 349
 350 <br />&nbsp;<br />&nbsp;<br />
 351 <b>Creating Connection to Server</b>
 352
 353 <br />&nbsp;<br />
 354 After your client is up and running you may create connection to remote
 355 SILC server.  It is done simply by calling:
 356
 357 <br />&nbsp;<br />
 358 <tt>&nbsp;&nbsp;silc_client_connect_to_server(client, &params,
 359                                               public_key, private_key,
 360                                               remote_host, remote_port,
 361                                               foo_connected_cb, foo_ctx);</tt>
 362
 363 <br />&nbsp;<br />
 364 The function will create the connection asynchronously to the server, ie.
 365 the function will return before the actual connection is created.  The
 366 `foo_connected_cb' will be called once the connection has been established.
 367 The `params' may be NULL but it may be used to provide additional parameters
 368 to the connecting.  For example it is possible to set the initial nickname
 369 you would like to use into the `params'.
 370
 371
 372 <br />&nbsp;<br />&nbsp;<br />
 373 <b>Debugging</b>
 374
 375 <br />&nbsp;<br />
 376 Being able to debug what you have coded is important when troubles occurs
 377 during coding, and they always do.  SILC supports extensive debugging
 378 capabilities which are also available for client library user.  You should
 379 have compiled the Toolkit with --enable-debug option so that run-time
 380 debugging is enabled.
 381
 382 <br />&nbsp;<br />
 383 Then, to say in your application you would like to use the debugging use
 384 the SILC_DEBUG macro.  Put this macro to your main header file, or
 385 some other file that needs the debugging enabled.  After using this macro
 386 you are able to use the debugging routines provided by the SILC Toolkit.
 387 Note that, the Toolkit library must be compiled with --enable-debug for
 388 this macro to have any effect.
 389
 390 <br />&nbsp;<br />
 391 To turn on the run-time debugging call function silc_log_debug with TRUE
 392 value.  To see packet hexdumps you can call also silc_log_debug_hexdump
 393 with TRUE value.  Hexdumps can create more debug log so not setting it
 394 to TRUE by default is probably best.  To get debug messages out of specific
 395 modules you can set a debug string with silc_log_set_debug_string function.
 396 The function takes regex string as argument, for example:
 397
 398 <br />&nbsp;<br />
 399 <tt>
 400 &nbsp;&nbsp;silc_log_debug(TRUE);<br />
 401 &nbsp;&nbsp;silc_log_set_debug_string("*");<br />
 402 </tt>
 403
 404 <br />&nbsp;<br />
 405 This piece of code turns on the debugging and sets "*" as debug string.  This
 406 means that all debug messages are printed.  To get debugging out of only
 407 for example SILC Client Library the debug string could be "silc_client*".
 408 The debug string matches to function names and filenames so it is possible
 409 to get debugging out of specific files, and specific functions.  Other
 410 examples could be:
 411
 412 <br />&nbsp;<br />
 413 <tt>
 414 &nbsp;&nbsp;silc_log_set_debug_string("silc_client*,*sock*,*ske*");<br />
 415 </tt>
 416
 417 <br />&nbsp;<br />
 418 By default, all debug messages are printed to standard error output (stderr).
 419 If you want to redirect the debug messages somewhere else you can set your
 420 own debug callback with silc_log_set_debug_callbacks function:
 421
 422 <br />&nbsp;<br />
 423 <tt>
 424 &nbsp;&nbsp;silc_log_set_debug_callbacks(my_debug_callback, my_context, my_hexdump_callback, my_context);<br />
 425 </tt>
 426
 427 <br />&nbsp;<br />
 428 See the lib/silcutil/silclog.h for definition of the callbacks.  See the
 429 same file for other logging and debugging information.
 430
 431 <br />&nbsp;<br />
 432 You can also use SILC debugging capabilities in your own application.  To
 433 produce debug messages you can use SILC_LOG_DEBUG and SILC_LOG_HEXDUMP
 434 macros in your application.  The SILC_LOG_DEBUG can print out normal debug
 435 messages with variable argument list, for example:
 436
 437 <br />&nbsp;<br />
 438 <tt>
 439 &nbsp;&nbsp;SILC_LOG_DEBUG(("Start"));<br />
 440 &nbsp;&nbsp;SILC_LOG_DEBUG(("Packet length %d", packet_len));<br />
 441 &nbsp;&nbsp;SILC_LOG_DEBUG(("The remote is %s on %d", sock->ip, sock->port));
 442 </tt>
 443
 444 <br />&nbsp;<br />
 445 The SILC_LOG_HEXDUMP macro can be used dump data which couldn't be printed
 446 out otherwise, for example binary data.
 447
 448 <br />&nbsp;<br />
 449 <tt>
 450 &nbsp;&nbsp;SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);<br />
 451 &nbsp;&nbsp;SILC_LOG_HEXDUMP(("Packet, size=%d", size), packet->data, packet->len);
 452 </tt>
 453
 454 <br />&nbsp;<br />
 455 Note that the variable arguments in SILC_LOG_HEXDUMP are before the second
 456 last parenthesis, and the last two arguments are the data, and its length that
 457 are hexdumped.
 458 <br /><br /><br /><br />
 459     </td></tr>
 460    </table>
 461   </td>
 462
 463   <td bgcolor="#cccccc" background="dot.gif">
 464    <img src="space.gif" width="1" height="1" border="0" alt=""></td>
 465
 466   <td width="180" bgcolor="#f0f0f0">
 467     <img src="space.gif" width="1" height="1" border="0" alt="">
 468     <table width="100%" cellpadding="4" cellspacing="0">
 469     <tr valign="top"><td>
 470 <br />
 471 <font face="Helvetica,Arial,Sans-serif" size="1">
 472 </font>
 473
 474 <br /><br /><br /><br />
 475     </td></tr>
 476     </table>
 477   </td>
 478 </tr>
 479 </table>
 480
 481 <table border="0" cellspacing="0" cellpadding="0" width="100%">
 482 <tr bgcolor="#444444"><td><img src="space.gif" width="1" height="1"border="0" alt="" ></td></tr>
 483 </table>
 484 <table border="0" cellspacing="0" cellpadding="6" width="100%">
 485  <tr valign="top" bgcolor="#dddddd">
 486   <td><small>Copyright &copy; 2001 - 2007 SILC Project<br />
 487     <a href="http://silcnet.org">SILC Project Website</a></small></td>
 488   <td align="right"><small>
 489    <a href="index.html">SILC Toolkit Reference Manual</a><br />
 490    <a href="toolkit_index.html">Index</a></small></td>
 491    </small></td>
 492  </tr>
 493 </table>
 494
 495 </body>
 496 </html>