docs/toolkit/manual/intro_reference.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>Introduction to the Manual</b></big>
 157 <br />&nbsp;<br />
 158
 159 This document is designed to help you understand how the reference manual is
 160 organized, how it can be used efficiently, and how to find the information
 161 you need.
 162
 163 <br />&nbsp;<br />&nbsp;<br />
 164 <b>Target Audience</b>
 165
 166 <br />&nbsp;<br />
 167 This Toolkit reference manual is targeted at application developers who
 168 would like to add SILC support into their application, and to create new
 169 SILC based applications.  It is especially aimed at C and C++ programmers,
 170 who would like to create SILC client applications, either based on command
 171 line interface (CLI) or on graphical user interface (GUI).
 172
 173 <br />&nbsp;<br />&nbsp;<br />
 174 <b>Overview</b>
 175
 176 <br />&nbsp;<br />
 177 The SILC Toolkit Reference Manual has collected the essential information
 178 needed by application developers.  The following guide and reference
 179 information is included in this manual:
 180
 181 <br />&nbsp;<br />
 182 <li>Describing the documentation conventions<br />
 183 <li>Describing the Toolkit design<br />
 184 <li>Describing the SILC Protocol<br />
 185 <li>Describing the programming conventions and idioms<br />
 186 <li>Documenting the set of public APIs available for programmers<br />
 187 <li>Describing the usage of various libraries
 188
 189 <br />&nbsp;<br />
 190 You can download the latest SILC Toolkit from the
 191 <a href="http://silcnet.org">SILC Project Website</a>, which includes the
 192 latest version of the reference manual. The Toolkit package includes the
 193 full sources of the Toolkit, and includes several example applications and
 194 piece of example codes.
 195
 196 <br />&nbsp;<br />&nbsp;<br />
 197 <b>Using the Reference Manual</b>
 198
 199 <br />&nbsp;<br />
 200 The API references are ogranized by libraries.  Each library will include
 201 list of interfaces it provides.  Each of the interface in the library
 202 provides list of public API items.  Each of the item in the list is a hyper
 203 link that opens the detailed page describing the API item.  All API
 204 references are automatically generated from the sources and they have a clear
 205 structural layout.  The references can provide cross links to other
 206 references inside the specific interface or the specific library.
 207
 208 <br />&nbsp;<br />
 209 The list of the library interface items can also include links to guides
 210 that describe the use of a specific library or interface.  These are
 211 intended as HOWTOs for programmers describing all aspects of the library
 212 or interface.  They make the application development easier by also providing
 213 small examples.
 214
 215 <br />&nbsp;<br />
 216 All interfaces provided by the reference manual are public, and it does not
 217 describe any internal or undocumented interfaces.  Since the reference
 218 manual is automatically generated, it is constantly evolving.  It also
 219 may omit some of the interfaces or libraries, that have not yet been
 220 documented in the sources.
 221
 222 <br />&nbsp;<br />&nbsp;<br />
 223 <b>Document Layout</b>
 224
 225 <br />&nbsp;<br />
 226 The document layout provides quick links to libraries, interfaces and
 227 specific API items by including list of links in the left and/or right
 228 side of the page in the web browser.  These links can be used to directly
 229 access the specific library, interface or API item.  The link lists may include
 230 other links to guides, and reference links to outside the reference manual
 231 as well.
 232
 233 <br />&nbsp;<br />&nbsp;<br />
 234 <b>Reference Conventions</b>
 235
 236 <br />&nbsp;<br />
 237 The structural layout of a API item describes the following information
 238 about the item:
 239
 240 <br />&nbsp;<br />
 241 <li>Type.  Types that can appear are Variable, Structure, Function.  A name
 242 that appears without type is constant, usually #define, enum or typedef.
 243 Usually the source code of the constants are appended to the reference.
 244
 245 <br />&nbsp;<br />
 246 <li>Name.  Describes the name of the item.  All functions start with
 247 <b>silc_</b> prefix, macros start with <b>SILC_</b> prefix, and type names
 248 and structures start with <b>Silc</b> prefix.
 249
 250 <br />&nbsp;<br />
 251 <li>Synopsis.  Functions also describe the synopsis of the function.
 252
 253 <br />&nbsp;<br />
 254 <li>Description.  Each of the item is described in detail of what the item
 255 does and how it can be used.
 256
 257 <br />&nbsp;<br />
 258 <li>Notes.  Optionally the item may describe additional notes to the
 259 detailed description.  These usually describe various exeptions or other
 260 important notes that the programmer should be aware of.
 261
 262 <br />&nbsp;<br />
 263 <li>Example.  Optionally the item may include a piece of source code that
 264 give short example of how the item may be used.
 265
 266 <br />&nbsp;<br />
 267 <li>See Also.  Optionally the item may include list of links to other
 268 items, or some other references that relate to the described item.
 269
 270 <br />&nbsp;<br />
 271 <li>Source.  Optionally the item may include the actual source code from
 272 the header file where the documentation was automatically generated.
 273
 274 <br />&nbsp;<br />
 275 Note that some of these informations are optional and not all API items
 276 include all of these informations.
 277
 278 <br />&nbsp;<br />&nbsp;<br />
 279 <b>Reference Example</b>
 280
 281 <br />&nbsp;<br />
 282 Please refer to this link for short example of the API item reference
 283 layout: <a href="silcexample.html">SILC Example API</a>.
 284
 285 <br /><br /><br /><br />
 286     </td></tr>
 287    </table>
 288   </td>
 289
 290   <td bgcolor="#cccccc" background="dot.gif">
 291    <img src="space.gif" width="1" height="1" border="0" alt=""></td>
 292
 293   <td width="180" bgcolor="#f0f0f0">
 294     <img src="space.gif" width="1" height="1" border="0" alt="">
 295     <table width="100%" cellpadding="4" cellspacing="0">
 296     <tr valign="top"><td>
 297 <br />
 298 <font face="Helvetica,Arial,Sans-serif" size="1">
 299 </font>
 300
 301 <br /><br /><br /><br />
 302     </td></tr>
 303     </table>
 304   </td>
 305 </tr>
 306 </table>
 307
 308 <table border="0" cellspacing="0" cellpadding="0" width="100%">
 309 <tr bgcolor="#444444"><td><img src="space.gif" width="1" height="1"border="0" alt="" ></td></tr>
 310 </table>
 311 <table border="0" cellspacing="0" cellpadding="6" width="100%">
 312  <tr valign="top" bgcolor="#dddddd">
 313   <td><small>Copyright &copy; 2001 - 2007 SILC Project<br />
 314     <a href="http://silcnet.org">SILC Project Website</a></small></td>
 315   <td align="right"><small>
 316    <a href="index.html">SILC Toolkit Reference Manual</a><br />
 317    <a href="toolkit_index.html">Index</a></small></td>
 318    </small></td>
 319  </tr>
 320 </table>
 321
 322 </body>
 323 </html>