diff options
author | Philip Withnall <philip.withnall@collabora.co.uk> | 2015-01-02 19:24:31 +0000 |
---|---|---|
committer | Philip Withnall <philip.withnall@collabora.co.uk> | 2015-01-02 19:24:31 +0000 |
commit | e4e0d5271f6fb018151e4abc4f7935bef40145db (patch) | |
tree | 2b611841f930040a4b4078034a60cc4d9860f374 /stun | |
parent | 8ddc812b4257137f3f376fb7bb6715e10b4d0e91 (diff) | |
download | libnice-e4e0d5271f6fb018151e4abc4f7935bef40145db.tar.gz |
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/.
Diffstat (limited to 'stun')
-rw-r--r-- | stun/constants.h | 118 | ||||
-rw-r--r-- | stun/debug.h | 18 | ||||
-rw-r--r-- | stun/stunmessage.h | 2 | ||||
-rw-r--r-- | stun/usages/timer.h | 1 | ||||
-rw-r--r-- | stun/usages/turn.h | 27 |
5 files changed, 165 insertions, 1 deletions
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, |