From 796f8e2f76add7778fd81a030f34af089fcbbd08 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wim.taymans@collabora.co.uk>
Date: Tue, 26 May 2009 15:37:18 +0200
Subject: [PATCH] netbuffer: document that the port is network order

Document the fact that we store the port number in network order in
GstNetAddress and that the caller should byteswap appropriately.
---
 gst-libs/gst/netbuffer/gstnetbuffer.c | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/gst-libs/gst/netbuffer/gstnetbuffer.c b/gst-libs/gst/netbuffer/gstnetbuffer.c
index 2348594a10..98e01bf0bc 100644
--- a/gst-libs/gst/netbuffer/gstnetbuffer.c
+++ b/gst-libs/gst/netbuffer/gstnetbuffer.c
@@ -137,6 +137,9 @@ gst_netbuffer_new (void)
  * @port: a port number to set.
  *
  * Set @naddr with the IPv4 @address and @port pair.
+ *
+ * Note that @port must be expressed in network byte order, use g_htons() to convert
+ * it to network byte order order.
  */
 void
 gst_netaddress_set_ip4_address (GstNetAddress * naddr, guint32 address,
@@ -156,6 +159,9 @@ gst_netaddress_set_ip4_address (GstNetAddress * naddr, guint32 address,
  * @port: a port number to set.
  *
  * Set @naddr with the IPv6 @address and @port pair.
+ *
+ * Note that @port must be expressed in network byte order, use g_htons() to convert
+ * it to network byte order order.
  */
 void
 gst_netaddress_set_ip6_address (GstNetAddress * naddr, guint8 address[16],
@@ -193,6 +199,9 @@ gst_netaddress_get_net_type (GstNetAddress * naddr)
  * Get the IPv4 address stored in @naddr into @address. This function requires
  * that the address type of @naddr is of type #GST_NET_TYPE_IP4.
  *
+ * Note that @port is expressed in network byte order, use g_ntohs() to convert
+ * it to host order.
+ *
  * Returns: TRUE if the address could be retrieved.
  */
 gboolean
@@ -223,6 +232,9 @@ gst_netaddress_get_ip4_address (GstNetAddress * naddr, guint32 * address,
  * If @naddr is of type GST_NET_TYPE_IP4, the transitional IP6 address is
  * returned.
  *
+ * Note that @port is expressed in network byte order, use g_ntohs() to convert
+ * it to host order.
+ *
  * Returns: TRUE if the address could be retrieved.
  */
 gboolean
@@ -258,6 +270,9 @@ gst_netaddress_get_ip6_address (GstNetAddress * naddr, guint8 address[16],
  *
  * Get just the address bytes stored in @naddr into @address.
  *
+ * Note that @port is expressed in network byte order, use g_ntohs() to convert
+ * it to host order.
+ *
  * Returns: number of bytes actually copied
  *
  * Since: 0.10.22
@@ -296,6 +311,9 @@ gst_netaddress_get_address_bytes (GstNetAddress * naddr, guint8 address[16],
  *
  * Set just the address bytes stored in @naddr into @address.
  *
+ * Note that @port must be expressed in network byte order, use g_htons() to convert
+ * it to network byte order order.
+ *
  * Returns: number of bytes actually copied
  *
  * Since: 0.10.22