lib/silcclient/README

   1
   2                       SILC Client Library Manual
   3
   4                              Version 0.7.4
   5
   6 1.0 Introduction
   7
   8 SILC Client library is a full featured SILC Client protocolimplementation.
   9 The library has been designed to be complete SILC client without actual
  10 user interface.  The library provides the API for the appliation which
  11 it can use to implement generally whatever user interface it wants.  The
  12 SILC Client Library recides in the lib/silcclient/ directory.  It uses
  13 common and core compomnent of SILC protocol from the lib/silccore, SKE
  14 from lib/silcske and general utility routines from lib/silcutil.
  15
  16 The `silcapi.h' file defines the function prototypes that application
  17 must implement in order to be able to create the user interface with the
  18 library.  The idea is that the application can implement whatever user
  19 interface routines in the functions and display the data whatever way
  20 it wants.  The library is entirely transparent to the user interface and
  21 it does not include any user interface specific issues such as window
  22 handling or item handling on the screen etc.  These does not interest
  23 the library.  The `silcapi.h' also defines the client libary interface
  24 the application can call.  The interface includes for example functions
  25 for sending channel and private messages, client and channel retrieval
  26 and other utility functions.
  27
  28
  29 1.0.1 Including Library Headers
  30
  31 Your application must include the following includes in your sources to
  32 get access all SILC Client Library routines:
  33
  34 #include "silcincludes.h"
  35 #include "clientlibincludes.h"
  36
  37 If you are compiling with C++ compiler then you need to include the
  38 headers as follows:
  39
  40 extern "C" {
  41 #include "silcincludes.h"
  42 #include "clientlibincludes.h"
  43 }
  44
  45
  46 1.1 Creating Client
  47
  48 The client is context or entity based, so several client entitites can
  49 be created in the application if needed.  However, it should be noted
  50 that they are completely independent from each other and can be seen
  51 as different applications.  Usually only one client entity is needed
  52 per application.
  53
  54 The client object is SilcClient which is usually allocated in following
  55 manner:
  56
  57         SilcClient client = silc_client_alloc(&ops, context, version);
  58
  59 `ops' is the static structure of client operations that library will call.
  60 `context' can be some application specific context that will be saved into
  61 the SilcClient object.  It is up to the caller to free this context.
  62 SilcClient is always passed to the application thus the application
  63 specific context can be retrieved from the SilcClient object.  See
  64 `client.h' file for detailed definition of SilcClient object.
  65
  66 `ops' can be defined for example as follows:
  67
  68 SilcClientOperations ops = {
  69   silc_say,
  70   silc_channel_message,
  71   silc_private_message,
  72   silc_notify,
  73   silc_command,
  74   silc_command_reply,
  75   silc_connect,
  76   silc_disconnect,
  77   silc_get_auth_method,
  78   silc_verify_public_key,
  79   silc_ask_passphrase,
  80   silc_failure,
  81   silc_key_agreement,
  82 };
  83
  84 Please see the `client_ops_example.h' header file in lib/silcclient/
  85 directory for predefined structure and stub functions for your
  86 convenince.  It is provided for programmers so that they can copy
  87 it and use it directly in their application.
  88
  89
  90 1.2 Initializing the Client
  91
  92 The client must be initialized before running.  However, there are also
  93 some other tasks that must be done before initializing the client.
  94 The following pointers must be set by the application  before calling
  95 the initializing function:
  96
  97         client->username
  98         client->hostname
  99         client->realname
 100         client->pkcs
 101         client->public_key
 102         client->private_key
 103
 104 You may also set client->nickname if you want.  If it is set then the
 105 library will change the nickname to that one after the client is connected
 106 to the server.  If not set, then server will initially give the nickname
 107 which is same as the username.
 108
 109 After setting the pointers one must call:
 110
 111         silc_client_init(client);
 112
 113 which then initializes the client library for the `client'.  If the
 114 pointers mentioned above are not initialized the silc_client_init will
 115 fail.  The application should check the return value of the silc_client_init
 116 function.
 117
 118
 119 1.3 Running the Client
 120
 121 The client is run by calling silc_client_run.  The function will call
 122 the scheduler from utility library that will be run until the program is
 123 ended.  When silc_client_run returns the application is ended.  Thus,
 124 to run the client, call:
 125
 126         silc_client_run(client);
 127
 128 Usually application may do some other initializations before calling
 129 this function.  For example before calling this function application
 130 should initialize the user interface.
 131
 132
 133 1.3.1 Running the Client in GUI application
 134
 135 Many GUI applications has their own main loop or event loop, which they
 136 would like to use or are forced to use by the underlaying system.  If you
 137 are developing for example GUI application on Unix system, and you are
 138 using GTK+ or QT as GUI library you would probably like to use their own
 139 main loop.  SILC Client can be run under external main loop as well.  The
 140 interface provides a function silc_client_run_one which will run the
 141 client library once, and returns immediately.  During that running it can
 142 process incoming data and send outgoing data, but it is guaranteed that it
 143 will not block the calling process.
 144
 145 It is suggested that you would call this function as many times in a
 146 second as possible to provide smooth action for the client library.  You
 147 can use an timeout task, or an idle task provided by your GUI library to
 148 accomplish this.  After you have initialized the client library with
 149 silc_client_init, you should register the timeout task or idle task that
 150 will call the silc_client_run_one periodically.  In the Toolkit package
 151 there is GTK-- GUI example in silcer/ directory.  That example calls the
 152 silc_client_run_one every 50 milliseconds, and it should be sufficient for
 153 smooth working.
 154
 155 For Win32 the silc_client_run can be used instead of using the Windows's
 156 own event loop.  However, if you would like to use the silc_client_run_one
 157 also on Win32 systems it is possible.
 158
 159
 160 1.3.1.1 Running Client in GTK--
 161
 162 Here is a short example how to run the SILC Client libary under the
 163 Gnome/GTK--'s main loop:
 164
 165 gint YourClass::silc_scheduler()
 166 {
 167   // Run the SILC client once, and return immediately.  This function
 168   // is called every 50 milliseconds by the Gnome main loop, to process
 169   // SILC stuff.  This function will read data, and write data to network,
 170   // etc.  Makes the client library tick! :)
 171   silc_client_run_one(silc_client);
 172   return 1;
 173 }
 174
 175 then, during initialization of the SILC Client call:
 176
 177   // Setup SILC scheduler as timeout task. This will handle the SILC
 178   // client library every 50 milliseconds.  It will actually make the
 179   // SILC client work on background.
 180   Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);
 181
 182 This will call the function silc_scheduler every 50 millisecconds, which
 183 on the otherhand will call silc_client_run_one, which will make the SILC
 184 Client library work on the background of the GUI application.
 185
 186
 187 1.4 Creating Connection to Server
 188
 189 Connection to remote SILC server is done by calling:
 190
 191         silc_client_connect_to_server(client, port, hostname, context);
 192
 193 The function will create the connection asynchronously to the server, ie.
 194 the function will return before the actual connection is created.  After
 195 the connection is created the client->ops->connect operation is called.
 196
 197 Generally speaking the connections are associated with windows' on the
 198 screen.  IRC is usually implemented this way, however it is not the
 199 necessary way to associate the client's connections.  SilcClientConnection
 200 object is provided by the library (and is always passed to the application)
 201 that can be used in the application to associate the connection from the
 202 library.  Application specific context can be saved to the
 203 SilcClientConnection object which then can be retrieved in the application,
 204 thus perhaps associate the connection with what ever object in
 205 application (window or something else).
 206
 207
 208 1.4.1 Using Own Connecting
 209
 210 Application might not want to use silc_client_connect_to_server function
 211 if it wants to perform its own connecting for some reason.  In this case
 212 application must call function silc_client_start_key_exchange after it
 213 has created the connection by itself.  This function starts the key
 214 exhange protocol between the client and server and the library takes care
 215 of everything after that.
 216
 217 After connection has been created application must call:
 218
 219         SilcClientConnection conn;
 220
 221         /* Add new connection to client */
 222         conn = silc_client_add_connection(client, hostname, port, context);
 223
 224         /* Start key exchange and let the library handle everything
 225            after this point on. */
 226         silc_client_start_key_exchange(client, conn, sock);
 227
 228 NOTE: These calls are performed only and only if application did not call
 229 silc_client_connect_to_server function, but performed the connecting
 230 process manually.
 231
 232
 233 1.5 Example Client
 234
 235 This section includes an example SILC client implementation in pseudo-like
 236 C code.  It creates and initializes the client and sets up an imaginary
 237 user interface.  The user will use the user interface then to create
 238 the connections.  The SilcClientOperations are expected to be implemented.
 239
 240 #include "silcincludes.h"
 241 #include "silcapi.h"
 242
 243 int main()
 244 {
 245         SilcClientOperations ops = {
 246           silc_say,
 247           silc_channel_message,
 248           silc_private_message,
 249           silc_notify,
 250           silc_command,
 251           silc_command_reply,
 252           silc_connect,
 253           silc_disconnect,
 254           silc_get_auth_method,
 255           silc_verify_public_key,
 256           silc_ask_passphrase,
 257           silc_failure,
 258           silc_key_agreement,
 259         };
 260
 261         SilcClient client;
 262
 263         /* Allocate SILC client. The `silc_version_string' is defined
 264            in includes/version.h file. */
 265         client = silc_client_alloc(&ops, NULL, silc_version_string);
 266
 267         /* Register default ciphers, pkcs, hash funtions and hmacs. */
 268         silc_cipher_register_default();
 269         silc_pkcs_register_default();
 270         silc_hash_register_default();
 271         silc_hmac_register_default();
 272
 273         /* Set the mandatory pointers, read public and private key from
 274            files (or somewhere) and return pointers and PKCS context. */
 275         client->username = silc_get_username();
 276         client->hostname = silc_net_localhost();
 277         client->realname = silc_get_real_name();
 278         client->pkcs = get_public_and_private_key(&client->public_key,
 279                                                   &client->private_key);
 280
 281         /* If the keys does not exist, create a key pair since we must
 282            provide key pair to the library. */
 283         if (!client->pkcs)
 284           generate_key_new_key_pair(client);
 285
 286         /* Iinitialize client */
 287         if (!silc_client_init(client))
 288           fatal_error("Could not initialize client");
 289
 290         /* Initialize user interface. The user interface can be generally
 291            initialized at any phase, including before actually allocating
 292            and initializing the client, if wished. */
 293         InitUserInterface();
 294         DoCoolThings();
 295
 296         /* Start the client. This will start the scheduler. At this phase
 297            the user might have the user interface in front of him already.
 298            He will use the user interface to create the connection to the
 299            server for example. When this function returns the program is
 300           ended. */
 301         silc_client_run(client);
 302
 303         /* Client is ended */
 304         return 0;
 305 }