Added silc_packet_stream_is_udp

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

diff --git a/lib/silccore/silcpacket.h b/lib/silccore/silcpacket.h
index d926bcb3ce5f99097c92baae40efb94139842c7d..6cceb8774a1f50cf64526d5df2dced90c549427c 100644 (file)
--- a/lib/silccore/silcpacket.h
+++ b/lib/silccore/silcpacket.h
@@ -388,7 +388,7 @@ void silc_packet_engine_stop(SilcPacketEngine engine);
  *    Create new packet stream and use the `stream' as underlaying stream.
  *    Usually the `stream' would be a socket stream, but it can be any
  *    stream.  After this function returns, packets can immediately be
- *    sent to or received from the stream.
+ *    sent to and received from the stream.
  *
  * NOTES
  *
@@ -406,6 +406,58 @@ SilcPacketStream silc_packet_stream_create(SilcPacketEngine engine,
                                           SilcSchedule schedule,
                                           SilcStream stream);
 
+/****f* silccore/SilcPacketAPI/silc_packet_stream_add_remote
+ *
+ * SYNOPSIS
+ *
+ *    SilcPacketStream silc_packet_stream_add_remote(SilcPacketStream stream,
+ *                                                   const char *remote_ip,
+ *                                                   SilcUInt16 remote_port,
+ *                                                   SilcPacket packet);
+ *
+ * DESCRIPTION
+ *
+ *    This function is used to add remote receivers in packet stream `stream'
+ *    that has UDP/IP socket stream as the underlaying stream.  This function
+ *    cannot be used with other type of streams.  This returns new packet
+ *    stream context that can be used to send to and receive packets from
+ *    the specified remote IP and remote port, or NULL on error.  The `stream'
+ *    is the actual stream that is used to send and receive the data.
+ *
+ *    When the parent `stream' receives packets from remote IP address
+ *    and port that does not have its own remote packet stream, it returns
+ *    the packet to the packet callback set for `stream'.  The sender's
+ *    IP address and port can then be retrieved by using the
+ *    silc_packet_get_sender function and to create new packet stream by
+ *    calling this function.  After that, all packets from that IP address
+ *    and port will be received by the new packet stream.
+ *
+ *    If the `packet' is non-NULL it will be injected into the new packet
+ *    stream as soon as the scheduler associated with `stream' schedules
+ *    new tasks.  It can be used to inject an incoming packet to the stream.
+ *
+ *    This interface is for connectionless UDP streams.  If it is possible
+ *    to create connected stream it should be done for performance reasons.
+ *
+ * EXAMPLE
+ *
+ *    // Create parent packet stream, it can receive packets from anywhere
+ *    listener = silc_net_udp_connect("0.0.0.0", 500, NULL, 0, schedule);
+ *    parent = silc_packet_stream_create(engine, schedule, listener);
+ *
+ *    ...
+ *    // Received a packet to the parent stream, get the sender information.
+ *    silc_packet_get_sender(packet, &ip, &port);
+ *
+ *    // Create new packet stream for this remote location.
+ *    remote = silc_packet_stream_add_remote(parent, ip, port, packet);
+ *
+ ***/
+SilcPacketStream silc_packet_stream_add_remote(SilcPacketStream stream,
+                                              const char *remote_ip,
+                                              SilcUInt16 remote_port,
+                                              SilcPacket packet);
+
 /****f* silccore/SilcPacketAPI/silc_packet_stream_destroy
  *
  * SYNOPSIS
@@ -415,7 +467,7 @@ SilcPacketStream silc_packet_stream_create(SilcPacketEngine engine,
  * DESCRIPTION
  *
  *    Destroy packet stream and the underlaying stream.  This will also
- *    send end of stream to the underlaying stream.
+ *    close and destroy the underlaying stream.
  *
  ***/
 void silc_packet_stream_destroy(SilcPacketStream stream);
@@ -560,6 +612,40 @@ void silc_packet_stream_unlink(SilcPacketStream stream,
                               SilcPacketCallbacks *callbacks,
                               void *callback_context);
 
+/****f* silccore/SilcPacketAPI/silc_packet_get_sender
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_packet_stream_is_udp(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ *    Returns TRUE if the packet stream indicated by `stream' is using
+ *    UDP transport.
+ *
+ ***/
+SilcBool silc_packet_stream_is_udp(SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_get_sender
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_packet_get_sender(SilcPacket packet,
+ *                                    const char **sender_ip,
+ *                                    SilcUInt16 *sender_port);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the packet sender's IP address and port from UDP packet
+ *    indicated by `packet'.  This can be called only from the packet
+ *    callback to retrieve the information of the packet's sender.  Returns
+ *    FALSE if the information is not available.
+ *
+ ***/
+SilcBool silc_packet_get_sender(SilcPacket packet,
+                               const char **sender_ip,
+                               SilcUInt16 *sender_port);
+
 /****f* silccore/SilcPacketAPI/silc_packet_stream_ref
  *
  * SYNOPSIS