From e4e0d5271f6fb018151e4abc4f7935bef40145db Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 2 Jan 2015 19:24:31 +0000 Subject: docs: Add various missing documentation comments and update sections.txt This straightens out the last few bits of the documentation and almost allows `make check` to pass in docs/. --- agent/address.h | 3 - docs/reference/libnice/libnice-sections.txt | 8 ++ stun/constants.h | 118 ++++++++++++++++++++++++++++ stun/debug.h | 18 +++++ stun/stunmessage.h | 2 + stun/usages/timer.h | 1 + stun/usages/turn.h | 27 ++++++- 7 files changed, 173 insertions(+), 4 deletions(-) diff --git a/agent/address.h b/agent/address.h index 9e91248..603afe2 100644 --- a/agent/address.h +++ b/agent/address.h @@ -67,9 +67,6 @@ G_BEGIN_DECLS /** * NiceAddress: - * @addr: Generic sockaddr address - * @ip4: IPv4 sockaddr address - * @ip6: IPv6 sockaddr address * * The #NiceAddress structure that represents an IPv4 or IPv6 address. */ diff --git a/docs/reference/libnice/libnice-sections.txt b/docs/reference/libnice/libnice-sections.txt index dd185f0..5c27fac 100644 --- a/docs/reference/libnice/libnice-sections.txt +++ b/docs/reference/libnice/libnice-sections.txt @@ -49,6 +49,7 @@ nice_agent_parse_remote_stream_sdp nice_agent_parse_remote_candidate_sdp nice_agent_get_io_stream nice_agent_get_selected_socket +nice_agent_get_component_state nice_component_state_to_string NICE_AGENT @@ -139,6 +140,7 @@ StunAgentUsageFlags StunValidationStatus StunMessageIntegrityValidate StunDefaultValidaterData +StunDebugHandler stun_agent_init stun_agent_validate stun_agent_default_validater @@ -152,8 +154,12 @@ stun_agent_forget_transaction stun_agent_set_software stun_debug_enable stun_debug_disable +stun_set_debug_handler StunAgentSavedIds +stun_debug +stun_debug_bytes +stun_agent_t @@ -266,6 +272,8 @@ stun_timer_start stun_timer_start_reliable stun_timer_refresh stun_timer_remainder + +stun_timer_s
diff --git a/stun/constants.h b/stun/constants.h index aa06153..29e1cec 100644 --- a/stun/constants.h +++ b/stun/constants.h @@ -38,6 +38,107 @@ #define _STUN_CONSTANTS_H +/** + * SECTION:stunconstants + * @short_description: STUN constants + * @include: stun/constants.h + * @stability: Stable + * + * Various constants defining parts of the STUN and TURN protocols and + * on-the-wire packet formats. + */ + +/** + * STUN_ATTRIBUTE_LENGTH_LEN: + * + * Length of the length field of a STUN attribute (in bytes). + */ +/** + * STUN_ATTRIBUTE_LENGTH_POS: + * + * Offset of the length field of a STUN attribute (in bytes). + */ +/** + * STUN_ATTRIBUTE_TYPE_LEN: + * + * Length of the type field of a STUN attribute (in bytes). + */ +/** + * STUN_ATTRIBUTE_TYPE_POS: + * + * Offset of the type field of a STUN attribute (in bytes). + */ +/** + * STUN_ATTRIBUTE_VALUE_POS: + * + * Offset of the value field of a STUN attribute (in bytes). + */ +/** + * STUN_ID_LEN: + * + * Length of the ID field of a STUN message (in bytes). + */ +/** + * STUN_MAGIC_COOKIE: + * + * Magic cookie value used to identify STUN messages. + */ +/** + * TURN_MAGIC_COOKIE: + * + * Magic cookie value used to identify TURN messages. + */ +/** + * STUN_MAX_MESSAGE_SIZE_IPV4: + * + * Maximum size of a STUN message sent over IPv4 (in bytes). + */ +/** + * STUN_MAX_MESSAGE_SIZE_IPV6: + * + * Maximum size of a STUN message sent over IPv6 (in bytes). + */ +/** + * STUN_MESSAGE_ATTRIBUTES_POS: + * + * Offset of the attributes of a STUN message (in bytes). + */ +/** + * STUN_MESSAGE_HEADER_LENGTH: + * + * Total length of a STUN message header (in bytes). + */ +/** + * STUN_MESSAGE_LENGTH_LEN: + * + * Length of the length field of a STUN message (in bytes). + */ +/** + * STUN_MESSAGE_LENGTH_POS: + * + * Offset of the length field of a STUN message (in bytes). + */ +/** + * STUN_MESSAGE_TRANS_ID_LEN: + * + * Length of the transaction ID field of a STUN message (in bytes). + */ +/** + * STUN_MESSAGE_TRANS_ID_POS: + * + * Offset of the transaction ID field of a STUN message (in bytes). + */ +/** + * STUN_MESSAGE_TYPE_LEN: + * + * Length of the type field of a STUN message (in bytes). + */ +/** + * STUN_MESSAGE_TYPE_POS: + * + * Offset of the type field of a STUN message (in bytes). + */ + #define STUN_MESSAGE_TYPE_POS 0 #define STUN_MESSAGE_TYPE_LEN 2 #define STUN_MESSAGE_LENGTH_POS \ @@ -59,6 +160,11 @@ #define STUN_ATTRIBUTE_VALUE_POS \ (STUN_ATTRIBUTE_LENGTH_POS + STUN_ATTRIBUTE_LENGTH_LEN) +/** + * STUN_ATTRIBUTE_HEADER_LENGTH: + * + * Length of a single STUN attribute header (in bytes). + */ #define STUN_ATTRIBUTE_HEADER_LENGTH STUN_ATTRIBUTE_VALUE_POS @@ -68,7 +174,19 @@ #define STUN_ID_LEN 16 +/** + * STUN_AGENT_MAX_SAVED_IDS: + * + * Maximum number of simultaneously ongoing STUN transactions. + */ #define STUN_AGENT_MAX_SAVED_IDS 200 + +/** + * STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES: + * + * Maximum number of unknown attribute which can be handled in a single STUN + * message. + */ #define STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES 256 #define STUN_MAGIC_COOKIE 0x2112A442 diff --git a/stun/debug.h b/stun/debug.h index 94498ff..d4884d5 100644 --- a/stun/debug.h +++ b/stun/debug.h @@ -59,8 +59,26 @@ void stun_debug_enable (void); */ void stun_debug_disable (void); +/** + * StunDebugHandler: + * @format: printf()-style debug message format string + * @ap: Parameters to substitute into message placeholders + * + * Callback for a debug message from the STUN code. + */ typedef void (*StunDebugHandler) (const char *format, va_list ap); +/** + * stun_set_debug_handler: + * @handler: (nullable): Handler for STUN debug messages, or %NULL to use the + * default + * + * Set a callback function to be invoked for each debug message from the STUN + * code. The callback will only be invoked if STUN debugging is enabled using + * stun_debug_enable(). + * + * The default callback prints the formatted debug message to stderr. + */ void stun_set_debug_handler (StunDebugHandler handler); #if defined(__GNUC__) && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)) diff --git a/stun/stunmessage.h b/stun/stunmessage.h index 75d2850..a57e170 100644 --- a/stun/stunmessage.h +++ b/stun/stunmessage.h @@ -163,6 +163,8 @@ typedef enum * TURN draft 09 and 12 * @STUN_ATTRIBUTE_LIFETIME: The LIFETIME attribute as defined by TURN * draft 04, 09 and 12 + * @STUN_ATTRIBUTE_MS_ALTERNATE_SERVER: The ALTERNATE-SERVER attribute as + * defined by [MS-TURN] * @STUN_ATTRIBUTE_MAGIC_COOKIE: The MAGIC-COOKIE attribute as defined by * the rosenberg-midcom TURN draft 08 * @STUN_ATTRIBUTE_BANDWIDTH: The BANDWIDTH attribute as defined by TURN draft 04 diff --git a/stun/usages/timer.h b/stun/usages/timer.h index e8f0786..e6501cb 100644 --- a/stun/usages/timer.h +++ b/stun/usages/timer.h @@ -200,6 +200,7 @@ void stun_timer_start (StunTimer *timer, unsigned int initial_timeout, /** * stun_timer_start_reliable: * @timer: The #StunTimer to start + * @initial_timeout: The initial timeout to use before the first retransmission * * Starts a STUN transaction retransmission timer for a reliable transport. * This should be called as soon as you send the message for the first time on diff --git a/stun/usages/turn.h b/stun/usages/turn.h index 388ec4f..7a2d4e6 100644 --- a/stun/usages/turn.h +++ b/stun/usages/turn.h @@ -96,6 +96,10 @@ typedef enum { * Google Talk's relay server * @STUN_USAGE_TURN_COMPATIBILITY_MSN: Use the specification compatible with * MSN TURN servers + * @STUN_USAGE_TURN_COMPATIBILITY_OC2007: Use the specification compatible with + * Microsoft Office Communicator 2007 + * @STUN_USAGE_TURN_COMPATIBILITY_RFC5766: Use the specification compatible with + * RFC 5766 (the final, canonical TURN standard) * * Specifies which TURN specification compatibility to use */ @@ -205,7 +209,28 @@ size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg, uint8_t *password, size_t password_len, StunUsageTurnCompatibility compatibility); - +/** + * stun_usage_turn_create_permission: + * @agent: The #StunAgent to use to build the request + * @msg: The #StunMessage to build + * @buffer: The buffer to use for creating the #StunMessage + * @buffer_len: The size of the @buffer + * @username: The username to use in the request + * @username_len: The length of @username + * @password: The key to use for building the MESSAGE-INTEGRITY + * @password_len: The length of @password + * @realm: The realm identifier to use in the request + * @realm_len: The length of @realm + * @nonce: Unique and securely random nonce to use in the request + * @nonce_len: The length of @nonce + * @peer: Server-reflexive host address to request permission for + * @compatibility: The compatibility mode to use for building the + * CreatePermission request + * + * Create a new TURN CreatePermission request + * + * Returns: The length of the message to send + */ size_t stun_usage_turn_create_permission (StunAgent *agent, StunMessage *msg, uint8_t *buffer, size_t buffer_len, uint8_t *username, size_t username_len, -- cgit v1.2.1