docs/toolkit/manual/porting.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>Porting from Toolkit 1.0 to 1.1</b></big>
 157
 158 <br />&nbsp;<br />
 159 This documents describes the differences between the SILC Toolkit 1.0 and
 160 1.1 and should help application programmers to port their SILC applications
 161 to the new Toolkit version.
 162
 163 <br />&nbsp;<br />
 164 <li><a href="#general">General</a><br />
 165 <li><a href="#platform">Platform changes</a>
 166 <li><a href="#client">Client library</a><br />
 167 <li><a href="#util">Utility library</a><br />
 168 <li><a href="#apputil">Application utility library</a>
 169 <li><a href="#crypto">Crypto library</a>
 170 <li><a href="#skr">Key Repository library</a>
 171 <li><a href="#vcard">VCard library</a>
 172 <li><a href="#http">HTTP library</a>
 173 <li><a href="#asn1">ASN.1 library</a>
 174
 175 <br />&nbsp;<br />
 176 <h3><a name="general"></a>General changes</h3>
 177
 178 The main SILC Toolkit header file has changed its name from silcincludes.h
 179 to silc.h.  The first task in porting from 1.0 to 1.1 is to change these
 180 filenames in your source tree.
 181
 182
 183 <br />&nbsp;<br />
 184 <h3><a name="platform"></a>Platform changes</h3>
 185
 186 The Windows support has been made better by improving the SILC scheduler
 187 and network routines.  Calling silc_net_win32_init and silc_net_win32_uninit
 188 is not needed anymore.  The network routines on Windows are enabled
 189 automatically.
 190
 191
 192 <br />&nbsp;<br />
 193 <h3><a name="client"></a>Client library, lib/silcclient/</h3>
 194
 195 The client library in Toolkit 1.1 has been partially rewritten.  It was
 196 rewritten to work out some technical issues and to increase performance
 197 and decrease memory consumption.  The client library API has also faced
 198 some changes, altough most of it has remained the same.  Most major change
 199 in the client library is that is now fully supports multiple threads.  In
 200 the past making multithreaded SILC client application was always a bit hard
 201 but with Toolkit 1.1 it should be relatively straightforward.
 202
 203 <h4>SilcClientOperations structure</h4>
 204
 205 The SilcClientOperations structure has changed significantly.  It no longer
 206 has `connected', `disconnected' and `failure' function pointers.  Instead a
 207 new SilcClientConnectCallback has been defined that is given as argument to
 208 functions like silc_client_connect_to_server, silc_client_connect_to_client
 209 and silc_client_key_exchange (last two being entirely new functions in the
 210 API).  That callback is called when connection is established and when it
 211 is disconnected, or if a protocol failure occurred during connecting.  That
 212 callback also delivers a detailed error information when error occurs.  New
 213 connection related status types in SilcClientConnectionStatus has also been
 214 added, see the API for the details.
 215
 216 <br />&nbsp;<br />
 217 Also the `detach' client operation function pointer has been removed.  Instead
 218 the detachment data is now simply delivered in the SILC_COMMAND_DETACH
 219 command reply.
 220
 221 <br />&nbsp;<br />
 222 Some of the remaining client operation function pointers have changed a bit.
 223 Most major change is the `command' operation now having the arguments that
 224 user gave on the user interface sent back to application.  The `command_reply'
 225 does not anymore include the SilcCommandPayload as an argument.  Also the
 226 variable argument lis is now delivered as va_list.  Also the boolean
 227 success indicator is removed and SilcStatus error argument instead is telling
 228 the exact error if the SilcStatus status is other than SILC_STATUS_OK.
 229
 230 <br />&nbsp;<br />
 231 The `get_auth_method' client operation now includes the authentication method
 232 that has been resolved from the remote server.  The application no longer
 233 needs to resolve it and the function silc_client_request_authentication_method
 234 has been removed from the API.
 235
 236 <br />&nbsp;<br />
 237 The `verify_public_key' client operation now include the SilcPublicKey pointer
 238 instead of the public key in raw encoded form.  Also the connection type
 239 argument has changed to SilcConnectionType.
 240
 241 <br />&nbsp;<br />
 242 The `key_agreement' client operation now includes a new protocol argument
 243 which tells whether the key agremeent is supposed to be done on TCP or on
 244 UDP transport.  The new Toolkit 1.1 supports both.
 245
 246 <h4>SilcClient</h4>
 247
 248 The SilcClientParams includes new fields and some fields have been removed
 249 or moved to other places.  All connection timeout related fields have been
 250 moved to SilcClientConnectionParams.  The nickname_parse callback pointer has
 251 also been removed from SilcClientParams.  The Toolkit 1.1 now automatically
 252 parses formatted nicknames.
 253
 254 <br />&nbsp;<br />
 255 The new field boolean `threads' can be used to tell whether the new SilcClient
 256 is to use multiple threads or not. If threads support has been compiled in
 257 and that field is set to TRUE then the client library will create new thread
 258 for each new connection to a remote host.  If you are going to use several
 259 connections or some of the connections are high throughput connections (like
 260 multimedia connections) then using threads is recommended for performance.
 261 Note that your application needs to be multithreaded and, if necessary to,
 262 perform concurrencly control in client operation callbacks which may be
 263 called from multiple threads at the same time for different connections.
 264 However, it is always guaranteed that for one connection the client
 265 operations cannot be called from multiple threads.  The multithreads
 266 support in Toolkit 1.1 client library means that each new connection and
 267 everything related to that connection is handled in own dedicated thread.
 268
 269 <br />&nbsp;<br />
 270 The silc_client_init function now takes several new arguments.  It now takes
 271 the username, hostname and realname as argument that used to be required
 272 by the application to update directly to SilcClient pointer.  This is not
 273 longer required.  Also the nickname is no longer required to be put to
 274 SilcClient context as it has been made SilcClientConnection specific.
 275 The function also takes a SilcClientRunning callback as argument which will
 276 be called when the client library is running.  Only after the callback is
 277 delivered may the application start using other client library API functions.
 278 For example, connecting to a server will fail if it is performed before
 279 the SilcClientRunning callback is called.  The callback is called after the
 280 silc_client_run or silc_client_run_one has been called.
 281
 282 <br />&nbsp;<br />
 283 The silc_client_stop function takes new SilcClientStopped callback as
 284 argument, and it will be called after the client library has been completely
 285 stopped.  The application should not quit before that is called in order
 286 to clean up all resources allocation by the client library.
 287
 288 <br />&nbsp;<br />
 289 It is also not required to put the public key pair (SilcPublicKey and
 290 SilcPrivateKey) into SilcClient.  They have been made connection specific so
 291 you simply give them as argument when you create new connection.  This way
 292 it is now possible to use different key pairs with different connections,
 293 one that was not possible in Toolkit 1.0 without creating new SilcClient
 294 instance for each new connection.
 295
 296 <h4>SilcClientConnection</h4>
 297
 298 The SilcClientConnection represents connection to a remote host.  In new
 299 Toolkit 1.1 this structure now includes all connection related data and
 300 no connection related data is anymore included in SilcClient.  For this
 301 reason it is no longer necessary to create multiple SilcClient instances
 302 just because you want to create multiple connections.
 303
 304 <br />&nbsp;<br />
 305 The SilcClientConnectionParams structure has many new fields.  This structure
 306 is given as argument to any function that is able to create a new connection
 307 or to create a network listener or to create a new SILC sessions.  See the
 308 API documentation for all the details but the following one field of special
 309 relevance when creating new SILC server connections.  The nickname field is
 310 now included in this structure and it is the nickname user would like to
 311 initially use in the SILC network.
 312
 313 <br />&nbsp;<br />
 314 The functions silc_client_connect_to_server, silc_client_connect_to_client
 315 and silc_client_key_exchange can all be used to create new SILC session with
 316 a remote.  To connect SILC server use silc_client_connect_to_server.  You
 317 now give the SilcClientConnectionParams as argument which includes the
 318 nicknameuser wants to use, you now can give the public key pair as argument that is
 319 to be used in the connecting.  The new SilcClientConnectCallback will be
 320 called once the connection has been established and it delivers the
 321 SilcClientConection context to the application.  It will be later called
 322 again to indicated disconnection from the remote host.  These functions
 323 now return SilcAsyncOperation context which can be used to cancel the
 324 connecting, if necessary.  In the past canceling connection was not possible.
 325
 326 <br />&nbsp;<br />
 327 <pre>
 328 SilcAsyncOperation op;
 329 SilcClientConnectionParams params;
 330
 331 memset(&params, 0, sizeof(params));
 332
 333 /* Set nickname user wants to use */
 334 params.nickname = nickname;
 335
 336 /* Set perfect forward secery for key exchange */
 337 params.pfs = TRUE;
 338
 339 /* Example of creating, and then canceling a connection */
 340 op = silc_client_connect_to_server(client, params, public_key, private_key,
 341                                    remote_host, remote_port, connection_cb,
 342                                    app_context);
 343 if (!op) {
 344   fatal("Connecting failed immediately"));
 345   exit(1);
 346 }
 347
 348 ...
 349
 350 /* Cancel connecting.  After canceling the `connection_cb' will not be
 351    called. */
 352 silc_async_abort(op);
 353 </pre>
 354
 355 <br />&nbsp;<br />
 356 The old function silc_client_start_key_exchange has been replaced with
 357 silc_client_key_exchange function.  Semantically it is equivalent to
 358 silc_client_connect_to_server but it does not create new connection.  Instead,
 359 it accepts SilcStream as argument which is already established connection
 360 to a remote host and it merely starts the key exchange.  See an example
 361 in the API documentation on how to use the silc_client_key_exchange, if
 362 your application wishes itself to create connection instead of using the
 363 client library to do it.
 364
 365 The functions silc_client_add_connection, silc_client_del_connection and
 366 silc_client_del_socket has been removed.  They are no longer needed.
 367
 368 <h4>Entries</h4>
 369
 370 Just like in Toolkit 1.0 we now have SilcClientEntry to represent user,
 371 SilcChannelEntry to represent channel and SilcServerEntry to represent
 372 server.  In the past these structures and all API functions that dealt
 373 with them were in <a href="silcclient.html">silcclient.h</a> file.  They
 374 are now in <a href="silcclient_entry.html">silcclient_entry.h</a> in
 375 Toolkit 1.1.
 376
 377 <br />&nbsp;<br />
 378 As an general convention each of these new entries now are reference
 379 counted and they have locks when using them in multithreaded application.
 380 Even in one-threaded application the application must always acquire a
 381 reference of the entry if it wishes to save the entry pointer in the
 382 application.  The reference must be released once the entry pointer is
 383 not needed anymore.  This ensures that the library cannot free the entry
 384 pointer underneath the application.  An own API for taking and releasing
 385 the reference is in Toolkit 1.1.
 386
 387 <br />&nbsp;<br />
 388 <pre>
 389 /* Take reference of the client entry I save to my own context. */
 390 my_context->client_entry = silc_client_ref_client(client, conn, client_entry);
 391 </pre>
 392
 393 <br />&nbsp;<br />
 394 If multiple threads are used and application wants to access the entry it
 395 must always first lock the entry.  After application has read the information
 396 it needs from the entry it must release the entry lock.  The entry lock
 397 should be held only for short periods of time and failure to release the
 398 lock will result into deadlock.   An own API for taking and releasing the
 399 entry lock is in Toolkit 1.1.  If you application is not multithreaded
 400 you do not need to use the entry locking.
 401
 402 <br />&nbsp;<br />
 403 <pre>
 404 /* Read data from client entry in multithreaded environment */
 405 silc_client_lock_client(client_entry);
 406 fprintf(stdout, "%s\n", client_entry->nickname);
 407 fprintf(stdout, "%s\n", silc_id_render(SILC_ID_CLIENT, &client_entry->id));
 408 silc_client_unlock_client(client_entry);
 409 </pre>
 410
 411 <br />&nbsp;<br />
 412 From the entries all unnecessary information for application has been either
 413 removed or moved to internal structure that is not accessible by the
 414 application.  As a result the entry structures are much smaller and cleaner.
 415
 416 <br />&nbsp;<br />
 417 The SilcClientEntry now includes nickname_normalized field and it is the
 418 normalized version of the user's nickname, in case application needs it.
 419 It is also guaranteed in Toolkit 1.1 that the nickname inside SilcCientEntry
 420 is always valid nickname.
 421
 422 <br />&nbsp;<br />
 423 The SilcChannelEntry now includes new channel_pubkeys list, which includes
 424 the channel public keys if they have added to the channel.  This information
 425 was not present in Toolkit 1.0.
 426
 427 <br />&nbsp;<br />
 428 The SilcServerEntry now includes new field public_key, which is the server's
 429 public key if we have resolved it.  This information was not present in
 430 Toolkit 1.0.
 431
 432 <br />&nbsp;<br />
 433 In Toolkit 1.1 it is now easier to search and resolve entries.  As a new
 434 feature it now also possible to search and resolve server entries from the
 435 SILC network.  See the API documentation for all the details on searching
 436 entries from the client library cache and from the SILC network.
 437
 438 <h4>Sending/Receiving messages</h4>
 439
 440 Sending messages has not much changed from the Toolkit 1.1.  In Toolkit 1.1
 441 the message may now safely be sent in from multiple threads for same client
 442 or for same channel.  In case the message are digitally signed the hash
 443 function used in the signature computation must now be given as argument.
 444 If this is done in multiple threads, each thread must use different SilcHash
 445 context because SilcHash does not support multiple threads.  Simply allocate
 446 new SilcHash for each thread where you send digitally signed messages.
 447
 448 <br />&nbsp;<br />
 449 Receiving message is same as in Toolkit 1.0.  You receive private_message
 450 or channel_message client operation.  It is always guaranteed that even in
 451 multithreaded application the messages are received in one thread.  You need
 452 concurrency control in your application only if you access shared data in
 453 your client operation callbacks.
 454
 455 <br />&nbsp;<br />
 456 In Toolkit 1.1 as a new feature it is also possible to wait for incoming
 457 private messages in a thread.  New function silc_client_private_message_wait
 458 can be used to block the calling process or thread until private message
 459 for the specified client is received.
 460
 461 <h4>Calling and sending commands</h4>
 462
 463 Just like in Toolkit 1.0 in Toolkit 1.1 you can call command implemented
 464 inside the client library with silc_client_command_call.  The command_reply
 465 client operation will be called once the command reply has arrived.
 466
 467 <br />&nbsp;<br />
 468 As a major change in semantics of sending commands with the
 469 silc_client_command_send function is the way the command reply is handled
 470 in Toolkit 1.1.  In the new Toolkit the command_reply client operation will
 471 not be anymore called for commands that has been sent with
 472 silc_client_command_send.  The command_reply client operation is called only
 473 when silc_client_command_call function is used.  With silc_client_command_send
 474 you can give the command reply callback, SilcClientCommandReply, as argument,
 475 and it will be called for each command reply that is received from the
 476 server.
 477
 478 <br />&nbsp;<br />
 479 Just likein 1.0 in 1.1 it is also possible to attach to pending commands
 480 by using silc_client_command_pending.  As a difference to 1.0 the command
 481 identifier is not anymore available to application from the
 482 SilcClientConnection context.  Instead the silc_client_command_call and
 483 silc_client_command_send return the command identifier, and application needs
 484 to save it in order to be able to attach to it at later time.  However,
 485 this feature is not expected to be very important for application
 486 programmers as the new silc_client_command_send already includes the
 487 command reply callback.
 488
 489 <br />&nbsp;<br />
 490 <pre>
 491 Comparison between 1.0 and 1.1
 492
 493 Toolkit 1.0:
 494 /* Send ping command.  The reply will be in the attached command reply
 495    and in the command_reply client operation. */
 496 silc_client_command_send(client, conn, SILC_COMMAND_PING, ++conn->cmd_ident,
 497                          1, 1, server_id, server_id_len);
 498 silc_client_command_pending(conn, SILC_COMMAND_PING, conn->cmd_ident,
 499                             ping_command_reply, context);
 500
 501 Toolkit 1.1:
 502 /* Send ping command.  The reply will be ping_command_reply function. */
 503 silc_client_command_send(client, conn, SILC_COMMAND_PING,
 504                          ping_command_reply, context,
 505                          1, 1, server_id, server_id_len);
 506
 507 </pre>
 508
 509 <h4>Notify arguments</h4>
 510
 511 In Toolkit 1.1 the following notify arguments have had changes.  See
 512 the <a href="notifyargs.html">Notify Arguments</a> for details.  You should
 513 go through your application and change the handling of the following notify
 514 messages for Toolkit 1.1.
 515
 516 <br />&nbsp;<br />
 517 SILC_NOTIFY_TYPE_NICK_CHANGE<br />
 518 SILC_NOTIFY_TYPE_CMODE_CHANGE<br />
 519 SILC_NOTIFY_TYPE_SIGNOFF<br />
 520 SILC_NOTIFY_TYPE_SERVER_SIGNOFF<br />
 521
 522 <br />&nbsp;<br />
 523 The basic changes in notify arguments from Toolkit 1.0 is that the
 524 Toolkit 1.1 parses various lists and other raw data for the application as
 525 opposed to sending them in the raw format.  This makes programming easier.
 526
 527 <h4>Command reply arguments</h4>
 528
 529 In Toolkit 1.1 the following command reply arguments have had changes.  See
 530 the <a href="command_reply_args.html">Command Reply Arguments</a> for
 531 details.  You should go through your application and change the handling
 532 of the following command replies for Toolkit 1.1.
 533
 534 <br />&nbsp;<br />
 535 SILC_COMMAND_WHOIS<br />
 536 SILC_COMMAND_INVITE<br />
 537 SILC_COMMAND_STATS<br />
 538 SILC_COMMAND_JOIN<br />
 539 SILC_COMMAND_CMODE<br />
 540 SILC_COMMAND_BAN<br />
 541 SILC_COMMAND_DETACH<br />
 542 SILC_COMMAND_USERS<br />
 543
 544 <br />&nbsp;<br />
 545 The basic changes in command reply arguments from Toolkit 1.0 is that the
 546 Toolkit 1.1 parses various lists and other raw data for the application as
 547 opposed to sending them in the raw format..  This makes programming easier.
 548
 549 <h4>Other changes in client library</h4>
 550
 551 There are many other smaller changes in Toolkit 1.1 that require you to
 552 change your application when porting from Toolkit 1.0.  We are not listing
 553 all of them here but briefly mention some API changes.
 554
 555 <br />&nbsp;<br />
 556 Listing channel private keys now return SilcDList instead of an array.
 557
 558 <br />&nbsp;<br />
 559 The key agreement API has changed a little bit and is now more cleaner and
 560 supports all the features that are needed in full featured key agreement.
 561 The silc_client_peform_key_agreement_fd has been replaced by
 562 silc_client_perform_key_agreement_stream.
 563
 564 <br />&nbsp;<br />
 565 The private message key API has slight changes also.  It is no longer
 566 necessary for the caller to specify whether the private message key is for
 567 responder or initiator use.
 568
 569 <br />&nbsp;<br />
 570 The file transfer API has changed a little bit and is now more cleaner and
 571 supports all the features that are needed in full featured file transfer.
 572 It is now easier to send files when you are behind NAT when you can
 573 specifically define the IPs that are used in both file sending and
 574 receiving.
 575
 576 <br />&nbsp;<br />
 577 As a new function silc_client_nickname_format can now be used to format
 578 the nickname of a client entry.  The client library automatically formats
 579 the nicknames but in some cases application might like to change the
 580 nickname of a certain client entry.
 581
 582
 583 <br />&nbsp;<br />
 584 <h3><a name="util"></a>Utility library, lib/silcutil/</h3>
 585
 586 The Utility library (runtime library) has had several changes and has several
 587 new interfaces.  Some interfaces has also been removed or moved to some
 588 other library.  Removed interfaces rae: silcprotocol.h and silcsockconn.h.
 589 Moved interfaces are: <a href="silcapputil.html">silcapputil.h</a> and
 590 <a href="silcvcard.html">silcvcard.h</a>.
 591
 592 <h4>SILC Async Operation Interface</h4>
 593
 594 A new asynchronous operation API (<a href="silcasync.html">silcasync.h</a>)
 595 has been added.  It can be used to control asynchronous operations, like
 596 to cancel them.  Many asynchronous routines in SILC Toolkit now return
 597 SilcAsyncOperation context so that the operation can be controlled by the
 598 caller.  It especiallly provides a generic way to cancel asynchronous
 599 operations which can be difficult.
 600
 601 <h4>SILC Atomic Operations Interface</h4>
 602
 603 A new atomic operations API (<a href="silcatomic.html">silcatomic.h</a>)
 604 has been added.  It provides routines to perform various operations on
 605 integeres and pointers atomically.
 606
 607 <h4>SILC Data Stack Interface</h4>
 608
 609 A new data stack (memory pool system) API
 610 (<a href="silcstack.html">silcstack.h</a>) has been added.
 611 It provides a fast memory allocation system.  Many routines in the SILC Toolkit
 612 are SilcStack aware thus enabling them to use the SilcStack as their source
 613 for memory allocation.  All routines that are SilcStack aware automatically
 614 revert back to normal memory allocation if SilcStack is not given as
 615 argument.  See silcstack.h for list of utility routines that support SilcStack
 616 by default.
 617
 618 <h4>SILC Condition Variable Interface</h4>
 619
 620 A new condition variable API (<a href="silccond.html">silccond.h</a>)
 621 has been added.  It provides condition variables for multithreaded
 622 applications.
 623
 624 <h4>SILC Stream Interface</h4>
 625
 626 A new abstract stream API (<a href="silcstream.html">silcstream.h</a>)
 627 has been added.  The SilcStream
 628 provides an abstract way of representing different kinds of streams.  The
 629 API provides functions that can be used to read, write, control and destroy
 630 streams.  The API is not used to create streams but separate interfaces
 631 exist for streams that use the SilcStream abstraction.  For example,
 632 socket stream and file descriptor stream exist.
 633
 634 <h4>SILC FD Stream Interface</h4>
 635
 636 A new file descriptor stream API
 637 (<a href="silcfdstream.html">silcfdstream.h</a>) has been added.  It
 638 provides a blocking and non-blocking file descriptor stream through the
 639 SilcStream abstraction.
 640
 641 <h4>SILC Socket Stream Interface</h4>
 642
 643 A new socket stream API
 644 (<a href="silcsocketstream.html">silcsocketstream.h</a>) has been added.
 645 It provides a blocking and non-blocking socket stream through the SilcStream
 646 abstraction.
 647
 648 <h4>SILC FSM Interface</h4>
 649
 650 A new Finite State Machine API
 651 (<a href="silcfsm.html">silcfsm.h</a>) has been added.  It provides
 652 an FSM that can be used to implement all kinds of machines and protocols.
 653 The machine also supports threads, and threads that are actually executed
 654 in real system threads.  The SILC FSM API also supports asynchronous
 655 events.
 656
 657 <h4>SILC Time Interface</h4>
 658
 659 A new SILC Time API
 660 (<a href="silctime.html">silctime.h</a>) has been added.  It provides utility
 661 functions to retrieve and represent time in different ways.  It supports
 662 Universal and Generalized time string creation and parsing and adds a new
 663 SilcTime structure to represent time.
 664
 665 <h4>SILC Snprintf Interface</h4>
 666
 667 A new snprintf API
 668 (<a href="silcsnprintf.html">silcsnprintf.h</a>) has been added.  It
 669 provides snprintf and other string formatting routines.
 670
 671 <h4>SILC Mutex Interface changes</h4>
 672
 673 The SILC Mutex API (<a href="silcmutex.html">silcmutex.h</a>)
 674 has several changes.  A support for read/write locks has been added
 675 (SilcRwLock).  Also silc_mutex_assert_locked function is added.
 676
 677 <h4>SILC Network Interface changes</h4>
 678
 679 The SILC Network API
 680 (<a href="silcnet.html">silcnet.h</a>) has several changes.  The API is almost
 681 entirely rewritten and most of the old functions have been removed.  The
 682 API has now both TCP and UDP support, and as previously supports IPv4
 683 and IPv6.  New functions are silc_net_tcp_create_listener,
 684 silc_net_listener_get_port, silc_net_close_listener, silc_net_tcp_connnect,
 685 silc_net_udp_connect, silc_net_udp_receive, silc_net_udp_send.
 686
 687 <h4>SILC Scheduler Interface changes</h4>
 688
 689 The SILC Schedule API
 690 (<a href="silcschedule.html">silcschedule.h</a>) has several changes.  The
 691 scheduler has been entirely rewritten but most of the API remains the same.
 692 The SILC_TASK_GENERIC and SILC_TASK_CALLBACK_GLOCAL have been removed.
 693 The way signal are dispatched has been changed.  The SILC Schedule is now
 694 able to itself dispatch all signals.  New functions are
 695 silc_schedule_task_add_fd, silc_schedule_task_add_timeout,
 696 silc_schedule_task_add_signal, silc_task_del_by_all,
 697 silc_schedule_get_fd_events.  The functions silc_schedule_signal_register,
 698 silc_schedule_signal_unregister and silc_schedule_signal_call have been
 699 removed.
 700
 701 <h4>SILC Types Interface changes</h4>
 702
 703 The SILC Type API (<a href="silctypes.html">silctypes.h</a>) has several
 704 changes.  The bool type is replaced with SilcBool.  Sockets are now
 705 represented by SilcSocket.
 706
 707 <h4>SILC String util Interface changes</h4>
 708
 709 The SILC string utility API
 710 (<a href="silcstrutil.html">silcstrutil.h</a>) has changes.  The PEM encoding
 711 and decoding routines has been renamed, silc_base64_encode,
 712 silc_base64_encode_file and silc_base64_decode.  The silc_mime_parse has
 713 been removed.  A new silc_string_split function has been added.
 714
 715 <h4>SILC Utility Interface changes</h4>
 716
 717
 718 <h4>SILC File Util Interface changes</h4>
 719
 720 The SILC file utility API (<a href="silcfileutil.html">silcfileutil.h</a>)
 721 has changes.  A new function silc_file_set_nonblock has been added.
 722
 723 <h4>SILC List and Dynamic List Interface changes</h4>
 724
 725 The SILC List (<a href="silclist.html">silclist.h</a>) and SILC Dynamic List
 726 (silcdlist.h) APIs have changes. New functions silc_list_insert and
 727 silc_dlist_insert have been added.
 728
 729 <h4>SILC Buffer Interface changes</h4>
 730
 731 The SILC Buffer API (<a href="silcbuffer.html">silcbuffer.h</a>) has several
 732 changes.  The SilcBuffer
 733 structure no longer contain the buffer length and true length fields
 734 but silc_buffer_len() and silc_buffr_truelen() macros are available
 735 instead.  Also silc_buffer_data(), silc_buffer_datalen(), silc_buffer_purge(),
 736 silc_buffer_reset(), silc_buffer_start(), silc_buffer_end() and
 737 silc_buffer_enlarge() has been added.  The API also supports SilcStack.
 738
 739 <h4>SILC Buffer Formatting Interface changes</h4>
 740
 741 The SILC Buffer Formatting API
 742 (<a href="silcbuffmt.html">silcbuffmt.h</a>) has several changes.  The
 743 silc_buffer_format now automatically allocates memory to the destination
 744 buffer if it does not have space.  Also new the following new formatters
 745 have been added: SILC_STR_DATA (replaces SILC_STR_UI_XNSTRING),
 746 SILC_STR_BUFFER, SILC_STR_FUNC, SILC_STF_OFFSET and SILC_STR_ADVANCE.
 747 The API also supports SilcStack.
 748
 749 <h4>SILC Memory Interface changes</h4>
 750
 751 The memory allocation API (<a href="silcmemory.html">silcmemory.h</a>) has
 752 several changes.  It supports now SilcStack as memory source.  Also all
 753 memory allocation routines can now fail and return NULL as opposed to fatally
 754 failing when memory allocation fails.
 755
 756 <br />&nbsp;<br />
 757 <h3><a name="apputil"></a>SILC Application Utility library, lib/silcapputil/</h3>
 758
 759 A new SILC Application Utility library has been added.  It provides
 760 various application specific utility libraries that are not part of
 761 the runtime library (lib/silcutil/).  The interfaces in the Application
 762 utility library were in other libraries in Toolkit 1.0 and the library
 763 does not contain any entirely new interfaces.
 764
 765 <h4>SILC Application Utility Interface</h4>
 766
 767 The <a href="silcapputil.html">silcapputil.h</a> contains various application
 768 utility functions.  It
 769 existed in Toolkit 1.0 but some of the APIs has been changed.  The
 770 silc_create_key_pair, silc_load_key_pair and silc_show_public_key APIs
 771 has changed.  A new silc_show_public_key_file has been added.  Functions
 772 silc_identifier_check, silc_identifier_verify, silc_channel_name_check,
 773 silc_channel_name_verify, silc_get_mode_list silc_get_status_message,
 774 silc_get_packet_name, silc_get_command_name, silc_parse_version_string,
 775 silc_version_to_num, silc_client_chmode, silc_client_chumode,
 776 silc_client_chumode_char and silc_id_render has been moved from other
 777 libraries into this interface in Toolkit 1.1.
 778
 779 <h4>SILC ID Cache Interface</h4>
 780
 781 The ID Cache interface (<a href="silcidcache.html">silcidcache.h</a>) has
 782 been moved from lib/silccore into lib/silcapputil/.
 783
 784 <br />&nbsp;<br />
 785 <h3><a name="skr"></a>SILC Key Repository library, lib/silcskr/</h3>
 786
 787 A new SILC Key Repository library has been added.  The library provides
 788 a SILC Key Repository API (<a href="silcskr.html">silcskr.h</a>) which provides
 789 a repository for storing and retrieving public keys.
 790
 791 <br />&nbsp;<br />
 792 <h3><a name="vcard"></a>SILC VCard library, lib/silcvcard/</h3>
 793
 794 A new SILC VCard library has been added.  The SILC VCard API has been
 795 moved from utility library to own library in lib/silcvcard/.
 796
 797 <br />&nbsp;<br />
 798 <h3><a name="http"></a>SILC HTTP library, lib/silchttp/</h3>
 799
 800 A new SILC HTTP library has been added.  The library includes SILC HTTP
 801 Server Interface and SILC HTTP PHP Translator Interface.
 802
 803 <h4>SILC HTTP Server Interface</h4>
 804
 805 The SILC HTTP Server API (<a href="silchttpserver.html">silchttpservder.h</a>)
 806 provides a simple HTTP server implementation for applications that want to
 807 integrate a small HTTP server.
 808
 809 <h4>SILC HTTP PHP Translator Interface</h4>
 810
 811 The SILC HTTP PHP Translator API (<a href="silchttpphp.html">silchttpphp.h</a>)
 812  provides PHP translates PHP code into HTML.  It can be used to serve PHP
 813 pages in HTTP server.
 814
 815 <br />&nbsp;<br />
 816 <h3><a name="asn1"></a>SILC ASN.1 library, lib/silcasn1/</h3>
 817
 818 A new Abstract Syntax Notation One (ASN.1) library has been added.  The
 819 library provides SILC ASN.1 encoder and decoder interface and SILC BER
 820 encoder and decoder interface.
 821
 822 <h4>SILC ASN.1 Interface</h4>
 823
 824 The SILC ASN.1 API (<a href="silcasn1.html">silcasn1.h</a>) provides ASN.1
 825 encoder and decoder.  The interface provides efficient encoder and decoder
 826 and is support SilcStack as memory source.  The interface is simple and it
 827 supports almost all ASN.1 features.
 828
 829 <h4>SILC BER Interface</h4>
 830
 831 The SILC BER API (<a href="silcber.html">silcber.h</a>) provides BER/DER
 832 encoder and decoder.  It is integral part of the ASN.1 library and the ASN.1
 833 encoder and decoder.
 834 <br /><br /><br /><br />
 835     </td></tr>
 836    </table>
 837   </td>
 838
 839   <td bgcolor="#cccccc" background="dot.gif">
 840    <img src="space.gif" width="1" height="1" border="0" alt=""></td>
 841
 842   <td width="180" bgcolor="#f0f0f0">
 843     <img src="space.gif" width="1" height="1" border="0" alt="">
 844     <table width="100%" cellpadding="4" cellspacing="0">
 845     <tr valign="top"><td>
 846 <br />
 847 <font face="Helvetica,Arial,Sans-serif" size="1">
 848 </font>
 849
 850 <br /><br /><br /><br />
 851     </td></tr>
 852     </table>
 853   </td>
 854 </tr>
 855 </table>
 856
 857 <table border="0" cellspacing="0" cellpadding="0" width="100%">
 858 <tr bgcolor="#444444"><td><img src="space.gif" width="1" height="1"border="0" alt="" ></td></tr>
 859 </table>
 860 <table border="0" cellspacing="0" cellpadding="6" width="100%">
 861  <tr valign="top" bgcolor="#dddddd">
 862   <td><small>Copyright &copy; 2001 - 2007 SILC Project<br />
 863     <a href="http://silcnet.org">SILC Project Website</a></small></td>
 864   <td align="right"><small>
 865    <a href="index.html">SILC Toolkit Reference Manual</a><br />
 866    <a href="toolkit_index.html">Index</a></small></td>
 867    </small></td>
 868  </tr>
 869 </table>
 870
 871 </body>
 872 </html>