[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