lib/silcclient/README

   1 SILC Client Library
   2 ===================
   3
   4 This directory includes the SILC Client implementation.  The library uses
   5 common and core components of SILC protocol from lib/silccore library and
   6 normal utility routines from lib/silcutil library.  The library has been
   7 designed to be complete SILC Client implementation without actual user
   8 interface.  The library provides the API for the application which it can
   9 use to implement generally whatever user interface it wants.
  10
  11 The `silcapi.h' file defines the function prototypes that application must
  12 implement in order to be able to create the user interface with the
  13 library.  The idea is that the application can implement whatever user
  14 interface routines in the functions and display the data whatever way
  15 it wants.  The library is entirely transparent to the user interface and
  16 it does not include any user interface specific issues such as window
  17 handling or item handling on the screen etc.  These does not interest
  18 the library.
  19
  20
  21 Creating Client
  22 ===============
  23
  24 The client is context or entity based (which ever) thus several client
  25 entitites can be created in the application if needed.  However, it should
  26 be noted that they are completely independent from each other and can
  27 be seen as different applications.  Usually only one client entity is
  28 needed per application.
  29
  30 The client object is SilcClient which is usually allocated in following
  31 manner:
  32
  33         SilcClient client = silc_client_alloc(&ops, context, version);
  34
  35 `ops' is the static structure of client operations that library will call.
  36 `context' can be some application specific context that will be saved into
  37 the SilcClient object.  It is up to the caller to free this context.
  38 SilcClient is always passed to the application thus the application specific
  39 context can be retrieved from the SilcClient object.  See `client.h' file
  40 for detailed definition of SilcClient object.
  41
  42 `ops' can be defined for example as follows:
  43
  44 SilcClientOperations ops = {
  45   silc_say,
  46   silc_channel_message,
  47   silc_private_message,
  48   silc_notify,
  49   silc_command,
  50   silc_command_reply,
  51   silc_connect,
  52   silc_disconnect,
  53   silc_get_auth_method,
  54   silc_verify_public_key,
  55   silc_ask_passphrase,
  56   silc_failure,
  57   silc_key_agreement,
  58 };
  59
  60
  61 Initializing the Client
  62 =======================
  63
  64 The client must be initialized before running.  However, there are also
  65 some other tasks that must be done before initializing the client.  Following
  66 pointers must be set before calling the initializing function:
  67
  68         client->username
  69         client->hostname
  70         client->realname
  71         client->pkcs
  72         client->public_key
  73         client->private_key
  74
  75 After setting the pointers one must call:
  76
  77         silc_client_init(client);
  78
  79 which then initializes the client library for the `client'.  If the pointers
  80 mentioned above are not initialized the silc_client_init will fail.
  81
  82
  83 Running the Client
  84 ==================
  85
  86 The client is run by calling silc_client_run.  The function will call
  87 the scheduler from utility library that will be run until the program is
  88 ended.  When silc_client_run returns the application is ended.  Thus,
  89 to run the client, call:
  90
  91         silc_client_run(client);
  92
  93 Usually application may do some other initializations before calling
  94 this function.  For example before calling this function application should
  95 initialize the user interface.
  96
  97
  98 Creating Connection to Server
  99 =============================
 100
 101 Connection to remote SILC server is done by calling:
 102
 103         silc_client_connect_to_server(client, port, hostname, context);
 104
 105 The function will create the connection asynchronously to the server, ie.
 106 the function will return before the actual connection is created.  After
 107 the connection is created the client->ops->connect operation is called.
 108
 109 Generally speaking the connections are associated with windows' on the
 110 screen.  IRC is usually implemented this way, however it is not the necessary
 111 way to associate the client's connections.  SilcClientConnection object
 112 is provided by the library (and is always passed to the application) that
 113 can be used in the application to associate the connection from the library.
 114 Application specific context can be saved to the SilcClientConnection object
 115 which then can be retrieved in the application, thus perhaps associate
 116 the connection with what ever object in the application (window or something
 117 else).
 118
 119
 120 Using Own Connecting
 121 ====================
 122
 123 Application might not want to use silc_client_connect_to_server function
 124 if it wants to perform its own connecting for some reason.  In this case
 125 application must call function silc_client_start_key_exchange after it
 126 has created the connection by itself.  This function starts the key exhange
 127 protocol between the client and server and the library takes care of
 128 everything after that.
 129
 130 After connection has been created application must call:
 131
 132         SilcClientConnection conn;
 133
 134         /* Add new connection to client */
 135         conn = silc_client_add_connection(client, hostname, port, context);
 136
 137         /* Start key exchange and let the library handle everything
 138            after this point on. */
 139         silc_client_start_key_exchange(client, conn, sock);
 140
 141 These calls are performed only and only if application did not call
 142 silc_client_connect_to_server function.