From 5a0d8b2194c472eaa704e4296bb3e2760dd5ae8c Mon Sep 17 00:00:00 2001 From: Pekka Riikonen Date: Wed, 15 Jan 2003 15:27:25 +0000 Subject: [PATCH] Added --- lib/doc/notifyargs.html | 268 +++++++++++++++++++++++++++++++++++++++ lib/silcclient/DIRECTORY | 1 + 2 files changed, 269 insertions(+) create mode 100644 lib/doc/notifyargs.html diff --git a/lib/doc/notifyargs.html b/lib/doc/notifyargs.html new file mode 100644 index 00000000..b3638485 --- /dev/null +++ b/lib/doc/notifyargs.html @@ -0,0 +1,268 @@ +SilcNotifyType Arguments + +
 
+The SILC Client Library 'notify' client operation (which is part of the +SilcClientOperation callback functions) returns different kind of +notifications from the SILC server to the SILC client. The 'notify' +client operation implementation has a variable argument list to deliver +SilcNotifyType type specific arguments to the application. This document +describes these arguments for all notify types to help SILC client +software developers to handle the incoming notifications. + +
 
 
+notify Client Library operation + +
 
+The 'notify' client operation callback function prototype is as follows: + +
 
+ +  void (*notify)(SilcClient client, SilcClientConnection conn, +SilcNotifyType type, ...); + + +
 
+The first argument 'client' is the SILC Client Library context, the `conn' +is the context for the connection to the remote server, and the `type' is +the notify type enumeration sent by the server. Rest of the arguments are +`type' specific and implementation should handle them by the +SilcNotifyType for example in a switch statement. The notify +types are defined in lib/silccore/silcnotify.h header file. A short +example: + +
 
+ +  switch(type)
+    {
+    case SILC_NOTIFY_TYPE_NONE:
+    ...
+    break;
+    case SILC_NOTIFY_TYPE_INVITE:
+    ...
+    break;
+    case SILC_NOTIFY_TYPE_JOIN:
+    ...
+    break;
+    ...
+    } + + +
 
 
+Arguments + +
 
+The following table describes all notify types and arguments that the +client library sends in the 'notify' client operation to the application. +By default all arguments that the libary sends to application are valid +pointers. However, it is possible that some pointers may be NULL. If +this is the case it is separately mentioned that the argument may be NULL. +In this case application must ignore that argument. The SilcNotifyType +arguments per notify type is as follows: + +
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionVariable Arguments
SILC_NOTIFY_TYPE_NONE +A message from server that usually does not include any critical +information. Application may ignore this or display it for the user. +The 'message' argument may be NULL. +char *message
SILC_NOTIFY_TYPE_INVITE +Sent to the client if the user is invited on a channel. The 'channel_name' +argument may be NULL. +SilcClientChannel channel, char *channel_name, +SilcClientEntry inviter +
SILC_NOTIFY_TYPE_JOIN +Sent when someone joins to a channel. +SilcClientEntry joining_client, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_LEAVE +Sent when someone leaves (parts) the channel. +SilcClientEntry leaving_client, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_SIGNOFF +Sent when someone signoff the SILC network. The 'signoff_message' may be +NULL. The 'leaving_client' SilcClientEntry may be incomplete and contain +NULL pointers, application must check it's pointers before attempting to +display for example nickname information. +SilcClientEntry signoff_client, char *signoff_message +
SILC_NOTIFY_TYPE_TOPIC_SET +Sent when the topic of a channel is set/changed. The 'setter_id_type' +is used to check what type of pointer the 'setter_entry' is. For +SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for +SILC_ID_CHANNEL SilcChannelEntry. +SilcIdType setter_id_type, void *setter_entry, +char *topic, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_NICK_CHANGE +Sent when someone changes their nickname. The 'old_client_entry' includes +the old nickname and the 'new_client_entry' includes the new nickname. +Application must understand that the 'old_client_entry' pointer becomes +invalid after returning from the function. +SilcClientEntry old_client_entry, +SilcClientEntry new_client_entry +
SILC_NOTIFY_TYPE_CMODE_CHANGE +Sent when channel's mode has changed. The 'changer_id_type' +is used to check what type of pointer the 'changer_entry' is. For +SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for +SILC_ID_CHANNEL SilcChannelEntry. The 'mode' is the mode mask after the +change. The 'hmac_name' argument may be NULL. +SilcIdType changer_id_type, void *changer_entry, +SilcUInt32 mode, NULL, char *hmac_name, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_CUMODE_CHANGE +Sent when a users mode on a channel has changed. The 'changer_id_type' +is used to check what type of pointer the 'changer_entry' is. For +SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for +SILC_ID_CHANNEL SilcChannelEntry. The 'mode' is the mode mask after the +change. The 'target_client' is the client whose mode was changed. +SilcIdType changer_id_type, void *changer_entry, +SilcUInt32 mode, SilcClientEntry target_client, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_MOTD +Message of the Day from the server. +char *motd +
SILC_NOTIFY_TYPE_CHANNEL_CHANGE +Sent when a channel's Channel ID changes. It is possible that channel's +ID changes and this notify is sent by the server when this happens. +Usually application does not need to handle this notify type and may +safely ignore it when received. +SilcChannelEntry channel +
SILC_NOTIFY_TYPE_SERVER_SIGNOFF +Sent when a server quits the network. The 'clients' is an array +SilcClientEntry pointers of size of 'clients_count'. Each client in the +entry is one client signing off from the SILC network. +NULL, SilcClientEntry *clients, SilcUInt32 clients_count +
SILC_NOTIFY_TYPE_KICKED +Sent when a client (possibly our client) is kicked from a channel. The +'kick_message' may be NULL. If our client was kicked then 'kicked' is our +local SilcClientEntry pointer. +SilcClientEntry kicked, char *kick_message, +SilcClientEntry kicker, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_KILLED +Sent when a client (possibly our client) is killed from the network. The +'kill_message' may be NULL. If our client was killed then 'killed' is our +local SilcClientEntry pointer. The 'killer_type' is used to check what +type of pointer the 'killer' is. For SILC_ID_CLIENT SilcClientEntry, for +SILC_ID_SERVER SilcServerEntry and for SILC_ID_CHANNEL SilcChannelEntry. +SilcClientEntry killed, char *kill_message, +SilcIdType killer_type, void *killer, SilcChannelEntry channel +
SILC_NOTIFY_TYPE_ERROR +Sent when an error occurs while handling some operation (except command) +from the client. Application usually cannot handle this notify type and +may safely ignore it. +SilcStatus error +
SILC_NOTIFY_TYPE_WATCH +Sent to notify some status change of a client we are wathing. The +SILC_COMMAND_WATCH is used to manage clients we are wathing and this +notify type is used to deliver information about that client. If the +client just changed nickname the 'new_nickname' includes the new nickname. +Otherwise this pointer is NULL. The 'user_mode' is the client's mode in +the SILC network. The 'notification' contains the notify type that +happened for the 'watched_client' (for example +SILC_NOTIFY_TYPE_NICK_CHANGE if the client changed their nickname). +SilcClientEntry watched_client, char *new_nickname, +SilcUInt32 user_mode, SilcNotifyType notification +
+ +
 
+SILC protocol defines some additional notify types but those notify types +are not delivered to the application. Some of those notify types are only +delivered between servers and routers and clients never receive them. +Only the notify types listed above are delivered to application. diff --git a/lib/silcclient/DIRECTORY b/lib/silcclient/DIRECTORY index 7fa78c18..631fee27 100644 --- a/lib/silcclient/DIRECTORY +++ b/lib/silcclient/DIRECTORY @@ -2,6 +2,7 @@ @LIBRARY=SILC Client Library @FILENAME=silcclientlib.html @LINK=silcclient_using.html:Using SILC Client Library +@LINK=silcclient_using.html:notify Client Operation Arguments @LINK=silcclient.html:Client Library Interface --> -- 2.43.0