[asterisk-commits] mmichelson: branch group/v6-new r270297 - /team/group/v6-new/include/asterisk/

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Mon Jun 14 15:49:21 CDT 2010


Author: mmichelson
Date: Mon Jun 14 15:49:18 2010
New Revision: 270297

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=270297
Log:
Doxygenify netsock2.h more.

Mostly added \brief, \since, \retval, and \param tags. In addition,
I found a few function prototypes that were listed multiple times, so
I removed the duplicates.


Modified:
    team/group/v6-new/include/asterisk/netsock2.h

Modified: team/group/v6-new/include/asterisk/netsock2.h
URL: http://svnview.digium.com/svn/asterisk/team/group/v6-new/include/asterisk/netsock2.h?view=diff&rev=270297&r1=270296&r2=270297
==============================================================================
--- team/group/v6-new/include/asterisk/netsock2.h (original)
+++ team/group/v6-new/include/asterisk/netsock2.h Mon Jun 14 15:49:18 2010
@@ -31,7 +31,7 @@
 
 #include <netinet/in.h>
 
-/**
+/*!
  * Values for address families that we support. This is reproduced from socket.h
  * because we do not want users to include that file. Only netsock2.c should
  * ever include socket.h.
@@ -42,7 +42,7 @@
 	AST_AF_INET6	= 10,
 };
 
-/**
+/*!
  * Socket address structure. The first member is big enough to contain addresses
  * of any family. The second member contains the length (in bytes) used in the
  * first member.
@@ -52,27 +52,47 @@
  */
 struct ast_sockaddr {
 	struct sockaddr_storage	 ss;
-	socklen_t		 len;
+	socklen_t len;
 };
 
-/**
- * \return 1 if \a addr is null, 0 otherwise.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Checks if the ast_sockaddr is null. "null" in this sense essentially
+ * means uninitialized, or having a 0 length.
+ *
+ * \param addr Pointer to the ast_sockaddr we wish to check
+ * \retval 1 \a addr is null
+ * \retval 0 \a addr is non-null.
  */
 static inline int ast_sockaddr_isnull(const struct ast_sockaddr *addr)
 {
 	return addr->len == 0;
 }
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Sets address \a addr to null.
+ *
+ * \retval void
  */
 static inline void ast_sockaddr_setnull(struct ast_sockaddr *addr)
 {
 	addr->len = 0;
 }
 
-/**
- * Copy socket address \a src to \a dst.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Copies the data from one ast_sockaddr to another
+ *
+ * \param dst The destination ast_sockaddr
+ * \param src The source ast_sockaddr
+ * \retval void
  */
 static inline void ast_sockaddr_copy(struct ast_sockaddr *dst,
 		const struct ast_sockaddr *src)
@@ -81,40 +101,51 @@
 	dst->len = src->len;
 };
 
-/**
- * Compares two socket addresses. Returns -1 if \a a is lexicographically
- * smaller than \a b, 0 if they are equal, and 1 otherwise.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Compares two ast_sockaddr structures
+ *
+ * \retval -1 \a a is lexicographically smaller than \a b
+ * \retval 0 \a a is equal to \a b
+ * \retval 1 \a b is lexicographically smaller than \a a
  */
 int ast_sockaddr_cmp(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
 
-/**
- * Compares two addresses. Returns -1 if \a a is lexicographically
- * smaller than \a b, 0 if they are equal, and 1 otherwise.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Compares the addresses of two ast_sockaddr structures.
+ *
+ * \retval -1 \a a is lexicographically smaller than \a b
+ * \retval 0 \a a is equal to \a b
+ * \retval 1 \a b is lexicographically smaller than \a a
  */
 int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
 
-/**
- * Compares two addresses. Returns -1 if \a a is lexicographically
- * smaller than \a b, 0 if they are equal, and 1 otherwise.
- */
-int ast_sockaddr_cmp_addr(const struct ast_sockaddr *a, const struct ast_sockaddr *b);
-
-/**
- * Convert a socket address to a string. This will be of the form a.b.c.d:xyz
- * for IPv4 and [a:b:c:...:d]:xyz for IPv6.
- *
- * This function is thread-safe. The returned string is on static
- * thread-specific storage.
- */
 #define AST_SOCKADDR_STR_ADDR		1
 #define AST_SOCKADDR_STR_PORT		2
 #define AST_SOCKADDR_STR_BRACKETS	4
 #define AST_SOCKADDR_STR_HOST		AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_BRACKETS
 #define AST_SOCKADDR_STR_DEFAULT	AST_SOCKADDR_STR_ADDR | AST_SOCKADDR_STR_PORT
 
-/**
- * Convert a socket address to a string with the following formats:
- *
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Convert a socket address to a string.
+ * 
+ * \details
+ * This will be of the form a.b.c.d:xyz
+ * for IPv4 and [a:b:c:...:d]:xyz for IPv6.
+ *
+ * This function is thread-safe. The returned string is on static
+ * thread-specific storage.
+ *
+ * \param addr The input to be stringified
+ * \param format one of the following:
  * AST_SOCKADDR_STR_DEFAULT:
  *    a.b.c.d:xyz for IPv4
  *    [a:b:c:...:d]:xyz for IPv6.
@@ -125,46 +156,72 @@
  *    a.b.c.d for IPv4
  *    [a:b:c:...:d] for IPv6.
  * AST_SOCKADDR_STR_PORT: port only
- *
- * This function is thread-safe. The returned string is on static
- * thread-specific storage.
+ * \retval "(null)" \a addr is null
+ * \retval "" An error occurred during processing
+ * \retval string The stringified form of the address
  */
 char *ast_sockaddr_stringify_fmt(const struct ast_sockaddr *addr, int format);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around ast_sockaddr_stringify_fmt() with default format
+ *
+ * \return same as ast_sockaddr_stringify_fmt()
  */
 static inline char *ast_sockaddr_stringify(const struct ast_sockaddr *addr)
 {
 	return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_DEFAULT);
 }
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only
+ *
+ * \return same as ast_sockaddr_stringify_fmt()
  */
 static inline char *ast_sockaddr_stringify_addr(const struct ast_sockaddr *addr)
 {
 	return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_ADDR);
 }
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around ast_sockaddr_stringify_fmt() to return an address only,
  * suitable for a URL (with brackets for IPv6).
+ *
+ * \return same as ast_sockaddr_stringify_fmt()
  */
 static inline char *ast_sockaddr_stringify_host(const struct ast_sockaddr *addr)
 {
 	return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_HOST);
 }
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around ast_sockaddr_stringify_fmt() to return a port only
+ *
+ * \return same as ast_sockaddr_stringify_fmt()
  */
 static inline char *ast_sockaddr_stringify_port(const struct ast_sockaddr *addr)
 {
 	return ast_sockaddr_stringify_fmt(addr, AST_SOCKADDR_STR_PORT);
 }
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Parse an IPv4 or IPv6 address string.
+ *
+ * \details
  * Parses a string containing an IPv4 or IPv6 address followed by an optional
  * port (separated by a colon) into a struct ast_sockaddr. The allowed formats
  * are the following:
@@ -177,16 +234,25 @@
  *
  * Host names are NOT allowed.
  *
+ * \param[out] addr The resulting ast_sockaddr
+ * \param str The string to parse
  * \param flags If set to zero, a port MAY be present. If set to
  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
  * port MUST NOT be present.
  *
- * \return 1 on success, 0 on failure.
+ * \retval 1 Success
+ * \retval 0 Failure
  */
 int ast_sockaddr_parse(struct ast_sockaddr *addr, const char *str, int flags);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Parses a string with an IPv4 or IPv6 address and place results into an array
+ *
+ * \details
  * Parses a string containing a host name or an IPv4 or IPv6 address followed 
  * by an optional port (separated by a colon).  The result is returned into a 
  * array of struct ast_sockaddr. Allowed formats for str are the following:
@@ -199,6 +265,8 @@
  * [a:b:c:...:d]
  * [a:b:c:...:d]:port
  *
+ * \param[out] addrs The resulting array of ast_sockaddrs
+ * \param str The string to parse
  * \param flags If set to zero, a port MAY be present. If set to
  * PARSE_PORT_IGNORE, a port MAY be present but will be ignored. If set to
  * PARSE_PORT_REQUIRE, a port MUST be present. If set to PARSE_PORT_FORBID, a
@@ -207,138 +275,242 @@
  * \param family Only addresses of the given family will be returned. Use 0 or
  * AST_SOCKADDR_UNSPEC to get addresses of all families.
  *
- * \return On success, returns the number of elements in addrs array. 0 on failure.
+ * \retval 0 Failure
+ * \retval non-zero The number of elements in addrs array.
  */
 int ast_sockaddr_resolve(struct ast_sockaddr **addrs, const char *str,
 			 int flags, int family);
 
-/**
- * Returns the port number of a socket address, or zero if the address is null.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Get the port number of a socket address.
  *
  * \warning Do not use this function unless you really know what you are doing.
  * And "I want the port number" is not knowing what you are doing.
+ *
+ * \retval 0 Address is null
+ * \retval non-zero The port number of the ast_sockaddr
  */
 uint16_t ast_sockaddr_port(const struct ast_sockaddr *addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Sets the port number of a socket address.
  *
  * \warning Do not use this function unless you really know what you are doing.
  * And "I want the port number" is not knowing what you are doing.
+ *
+ * \param addr Address on which to set the port
+ * \param port The port you wish to set the address to use
+ * \retval void
  */
 void ast_sockaddr_set_port(struct ast_sockaddr *addr, uint16_t port);
 
-/**
- * Returns the IPv4 address as a 32-bit value in network order.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Get an IPv4 address of an ast_sockaddr
  *
  * \warning You should rarely need this function. Only use if you know what
  * you're doing.
+ * \return IPv4 address in network byte order
  */
 uint32_t ast_sockaddr_ipv4(const struct ast_sockaddr *addr);
 
-/**
- * Returns 1 if this is an IPv4 address, 0 otherwise. IPv4-mapped IPv6 addresses
- * return 0.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Determine if the address is an IPv4 address
  *
  * \warning You should rarely need this function. Only use if you know what
  * you're doing.
+ * \retval 1 This is an IPv4 address
+ * \retval 0 This is an IPv6 or IPv4-mapped IPv6 address
  */
 int ast_sockaddr_is_ipv4(const struct ast_sockaddr *addr);
 
-/**
- * Returns 1 if this is an IPv4-mapped IPv6 address, 0 otherwise.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Determine if this is an IPv4-mapped IPv6 address
  *
  * \warning You should rarely need this function. Only use if you know what
  * you're doing.
+ *
+ * \retval 1 This is an IPv4-mapped IPv6 address.
+ * \retval 0 This is not an IPv4-mapped IPv6 address.
  */
 int ast_sockaddr_is_ipv4_mapped(const struct ast_sockaddr *addr);
 
-/**
- * Returns 1 if this is an IPv6 address, 0 otherwise. IPv4-mapped IPv6 addresses
- * return 1.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Determine if this is an IPv6 address
  *
  * \warning You should rarely need this function. Only use if you know what
  * you're doing.
+ *
+ * \retval 1 This is an IPv6 or IPv4-mapped IPv6 address.
+ * \retval 0 This is an IPv4 address.
  */
 int ast_sockaddr_is_ipv6(const struct ast_sockaddr *addr);
 
-
-/**
- * Returns 1 if this is an "any" address, such as 0.0.0.0 for IPv4 and :: for
- * IPv6. The port number is ignored.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Determine if the address type is unspecified, or "any" address.
+ *
+ * \details
+ * For IPv4, this would be the address 0.0.0.0, and for IPv6,
+ * this would be the address ::. The port number is ignored.
+ *
+ * \retval 1 This is an "any" address
+ * \retval 0 This is not an "any" address
  */
 int ast_sockaddr_is_any(const struct ast_sockaddr *addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Computes a hash value from the address. The port is ignored.
+ *
+ * \retval 0 Unknown address family
+ * \retval other A 32-bit hash derived from the address
  */
 int ast_sockaddr_hash(const struct ast_sockaddr *addr);
 
-/**
- * Returns 1 if this is an "any" address, such as 0.0.0.0 for IPv4 and :: for
- * IPv6. The port number is ignored.
- */
-int ast_sockaddr_is_any(const struct ast_sockaddr *addr);
-
-/**
- * Computes a hash value from the address. The port is ignored.
- */
-int ast_sockaddr_hash(const struct ast_sockaddr *addr);
-
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around accept(2) that uses struct ast_sockaddr.
+ *
+ * \details
+ * For parameter and return information, see the man page for
+ * accept(2).
  */
 int ast_accept(int sockfd, struct ast_sockaddr *addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around bind(2) that uses struct ast_sockaddr.
+ *
+ * \details
+ * For parameter and return information, see the man page for
+ * bind(2).
  */
 int ast_bind(int sockfd, const struct ast_sockaddr *addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around connect(2) that uses struct ast_sockaddr.
+ *
+ * \details
+ * For parameter and return information, see the man page for
+ * connect(2).
  */
 int ast_connect(int sockfd, const struct ast_sockaddr *addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around getsockname(2) that uses struct ast_sockaddr.
+ *
+ * \details
+ * For parameter and return information, see the man page for
+ * getsockname(2).
  */
 int ast_getsockname(int sockfd, struct ast_sockaddr *addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around recvfrom(2) that uses struct ast_sockaddr.
+ *
+ * \details
+ * For parameter and return information, see the man page for
+ * recvfrom(2).
  */
 ssize_t ast_recvfrom(int sockfd, void *buf, size_t len, int flags,
 		     struct ast_sockaddr *src_addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Wrapper around sendto(2) that uses ast_sockaddr.
+ * 
+ * \details
+ * For parameter and
+ * return information, see the man page for sendto(2)
  */
 ssize_t ast_sendto(int sockfd, const void *buf, size_t len, int flags,
 		   const struct ast_sockaddr *dest_addr);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Set type of service
+ * 
+ * \details
  * Set ToS ("Type of Service for IPv4 and "Traffic Class for IPv6) and
  * CoS (Linux's SO_PRIORITY)
+ *
+ * \param sockfd File descriptor for socket on which to set the parameters
+ * \param tos The type of service for the socket
+ * \param cos The cost of service for the socket
+ * \param desc A text description of the socket in question.
+ * \retval 0 Success
+ * \retval -1 Error, with errno set to an appropriate value
  */
 int ast_set_qos(int sockfd, int tos, int cos, const char *desc);
 
-/**
+/*!
  * These are backward compatibility functions that may be used by subsystems
  * that have not yet been converted to IPv6. They will be removed when all
  * subsystems are IPv6-ready.
  */
 /*@{*/
 
-/**
- * Converts a struct ast_sockaddr to a struct sockaddr_in. Returns nonzero on
- * success, zero otherwise.
+/*!
+ * \since 1.8
+ *
+ * \brief
+ * Converts a struct ast_sockaddr to a struct sockaddr_in.
+ *
+ * \param addr The ast_sockaddr to convert
+ * \param[out] sin The resulting sockaddr_in struct
+ * \retval nonzero Success
+ * \retval zero Failure
  */
 int ast_sockaddr_to_sin(const struct ast_sockaddr *addr,
 			struct sockaddr_in *sin);
 
-/**
+/*!
+ * \since 1.8
+ *
+ * \brief
  * Converts a struct sockaddr_in to a struct ast_sockaddr.
+ * 
+ * \param sin The sockaddr_in to convert
+ * \return an ast_sockaddr structure
  */
 struct ast_sockaddr ast_sockaddr_from_sin(struct sockaddr_in sin);
 




More information about the asterisk-commits mailing list