/*
-
+
silcnotify.h
-
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
- Copyright (C) 1997 - 2000 Pekka Riikonen
-
+
+ Author: Pekka Riikonen <priikone@silcnet.org>
+
+ Copyright (C) 1997 - 2001 Pekka Riikonen
+
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
-
+
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
*/
+/****h* silccore/SILC Notify Interface
+ *
+ * DESCRIPTION
+ *
+ * Implementation of the Notify Payload. Notify Payload is used usually
+ * by servers to send different kind of important notify messages to other
+ * servers and to clients.
+ *
+ ***/
+
#ifndef SILCNOTIFY_H
#define SILCNOTIFY_H
-/* Forward declarations */
+/****s* silccore/SilcNotifyAPI/SilcNotifyPayload
+ *
+ * NAME
+ *
+ * typedef struct SilcNotifyPayloadStruct *SilcNotifyPayload;
+ *
+ * DESCRIPTION
+ *
+ * This context is the actual Notify Payload and is allocated
+ * by silc_notify_payload_parse and given as argument usually to
+ * all silc_notify_payload_* functions. It is freed by the
+ * silc_notify_payload_free function.
+ *
+ ***/
typedef struct SilcNotifyPayloadStruct *SilcNotifyPayload;
-/* Type definition of notify type */
-typedef uint16 SilcNotifyType;
+/****d* silccore/SilcNotifyAPI/SilcNotifyType
+ *
+ * NAME
+ *
+ * typedef SilcUInt16 SilcNotifyType;
+ *
+ * DESCRIPTION
+ *
+ * The notify type definition and all of the notify types.
+ *
+ * SOURCE
+ */
+typedef SilcUInt16 SilcNotifyType;
/* SILC notify types. Server may send these notify types to client to
notify of some action. */
-#define SILC_NOTIFY_TYPE_NONE 0 /* no specific type */
-#define SILC_NOTIFY_TYPE_INVITE 1 /* invites/invite list change */
-#define SILC_NOTIFY_TYPE_JOIN 2 /* "has joined channel" */
-#define SILC_NOTIFY_TYPE_LEAVE 3 /* "has left channel" */
-#define SILC_NOTIFY_TYPE_SIGNOFF 4 /* "signoff" */
-#define SILC_NOTIFY_TYPE_TOPIC_SET 5 /* "topic has been changed" */
-#define SILC_NOTIFY_TYPE_NICK_CHANGE 6 /* "has changed nickname" */
-#define SILC_NOTIFY_TYPE_CMODE_CHANGE 7 /* "has changed channel mode" */
-#define SILC_NOTIFY_TYPE_CUMODE_CHANGE 8 /* "has change mode" */
-#define SILC_NOTIFY_TYPE_MOTD 9 /* message of the day */
+#define SILC_NOTIFY_TYPE_NONE 0 /* no specific type */
+#define SILC_NOTIFY_TYPE_INVITE 1 /* invites/invite list change */
+#define SILC_NOTIFY_TYPE_JOIN 2 /* "has joined channel" */
+#define SILC_NOTIFY_TYPE_LEAVE 3 /* "has left channel" */
+#define SILC_NOTIFY_TYPE_SIGNOFF 4 /* "signoff" */
+#define SILC_NOTIFY_TYPE_TOPIC_SET 5 /* "topic has been changed" */
+#define SILC_NOTIFY_TYPE_NICK_CHANGE 6 /* "has changed nickname" */
+#define SILC_NOTIFY_TYPE_CMODE_CHANGE 7 /* "has changed channel mode" */
+#define SILC_NOTIFY_TYPE_CUMODE_CHANGE 8 /* "has change mode" */
+#define SILC_NOTIFY_TYPE_MOTD 9 /* message of the day */
#define SILC_NOTIFY_TYPE_CHANNEL_CHANGE 10 /* Channel's ID has changed */
#define SILC_NOTIFY_TYPE_SERVER_SIGNOFF 11 /* Server quitting SILC */
#define SILC_NOTIFY_TYPE_KICKED 12 /* Kicked from channel */
#define SILC_NOTIFY_TYPE_KILLED 13 /* Killed from the network */
#define SILC_NOTIFY_TYPE_UMODE_CHANGE 14 /* user mode was changed */
#define SILC_NOTIFY_TYPE_BAN 15 /* ban list change */
+#define SILC_NOTIFY_TYPE_ERROR 16 /* error notify */
+/***/
/* Prototypes */
-SilcNotifyPayload silc_notify_payload_parse(SilcBuffer buffer);
-SilcBuffer silc_notify_payload_encode(SilcNotifyType type, uint32 argc,
+
+/****f* silccore/SilcNotifyAPI/silc_notify_payload_parse
+ *
+ * SYNOPSIS
+ *
+ * SilcNotifyPayload
+ * silc_notify_payload_parse(const unsigned char *payload,
+ * SilcUInt32 payload_len);
+ *
+ * DESCRIPTION
+ *
+ * Parse notify payload buffer and return data into payload structure.
+ * The `buffer' is the raw payload data.
+ *
+ ***/
+SilcNotifyPayload silc_notify_payload_parse(const unsigned char *payload,
+ SilcUInt32 payload_len);
+
+/****f* silccore/SilcNotifyAPI/silc_notify_payload_encode
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_notify_payload_encode(SilcNotifyType type,
+ * SilcUInt32 argc,
+ * va_list ap);
+ *
+ * DESCRIPTION
+ *
+ * Encode notify payload with variable argument list. If `argc' is > 0
+ * argument payloads will be associated to the notify payload. Variable
+ * arguments must be {unsigned char *, SilcUInt32 (len)}.
+ *
+ ***/
+SilcBuffer silc_notify_payload_encode(SilcNotifyType type, SilcUInt32 argc,
va_list ap);
+
+/****f* silccore/SilcNotifyAPI/silc_notify_payload_encode_args
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_notify_payload_encode_args(SilcNotifyType type,
+ * SilcUInt32 argc,
+ * SilcBuffer args);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_notify_payload_encode but takes arguments from the `args'
+ * encoded Argument Payload buffer.
+ *
+ ***/
SilcBuffer silc_notify_payload_encode_args(SilcNotifyType type,
- uint32 argc,
+ SilcUInt32 argc,
SilcBuffer args);
+
+/****f* silccore/SilcNotifyAPI/silc_notify_payload_free
+ *
+ * SYNOPSIS
+ *
+ * void silc_notify_payload_free(SilcNotifyPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Frees the Notify Payload and all data in it.
+ *
+ ***/
void silc_notify_payload_free(SilcNotifyPayload payload);
+
+/****f* silccore/SilcNotifyAPI/silc_notify_get_type
+ *
+ * SYNOPSIS
+ *
+ * SilcNotifyType silc_notify_get_type(SilcNotifyPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the notify type from the payload.
+ *
+ ***/
SilcNotifyType silc_notify_get_type(SilcNotifyPayload payload);
-uint32 silc_notify_get_arg_num(SilcNotifyPayload payload);
+
+/****f* silccore/SilcNotifyAPI/silc_notify_get_arg_num
+ *
+ * SYNOPSIS
+ *
+ * SilcUInt32 silc_notify_get_arg_num(SilcNotifyPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the number of the arguments associated with the Notify Payload.
+ *
+ ***/
+SilcUInt32 silc_notify_get_arg_num(SilcNotifyPayload payload);
+
+/****f* silccore/SilcNotifyAPI/silc_notify_get_args
+ *
+ * SYNOPSIS
+ *
+ * SilcArgumentPayload silc_notify_get_args(SilcNotifyPayload payload);
+ *
+ * DESCRIPTION
+ *
+ * Return the Argument Payload containing the arguments from the
+ * Notify Payload. The caller must not free it.
+ *
+ ***/
SilcArgumentPayload silc_notify_get_args(SilcNotifyPayload payload);
#endif