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);
  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   say:                  silc_say,
  46   channel_message:      silc_channel_message,
  47   private_message:      silc_private_message,
  48   notify:               silc_notify,
  49   command:              silc_command,
  50   command_reply:        silc_command_reply,
  51   connect:              silc_connect,
  52   disconnect:           silc_disconnect,
  53   get_auth_method:      silc_get_auth_method,
  54   verify_public_key:    silc_verify_public_key,
  55   ask_passphrase:       silc_ask_passphrase,
  56   failure:              silc_failure,
  57 };
  58
  59
  60 Initializing the Client
  61 =======================
  62
  63 The client must be initialized before running.  However, there are also
  64 some other tasks that must be done before initializing the client.  Following
  65 pointers must be set before calling the initializing function:
  66
  67         client->username
  68         client->hostname
  69         client->realname
  70         client->pkcs
  71         client->public_key
  72         client->private_key
  73
  74 After setting the pointers one must call:
  75
  76         silc_client_init(client);
  77
  78 which then initializes the client library for the `client'.  If the pointers
  79 mentioned above are not initialized the silc_client_init will fail.
  80
  81
  82 Running the Client
  83 ==================
  84
  85 The client is run by calling silc_client_run.  The function will call
  86 the scheduler from utility library that will be run until the program is
  87 ended.  When silc_client_run returns the application is ended.  Thus,
  88 to run the client, call:
  89
  90         silc_client_run(client);
  91
  92 Usually application may do some other initializations before calling
  93 this function.  For example before calling this function application should
  94 initialize the user interface.
  95
  96
  97 Creating Connection to Server
  98 =============================
  99
 100 Connection to remote SILC server is done by calling:
 101
 102         silc_client_connect_to_server(client, port, hostname, context);
 103
 104 The function will create the connection asynchronously to the server, ie.
 105 the function will return before the actual connection is created.  After
 106 the connection is created the client->ops->connect operation is called.
 107
 108 Generally speaking the connections are associated with windows' on the
 109 screen.  IRC is usually implemented this way, however it is not the necessary
 110 way to associate the client's connections.  SilcClientConnection object
 111 is provided by the library (and is always passed to the application) that
 112 can be used in the application to associate the connection from the library.
 113 Application specific context can be saved to the SilcClientConnection object
 114 which then can be retrieved in the application, thus perhaps associate
 115 the connection with what ever object in the application (window or something
 116 else).
 117
 118
 119 Using Own Connecting
 120 ====================
 121
 122 Application might not want to use silc_client_connect_to_server function
 123 if it wants to perform its own connecting for some reason.  In this case
 124 application must call function silc_client_start_key_exchange after it
 125 has created the connection by itself.  This function starts the key exhange
 126 protocol between the client and server and the library takes care of
 127 everything after that.
 128
 129 After connection has been created application must call:
 130
 131         SilcClientConnection conn;
 132
 133         /* Add new connection to client */
 134         conn = silc_client_add_connection(client, hostname, port, context);
 135
 136         /* Start key exchange and let the library handle everything
 137            after this point on. */
 138         silc_client_start_key_exchange(client, conn, sock);
 139
 140 These calls are performed only and only if application did not call
 141 silc_client_connect_to_server function.