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   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_server_key:    silc_verify_server_key,
  55   ask_passphrase:       silc_ask_passphrase,
  56 };
  57
  58
  59 Initializing the Client
  60 =======================
  61
  62 The client must be initialized before running.  However, there are also
  63 some other tasks that must be done before initializing the client.  Following
  64 pointers must be set before calling the initializing function:
  65
  66         client->username
  67         client->realname
  68         client->pkcs
  69         client->public_key
  70         client->private_key
  71
  72 After setting the pointers one must call:
  73
  74         silc_client_init(client);
  75
  76 which then initializes the client library for the `client'.  If the pointers
  77 mentioned above are not initialized the silc_client_init will fail.
  78
  79
  80 Running the Client
  81 ==================
  82
  83 The client is run by calling silc_client_run.  The function will call
  84 the scheduler from utility library that will be run until the program is
  85 ended.  When silc_client_run returns the application is ended.  Thus,
  86 to run the client, call:
  87
  88         silc_client_run(client);
  89
  90 Usually application may do some other initializations before calling
  91 this function.  For example before calling this function application should
  92 initialize the user interface.
  93
  94
  95 Creating Connection to Server
  96 =============================
  97
  98 Connection to remote SILC server is done by calling:
  99
 100         silc_client_connect_to_server(client, port, hostname, context);
 101
 102 The function will create the connection asynchronously to the server, ie.
 103 the function will return before the actual connection is created.  After
 104 the connection is created the client->ops->connect operation is called.
 105
 106 Generally speaking the connections are associated with windows' on the
 107 screen.  IRC is usually implemented this way, however it is not the necessary
 108 way to associate the client's connections.  SilcClientConnection object
 109 is provided by the library (and is always passed to the application) that
 110 can be used in the application to associate the connection from the library.
 111 Application specific context can be saved to the SilcClientConnection object
 112 which then can be retrieved in the application, thus perhaps associate
 113 the connection with what ever object in the application (window or something
 114 else).