updates

[crypto.git] / lib / silccore / silcprivate.h

diff --git a/lib/silccore/silcprivate.h b/lib/silccore/silcprivate.h
index 79e00b89f64cd4a7c684771fd97239a37952659e..0f274f2439962970689e4f0efeec85deaf94fc4c 100644 (file)
--- a/lib/silccore/silcprivate.h
+++ b/lib/silccore/silcprivate.h
@@ -1,43 +1,136 @@
-/*
-
-  silcprivate.h
-
-  Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
-  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
-  GNU General Public License for more details.
-
-*/
+/****h* silccore/silcprivate.h
+ *
+ * NAME
+ *
+ * silcprivate.h
+ *
+ * COPYRIGHT
+ *
+ * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ *
+ * 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
+ * GNU General Public License for more details.
+ *
+ * DESCRIPTION
+ *
+ * Implementation of the SILC Private Message Payload that is used to
+ * deliver private messages.
+ *
+ ***/
 
 #ifndef SILCPRIVATE_H
 #define SILCPRIVATE_H
 
-/* Forward declaration of the Private Message Payload. */
+/****s* silccore/SilcPrivateAPI/SilcPrivateMessagePayload
+ *
+ * NAME
+ * 
+ *    typedef struct SilcPrivateMessagePayloadStruct 
+ *                     *SilcPrivateMessagePayload;
+ *
+ *
+ * DESCRIPTION
+ *
+ *    This context is the actual Private Message Payload and is allocated
+ *    by silc_private_message_payload_parse and given as argument usually
+ *    to all silc_private_message_* functions.  It is freed by the
+ *    silc_private_message_payload_free function.
+ *
+ ***/
 typedef struct SilcPrivateMessagePayloadStruct *SilcPrivateMessagePayload;
 
 /* Prototypes */
 
+/****f* silccore/SilcPrivateAPI/silc_private_message_payload_parse
+ *
+ * SYNOPSIS
+ *
+ *    SilcPrivateMessagePayload 
+ *    silc_private_message_payload_parse(SilcBuffer buffer, SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ *    Parses private message payload returning new private mesage payload 
+ *    structure. This also decrypts the message if the `cipher' is provided.
+ *
+ ***/
 SilcPrivateMessagePayload 
 silc_private_message_payload_parse(SilcBuffer buffer, SilcCipher cipher);
+
+/****f* silccore/SilcPrivateAPI/silc_private_message_payload_encode
+ *
+ * SYNOPSIS
+ *
+ *    SilcBuffer silc_private_message_payload_encode(uint16 flags,
+ *                                                   uint16 data_len,
+ *                                                   unsigned char *data,
+ *                                                   SilcCipher cipher);
+ *
+ * DESCRIPTION
+ *
+ *    Encodes private message payload into a buffer and returns it.  If
+ *    the cipher is provided the packet is also encrypted here.  It is provided
+ *    if the private message private keys are used.
+ *
+ ***/
 SilcBuffer silc_private_message_payload_encode(uint16 flags,
                                               uint16 data_len,
                                               unsigned char *data,
                                               SilcCipher cipher);
+
+/****f* silccore/SilcPrivateAPI/silc_private_message_payload_free
+ *
+ * SYNOPSIS
+ *
+ *    void 
+ *    silc_private_message_payload_free(SilcPrivateMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ *    Frees Private Message Payload
+ *
+ ***/
 void silc_private_message_payload_free(SilcPrivateMessagePayload payload);
+
+/****f* silccore/SilcPrivateAPI/silc_private_message_get_flags
+ *
+ * SYNOPSIS
+ *
+ *    uint16 
+ *    silc_private_message_get_flags(SilcPrivateMessagePayload payload);
+ *
+ * DESCRIPTION
+ *
+ *    Returns flags from the payload. Message flags may indicate some
+ *    status of the message. Private message flags are equivalent to the
+ *    channel message flags.
+ *
+ ***/
 uint16 
 silc_private_message_get_flags(SilcPrivateMessagePayload payload);
-unsigned char *
-silc_private_message_get_nickname(SilcPrivateMessagePayload payload,
-                                 uint32 *nickname_len);
+
+/****f* silccore/SilcPrivateAPI/silc_private_message_get_message
+ *
+ * SYNOPSIS
+ *
+ *    unsigned char *
+ *    silc_private_message_get_nickname(SilcPrivateMessagePayload payload,
+ *                                      uint32 *nickname_len);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the actual private message. The caller must not free it.
+ *
+ ***/
 unsigned char *
 silc_private_message_get_message(SilcPrivateMessagePayload payload,
                                 uint32 *message_len);