Added blocking support for wrapped packet stream.

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

diff --git a/lib/silccore/silcpacket.h b/lib/silccore/silcpacket.h
index b9ecfef3fb0f0cd6f35c7b1c77704ffab940626c..7ddabff11732bfbfc7b7c6fe856756738b1847f7 100644 (file)
--- a/lib/silccore/silcpacket.h
+++ b/lib/silccore/silcpacket.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 1997 - 2006 Pekka Riikonen
+  Copyright (C) 1997 - 2007 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
@@ -85,6 +85,7 @@ typedef SilcUInt8 SilcPacketType;
 #define SILC_PACKET_RESUME_ROUTER        26      /* Backup router resume */
 #define SILC_PACKET_FTP                  27      /* File Transfer */
 #define SILC_PACKET_RESUME_CLIENT        28      /* Client resume */
+#define SILC_PACKET_ACK                  29      /* Acknowledgement */
 
 #define SILC_PACKET_PRIVATE              200     /* Private range start  */
 #define SILC_PACKET_MAX                  255     /* RESERVED */
@@ -611,6 +612,48 @@ void silc_packet_stream_unlink(SilcPacketStream stream,
                               SilcPacketCallbacks *callbacks,
                               void *callback_context);
 
+/****f* silccore/SilcPacketAPI/silc_packet_stream_wrap
+ *
+ * SYNOPSIS
+ *
+ *    SilcStream silc_packet_stream_wrap(SilcPacketStream stream,
+ *                                       SilcPacketType type,
+ *                                       SilcPacketFlags flags,
+ *                                       SilcBool blocking_mode);
+ *
+ * DESCRIPTION
+ *
+ *    Wraps the packet stream indicated by `stream' into a SilcStream for
+ *    the packet type indicated by `type' with packet flags indicated by
+ *    `flags'.  The returned SilcStream can be used to read and write the
+ *    specified SILC packets with the specified packet flags, by calling
+ *    silc_stream_read and silc_stream_write, respectively.  The returned
+ *    stream can be destroyed by calling silc_stream_destroy.  It does not
+ *    destroy the wrapped packet stream.
+ *
+ *    If the `blocking_mode' mode is TRUE then the silc_stream_read and
+ *    silc_stream_write may block the calling process or thread until SILC
+ *    packet is read or written.  If it is FALSE the stream is in non-blocking
+ *    mode and the calls never block.  The returned stream is thread-safe and
+ *    packets may be read and written in multi-threaded environment.
+ *
+ *    In non-blocking mode the silc_stream_set_notifier must be called before
+ *    the returned stream can be used to read packets.  The stream status
+ *    SILC_STREAM_CAN_READ will be returned to the notifier callback to
+ *    indicate that a packet is ready for reading.  Calling silc_stream_read
+ *    once returns one complete SILC packet data payload (which is of type of
+ *    `type').
+ *
+ *    The returned SilcStream can be used as any normal stream and all
+ *    SilcStream API functions may be used with the stream.  This returns
+ *    NULL on error.
+ *
+ ***/
+SilcStream silc_packet_stream_wrap(SilcPacketStream stream,
+                                  SilcPacketType type,
+                                  SilcPacketFlags flags,
+                                  SilcBool blocking_mode);
+
 /****f* silccore/SilcPacketAPI/silc_packet_get_sender
  *
  * SYNOPSIS