lib/doc/notifyargs.html

   1 <big><b>SilcNotifyType Arguments</b></big>
   2
   3 <br />&nbsp;<br />
   4 The SILC Client Library 'notify' client operation (which is part of the
   5 <a href="silcclient-SilcClientOperations.html">
   6 SilcClientOperation</a> callback functions) returns different kind of
   7 notifications from the SILC server to the SILC client.  The 'notify'
   8 client operation implementation has a variable argument list to deliver
   9 <a href="silcnotify-SilcNotifyType.html">SilcNotifyType</a> type specific arguments to the application.  This document
  10 describes these arguments for all notify types to help SILC client
  11 software developers to handle the incoming notifications.
  12
  13 <br />&nbsp;<br />&nbsp;<br />
  14 <b>notify Client Library operation</b>
  15
  16 <br />&nbsp;<br />
  17 The 'notify' client operation callback function prototype is as follows:
  18
  19 <br />&nbsp;<br />
  20 <tt>
  21 &nbsp;&nbsp;void (*notify)(SilcClient client, SilcClientConnection conn,
  22 SilcNotifyType type, ...);
  23 </tt>
  24
  25 <br />&nbsp;<br />
  26 The first argument 'client' is the SILC Client Library context, the `conn'
  27 is the context for the connection to the remote server, and the `type' is
  28 the notify type enumeration sent by the server.  Rest of the arguments are
  29 `type' specific and implementation should handle them by the
  30 SilcNotifyType for example in a <tt>switch</tt> statement.  The notify
  31 types are defined in lib/silccore/silcnotify.h header file.  A short
  32 example:
  33
  34 <br />&nbsp;<br />
  35 <tt>
  36 &nbsp;&nbsp;switch(type)<br />
  37 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
  38 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_NOTIFY_TYPE_NONE:<br />
  39 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  40 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  41 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_NOTIFY_TYPE_INVITE:<br />
  42 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  43 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  44 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_NOTIFY_TYPE_JOIN:<br />
  45 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  46 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  47 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  48 &nbsp;&nbsp;&nbsp;&nbsp;}
  49 </tt>
  50
  51 <br />&nbsp;<br />&nbsp;<br />
  52 <b>Arguments</b>
  53
  54 <br />&nbsp;<br />
  55 The following table describes all notify types and arguments that the
  56 client library sends in the 'notify' client operation to the application.
  57 By default all arguments that the library sends to application are valid
  58 pointers.  However, it is possible that some pointers may be NULL.  If
  59 this is the case it is separately mentioned that the argument may be NULL.
  60 In this case application must ignore that argument.  The SilcNotifyType
  61 arguments per notify type is as follows:
  62
  63 <br />&nbsp;<br />
  64 <table border="1" width="100%" cellpadding="3" cellspacing="0">
  65
  66 <tr>
  67 <td><small>Name</td>
  68 <td><small>Description</td>
  69 <td width="50%"><small>Variable Arguments</td>
  70 </tr>
  71
  72 <tr>
  73 <td><small>SILC_NOTIFY_TYPE_NONE</td>
  74 <td><small>
  75 A message from server that usually does not include any critical
  76 information.  Application may ignore this or display it for the user.
  77 The 'message' argument may be NULL.
  78 </td>
  79 <td width="50%"><small>char *message</td>
  80 </tr>
  81
  82 <tr>
  83 <td><small>SILC_NOTIFY_TYPE_INVITE</td>
  84 <td><small>
  85 Sent to the client if the user is invited on a channel. The 'channel_name'
  86 argument may be NULL.
  87 </td>
  88 <td width="50%"><small>SilcClientChannel channel, char *channel_name,
  89 SilcClientEntry inviter
  90 </td>
  91 </tr>
  92
  93 <tr>
  94 <td><small>SILC_NOTIFY_TYPE_JOIN</td>
  95 <td><small>
  96 Sent when someone joins to a channel.
  97 </td>
  98 <td width="50%"><small>SilcClientEntry joining_client, SilcChannelEntry channel
  99 </td>
 100 </tr>
 101
 102 <tr>
 103 <td><small>SILC_NOTIFY_TYPE_LEAVE</td>
 104 <td><small>
 105 Sent when someone leaves (parts) the channel.
 106 </td>
 107 <td width="50%"><small>SilcClientEntry leaving_client, SilcChannelEntry channel
 108 </td>
 109 </tr>
 110
 111 <tr>
 112 <td><small>SILC_NOTIFY_TYPE_SIGNOFF</td>
 113 <td><small>
 114 Sent when someone signoff the SILC network.  The 'signoff_message' may be
 115 NULL.  The 'leaving_client' SilcClientEntry may be incomplete and contain
 116 NULL pointers, application must check it's pointers before attempting to
 117 display for example nickname information.
 118 </td>
 119 <td width="50%"><small>SilcClientEntry signoff_client, char *signoff_message
 120 </td>
 121 </tr>
 122
 123 <tr>
 124 <td><small>SILC_NOTIFY_TYPE_TOPIC_SET</td>
 125 <td><small>
 126 Sent when the topic of a channel is set/changed.  The 'setter_id_type'
 127 is used to check what type of pointer the 'setter_entry' is.  For
 128 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 129 SILC_ID_CHANNEL SilcChannelEntry.
 130 </td>
 131 <td width="50%"><small>SilcIdType setter_id_type, void *setter_entry,
 132 char *topic, SilcChannelEntry channel
 133 </td>
 134 </tr>
 135
 136 <tr>
 137 <td><small>SILC_NOTIFY_TYPE_NICK_CHANGE</td>
 138 <td><small>
 139 Sent when someone changes their nickname.  The 'old_client_entry' includes
 140 the old nickname and the 'new_client_entry' includes the new nickname.
 141 Application must understand that the 'old_client_entry' pointer becomes
 142 invalid after returning from the function.
 143 </td>
 144 <td width="50%"><small>SilcClientEntry old_client_entry,
 145 SilcClientEntry new_client_entry
 146 </td>
 147 </tr>
 148
 149 <tr>
 150 <td><small>SILC_NOTIFY_TYPE_CMODE_CHANGE</td>
 151 <td><small>
 152 Sent when channel's mode has changed. The 'changer_id_type'
 153 is used to check what type of pointer the 'changer_entry' is.  For
 154 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 155 SILC_ID_CHANNEL SilcChannelEntry.  The 'mode' is the mode mask after the
 156 change.  The 'hmac_name' argument may be NULL.
 157 </td>
 158 <td width="50%"><small>SilcIdType changer_id_type, void *changer_entry,
 159 SilcUInt32 mode, NULL, char *hmac_name, SilcChannelEntry channel
 160 </td>
 161 </tr>
 162
 163 <tr>
 164 <td><small>SILC_NOTIFY_TYPE_CUMODE_CHANGE</td>
 165 <td><small>
 166 Sent when a users mode on a channel has changed. The 'changer_id_type'
 167 is used to check what type of pointer the 'changer_entry' is.  For
 168 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 169 SILC_ID_CHANNEL SilcChannelEntry.  The 'mode' is the mode mask after the
 170 change.  The 'target_client' is the client whose mode was changed.
 171 </td>
 172 <td width="50%"><small>SilcIdType changer_id_type, void *changer_entry,
 173 SilcUInt32 mode, SilcClientEntry target_client, SilcChannelEntry channel
 174 </td>
 175 </tr>
 176
 177 <tr>
 178 <td><small>SILC_NOTIFY_TYPE_MOTD</td>
 179 <td><small>
 180 Message of the Day from the server.
 181 </td>
 182 <td width="50%"><small>char *motd
 183 </td>
 184 </tr>
 185
 186 <tr>
 187 <td><small>SILC_NOTIFY_TYPE_CHANNEL_CHANGE</td>
 188 <td><small>
 189 Sent when a channel's Channel ID changes.  It is possible that channel's
 190 ID changes and this notify is sent by the server when this happens.
 191 Usually application does not need to handle this notify type and may
 192 safely ignore it when received.
 193 </td>
 194 <td width="50%"><small>SilcChannelEntry channel
 195 </td>
 196 </tr>
 197
 198 <tr>
 199 <td><small>SILC_NOTIFY_TYPE_SERVER_SIGNOFF</td>
 200 <td><small>
 201 Sent when a server quits the network.  The 'clients' is an array
 202 SilcClientEntry pointers of size of 'clients_count'.  Each client in the
 203 entry is one client signing off from the SILC network.
 204 </td>
 205 <td width="50%"><small>NULL, SilcClientEntry *clients, SilcUInt32 clients_count
 206 </td>
 207 </tr>
 208
 209 <tr>
 210 <td><small>SILC_NOTIFY_TYPE_KICKED</td>
 211 <td><small>
 212 Sent when a client (possibly our client) is kicked from a channel.  The
 213 'kick_message' may be NULL.  If our client was kicked then 'kicked' is our
 214 local SilcClientEntry pointer.
 215 </td>
 216 <td width="50%"><small>SilcClientEntry kicked, char *kick_message,
 217 SilcClientEntry kicker, SilcChannelEntry channel
 218 </td>
 219 </tr>
 220
 221 <tr>
 222 <td><small>SILC_NOTIFY_TYPE_KILLED</td>
 223 <td><small>
 224 Sent when a client (possibly our client) is killed from the network.  The
 225 'kill_message' may be NULL.  If our client was killed then 'killed' is our
 226 local SilcClientEntry pointer.  The 'killer_type' is used to check what
 227 type of pointer the 'killer' is.  For SILC_ID_CLIENT SilcClientEntry, for
 228 SILC_ID_SERVER SilcServerEntry and for SILC_ID_CHANNEL SilcChannelEntry.
 229 </td>
 230 <td width="50%"><small>SilcClientEntry killed, char *kill_message,
 231 SilcIdType killer_type, void *killer, SilcChannelEntry channel
 232 </td>
 233 </tr>
 234
 235 <tr>
 236 <td><small>SILC_NOTIFY_TYPE_ERROR</td>
 237 <td><small>
 238 Sent when an error occurs while handling some operation (except command)
 239 from the client.  Application usually cannot handle this notify type and
 240 may safely ignore it.
 241 </td>
 242 <td width="50%"><small>SilcStatus error
 243 </td>
 244 </tr>
 245
 246 <tr>
 247 <td><small>SILC_NOTIFY_TYPE_WATCH</td>
 248 <td><small>
 249 Sent to notify some status change of a client we are wathing.  The
 250 SILC_COMMAND_WATCH is used to manage clients we are wathing and this
 251 notify type is used to deliver information about that client.  If the
 252 client just changed nickname the 'new_nickname' includes the new nickname.
 253 Otherwise this pointer is NULL.  The 'user_mode' is the client's mode in
 254 the SILC network.  The 'notification' contains the notify type that
 255 happened for the 'watched_client' (for example
 256 SILC_NOTIFY_TYPE_NICK_CHANGE if the client changed their nickname).
 257 </td>
 258 <td width="50%"><small>SilcClientEntry watched_client, char *new_nickname,
 259 SilcUInt32 user_mode, SilcNotifyType notification
 260 </td>
 261 </tr>
 262
 263 </table>
 264
 265 <br />&nbsp;<br />
 266 SILC protocol defines some additional notify types but those notify types
 267 are not delivered to the application.  Some of those notify types are only
 268 delivered between servers and routers and clients never receive them.
 269 Only the notify types listed above are delivered to application.