doc/development/lib_reference.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!--
   4 #
   5 #  SILC Library Reference Manual SGML source code
   6 #
   7 #  Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   8 #
   9 #  Copyright (C) 2000 Pekka Riikonen
  10 #
  11 #  This program is free software; you can redistribute it and/or modify
  12 #  it under the terms of the GNU General Public License as published by
  13 #  the Free Software Foundation; either version 2 of the License, or
  14 #  (at your option) any later version.
  15 #
  16 #  This program is distributed in the hope that it will be useful,
  17 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 #  GNU General Public License for more details.
  20 #
  21
  22 -->
  23
  24 <article>
  25
  26 <!-- Title information -->
  27
  28 <title>SILC Library Reference Manual
  29 <author>Pekka Riikonen <tt>priikone@poseidon.pspt.fi</tt>
  30 <date>Last updated: $Id$
  31 <abstract>
  32 This document describes the SILC Library functions and programming
  33 application interfaces.  The SILC Library is pretty much generic purpose
  34 library in many ways.  It includes routines for basic things like buffer
  35 management, network connection management, scheduling and task management.
  36 However, it includes a lot routines that are related only to SILC.  This
  37 document does not describe the implementation of the SILC client and SILC
  38 server.  They and their API's will be described in separate documents.
  39 </abstract>
  40
  41 <!-- Table of contents -->
  42 <toc>
  43
  44 <!-- Begin the document -->
  45
  46 <sect>Overview
  47
  48 <p>
  49 This document describes the SILC Library functions and programming
  50 application interfaces.  The SILC Library is pretty much generic purpose
  51 library in many ways.  It includes routines for basic things like buffer
  52 management, network connection management, scheduling and task management.
  53 However, it includes a lot routines that are related only to SILC.  This
  54 document does not describe the implementation of the SILC client and SILC
  55 server.  They and their API's will be described in separate documents.
  56
  57 <sect><tt>lib/</tt> directory
  58
  59 <p>
  60 This section describes the libraries implemented in the SILC Library
  61 as a whole.  The SILC package and the SILC library includes other libraries
  62 that are out of scope of this document.  Those libraries are mentioned
  63 separately and reference to the corresponding library manual is given.
  64
  65 <sect1><tt>silccore</tt>
  66
  67 <p>
  68 This directory includes the core library of the SILC.  It includes all the
  69 basic and common routines used by SILC client and server applications.
  70 This includes buffer management, file management, network connection
  71 mangement, task management and scheduling.
  72
  73 <sect1><tt>silccrypt</tt>
  74
  75 <p>
  76 This directory includes the crypto library.  It includes implementations
  77 of various cryptographic algrotihms, hash functions and public key
  78 cryptosystems.  It also includes cryptographically strong random number
  79 generator.  Most of the implementations of the algorithms are copied
  80 from other crypto libraries.
  81
  82 <sect1><tt>silcmath</tt>
  83
  84 <p>
  85 This directory includes math library.  It includes GNU MP library and
  86 some other routines.  The math library is tightly related to the crypto
  87 library and specificly public key cryptosystems.
  88
  89 <sect2><tt>silcmath/gmp-3.0.1</tt>
  90
  91 <p>
  92 This directory includes the GNU MP library.  The description of this
  93 library is out of scope of this document.  See
  94 <url url="http://www.swox.com/gmp/"> for more detailed information.
  95
  96 <sect1><tt>silcsim</tt>
  97
  98 <p>
  99 This directory includes the SILC Module (SIM) library.  SIM's are dynamically
 100 loadable shared objects.
 101
 102 <sect1><tt>silcske</tt>
 103
 104 <p>
 105 This directory includes implementation of the SILC Key Exchange (SKE)
 106 protocol.  SKE protocol is used to perform key exchange between two
 107 connecting entities such as client and server.  The SKE protocol
 108 specification is described in the Internet Draft
 109 <tt>draft-riikonen-silc-ke-auth-00.txt</tt> document available from
 110 <url url="http://www.ietf.org">.
 111
 112 <sect>Basic programming with SILC library
 113
 114 <p>
 115
 116
 117 <sect>Core Library
 118
 119 <p>
 120 SILC Core library includes all the basic and common routines used by
 121 SILC client and server applications.  This includes buffer management,
 122 file management, network connection mangement, task management and scheduling.
 123 It also includes core components related to the actual SILC protocol
 124 implementation such as ID routines, ID cache system and SILC packet management.
 125
 126 <p>
 127 This section lists all the public header files of the core library thus
 128 all the public application programming interfaces of the core library.
 129
 130 <sect1>lib/silccore/id.h
 131
 132 <p>
 133    These are important ID types used in SILC. SILC server creates these
 134    but SILC client has to handle these as well since these are used in
 135    packet sending and reception. However, client never creates these
 136    but it receives the correct ID's from server. Clients, servers and
 137    channels are identified by the these ID's. Note that these are currently
 138    IPv4 specific, although adding IPv6 support is not a bad task and SILC
 139    protocol already supports IPv6.
 140
 141 <sect2>Includes
 142
 143 <p>
 144 <tt>#include "id.h"</tt>
 145
 146 <sect2>Definitions
 147
 148 <p>
 149 <verb>typedef unsigned char SilcIdType;</verb>
 150 <descrip><quote>
 151 Type definition for all ID types.
 152 </quote></descrip>
 153
 154 <p>
 155 <verb>
 156 #define SILC_ID_SERVER_LEN
 157 #define SILC_ID_CLIENT_LEN
 158 #define SILC_ID_CHANNEL_LEN
 159 </verb>
 160 <descrip><quote>
 161 Length of the ID's.
 162 </quote></descrip>
 163
 164 <p>
 165 <verb>
 166 #define SILC_ID_NONE
 167 #define SILC_ID_SERVER
 168 #define SILC_ID_CLIENT
 169 #define SILC_ID_CHANNEL
 170 </verb>
 171 <descrip><quote>
 172 All types of the ID's.
 173 </quote></descrip>
 174
 175 <p>
 176 <verb>
 177 typedef struct {
 178   struct in_addr ip;                            /* 32 bit IP */
 179   unsigned short port;                          /* 16 bit port */
 180   unsigned short rnd;                           /* 16 bit random number */
 181 } SilcServerID;
 182 </verb>
 183 <descrip><quote>
 184 Defines the Server ID structure.  This is used to distinguish a server in
 185 SILC network.
 186 </quote></descrip>
 187
 188 <p>
 189 <verb>
 190 typedef struct {
 191   struct in_addr ip;                            /* 32 bit IP */
 192   unsigned char rnd;                            /* 8 bit random number */
 193   unsigned char hash[CLIENTID_HASH_LEN];        /* 88 bit MD5 hash */
 194 } SilcClientID;
 195 </verb>
 196 <descrip><quote>
 197 Defines the Client ID structure.  This is used to distinguish a client in
 198 SILC network.
 199 </quote></descrip>
 200
 201 <p>
 202 <verb>
 203 typedef struct {
 204   struct in_addr ip;                            /* 32 bit IP */
 205   unsigned short port;                          /* 16 bit port */
 206   unsigned short rnd;                           /* 16 bit random number */
 207 } SilcChannelID;
 208 </verb>
 209 <descrip><quote>
 210 Defines the Channel ID structure.  This is used to distinguish a channel in
 211 SILC network.
 212 </quote></descrip>
 213
 214 <sect2>Public Interface
 215
 216 <p>
 217 <verb>
 218 unsigned char *silc_id_id2str(void *id, SilcIdType type);
 219 </verb>
 220 <descrip><quote>
 221 Converts ID to unsigned char string. First argument is a pointer of the
 222 ID to be converted, second argument is the of the ID. Returns the converted
 223 ID.
 224 </quote></descrip>
 225
 226 <p>
 227 <verb>
 228 void *silc_id_str2id(unsigned char *id, SilcIdType type);
 229 </verb>
 230 <descrip><quote>
 231 Converts string to ID. First argument is the string ID seconf is the type
 232 of the ID. Returns the converted ID.
 233 </quote></descrip>
 234
 235 <p>
 236 <verb>
 237 unsigned int silc_id_get_len(SilcIdType type);
 238 </verb>
 239 <descrip><quote>
 240 Returns length of a type of an ID.
 241 </quote></descrip>
 242
 243
 244 <sect1>lib/silccore/idcache.h
 245 <sect1>lib/silccore/silcbuffer.h
 246 <sect1>lib/silccore/silcbuffmt.h
 247 <sect1>lib/silccore/silcbufutil.h
 248 <sect1>lib/silccore/silcchannel.h
 249 <sect1>lib/silccore/silccommand.h
 250 <sect1>lib/silccore/silcconfig.h
 251 <sect1>lib/silccore/silclog.h
 252 <sect1>lib/silccore/silcmemory.h
 253 <sect1>lib/silccore/silcnet.h
 254 <sect1>lib/silccore/silcpacket.h
 255 <sect1>lib/silccore/silcprotocol.h
 256 <sect1>lib/silccore/silcschedule.h
 257 <sect1>lib/silccore/silcsockconn.h
 258 <sect1>lib/silccore/silctask.h
 259 <sect1>lib/silccore/silcutil.h
 260
 261
 262 <sect>Crypto Library
 263
 264 <sect>Math Library
 265
 266 <sect>SIM Library
 267
 268 <sect>SKE library
 269
 270 <p>
 271 All right, so you're typing along, and you want to show some example code,
 272 or example I/O with a program, whatever. Use the <tt/code/ or <tt/verb/
 273 ``environments'' for this, wrapped in a <tt/tscreen/ environment, as so:
 274 <tscreen><verb>
 275 This is an example verb environment.
 276 </verb></tscreen>
 277 As well as:
 278 <tscreen><code>
 279 This is an example code environment.
 280 </code></tscreen>
 281 The <tt/tscreen/ environment just sets the font to small type and
 282 indents it nicely. It's not required for using <tt/verb/ or <tt/code/,
 283 but I suggest that you do.
 284
 285 The <em/Linuxdoc-SGML User's Guide/ explains what special characters you
 286 can and can't use in the <tt/verb/ and <tt/code/ environments.
 287
 288 <sect1><heading><label id="test-ref">Cross references</>
 289
 290 <p>
 291 What about cross-references? This section has been marked with the
 292 <tt>label</> command; using <tt>ref</> will provide a cross reference,
 293 as in ``See Section <ref id="test-ref">'' for more.
 294
 295 Right now cross-references don't work in the <tt/groff/ translation for
 296 plain ASCII.  They do work when generating LaTeX or HTML output.
 297
 298 <sect1>Using fonts
 299
 300 <p>
 301 You want fonts, we got fonts. Of course these won't show up in the
 302 plain ASCII text, but they all map into the various output formats:
 303 <bf/boldface/, <em/emphasis/, <sf/sans serif/, <sl/slanted/,
 304 <tt/typewriter/, and <it/italics/.
 305
 306 <sect1>Lists
 307
 308 <p>
 309 Lists are easy as well. Just use the <tt/itemize/ element with the
 310 <tt/item/ commands, seen here:
 311 <itemize>
 312 <item> This is a list.
 313 <item> Nothing exciting about that.
 314        <itemize>
 315        <item> Multiple levels are supported as well.
 316        <item> Again, that's no surprise.
 317        </itemize>
 318        <enum>
 319        <item> Enumerated lists using <tt>enum</> also work.
 320        <item> Description environments using <tt>descrip</> along
 321               with <tt>tag</> are also available, as seen here.
 322        </enum>
 323        <descrip>
 324        <tag/First item./ Here's one item.
 325        <tag/Second item./ Here's another.
 326        <tag/Third item./ Can we go for three?
 327        </descrip>
 328 <item> A final item to top it all off.
 329 </itemize>
 330
 331 This is just about everything that you need to get started with
 332 writing SGML docs using the <tt/linuxdoc-sgml/ DTD. Please let me know
 333 if you think something should be changed or added to this document.
 334
 335 </article>