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
  86 argument may be NULL but the `channel_name' is always provided.
  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.  This is also sent whenever you join
  97 a channel, in addition of receiving SILC_COMMAND_JOIN command reply.
  98 </td>
  99 <td width="50%"><small>SilcClientEntry joining_client, SilcChannelEntry channel
 100 </td>
 101 </tr>
 102
 103 <tr>
 104 <td><small>SILC_NOTIFY_TYPE_LEAVE</td>
 105 <td><small>
 106 Sent when someone leaves (parts) the channel.
 107 </td>
 108 <td width="50%"><small>SilcClientEntry leaving_client, SilcChannelEntry channel
 109 </td>
 110 </tr>
 111
 112 <tr>
 113 <td><small>SILC_NOTIFY_TYPE_SIGNOFF</td>
 114 <td><small>
 115 Sent when someone signoff the SILC network.  The 'signoff_message' may be
 116 NULL.  The 'leaving_client' SilcClientEntry may be incomplete and contain
 117 NULL pointers, application must check it's pointers before attempting to
 118 display for example nickname information.
 119 </td>
 120 <td width="50%"><small>SilcClientEntry signoff_client, char *signoff_message
 121 </td>
 122 </tr>
 123
 124 <tr>
 125 <td><small>SILC_NOTIFY_TYPE_TOPIC_SET</td>
 126 <td><small>
 127 Sent when the topic of a channel is set/changed.  The 'setter_id_type'
 128 is used to check what type of pointer the 'setter_entry' is.  For
 129 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 130 SILC_ID_CHANNEL SilcChannelEntry.
 131 </td>
 132 <td width="50%"><small>SilcIdType setter_id_type, void *setter_entry,
 133 char *topic, SilcChannelEntry channel
 134 </td>
 135 </tr>
 136
 137 <tr>
 138 <td><small>SILC_NOTIFY_TYPE_NICK_CHANGE</td>
 139 <td><small>
 140 Sent when someone changes their nickname.  The 'client_entry' is the client
 141 whose nickname is changed.  The `old_nickname' is the old nickname and the
 142 `new_nickname' is the new nickname.  It has been already updated into the
 143 `client_entry'.
 144 </td>
 145 <td width="50%"><small>SilcClientEntry client_entry, const char *old_nickname,
 146 const char *new_nickname
 147 </td>
 148 </tr>
 149
 150 <tr>
 151 <td><small>SILC_NOTIFY_TYPE_CMODE_CHANGE</td>
 152 <td><small>
 153 Sent when channel's mode has changed. The 'changer_id_type'
 154 is used to check what type of pointer the 'changer_entry' is.  For
 155 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 156 SILC_ID_CHANNEL SilcChannelEntry.  The 'mode' is the mode mask after the
 157 change.  The `cipher_name' is the cipher set for the channel.
 158 The `hmac_name' is the HMAC set for the channel.  The `passphrase'
 159 is the passphrase that was set for the channel.  The `founder_key' is the
 160 founder's public key when it was set for the channel.  The `channel_pubkeys'
 161 is a list of SilcArgumentDecodedList contexts each containing one channel
 162 public key.  The library will free the list automatically.  The arguments
 163 'cipher_name', 'hmac_name', 'passphrase', 'founder_key' and 'channel_pubkeys'
 164 may be NULL.
 165 </td>
 166 <td width="50%"><small>SilcIdType changer_id_type, void *changer_entry,
 167 SilcUInt32 mode, char *cipher_name, char *hmac_name, char *passphrase,
 168 SilcPublicKey founder_key, SilcDList channel_pubkeys, SilcChannelEntry channel
 169 </td>
 170 </tr>
 171
 172 <tr>
 173 <td><small>SILC_NOTIFY_TYPE_CUMODE_CHANGE</td>
 174 <td><small>
 175 Sent when a users mode on a channel has changed. The 'changer_id_type'
 176 is used to check what type of pointer the 'changer_entry' is.  For
 177 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 178 SILC_ID_CHANNEL SilcChannelEntry.  The 'mode' is the mode mask after the
 179 change.  The 'target_client' is the client whose mode was changed.
 180 </td>
 181 <td width="50%"><small>SilcIdType changer_id_type, void *changer_entry,
 182 SilcUInt32 mode, SilcClientEntry target_client, SilcChannelEntry channel
 183 </td>
 184 </tr>
 185
 186 <tr>
 187 <td><small>SILC_NOTIFY_TYPE_MOTD</td>
 188 <td><small>
 189 Message of the Day from the server.
 190 </td>
 191 <td width="50%"><small>char *motd
 192 </td>
 193 </tr>
 194
 195 <tr>
 196 <td><small>SILC_NOTIFY_TYPE_CHANNEL_CHANGE</td>
 197 <td><small>
 198 Sent when a channel's Channel ID changes.  It is possible that channel's
 199 ID changes and this notify is sent by the server when this happens.
 200 Usually application does not need to handle this notify type and may
 201 safely ignore it when received.
 202 </td>
 203 <td width="50%"><small>SilcChannelEntry channel
 204 </td>
 205 </tr>
 206
 207 <tr>
 208 <td><small>SILC_NOTIFY_TYPE_SERVER_SIGNOFF</td>
 209 <td><small>
 210 Sent when a server quits the network.  The 'clients' is a list of
 211 SilcClientEntry pointers.  Each client in the entry is one client signing
 212 off from the SILC network.  The library will free the list.  The `server'
 213 is the quitting server, and it is NULL if the server isn't cached in the
 214 client library.
 215 </td>
 216 <td width="50%"><small>SilcServerEntry server, SilcDList clients
 217 </td>
 218 </tr>
 219
 220 <tr>
 221 <td><small>SILC_NOTIFY_TYPE_KICKED</td>
 222 <td><small>
 223 Sent when a client (possibly our client) is kicked from a channel.  The
 224 'kick_message' may be NULL.  If our client was kicked then 'kicked' is our
 225 local SilcClientEntry pointer.
 226 </td>
 227 <td width="50%"><small>SilcClientEntry kicked, char *kick_message,
 228 SilcClientEntry kicker, SilcChannelEntry channel
 229 </td>
 230 </tr>
 231
 232 <tr>
 233 <td><small>SILC_NOTIFY_TYPE_KILLED</td>
 234 <td><small>
 235 Sent when a client (possibly our client) is killed from the network.  The
 236 'kill_message' may be NULL.  If our client was killed then 'killed' is our
 237 local SilcClientEntry pointer.  The 'killer_type' is used to check what
 238 type of pointer the 'killer' is.  For SILC_ID_CLIENT SilcClientEntry, for
 239 SILC_ID_SERVER SilcServerEntry and for SILC_ID_CHANNEL SilcChannelEntry.
 240 </td>
 241 <td width="50%"><small>SilcClientEntry killed, char *kill_message,
 242 SilcIdType killer_type, void *killer, SilcChannelEntry channel
 243 </td>
 244 </tr>
 245
 246 <tr>
 247 <td><small>SILC_NOTIFY_TYPE_ERROR</td>
 248 <td><small>
 249 Sent when an error occurs while handling some operation (except command)
 250 from the client.  Application usually cannot handle this notify type and
 251 may safely ignore it.
 252 </td>
 253 <td width="50%"><small>SilcStatus error
 254 </td>
 255 </tr>
 256
 257 <tr>
 258 <td><small>SILC_NOTIFY_TYPE_WATCH</td>
 259 <td><small>
 260 Sent to notify some status change of a client we are wathing.  The
 261 SILC_COMMAND_WATCH is used to manage clients we are wathing and this
 262 notify type is used to deliver information about that client.  If the
 263 client just changed nickname the 'new_nickname' includes the new nickname.
 264 Otherwise this pointer is NULL.  The 'user_mode' is the client's mode in
 265 the SILC network.  The 'notification' contains the notify type that
 266 happened for the 'watched_client' (for example
 267 SILC_NOTIFY_TYPE_NICK_CHANGE if the client changed their nickname).
 268 </td>
 269 <td width="50%"><small>SilcClientEntry watched_client, char *new_nickname,
 270 SilcUInt32 user_mode, SilcNotifyType notification, SilcPublicKey
 271 public_key
 272 </td>
 273 </tr>
 274
 275 </table>
 276
 277 <br />&nbsp;<br />
 278 SILC protocol defines some additional notify types but those notify types
 279 are not delivered to the application.  Some of those notify types are only
 280 delivered between servers and routers and clients never receive them.
 281 Only the notify types listed above are delivered to application.