SILC Toolkit 0.9

[Pekka R. <pri...@ik...>]

The SILC Toolkit version 0.9 is now available!  The software is
available from the following sources:

        http://silcnet.org/
        ftp://ftp.silcnet.org/

SILC Toolkit 0.9 implementing the new SILC protocol version 1.1 is now
out.  The Toolkit is released before any other package so that the Toolkit
programmers can get their programs up to date supporting protocol version
1.1 as soon as possible.  If you are not SILC Toolkit programmer then it
is not necessary for you to read this email any further.

For Toolkit programmers this email can be used as reference to modify
your application to support this Toolkit version and new protocol
version.  I will list here changes in the Toolkit in code level, and list
all required changes for Client Library users.

o New commands:  "DETACH" and "WATCH".  The SILC_COMMAND_DETACH is a
  command which can be used to detach from the server without actually
  signing off from the network.  When called, the library will call
  a new 'detach' client operation to the application to deliver a
  detachment data.  More of this later in this email.

  The SILC_COMMAND_WATCH is a command which can be used to add or delete
  a nickname in a watch list.  When nickname is added to watch list
  the server will notify the client when the nickname comes or leaves
  the network, changes user mode (like AWAY) or changes nickname.
  The notify will call the 'notify' client operation with a new
  notify type SILC_NOTIFY_TYPE_WATCH.

  The server does not provide a mechanism to fetch the current
  watch list, so it is application's responsible of keeping a list
  if you want to provide such feature for a user in user interface.

  Ref:
  http://silcnet.org/docs/toolkit/silccommand.html
  http://silcnet.org/docs/toolkit/silccommand-SilcCommand.html


o 'connect' client operation API change:  The 'connect' client operation
  that is called after the connection to the server has been created,
  now has SilcClientConnectionStatus argument, which replaces the old
  boolean success/failure indicator.  SILC_CLIENT_CONN_SUCCESS indicates
  that connection was created successfully,
  SILC_CLIENT_CONN_SUCCESS_RESUME indicates that connection was created
  successfully, and old session was resumed in the server.  Any other
  status value is currently an error.

  Ref:
  http://silcnet.org/docs/toolkit/silcclient.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientOperations.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientConnectionStatus.html


o A new 'detach' client operation:  This new client operation is called
  after the new DETACH command is called.  Library delivers a data block
  to application which the application must save in order to able to
  resume the detached session at a later time.  Application may save
  it for example into a file.  If application does not save it, it
  is impossible to resume the session in the server later.

  To resume a detached session, the application must provide the
  detachment data to the library when creating a new connection to a
  server.  There is a new structure SilcClientConnectionParams which
  includes generic connection creation parameters, including the
  detachment data.  This structure can be given as argument to either
  silc_client_connect_to_server, or silc_client_add_connection, which
  ever your application use currently.  When the detachment data is
  saved in the stucture the library will use the data to resume the
  session in the network.  If this is successful the new connection
  status SILC_CLIENT_CONN_SUCCESS_RESUME is returned in 'connect'
  client operation.  After the detachment data is used, it cannot
  be re-used later, so application should delete after using it
  (regardless whether the resuming was successful or not).

  When resuming a session to server the library will call various
  client operations, such as 'command_reply' client operation for
  JOIN, UMODE, CMODE, USERS, TOPIC etc.  The reason for this is
  that the library sets itself into the same state it was when the
  session was detached.  So if the client was on 3 channels, all
  those channels are created again, and the library calls command
  reply for JOIN command.  The application should do exactly the
  same thing as it would do normally when receiving these client
  operations.  This is to make the resuming as simple as possible
  for application.  Also note that these client operations are
  called *before* the 'connect' client operation so make sure you
  handle this in your application.

  This is a great new feature which makes a difference for users
  and I hope that applications start supporting this.

  Ref:
  http://silcnet.org/docs/toolkit/silcclient.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientOperations.html
  http://silcnet.org/docs/toolkit/silcclient-silc_client_connect_to_server.html
  http://silcnet.org/docs/toolkit/silcclient-silc_client_add_connection.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientConnectionStatus.html


o New user modes:  If you application handles user modes like
  SILC_UMODE_GONE, SILC_UMODE_SERVER_OPERATOR and
  SILC_UMODE_ROUTER_OPERATOR you need to know that there is a bunch of
  new ones now: SILC_UMODE_INDISPOSED, SILC_UMODE_BUSY,
  SILC_UMODE_PAGE, SILC_UMODE_HYPER, SILC_UMODE_ROBOT,
  SILC_UMODE_ANONYMOUS, SILC_UMODE_BLOCK_PRIVMSG,
  SILC_UMODE_REJECT_WATCHING and SILC_UMODE_BLOCK_INVITE modes
  are defined in lib/silccore/silcmode.h.

  Ref:
  http://silcnet.org/docs/toolkit/silcmode.html
  http://silcnet.org/docs/toolkit/silcmode-SilcUserMode.html


o Two new channel modes: SILC_CHANNEL_MODE_SILENCE_USERS
  and SILC_CHANNEL_MODE_SILENCE_OPERS which are defined in
  lib/silccore/silcmode.h.  These modes can be handled through
  the CMODE command.

  Ref:
  http://silcnet.org/docs/toolkit/silcmode.html
  http://silcnet.org/docs/toolkit/silcmode-ChannelModes.html


o Four new channel user modes: SILC_CHANNEL_UMODE_BLOCK_MESSAGES,
  SILC_CHANNEL_UMODE_BLOCK_MESSAGES_USERS,
  SILC_CHANNEL_UMODE_BLOCK_MESSAGES_ROBOTS and
  SILC_CHANNEL_UMODE_QUIET which are defined also in
  lib/silccore/silcmode.h.  These modes can be handled through
  the CUMODE command.

  Ref:
  http://silcnet.org/docs/toolkit/silcmode.html
  http://silcnet.org/docs/toolkit/silcmode-ChannelUserModes.html


o The silc_client_command_status_message function is removed and a new
  generic silc_get_status_message function was added.  The old
  status types SilcCommandStatus is now renamed to SilcStatus
  and the silc_get_status_message can be used to map the SilcStatus
  into human readable message if your application wants to do it.

  Also note that all client operations that had the old
  SilcCommandStatus argument now use the SilcStatus argument, so
  update your code on this.

  Ref:
  http://silcnet.org/docs/toolkit/silcstatus.html
  http://silcnet.org/docs/toolkit/silcstatus-SilcStatus.html
  http://silcnet.org/docs/toolkit/silcutil.html
  http://silcnet.org/docs/toolkit/silcutil-silc_get_status_message.html


o New notify types:  SILC_NOTIFY_TYPE_ERROR and SILC_NOTIFY_TYPE_WATCH.
  The ERROR is a generic error notification which the server may
  send to client when an error has occurred.  The error is SilcStatus
  so your application can use silc_get_status_message to map the
  error message if wanted.  The WATCH notify type is called when
  a nickname which was added using "WATCH" command has had a
  change.  The WATCH notify returns SilcClientEntry, char *nickname,
  SilcUInt32 mode and SilcNotifyType in 'notify' client operation.
  The SilcNotifyType indicates which action happened for the
  watched nickname.  The nickname returned may be NULL.  Notify
  types that may be returned in this WATCH notify are:
  SILC_NOTIFY_TYPE_NICK_CHANGE, SILC_NOTIFY_TYPE_UMODE_CHANGE,
  SILC_NOTIFY_TYPE_KILLED, SILC_NOTIFY_TYPE_SIGNOFF or
  SILC_NOTIFY_TYPE_SERVER_SIGNOFF.

  Ref:
  http://silcnet.org/docs/toolkit/silcnotify.html
  http://silcnet.org/docs/toolkit/silcnotify-SilcNotifyType.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientOperations.html


o silc_client_close_connection does not have SilcSocketConnection
  argument anymore.

  Ref:
  http://silcnet.org/docs/toolkit/silcclient.html
  http://silcnet.org/docs/toolkit/silcclient-silc_client_close_connection.html


o The SILC_NOTIFY_TYPE_KILLED notify type now returns the killer's
  SilcClientEntry as last argument in 'notify' client operation.

  Ref:
  http://silcnet.org/docs/toolkit/silcnotify.html
  http://silcnet.org/docs/toolkit/silcnotify-SilcNotifyType.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientOperations.html


o API changes in 'channel_message' and 'private_message' client
  operations:  The message which used to be the 'msg' argument is
  now const unsigned char *message, and new argument
  SilcUInt32 message_len indicates the message length.  The reason
  for this change is that the 'message' may be now pure binary
  data.  More of these binary messages later in this email.

  Ref:
  http://silcnet.org/docs/toolkit/silcclient.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientOperations.html


o API change in 'command' client operation.  Applications usually
  don't use this client operation much, but anyway, now it returns
  the specific error status (SilcStatus) to application to indicate
  which went wrong when executing the command in the library.

  Ref:
  http://silcnet.org/docs/toolkit/silcclient.html
  http://silcnet.org/docs/toolkit/silcclient-SilcClientOperations.html
  http://silcnet.org/docs/toolkit/silcstatus.html
  http://silcnet.org/docs/toolkit/silcstatus-SilcStatus.html


o New message flag SILC_MESSAGE_FLAG_DATA, which represents
  binary data.  The message that has this SilcMessageFlag includes
  a MIME object as a message.  Make sure you check for this flag
  in your application and display the message only if you first
  parse the MIME object.  A new function silc_mime_parse was
  added for you convenience in lib/silcutil/silcstrutil.h if you
  do not have your own MIME parser available.  I also suggest
  checking all the other message flags that exist and handle the
  message only if you know how to handle it.  This new message
  flag makes it possible to send any binary data, such as video
  stream, audio stream, images, etc. as channel message or private
  message.

  Ref:
  http://silcnet.org/docs/toolkit/silcchannel-SilcMessageFlags.html
  http://silcnet.org/docs/toolkit/silcstrutil.html
  http://silcnet.org/docs/toolkit/silcstrutil-silc_mime_parse.html


o API change in silc_client_file_receive.  A new argument 'path'
  was added which can be used to tell the destination path (directory)
  where the received file should be saved.  If omitted, current
  directory is used.

  Ref:
  http://silcnet.org/docs/toolkit/silcclient.html
  http://silcnet.org/docs/toolkit/silcclient-silc_client_file_receive.html


o I'm sure there's other minor changes in APIs and stuff but I'm
  sure you can figure them our really quickly.  Use the new Toolkit
  Reference Manual also as much as possible.


Also remember that everything listed here is implemented in the Irssi
SILC client.  It is the reference client implementation and the code
is included in the Toolkit package.  If you are in doubt or want to see
how it is done in Irssi SILC client, be sure to check the code in
irssi/src/silc/core/.  For troubleshooting use this silc-devel mailing
list.  It is preferred to use this mailing list instead of talking online
since there are many people usually wondering the same problem.  You can
also test your own client against the server found in the Toolkit package
instead of silc.silcnet.org which is still old version.

Note also that this is major new release and it is quite expected that
there are bugs because of lack of testing.  Expect bugfix releases soon.

The Win32 binary package is also coming soon for Win32 application
programmers on the website.  Please refer to the ChangeLog on the website,
or the CHANGES file in the package for a lot more detailed list of
changes.  Reading the changes list for all the way down to April 1st is
suggested.

	Pekka
________________________________________________________________________
 Pekka Riikonen                                 priikone at silcnet.org
 Secure Internet Live Conferencing (SILC)       http://silcnet.org/