Packet streams: make packet handling callback pointers read only.

[silc.git] / lib / silccore / silcpacket.h

diff --git a/lib/silccore/silcpacket.h b/lib/silccore/silcpacket.h
index 240c446d97ad9cd720918cc06daa019a2c7ad92b..0caf10d8c21bc8b54c245e3311265b8b785e6e9a 100644 (file)
--- a/lib/silccore/silcpacket.h
+++ b/lib/silccore/silcpacket.h
@@ -34,8 +34,6 @@
 #ifndef SILCPACKET_H
 #define SILCPACKET_H
 
-/* XXX many of these could go to silcpacket_i.h */
-
 /* Maximum packet length */
 #define SILC_PACKET_MAX_LEN 0xffff
 
@@ -117,7 +115,7 @@ typedef SilcUInt8 SilcPacketFlags;
 #define SILC_PACKET_FLAG_ACK              0x10    /* Acknowledge packet */
 
 /* Impelemntation specific flags */
-#define SILC_PACKET_FLAG_LONG_PAD         0x12    /* Use maximum padding */
+#define SILC_PACKET_FLAG_LONG_PAD         0x20    /* Use maximum padding */
 /***/
 
 /****s* silccore/SilcPacketAPI/SilcPacketEngine
@@ -363,7 +361,7 @@ typedef struct {
  ***/
 SilcPacketEngine
 silc_packet_engine_start(SilcRng rng, SilcBool router,
-                        SilcPacketCallbacks *callbacks,
+                        const SilcPacketCallbacks *callbacks,
                         void *callback_context);
 
 /****f* silccore/SilcPacketAPI/silc_packet_engine_stop
@@ -402,11 +400,30 @@ const char *silc_packet_error_string(SilcPacketError error);
  * DESCRIPTION
  *
  *    Returns list of packet streams added to the packet engine.  The caller
- *    must free the list with silc_dlist_uninit.
+ *    must free the list with silc_packet_engine_free_streams_list.
+ *
+ * NOTES
+ *
+ *    This function may also return disconnected and destroyed streams.  The
+ *    caller should use silc_packet_stream_is_valid to check if the stream
+ *    is valid.
  *
  ***/
 SilcDList silc_packet_engine_get_streams(SilcPacketEngine engine);
 
+/****f* silccore/SilcPacketAPI/silc_packet_engine_free_streams_list
+ *
+ * SYNOPSIS
+ *
+ *    void silc_packet_engine_free_streams_list(SilcDList streams);
+ *
+ * DESCRIPTION
+ *
+ *    Free's the streams list returned by silc_packet_engine_get_streams.
+ *
+ ***/
+void silc_packet_engine_free_streams_list(SilcDList streams);
+
 /****f* silccore/SilcPacketAPI/silc_packet_stream_create
  *
  * SYNOPSIS
@@ -634,7 +651,7 @@ SilcStream silc_packet_stream_get_stream(SilcPacketStream stream);
  *
  ***/
 SilcBool silc_packet_stream_link(SilcPacketStream stream,
-                                SilcPacketCallbacks *callbacks,
+                                const SilcPacketCallbacks *callbacks,
                                 void *callback_context,
                                 int priority, ...);
 
@@ -654,7 +671,7 @@ SilcBool silc_packet_stream_link(SilcPacketStream stream,
  *
  ***/
 void silc_packet_stream_unlink(SilcPacketStream stream,
-                              SilcPacketCallbacks *callbacks,
+                              const SilcPacketCallbacks *callbacks,
                               void *callback_context);
 
 /****f* silccore/SilcPacketAPI/SilcPacketWrapCoder
@@ -915,7 +932,7 @@ SilcBool silc_packet_set_ids(SilcPacketStream stream,
                             SilcIdType src_id_type, const void *src_id,
                             SilcIdType dst_id_type, const void *dst_id);
 
-/****f* silccore/SilcPacketAPI/silc_packet_set_ids
+/****f* silccore/SilcPacketAPI/silc_packet_get_ids
  *
  * SYNOPSIS
  *
@@ -1065,23 +1082,30 @@ SilcBool silc_packet_send_va_ext(SilcPacketStream stream,
                                 SilcIdType dst_id_type, void *dst_id,
                                 SilcCipher cipher, SilcHmac hmac, ...);
 
-/****f* silccore/SilcPacketAPI/silc_packet_wait
+/****f* silccore/SilcPacketAPI/silc_packet_wait_init
  *
  * SYNOPSIS
  *
- *    void *silc_packet_wait_init(SilcPacketStream stream, ...);
+ *    void *silc_packet_wait_init(SilcPacketStream stream,
+ *                                const SilcID *source_id, ...);
  *
  * DESCRIPTION
  *
  *    Initializes a packet waiter for the packet stream `stream' and
  *    for the variable argument list of packet types.  The function
  *    silc_packet_wait can be used to block the thread until a packet
- *    has been received.  This function is used to initialize the waiting
- *    and to give the list of packet types that caller wish to receive.
- *    The variable argument list must end with -1.  To receive all
- *    packets use SILC_PACKET_ANY.  Returns a context that must be given
- *    to the silc_packet_wait function as argument.  Returns NULL on
- *    error.  To uninitialize the waiting call silc_packet_wait_uninit.
+ *    has been received.
+ *
+ *    This function is used to initialize the waiting and to give the list
+ *    of packet types that caller wish to receive.  The variable argument
+ *    list must end with -1.  To receive all packets use SILC_PACKET_ANY.
+ *    If the `source_id' is non-NULL then only packets of the specified
+ *    type from the specified `source_id' are received.  If it is NULL
+ *    then the packet source is ignored.
+ *
+ *    Returns a context that must be given to the silc_packet_wait function
+ *    as argument.  Returns NULL on error.  To uninitialize the waiting
+ *    call silc_packet_wait_uninit.
  *
  * NOTES
  *
@@ -1093,12 +1117,12 @@ SilcBool silc_packet_send_va_ext(SilcPacketStream stream,
  *    void *waiter;
  *
  *    // Will wait for private message packets
- *    waiter = silc_packet_wait_init(stream,
+ *    waiter = silc_packet_wait_init(stream, NULL,
  *                                   SILC_PACKET_PRIVATE_MESSAGE, -1);
  *
- *
  ***/
-void *silc_packet_wait_init(SilcPacketStream stream, ...);
+void *silc_packet_wait_init(SilcPacketStream stream,
+                           const SilcID *source_id, ...);
 
 /****f* silccore/SilcPacketAPI/silc_packet_wait_uninit
  *