Copyright © 2001 - 2007 SILC Project SILC Project Website | SILC Toolkit Reference Manual Index

SILC Toolkit Reference Manual
SILC VCard Library
SILC VCard Interface
SILC Crypto Library
Introduction to SILC RNG
SILC RNG Interface
SILC Cipher API
SILC PKCS API
SILC Public Key API
SILC PKCS #1 API
SILC Hash Interface
SILC HMAC Interface
SILC Client Library
Using SILC Client Library Tutorial
Arguments for command_reply Client Operation
SilcStatus Error Arguments in command_reply Client Operation
Arguments for notify Client Operation
Unicode and UTF-8 Strings in Client Library
Client Library Interface Reference
Client Entry Interface Reference
SILC Math Library
SILC MP Interface
SILC Math Interface
SILC Application Utility Library
SILC Application Utilities
SILC ID Cache Interface
SILC Key Repository Library
SILC SKR Interface
SILC ASN.1 Library
SILC ASN.1 Interface
SILC BER interface
SILC Key Exchange Library
SILC SKE Interface
SILC Connection Authentication Interface
SILC SFTP Library
SILC SFTP Interface
SFTP Filesystems Interface
SILC Core Library
SILC Authentication Interface
SILC Message Interface
SILC Channel Interface
SILC Command Interface
SILC Notify Interface
SILC Status Types
SILC Modes
SILC ID Interface
SILC Argument Interface
SILC Attributes Interface
Packet Engine Interface
SILC Public Key Payload Interface
SILC Utility Library
Basic Types and Definitions
Data Buffer Interface
Data Buffer Format Interface
Hash Table Interface
Memory Allocation Interface
Data Stack (memory pool) Interface
Finite State Machine Interface
Thread Interface
Mutual Exclusion Lock Interface
Condition Variable Interface
Atomic Operations Interface
Network (TCP and UDP) Interface
Scheduler Interface
Asynchronous Operation Interface
Abstract Stream Interface
Socket Stream Interface
File Descriptor Stream Interface
File Utility Functions
String Utility Interface
Snprintf Interface
UTF-8 String Interface
Stringprep Interface
Utility Functions
List Interface
Dynamic List Interface
MIME Interface
Time Utility Functions
Logging Interface
Config File Interface
SILC HTTP Library
SILC HTTP Server Interface
SILC HTTP PHP Translator
Resource Links
SILC Project Website
SILC Protocol Documentation
SILC White Paper
SILC FAQs

Using SILC Client Library
Introduction
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.
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' and `silcclient_entry.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.
Including Library Headers
Your application must include the following includes in your sources to get access all SILC Client Library routines:
`#include "silc.h"
#include "silcclient.h"`
Creating Client
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.
The client object is SilcClient which is usually allocated in following manner:
`SilcClient client = silc_client_alloc(&ops, params, context, NULL);`
`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.
`ops' can be defined for example as follows:
`SilcClientOperations ops = {
silc_say,
silc_channel_message,
silc_private_message,
silc_notify,
silc_command,
silc_command_reply,
silc_get_auth_method,
silc_verify_public_key,
silc_ask_passphrase,
silc_key_agreement,
silc_file_transfer,
};
`
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.
Initializing the Client
The client must be initialized before running. The client is initialized simply by calling silc_client_init function:
`silc_client_init(client, username, hostname, realname, foo_client_running, foo_ctx);`
which then initializes the client library for the `client'. The `username' and `hostname' pointers are required. The `foo_client_running' with `foo_ctx' in this example will be called by the client library after the client is up and running. After you receive this callback you may start using other API functions, such as creating connection to remote server.
Running the Client
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:
`silc_client_run(client);`
Usually application may do some other initializations before calling this function. For example before calling this function application should initialize the user interface.
Running the Client in GUI application
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.
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.
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 system it is possible.
Running Client in GTK--
Here is a short example how to run the SILC Client libary under the Gnome/GTK--'s main loop:
`gint YourClass::silc_scheduler()
{
// Run the SILC client once, and return immediately. This function
// is called every 50 milliseconds by the Gnome main loop, to process
// SILC stuff. This function will read data, and write data to network,
// etc. Makes the client library tick! :)
silc_client_run_one(silc_client);
return 1;
}
`
then, during initialization of the SILC Client call:
`// Setup SILC scheduler as timeout task. This will handle the SILC
// client library every 50 milliseconds. It will actually make the
// SILC client work on background.
Gnome::Main::timeout.connect(slot(this, &YourClass::silc_scheduler), 50);
`
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.
Creating Connection to Server
After your client is up and running you may create connection to remote SILC server. It is done simply by calling:
`silc_client_connect_to_server(client, ¶ms, public_key, private_key, remote_host, remote_port, foo_connected_cb, foo_ctx);`
The function will create the connection asynchronously to the server, ie. the function will return before the actual connection is created. The `foo_connected_cb' will be called once the connection has been established. The `params' may be NULL but it may be used to provide additional parameters to the connecting. For example it is possible to set the initial nickname you would like to use into the `params'.
Debugging
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.
Then, to say in your application you would like to use the debugging use the SILC_DEBUG macro. Put this macro to your main header file, or some other file that needs the debugging enabled. After using this macro you are able to use the debugging routines provided by the SILC Toolkit. Note that, the Toolkit library must be compiled with --enable-debug for this macro to have any effect.
To turn on the run-time debugging call function silc_log_debug with TRUE value. To see packet hexdumps you can call also silc_log_debug_hexdump with TRUE value. 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:
`silc_log_debug(TRUE);
silc_log_set_debug_string("*");
`
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:
`silc_log_set_debug_string("silc_client*,*sock*,*ske*");
`
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:
`silc_log_set_debug_callbacks(my_debug_callback, my_context, my_hexdump_callback, my_context);
`
See the lib/silcutil/silclog.h for definition of the callbacks. See the same file for other logging and debugging information.
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:
`SILC_LOG_DEBUG(("Start"));
SILC_LOG_DEBUG(("Packet length %d", packet_len));
SILC_LOG_DEBUG(("The remote is %s on %d", sock->ip, sock->port));`
The SILC_LOG_HEXDUMP macro can be used dump data which couldn't be printed out otherwise, for example binary data.
`SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);
SILC_LOG_HEXDUMP(("Packet, size=%d", size), packet->data, packet->len);`
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.

Copyright © 2001 - 2007 SILC Project SILC Project Website | SILC Toolkit Reference Manual Index