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