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 API for the application which can use
   9 it to implement generally what ever user interface it wants.
  10
  11 The `ops.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 what ever user
  14 interface routines in the functions and display the data what ever 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
  22 Creating Client
  23 ===============
  24
  25 The client is context or entity based (which ever) thus several client
  26 entitites can be created in the application if needed.  However, it should
  27 be noted that they are completely independent from each other and can
  28 be seen as different applications.  Usually only one client entity is
  29 needed per application.
  30
  31 The client object is SilcClient which is usually allocated in following
  32 manner:
  33
  34         SilcClient client = silc_client_alloc(&ops, context);
  35
  36 `ops' is the static structure of client operations that library will call.
  37 `context' can be some application specific context that will be saved into
  38 the SilcClient object.  It is up to the caller to free this context.
  39 SilcClient is always passed to the application thus the application specific
  40 context can be retrieved from the SilcClient object.  See `client.h' file
  41 for detailed definition of SilcClient object.
  42
  43 `ops' can be defined for example as follows:
  44
  45 SilcClientOperations ops = {
  46   say:                  silc_say,
  47   channel_message:      silc_channel_message,
  48   private_message:      silc_private_message,
  49   notify:               silc_notify,
  50   command:              silc_command,
  51   command_reply:        silc_command_reply,
  52   connect:              silc_connect,
  53   disconnect:           silc_disconnect,
  54   get_auth_method:      silc_get_auth_method,
  55   verify_server_key:    silc_verify_server_key,
  56   ask_passphrase:       silc_ask_passphrase,
  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->realname
  69         client->pkcs
  70         client->public_key
  71         client->private_key
  72
  73 After setting the pointers one must call:
  74
  75         silc_client_init(client);
  76
  77 which then initializes the client library for the `client'.  If the pointers
  78 mentioned above are not initialized the silc_client_init will fail.
  79
  80
  81 Running the Client
  82 ==================
  83
  84 The client is run by calling silc_client_run.  The function will call
  85 the scheduler from utility library that will be run until the program is
  86 ended.  When silc_client_run returns the application is ended.  Thus,
  87 to run the client, call:
  88
  89         silc_client_run(client);
  90
  91 Usually application may do some other initializations before calling
  92 this function.  For example before calling this function application should
  93 initialize the user interface.
  94
  95
  96 Creating Connection to Server
  97 =============================
  98
  99 Connection to remote SILC server is done by calling:
 100
 101         silc_client_connect_to_server(client, port, hostname, context);
 102
 103 The function will create the connection asynchronously to the server, ie.
 104 the function will return before the actual connection is created.  After
 105 the connection is created the client->ops->connect operation is called.
 106
 107 Generally speaking the connections are associated with windows' on the
 108 screen.  IRC is usually implemented this way, however it is not the necessary
 109 way to associate the client's connections.  SilcClientConnection object
 110 is provided by the library (and is always passed to the application) that
 111 can be used in the application to associate the connection from the library.
 112 Application specific context can be saved to the SilcClientConnection object
 113 which then can be retrieved in the application, thus perhaps associate
 114 the connection with what ever object in the application (window or something
 115 else).
 116
 117
 118 Using Own Connecting
 119 ====================
 120
 121 Application might not want to use silc_client_connect_to_server function
 122 if it wants to perform its own connecting for some reason.  In this case
 123 application must call function silc_client_start_key_exchange after it
 124 has created the connection by itself.  This function starts key exhange
 125 protocol between the client and server and the library takes care of
 126 everything after that.
 127
 128 After connection has been created application must call:
 129
 130         SilcClientConnection conn;
 131
 132         /* Add new connection to client library */
 133         conn = silc_client_add_connection(client, context);
 134         conn->remote_host = hostname;
 135         conn->remote_port = port;
 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.