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.
 213 </td>
 214 <td width="50%"><small>NULL, SilcClientEntry *clients, SilcUInt32 clients_count
 215 </td>
 216 </tr>
 217
 218 <tr>
 219 <td><small>SILC_NOTIFY_TYPE_KICKED</td>
 220 <td><small>
 221 Sent when a client (possibly our client) is kicked from a channel.  The
 222 'kick_message' may be NULL.  If our client was kicked then 'kicked' is our
 223 local SilcClientEntry pointer.
 224 </td>
 225 <td width="50%"><small>SilcClientEntry kicked, char *kick_message,
 226 SilcClientEntry kicker, SilcChannelEntry channel
 227 </td>
 228 </tr>
 229
 230 <tr>
 231 <td><small>SILC_NOTIFY_TYPE_KILLED</td>
 232 <td><small>
 233 Sent when a client (possibly our client) is killed from the network.  The
 234 'kill_message' may be NULL.  If our client was killed then 'killed' is our
 235 local SilcClientEntry pointer.  The 'killer_type' is used to check what
 236 type of pointer the 'killer' is.  For SILC_ID_CLIENT SilcClientEntry, for
 237 SILC_ID_SERVER SilcServerEntry and for SILC_ID_CHANNEL SilcChannelEntry.
 238 </td>
 239 <td width="50%"><small>SilcClientEntry killed, char *kill_message,
 240 SilcIdType killer_type, void *killer, SilcChannelEntry channel
 241 </td>
 242 </tr>
 243
 244 <tr>
 245 <td><small>SILC_NOTIFY_TYPE_ERROR</td>
 246 <td><small>
 247 Sent when an error occurs while handling some operation (except command)
 248 from the client.  Application usually cannot handle this notify type and
 249 may safely ignore it.
 250 </td>
 251 <td width="50%"><small>SilcStatus error
 252 </td>
 253 </tr>
 254
 255 <tr>
 256 <td><small>SILC_NOTIFY_TYPE_WATCH</td>
 257 <td><small>
 258 Sent to notify some status change of a client we are wathing.  The
 259 SILC_COMMAND_WATCH is used to manage clients we are wathing and this
 260 notify type is used to deliver information about that client.  If the
 261 client just changed nickname the 'new_nickname' includes the new nickname.
 262 Otherwise this pointer is NULL.  The 'user_mode' is the client's mode in
 263 the SILC network.  The 'notification' contains the notify type that
 264 happened for the 'watched_client' (for example
 265 SILC_NOTIFY_TYPE_NICK_CHANGE if the client changed their nickname).
 266 </td>
 267 <td width="50%"><small>SilcClientEntry watched_client, char *new_nickname,
 268 SilcUInt32 user_mode, SilcNotifyType notification, SilcPublicKey
 269 public_key
 270 </td>
 271 </tr>
 272
 273 </table>
 274
 275 <br />&nbsp;<br />
 276 SILC protocol defines some additional notify types but those notify types
 277 are not delivered to the application.  Some of those notify types are only
 278 delivered between servers and routers and clients never receive them.
 279 Only the notify types listed above are delivered to application.