Commit e4e0d527 authored by Philip Withnall's avatar Philip Withnall

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/.
parent 8ddc812b
......@@ -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.
*/
......
......@@ -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
<SUBSECTION Standard>
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
<SUBSECTION Private>
StunAgentSavedIds
stun_debug
stun_debug_bytes
stun_agent_t
</SECTION>
......@@ -266,6 +272,8 @@ stun_timer_start
stun_timer_start_reliable
stun_timer_refresh
stun_timer_remainder
<SUBSECTION Private>
stun_timer_s
</SECTION>
<SECTION>
......
......@@ -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
......
......@@ -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))
......
......@@ -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
......
......@@ -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
......
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment