From: Wim Taymans <wim.taymans@collabora.co.uk>
Date: Tue, 26 May 2009 13:37:18 +0000 (+0200)
Subject: netbuffer: document that the port is network order
X-Git-Tag: 1.19.3~511^2~9614
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=796f8e2f76add7778fd81a030f34af089fcbbd08;p=platform%2Fupstream%2Fgstreamer.git

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.
---

diff --git a/gst-libs/gst/netbuffer/gstnetbuffer.c b/gst-libs/gst/netbuffer/gstnetbuffer.c
index 2348594..98e01bf 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