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,
--
_____________________________________________________________________
-- Bandwidth and Colocation Provided by http://www.api-digital.com --
svn-commits mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/svn-commits
