Improved UTF-8 encoding and decoding, improved toolkit doc,

[silc.git] / lib / doc / silcclient_using.html

<big><b>Using SILC Client Library</b></big>

<br />&nbsp;<br />&nbsp;<br />
<b>Introduction</b>

<br />&nbsp;<br />
SILC Client library is a full featured SILC Client protocol implementation.
The library has been designed to be complete SILC client without actual
user interface.  The library provides the API for the appliation which
it can use to implement generally whatever user interface it wants.  The
SILC Client Library recides in the lib/silcclient/ directory.  It uses
common and core component of SILC protocol from the lib/silccore, SKE
from lib/silcske and general utility routines from lib/silcutil.

<br />&nbsp;<br />
The `silcclient.h' file defines the function prototypes that application
must implement in order to be able to create the user interface with the
library.  The idea is that the application can implement whatever user
interface routines in the functions and display the data whatever way
it wants.  The library is entirely transparent to the user interface and
it does not include any user interface specific issues such as window
handling or item handling on the screen etc.  These does not interest
the library.  The `silcclient.h' also defines the client libary interface
the application can call.  The interface includes for example functions
for sending channel and private messages, client and channel retrieval
and other utility functions.

<br />&nbsp;<br />&nbsp;<br />
<b>Including Library Headers</b>

<br />&nbsp;<br />
Your application must include the following includes in your sources to 
get access all SILC Client Library routines:

<br />&nbsp;<br />
<tt>
#include "silcincludes.h"<br />
#include "silcclient.h"
</tt>

<br />&nbsp;<br />&nbsp;<br />
<b>Network Initialization on Win32</b>

<br />&nbsp;<br />
If you are programming your SILC client application on Windows system,
you will need to initialize the network routines in order to be able
to use the client library.  The network initialization is done by
calling the silc_net_win32_init at the start of your Windows application.
Usually this is done either in main() or WinMain() function, or other
similar place.  This function should be called before calling any other
SILC routine.

<br />&nbsp;<br />
<tt>
if (silc_net_win32_init() == FALSE)<br />
&nbsp;&nbsp;exit_with_error();
</tt>

<br />&nbsp;<br />
This function is available only on Win32 platforms, and on other platforms
the network routines are initialized automatically by the operating system.


<br />&nbsp;<br />&nbsp;<br />
<b>Creating Client</b>

<br />&nbsp;<br />
The client is context or entity based, so several client entitites can
be created in the application if needed.  However, it should be noted
that they are completely independent from each other and can be seen
as different applications.  Usually only one client entity is needed
per application.

<br />&nbsp;<br />
The client object is SilcClient which is usually allocated in following
manner:

<br />&nbsp;<br />
<tt>&nbsp;&nbsp;SilcClient client = silc_client_alloc(&ops, params, context, silc_version_string);</tt>

<br />&nbsp;<br />
`ops' is the static structure of client operations that library will call.
`context' can be some application specific context that will be saved into
the SilcClient object.  It is up to the caller to free this context.
SilcClient is always passed to the application thus the application
specific context can be retrieved from the SilcClient object.  See 
`client.h' file for detailed definition of SilcClient object.

<br />&nbsp;<br />
The `silc_version_string' is the current protocol version string, and you
can get it by including `silcversion.h' header in your source code.

<br />&nbsp;<br />
`ops' can be defined for example as follows:

<br />&nbsp;<br />
<tt>
SilcClientOperations ops = {<br />
&nbsp;&nbsp;  silc_say,<br />
&nbsp;&nbsp;  silc_channel_message,<br />
&nbsp;&nbsp;  silc_private_message,<br />
&nbsp;&nbsp;  silc_notify,<br />
&nbsp;&nbsp;  silc_command,<br />
&nbsp;&nbsp;  silc_command_reply,<br />
&nbsp;&nbsp;  silc_connect,<br />
&nbsp;&nbsp;  silc_disconnect,<br />
&nbsp;&nbsp;  silc_get_auth_method,<br />
&nbsp;&nbsp;  silc_verify_public_key,<br />
&nbsp;&nbsp;  silc_ask_passphrase,<br />
&nbsp;&nbsp;  silc_failure,<br />
&nbsp;&nbsp;  silc_key_agreement,<br />
};<br />
</tt>

<br />&nbsp;<br />
Please see the `client_ops_example.c' source file in lib/silcclient/
directory for predefined structure and stub functions for your
convenience.  It is provided for programmers so that they can copy
it and use it directly in their application.


<br />&nbsp;<br />&nbsp;<br />
<b>Initializing the Client</b>

<br />&nbsp;<br />
The client must be initialized before running.  However, there are also
some other tasks that must be done before initializing the client.
The following pointers must be set by the application  before calling
the initializing function:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;client->username<br />
&nbsp;&nbsp;client->hostname<br />
&nbsp;&nbsp;client->realname<br />
&nbsp;&nbsp;client->pkcs<br />
&nbsp;&nbsp;client->public_key<br />
&nbsp;&nbsp;client->private_key
</tt>

<br />&nbsp;<br />
You may also set client->nickname if you want.  If it is set then the
library will change the nickname to that one after the client is connected
to the server.  If not set, then server will initially give the nickname
which is same as the username.

<br />&nbsp;<br />
After setting the pointers one must call:

<br />&nbsp;<br />
<tt>&nbsp;&nbsp;silc_client_init(client);</tt>

<br />&nbsp;<br />
which then initializes the client library for the `client'.  If the
pointers mentioned above are not initialized the silc_client_init will
fail.  The application should check the return value of the silc_client_init
function.


<br />&nbsp;<br />&nbsp;<br />
<b>Running the Client</b>

<br />&nbsp;<br />
The client is run by calling silc_client_run.  The function will call
the scheduler from utility library that will be run until the program is
ended.  When silc_client_run returns the application is ended.  Thus,
to run the client, call:

<br />&nbsp;<br />
<tt>&nbsp;&nbsp;silc_client_run(client);</tt>

<br />&nbsp;<br />
Usually application may do some other initializations before calling
this function.  For example before calling this function application
should initialize the user interface.


<br />&nbsp;<br />&nbsp;<br />
<b>Running the Client in GUI application</b>

<br />&nbsp;<br />
Many GUI applications has their own main loop or event loop, which they 
would like to use or are forced to use by the underlaying system.  If you 
are developing for example GUI application on Unix system, and you are 
using GTK+ or QT as GUI library you would probably like to use their own 
main loop.  SILC Client can be run under external main loop as well.  The 
interface provides a function silc_client_run_one which will run the 
client library once, and returns immediately.  During that running it can 
process incoming data and send outgoing data, but it is guaranteed that it 
will not block the calling process.

<br />&nbsp;<br />
It is suggested that you would call this function as many times in a 
second as possible to provide smooth action for the client library.  You 
can use an timeout task, or an idle task provided by your GUI library to 
accomplish this.  After you have initialized the client library with 
silc_client_init, you should register the timeout task or idle task that 
will call the silc_client_run_one periodically.  In the Toolkit package 
there is GTK-- GUI example in silcer/ directory.  That example calls the 
silc_client_run_one every 50 milliseconds, and it should be sufficient for 
smooth working.

<br />&nbsp;<br />
For Win32 the silc_client_run can be used instead of using the Windows's 
own event loop.  However, if you would like to use the silc_client_run_one 
also on Win32 systems it is possible.


<br />&nbsp;<br />&nbsp;<br />
<b>Running Client in GTK--</b>

<br />&nbsp;<br />
Here is a short example how to run the SILC Client libary under the 
Gnome/GTK--'s main loop:

<br />&nbsp;<br />
<tt>
gint YourClass::silc_scheduler()<br />
{<br />
&nbsp;&nbsp;  // Run the SILC client once, and return immediately.  This function<br />
&nbsp;&nbsp;  // is called every 50 milliseconds by the Gnome main loop, to process<br />
&nbsp;&nbsp;  // SILC stuff.  This function will read data, and write data to network,<br />
&nbsp;&nbsp;  // etc.  Makes the client library tick! :)<br />
&nbsp;&nbsp;  silc_client_run_one(silc_client);<br />
&nbsp;&nbsp;  return 1;<br />
}<br />
</tt>

<br />&nbsp;<br />
then, during initialization of the SILC Client call:

<br />&nbsp;<br />
<tt>
// Setup SILC scheduler as timeout task. This will handle the SILC<br />
// client library every 50 milliseconds.  It will actually make the<br />
// SILC client work on background.<br />
Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);<br />
</tt>

<br />&nbsp;<br />
This will call the function silc_scheduler every 50 millisecconds, which 
on the otherhand will call silc_client_run_one, which will make the SILC 
Client library work on the background of the GUI application.


<br />&nbsp;<br />&nbsp;<br />
<b>Creating Connection to Server</b>

<br />&nbsp;<br />
Connection to remote SILC server is done by calling:

<br />&nbsp;<br />
<tt>&nbsp;&nbsp;silc_client_connect_to_server(client, port, hostname, context);</tt>

<br />&nbsp;<br />
The function will create the connection asynchronously to the server, ie.
the function will return before the actual connection is created.  After
the connection is created the client->ops->connect operation is called.

<br />&nbsp;<br />
Generally speaking the connections are associated with windows' on the
screen.  IRC is usually implemented this way, however it is not the
necessary way to associate the client's connections.  SilcClientConnection
object is provided by the library (and is always passed to the application)
that can be used in the application to associate the connection from the
library.  Application specific context can be saved to the 
SilcClientConnection object which then can be retrieved in the application,
thus perhaps associate the connection with what ever object in 
application (window or something else).


<br />&nbsp;<br />&nbsp;<br />
<b>Using Own Connecting</b>

<br />&nbsp;<br />
Application might not want to use silc_client_connect_to_server function
if it wants to perform its own connecting for some reason.  In this case
application must call function silc_client_start_key_exchange after it
has created the connection by itself.  This function starts the key
exhange protocol between the client and server and the library takes care
of everything after that.

<br />&nbsp;<br />
After connection has been created application must call:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;SilcClientConnection conn;

<br />&nbsp;<br />
&nbsp;&nbsp;/* Add new connection to client */<br />
&nbsp;&nbsp;conn = silc_client_add_connection(client, hostname, port, context);

<br />&nbsp;<br />
&nbsp;&nbsp;/* Start key exchange and let the library handle everything<br />
&nbsp;&nbsp;   after this point on. */<br />
&nbsp;&nbsp;silc_client_start_key_exchange(client, conn, sock);
</tt>

<br />&nbsp;<br />
NOTE: These calls are performed only and only if application did not call
silc_client_connect_to_server function, but performed the connecting 
process manually.


<br />&nbsp;<br />&nbsp;<br />
<b>Debugging</b>

<br />&nbsp;<br />
Being able to debug what you have coded is important when troubles occurs
during coding, and they always do.  SILC supports extensive debugging
capabilities which are also available for client library user.  You should
have compiled the Toolkit with --enable-debug option so that run-time
debugging is enabled.

<br />&nbsp;<br />
To turn on the run-time debugging set the global variable "silc_debug" to
TRUE.  To see packet hexdumps you can set also "silc_debug_hexdump" to TRUE.
Hexdumps can create more debug log so not setting it to TRUE by default is
probably best.  To get debug messages out of specific modules you can set
a debug string with silc_log_set_debug_string function.  The function takes
regex string as argument, for example:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;silc_debug = TRUE;<br />
&nbsp;&nbsp;silc_log_set_debug_string("*");<br />
</tt>

<br />&nbsp;<br />
This piece of code turns on the debugging and sets "*" as debug string.  This
means that all debug messages are printed.  To get debugging out of only
for example SILC Client Library the debug string could be "silc_client*".
The debug string matches to function names and filenames so it is possible
to get debugging out of specific files, and specific functions.  Other
examples could be:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;silc_log_set_debug_string("silc_client*,*socket*,*ske*");<br />
</tt>

<br />&nbsp;<br />
By default, all debug messages are printed to standard error output (stderr).
If you want to redirect the debug messages somewhere else you can set your
own debug callback with silc_log_set_debug_callbacks function:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;silc_log_set_debug_callbacks(my_debug_callback, my_context, my_hexdump_callback, my_context);<br />
</tt>

<br />&nbsp;<br />
See the lib/silcutil/silclog.h for definition of the callbacks.  See the
same file for other logging and debugging information.

<br />&nbsp;<br />
You can also use SILC debugging capabilities in your own application.  To
produce debug messages you can use SILC_LOG_DEBUG and SILC_LOG_HEXDUMP
macros in your application.  The SILC_LOG_DEBUG can print out normal debug
messages with variable argument list, for example:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;SILC_LOG_DEBUG(("Start"));<br />
&nbsp;&nbsp;SILC_LOG_DEBUG(("Packet length %d", packet_len));<br />
&nbsp;&nbsp;SILC_LOG_DEBUG(("The remote is %s on %d", sock->ip, sock->port));
</tt>

<br />&nbsp;<br />
The SILC_LOG_HEXDUMP macro can be used dump data which couldn't be printed
out otherwise, for example binary data.

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);<br />
&nbsp;&nbsp;SILC_LOG_HEXDUMP(("Packet, size=%d", size), packet->data, packet->len);
</tt>

<br />&nbsp;<br />
Note that the variable arguments in SILC_LOG_HEXDUMP are before the second
last parenthesis, and the last two arguments are the data, and its length that
are hexdumped.


<br />&nbsp;<br />&nbsp;<br />
<b>Example Client</b>

<br />&nbsp;<br />
This section includes an example SILC client implementation in pseudo-like
C code.  It creates and initializes the client and sets up an imaginary
user interface.  The user will use the user interface then to create
the connections.  The SilcClientOperations are expected to be implemented.

<br />&nbsp;<br />
<pre>
#include "silcincludes.h"
#include "silcclient.h"

int main()
{
        SilcClientOperations ops = {
          silc_say,
          silc_channel_message,
          silc_private_message,
          silc_notify,
          silc_command,
          silc_command_reply,
          silc_connect,
          silc_disconnect,
          silc_get_auth_method,
          silc_verify_public_key,
          silc_ask_passphrase,
          silc_failure,
          silc_key_agreement,
          silc_ftp,
          silc_detach
        };

        SilcClient client;

        /* Allocate SILC client. The `silc_version_string' is defined
           in includes/version.h file. */
        client = silc_client_alloc(&ops, NULL, NULL, silc_version_string);

        /* Register default ciphers, pkcs, hash funtions and hmacs. */
        silc_cipher_register_default();
        silc_pkcs_register_default();
        silc_hash_register_default();
        silc_hmac_register_default();

        /* Set the mandatory pointers, read public and private key from
           files (or somewhere) and return pointers and PKCS context. */
        client->username = silc_get_username();
        client->hostname = silc_net_localhost();
        client->realname = silc_get_real_name();
        client->pkcs = get_public_and_private_key(&client->public_key,
                                                  &client->private_key);

        /* If the keys does not exist, create a key pair since we must
           provide key pair to the library. */
        if (!client->pkcs)
          generate_key_new_key_pair(client);

        /* Iinitialize client */
        if (!silc_client_init(client))
          fatal_error("Could not initialize client");

        /* Initialize user interface. The user interface can be generally
           initialized at any phase, including before actually allocating
           and initializing the client, if wished. */
        InitUserInterface();
        DoCoolThings();

        /* Start the client. This will start the scheduler. At this phase
           the user might have the user interface in front of him already.
           He will use the user interface to create the connection to the
           server for example. When this function returns the program is 
          ended. */
        silc_client_run(client);

        /* Client is ended */
        return 0;
}
</pre>