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.  Note that this notify is not
 143 delivered when user changes its own nickname.
 144 </td>
 145 <td width="50%"><small>SilcClientEntry old_client_entry,
 146 SilcClientEntry new_client_entry
 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 an Argument List Payload where each argument is Public Key Payload
 162 containing one channel public key.  The arguments 'cipher_name', 'hmac_name',
 163 'passphrase', 'founder_key' and 'channel_pubkeys' may be NULL.
 164 </td>
 165 <td width="50%"><small>SilcIdType changer_id_type, void *changer_entry,
 166 SilcUInt32 mode, char *cipher_name, char *hmac_name, char *passphrase,
 167 SilcPublicKey founder_key, SilcBuffer channel_pubkeys, SilcChannelEntry channel
 168 </td>
 169 </tr>
 170
 171 <tr>
 172 <td><small>SILC_NOTIFY_TYPE_CUMODE_CHANGE</td>
 173 <td><small>
 174 Sent when a users mode on a channel has changed. The 'changer_id_type'
 175 is used to check what type of pointer the 'changer_entry' is.  For
 176 SILC_ID_CLIENT SilcClientEntry, for SILC_ID_SERVER SilcServerEntry and for
 177 SILC_ID_CHANNEL SilcChannelEntry.  The 'mode' is the mode mask after the
 178 change.  The 'target_client' is the client whose mode was changed.
 179 </td>
 180 <td width="50%"><small>SilcIdType changer_id_type, void *changer_entry,
 181 SilcUInt32 mode, SilcClientEntry target_client, SilcChannelEntry channel
 182 </td>
 183 </tr>
 184
 185 <tr>
 186 <td><small>SILC_NOTIFY_TYPE_MOTD</td>
 187 <td><small>
 188 Message of the Day from the server.
 189 </td>
 190 <td width="50%"><small>char *motd
 191 </td>
 192 </tr>
 193
 194 <tr>
 195 <td><small>SILC_NOTIFY_TYPE_CHANNEL_CHANGE</td>
 196 <td><small>
 197 Sent when a channel's Channel ID changes.  It is possible that channel's
 198 ID changes and this notify is sent by the server when this happens.
 199 Usually application does not need to handle this notify type and may
 200 safely ignore it when received.
 201 </td>
 202 <td width="50%"><small>SilcChannelEntry channel
 203 </td>
 204 </tr>
 205
 206 <tr>
 207 <td><small>SILC_NOTIFY_TYPE_SERVER_SIGNOFF</td>
 208 <td><small>
 209 Sent when a server quits the network.  The 'clients' is an array
 210 SilcClientEntry pointers of size of 'clients_count'.  Each client in the
 211 entry is one client signing off from the SILC network.
 212 </td>
 213 <td width="50%"><small>NULL, SilcClientEntry *clients, SilcUInt32 clients_count
 214 </td>
 215 </tr>
 216
 217 <tr>
 218 <td><small>SILC_NOTIFY_TYPE_KICKED</td>
 219 <td><small>
 220 Sent when a client (possibly our client) is kicked from a channel.  The
 221 'kick_message' may be NULL.  If our client was kicked then 'kicked' is our
 222 local SilcClientEntry pointer.
 223 </td>
 224 <td width="50%"><small>SilcClientEntry kicked, char *kick_message,
 225 SilcClientEntry kicker, SilcChannelEntry channel
 226 </td>
 227 </tr>
 228
 229 <tr>
 230 <td><small>SILC_NOTIFY_TYPE_KILLED</td>
 231 <td><small>
 232 Sent when a client (possibly our client) is killed from the network.  The
 233 'kill_message' may be NULL.  If our client was killed then 'killed' is our
 234 local SilcClientEntry pointer.  The 'killer_type' is used to check what
 235 type of pointer the 'killer' is.  For SILC_ID_CLIENT SilcClientEntry, for
 236 SILC_ID_SERVER SilcServerEntry and for SILC_ID_CHANNEL SilcChannelEntry.
 237 </td>
 238 <td width="50%"><small>SilcClientEntry killed, char *kill_message,
 239 SilcIdType killer_type, void *killer, SilcChannelEntry channel
 240 </td>
 241 </tr>
 242
 243 <tr>
 244 <td><small>SILC_NOTIFY_TYPE_ERROR</td>
 245 <td><small>
 246 Sent when an error occurs while handling some operation (except command)
 247 from the client.  Application usually cannot handle this notify type and
 248 may safely ignore it.
 249 </td>
 250 <td width="50%"><small>SilcStatus error
 251 </td>
 252 </tr>
 253
 254 <tr>
 255 <td><small>SILC_NOTIFY_TYPE_WATCH</td>
 256 <td><small>
 257 Sent to notify some status change of a client we are wathing.  The
 258 SILC_COMMAND_WATCH is used to manage clients we are wathing and this
 259 notify type is used to deliver information about that client.  If the
 260 client just changed nickname the 'new_nickname' includes the new nickname.
 261 Otherwise this pointer is NULL.  The 'user_mode' is the client's mode in
 262 the SILC network.  The 'notification' contains the notify type that
 263 happened for the 'watched_client' (for example
 264 SILC_NOTIFY_TYPE_NICK_CHANGE if the client changed their nickname).
 265 </td>
 266 <td width="50%"><small>SilcClientEntry watched_client, char *new_nickname,
 267 SilcUInt32 user_mode, SilcNotifyType notification
 268 </td>
 269 </tr>
 270
 271 </table>
 272
 273 <br />&nbsp;<br />
 274 SILC protocol defines some additional notify types but those notify types
 275 are not delivered to the application.  Some of those notify types are only
 276 delivered between servers and routers and clients never receive them.
 277 Only the notify types listed above are delivered to application.