[asterisk-commits] mmichelson: branch group/dns_naptr r433572 - /team/group/dns_naptr/tests/

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Fri Mar 27 09:23:50 CDT 2015


Author: mmichelson
Date: Fri Mar 27 09:23:46 2015
New Revision: 433572

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=433572
Log:
Add doxygen to NAPTR test file.

Modified:
    team/group/dns_naptr/tests/test_dns_naptr.c

Modified: team/group/dns_naptr/tests/test_dns_naptr.c
URL: http://svnview.digium.com/svn/asterisk/team/group/dns_naptr/tests/test_dns_naptr.c?view=diff&rev=433572&r1=433571&r2=433572
==============================================================================
--- team/group/dns_naptr/tests/test_dns_naptr.c (original)
+++ team/group/dns_naptr/tests/test_dns_naptr.c Fri Mar 27 09:23:46 2015
@@ -50,6 +50,21 @@
 	0x00, 0x00,
 };
 
+/*!
+ * \brief Generate a DNS header and write it to a buffer
+ *
+ * The DNS header is the first part of a DNS request or response. In our
+ * case, the only part of the header that a test can affect is the number
+ * of answers. The rest of the DNS header is based on hard-coded values.
+ *
+ * There is no buffer size passed to this function since we provide
+ * the data ourselves and have sized the buffer to be way larger
+ * than necessary for the tests.
+ * 
+ * \param num_records The number of DNS records in this DNS response
+ * \param buf The buffer to write the header into
+ * \retval The number of bytes written to the buffer
+ */
 static int generate_dns_header(unsigned short num_records, char *buf)
 {
 	unsigned short net_num_records = htons(num_records);
@@ -74,6 +89,20 @@
 	0x00, 0x01,
 };
 
+/*!
+ * \brief Generate a DNS question and write it to a buffer
+ *
+ * The DNS question is the second part of a DNS request or response.
+ * All DNS questions in this file are for the same domain and thus
+ * the DNS question is a hard-coded value.
+ *
+ * There is no buffer size passed to this function since we provide
+ * the data ourselves and have sized the buffer to be way larger
+ * than necessary for the tests.
+ * 
+ * \param buf The buffer to write the question into
+ * \retval The number of bytes written to the buffer
+ */
 static int generate_dns_question(char *buf)
 {
 	memcpy(buf, DNS_QUESTION, ARRAY_LEN(DNS_QUESTION));
@@ -91,6 +120,22 @@
 	0x00, 0x00, 0x30, 0x39,
 };
 
+/*!
+ * \brief Generate a DNS answer and write it to a buffer
+ *
+ * The DNS answer is the third (and in our case final) part of a
+ * DNS response. The DNS answer generated here is only partial.
+ * The record-specific data is generated by a separate function.
+ * DNS answers in our tests may have variable TTLs, but the rest
+ * is hard-coded.
+ *
+ * There is no buffer size passed to this function since we provide
+ * the data ourselves and have sized the buffer to be way larger
+ * than necessary for the tests.
+ * 
+ * \param buf The buffer to write the answer into
+ * \retval The number of bytes written to the buffer
+ */
 static int generate_dns_answer(int ttl, char *buf)
 {
 	int net_ttl = htonl(ttl);
@@ -104,11 +149,32 @@
 	return ARRAY_LEN(NAPTR_ANSWER);
 }
 
+/*!
+ * \brief Representation of a string in DNS
+ *
+ * In DNS, a string has a byte to indicate the length,
+ * followed by a series of bytes representing the string.
+ * DNS does not NULL-terminate its strings.
+ */
 struct dns_string {
 	uint8_t len;
 	const char *val;
 };
 
+/*!
+ * \brief Write a DNS string to a buffer
+ *
+ * This writes the DNS string to the buffer and returns the total
+ * number of bytes written to the buffer.
+ *
+ * There is no buffer size passed to this function since we provide
+ * the data ourselves and have sized the buffer to be way larger
+ * than necessary for the tests.
+ *
+ * \param string The string to write
+ * \param buf The buffer to write the string into
+ * \return The number of bytes written to the buffer
+ */
 static int write_dns_string(const struct dns_string *string, char *buf)
 {
 	uint8_t len = string->len;
@@ -125,6 +191,23 @@
 	return strlen(string->val) + 1;
 }
 
+/*!
+ * \brief Write a DNS domain to a buffer
+ *
+ * A DNS domain consists of a series of labels separated
+ * by dots. Each of these labels gets written as a DNS
+ * string. A DNS domain ends with a NULL label, which is
+ * essentially a zero-length DNS string.
+ *
+ *
+ * There is no buffer size passed to this function since we provide
+ * the data ourselves and have sized the buffer to be way larger
+ * than necessary for the tests.
+ *
+ * \param string The DNS domain to write
+ * \param buf The buffer to write the domain into
+ * \return The number of bytes written to the buffer
+ */
 static int write_dns_domain(const char *string, char *buf)
 {
 	char *copy = ast_strdupa(string);
@@ -160,6 +243,20 @@
 	const char * replacement;
 };
 
+/*!
+ * \brief Given a NAPTR record, generate a binary form, as would appear in DNS RDATA
+ *
+ * This is part of a DNS answer, specific to NAPTR. It consists of all parts of
+ * the NAPTR record, encoded as it should be in a DNS record.
+ *
+ * There is no buffer size passed to this function since we provide
+ * the data ourselves and have sized the buffer to be way larger
+ * than necessary for the tests.
+ *
+ * \param string The NAPTR record to encode
+ * \param buf The buffer to write the record into
+ * \return The number of bytes written to the buffer
+ */
 static int generate_naptr_record(struct naptr_record *record, char *buf)
 {
 	uint16_t net_order = htons(record->order);
@@ -180,10 +277,37 @@
 	return ptr - buf;
 }
 
+/*!
+ * \brief A pointer to an array of records for a test
+ *
+ * Each test is expected to set this pointer to its local
+ * array of records and then re-set tis pointer to NULL
+ * at the end of the test
+ */
 static struct naptr_record *test_records;
+/*!
+ * \brief The number of records in the test_records array.
+ * 
+ * Each test must set this to the appropriate value at the
+ * beginning of the test and must set this back to zero at
+ * the end of the test.
+ */
 static int num_test_records;
+/*!
+ * \brief A buffer to place raw DNS records into.
+ *
+ * This buffer is way larger than any DNS records we actually
+ * wish to create during any of the tests, but that's fine.
+ */
 static char ans_buffer[1024];
 
+/*!
+ * \brief Asynchronous NAPTR resolution thread.
+ *
+ * This builds an appropriate DNS response based on the NAPTR
+ * records for a given test. Once the records have been created,
+ * the records are added to the DNS result
+ */
 static void *naptr_thread(void *dns_query)
 {
 	struct ast_dns_query *query = dns_query;
@@ -221,6 +345,11 @@
 	return NULL;
 }
 
+/*!
+ * \brief Mock NAPTR resolution method.
+ *
+ * This spawns a thread to handle generation of the necessary NAPTR records
+ */
 static int naptr_resolve(struct ast_dns_query *query)
 {
 	pthread_t thread;
@@ -228,11 +357,17 @@
 	return ast_pthread_create_detached(&thread, NULL, naptr_thread, ao2_bump(query));
 }
 
+/*!
+ * \brief A STUB
+ */
 static int naptr_cancel(struct ast_dns_query *query)
 {
 	return 0;
 }
 
+/*!
+ * \brief Mock NAPTR resolver
+ */
 static struct ast_dns_resolver naptr_resolver = {
 	.name = "naptr_test",
 	.priority = 0,




More information about the asterisk-commits mailing list