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 compomnent of SILC protocol from the lib/silccore, SKE
+common and core component of SILC protocol from the lib/silccore, SKE
from lib/silcske and general utility routines from lib/silcutil.
<br /> <br />
-The `silcapi.h' file defines the function prototypes that application
+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 `silcapi.h' also defines the client libary interface
+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 /> <br />
<tt>
#include "silcincludes.h"<br />
-#include "clientlibincludes.h"
+#include "silcclient.h"
</tt>
+<br /> <br /> <br />
+<b>Network Initialization on Win32</b>
+
<br /> <br />
-If you are compiling with C++ compiler then you need to include the
-headers as follows:
+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 /> <br />
<tt>
-extern "C" {<br />
-#include "silcincludes.h"<br />
-#include "clientlibincludes.h"<br &/>
-}
+if (silc_net_win32_init() == FALSE)<br />
+ exit_with_error();
</tt>
+<br /> <br />
+This function is available only on Win32 platforms, and on other platforms
+the network routines are initialized automatically by the operating system.
+
<br /> <br /> <br />
<b>Creating Client</b>
manner:
<br /> <br />
-<tt> SilcClient client = silc_client_alloc(&ops, params, context, version);</tt>
+<tt> SilcClient client = silc_client_alloc(&ops, params, context, silc_version_string);</tt>
<br /> <br />
`ops' is the static structure of client operations that library will call.
specific context can be retrieved from the SilcClient object. See
`client.h' file for detailed definition of SilcClient object.
+<br /> <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 /> <br />
`ops' can be defined for example as follows:
process manually.
+<br /> <br /> <br />
+<b>Debugging</b>
+
+<br /> <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 /> <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 /> <br />
+<tt>
+ silc_debug = TRUE;<br />
+ silc_log_set_debug_string("*");<br />
+</tt>
+
+<br /> <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 /> <br />
+<tt>
+ silc_log_set_debug_string("silc_client*,*socket*,*ske*");<br />
+</tt>
+
+<br /> <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 /> <br />
+<tt>
+ silc_log_set_debug_callbacks(my_debug_callback, my_context, my_hexdump_callback, my_context);<br />
+</tt>
+
+<br /> <br />
+See the lib/silcutil/silclog.h for definition of the callbacks. See the
+same file for other logging and debugging information.
+
+<br /> <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 /> <br />
+<tt>
+ SILC_LOG_DEBUG(("Start"));<br />
+ SILC_LOG_DEBUG(("Packet length %d", packet_len));<br />
+ SILC_LOG_DEBUG(("The remote is %s on %d", sock->ip, sock->port));
+</tt>
+
+<br /> <br />
+The SILC_LOG_HEXDUMP macro can be used dump data which couldn't be printed
+out otherwise, for example binary data.
+
+<br /> <br />
+<tt>
+ SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);<br />
+ SILC_LOG_HEXDUMP(("Packet, size=%d", size), packet->data, packet->len);
+</tt>
+
+<br /> <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 /> <br /> <br />
<b>Example Client</b>
<br /> <br />
<pre>
#include "silcincludes.h"
-#include "silcapi.h"
+#include "silcclient.h"
int main()
{
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, silc_version_string);
+ client = silc_client_alloc(&ops, NULL, NULL, silc_version_string);
/* Register default ciphers, pkcs, hash funtions and hmacs. */
silc_cipher_register_default();
projects / silc.git / blobdiff