Commit 259d6efa authored by Youness Alaoui's avatar Youness Alaoui

Add documentation for libstun and fix some docs elsewhere

parent b5d0c1fd
...@@ -13,7 +13,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml ...@@ -13,7 +13,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# gtk-doc will search all .c & .h files beneath here for inline comments # gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros. # documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk # e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR=$(top_srcdir)/agent DOC_SOURCE_DIR=$(top_srcdir)
# Extra options to pass to gtkdoc-scangobj. Not normally needed. # Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS= SCANGOBJ_OPTIONS=
...@@ -37,12 +37,20 @@ FIXXREF_OPTIONS= ...@@ -37,12 +37,20 @@ FIXXREF_OPTIONS=
# Used for dependencies. The docs will be rebuilt if any of these change. # Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c # e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(DOC_SOURCE_DIR)/agent.h $(DOC_SOURCE_DIR)/address.h $(DOC_SOURCE_DIR)/debug.h $(DOC_SOURCE_DIR)/candidate.h $(DOC_SOURCE_DIR)/interfaces.h HFILE_GLOB=$(DOC_SOURCE_DIR)/agent/agent.h $(DOC_SOURCE_DIR)/agent/address.h \
CFILE_GLOB=$(DOC_SOURCE_DIR)/agent.c $(DOC_SOURCE_DIR)/agent/debug.h $(DOC_SOURCE_DIR)/agent/candidate.h \
$(DOC_SOURCE_DIR)/agent/interfaces.h \
$(DOC_SOURCE_DIR)/stun/stunmessage.h $(DOC_SOURCE_DIR)/stun/stun5389.h \
$(DOC_SOURCE_DIR)/stun/utils.h $(DOC_SOURCE_DIR)/stun/stunagent.h \
$(DOC_SOURCE_DIR)/stun/usages/bind.h \
$(DOC_SOURCE_DIR)/stun/usages/ice.h \
$(DOC_SOURCE_DIR)/stun/usages/timer.h \
$(DOC_SOURCE_DIR)/stun/usages/turn.h
CFILE_GLOB=$(DOC_SOURCE_DIR)/agent/agent.c
# Header files to ignore when scanning. # Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES= conncheck.h discovery.h stream.h IGNORE_HFILES= conncheck.h discovery.h stream.h gstnice.h gstnicesrc.h gstnicesink.h
# Images to copy into HTML directory. # Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
...@@ -69,7 +77,7 @@ AM_CFLAGS = $(ERROR_CFLAGS) \ ...@@ -69,7 +77,7 @@ AM_CFLAGS = $(ERROR_CFLAGS) \
-I $(top_srcdir)/socket \ -I $(top_srcdir)/socket \
-I $(top_srcdir)/stun -I $(top_srcdir)/stun
GTKDOC_LIBS= $(top_builddir)/agent/libagent.la $(GLIB_LIBS) GTKDOC_LIBS= $(top_builddir)/agent/libagent.la $(GLIB_LIBS) $(top_builddir)/stun/libstun.la
# This includes the standard gtk-doc make rules, copied by gtkdocize. # This includes the standard gtk-doc make rules, copied by gtkdocize.
......
...@@ -17,5 +17,11 @@ ...@@ -17,5 +17,11 @@
<xi:include href="xml/debug.xml"/> <xi:include href="xml/debug.xml"/>
<xi:include href="xml/candidate.xml"/> <xi:include href="xml/candidate.xml"/>
<xi:include href="xml/interfaces.xml"/> <xi:include href="xml/interfaces.xml"/>
<xi:include href="xml/stunagent.xml"/>
<xi:include href="xml/stunmessage.xml"/>
<xi:include href="xml/turn.xml"/>
<xi:include href="xml/bind.xml"/>
<xi:include href="xml/ice.xml"/>
<xi:include href="xml/timer.xml"/>
</chapter> </chapter>
</book> </book>
<SECTION> <SECTION>
<FILE>agent</FILE> <FILE>agent</FILE>
NICE_AGENT_MAX_REMOTE_CANDIDATES <TITLE>NiceAgent</TITLE>
NiceAgent
NiceComponentState NiceComponentState
NiceComponentType NiceComponentType
NiceProxyType
NiceCompatibility NiceCompatibility
NiceAgentRecvFunc NiceAgentRecvFunc
<TITLE>NiceAgent</TITLE> NICE_AGENT_MAX_REMOTE_CANDIDATES
NiceAgent
nice_agent_new nice_agent_new
nice_agent_add_local_address nice_agent_add_local_address
nice_agent_add_stream nice_agent_add_stream
...@@ -15,15 +16,14 @@ nice_agent_set_relay_info ...@@ -15,15 +16,14 @@ nice_agent_set_relay_info
nice_agent_gather_candidates nice_agent_gather_candidates
nice_agent_set_remote_credentials nice_agent_set_remote_credentials
nice_agent_get_local_credentials nice_agent_get_local_credentials
nice_agent_add_remote_candidate
nice_agent_set_remote_candidates nice_agent_set_remote_candidates
nice_agent_send
nice_agent_get_local_candidates
nice_agent_get_remote_candidates nice_agent_get_remote_candidates
nice_agent_restart nice_agent_get_local_candidates
nice_agent_send
nice_agent_attach_recv nice_agent_attach_recv
nice_agent_set_selected_pair nice_agent_set_selected_pair
nice_agent_set_selected_remote_candidate nice_agent_set_selected_remote_candidate
nice_agent_restart
<SUBSECTION Standard> <SUBSECTION Standard>
NICE_AGENT NICE_AGENT
NICE_IS_AGENT NICE_IS_AGENT
...@@ -36,25 +36,15 @@ NICE_AGENT_GET_CLASS ...@@ -36,25 +36,15 @@ NICE_AGENT_GET_CLASS
NiceAgentClass NiceAgentClass
</SECTION> </SECTION>
<SECTION>
<FILE>debug</FILE>
<TITLE>Debug messages</TITLE>
nice_debug_enable
nice_debug_disable
<SUBSECTION Private>
nice_debug_init
nice_debug
</SECTION>
<SECTION> <SECTION>
<FILE>candidate</FILE> <FILE>candidate</FILE>
<TITLE>NiceCandidate</TITLE> <TITLE>NiceCandidate</TITLE>
NICE_CANDIDATE_MAX_FOUNDATION NiceCandidate
NiceCandidateType NiceCandidateType
NiceCandidateTransport NiceCandidateTransport
NiceRelayType
NiceCandidate
TurnServer TurnServer
NiceRelayType
NICE_CANDIDATE_MAX_FOUNDATION
nice_candidate_new nice_candidate_new
nice_candidate_free nice_candidate_free
nice_candidate_copy nice_candidate_copy
...@@ -70,22 +60,11 @@ nice_candidate_ice_priority ...@@ -70,22 +60,11 @@ nice_candidate_ice_priority
nice_candidate_pair_priority nice_candidate_pair_priority
</SECTION> </SECTION>
<SECTION>
<FILE>interfaces</FILE>
<TITLE>Network interfaces discovery</TITLE>
<INCLUDE>gst/farsight/fs-interfaces.h</INCLUDE>
nice_interfaces_get_ip_for_interface
nice_interfaces_get_local_interfaces
nice_interfaces_get_local_ips
</SECTION>
<SECTION> <SECTION>
<FILE>address</FILE> <FILE>address</FILE>
<TITLE>NiceAddress</TITLE> <TITLE>NiceAddress</TITLE>
NICE_ADDRESS_STRING_LEN
NiceAddress NiceAddress
NICE_ADDRESS_STRING_LEN
nice_address_init nice_address_init
nice_address_new nice_address_new
nice_address_free nice_address_free
...@@ -104,51 +83,131 @@ nice_address_is_valid ...@@ -104,51 +83,131 @@ nice_address_is_valid
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>component</FILE> <FILE>debug</FILE>
<TITLE>Debug messages</TITLE>
nice_debug_enable
nice_debug_disable
<SUBSECTION Private> <SUBSECTION Private>
Component nice_debug_init
CandidatePair nice_debug
IncomingCheck
component_new
component_free
component_find_socket_by_fd
component_find_pair
component_restart
component_update_selected_pair
component_find_remote_candidate
component_set_selected_remote_candidate
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>agent-priv</FILE> <FILE>interfaces</FILE>
<SUBSECTION Private> <TITLE>Network interfaces discovery</TITLE>
NICE_AGENT_TIMER_TA_DEFAULT nice_interfaces_get_ip_for_interface
NICE_AGENT_TIMER_TR_DEFAULT nice_interfaces_get_local_interfaces
NICE_AGENT_TIMER_TR_MIN nice_interfaces_get_local_ips
NICE_AGENT_MAX_CONNECTIVITY_CHECKS_DEFAULT
MAX_STUN_DATAGRAM_PAYLOAD
NiceAgent
agent_find_component
agent_find_stream
agent_gathering_done
agent_signal_gathering_done
agent_signal_new_selected_pair
agent_signal_component_state_change
agent_signal_new_candidate
agent_signal_new_remote_candidate
agent_signal_initial_binding_request_received
agent_candidate_pair_priority
agent_timeout_add_with_context
priv_attach_stream_component_socket
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>agent-signals-marshal</FILE> <FILE>stunagent</FILE>
<TITLE>StunAgent</TITLE>
StunAgent
StunCompatibility
StunAgentUsageFlags
StunValidationStatus
StunMessageIntegrityValidate
StunDefaultValidaterData
stun_agent_init
stun_agent_validate
stun_agent_default_validater
stun_agent_init_request
stun_agent_init_indication
stun_agent_init_response
stun_agent_init_error
stun_agent_build_unknown_attributes_error
stun_agent_finish_message
stun_debug_enable
stun_debug_disable
<SUBSECTION Private> <SUBSECTION Private>
agent_marshal_VOID__UINT_UINT_UINT StunAgentSavedIds
agent_marshal_VOID__UINT_UINT_STRING_STRING </SECTION>
agent_marshal_VOID__UINT_UINT_STRING
agent_marshal_VOID__UINT
<SECTION>
<FILE>stunmessage</FILE>
<TITLE>StunMessage</TITLE>
StunMessage
StunClass
StunMethod
StunAttribute
StunTransactionId
StunError
StunMessageReturn
STUN_MESSAGE_BUFFER_INCOMPLETE
STUN_MESSAGE_BUFFER_INVALID
stun_message_init
stun_message_length
stun_message_find
stun_message_find_flag
stun_message_find32
stun_message_find64
stun_message_find_string
stun_message_find_addr
stun_message_find_xor_addr
stun_message_find_xor_addr_full
stun_message_find_error
stun_message_append
stun_message_append_bytes
stun_message_append_flag
stun_message_append32
stun_message_append64
stun_message_append_string
stun_message_append_addr
stun_message_append_xor_addr
stun_message_append_xor_addr_full
stun_message_append_error
stun_message_validate_buffer_length
stun_message_id
stun_message_get_class
stun_message_get_method
stun_message_has_attribute
stun_message_has_cookie
stun_optional
stun_strerror
</SECTION>
<SECTION>
<FILE>turn</FILE>
StunUsageTurnCompatibility
StunUsageTurnRequestPorts
StunUsageTurnReturn
stun_usage_turn_create
stun_usage_turn_create_refresh
stun_usage_turn_process
stun_usage_turn_refresh_process
</SECTION>
<SECTION>
<FILE>ice</FILE>
StunUsageIceCompatibility
StunUsageIceReturn
stun_usage_ice_conncheck_create
stun_usage_ice_conncheck_process
stun_usage_ice_conncheck_create_reply
stun_usage_ice_conncheck_priority
stun_usage_ice_conncheck_use_candidate
</SECTION>
<SECTION>
<FILE>timer</FILE>
StunTimer
StunUsageTimerReturn
stun_timer_start
stun_timer_start_reliable
stun_timer_refresh
stun_timer_remainder
</SECTION>
<SECTION>
<FILE>bind</FILE>
StunUsageBindReturn
stun_usage_bind_create
stun_usage_bind_process
stun_usage_bind_keepalive
stun_usage_bind_run
</SECTION> </SECTION>
This diff is collapsed.
...@@ -36,6 +36,18 @@ ...@@ -36,6 +36,18 @@
#define _STUN_MESSAGE_H #define _STUN_MESSAGE_H
/**
* SECTION:stunmessage
* @short_description: STUN messages parsing and formatting functions
* @see_also: #StunAgent
* @stability: Stable
*
* The STUN Messages API allows you to create STUN messages easily as well as to
* parse existing messages.
*
*/
#ifdef _WIN32 #ifdef _WIN32
#include "win32_common.h" #include "win32_common.h"
#else #else
...@@ -351,6 +363,8 @@ typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN]; ...@@ -351,6 +363,8 @@ typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];
* "Active Destination Already Set" error as defined in TURN draft 04. * "Active Destination Already Set" error as defined in TURN draft 04.
* @STUN_ERROR_UNSUPPORTED_FAMILY: The ERROR-CODE value for the * @STUN_ERROR_UNSUPPORTED_FAMILY: The ERROR-CODE value for the
* "Address Family not Supported" error as defined in TURN IPV6 Draft 05. * "Address Family not Supported" error as defined in TURN IPV6 Draft 05.
* @STUN_ERROR_WRONG_CREDENTIALS: The ERROR-CODE value for the
* "Wrong Credentials" error as defined in TURN Draft 12.
* @STUN_ERROR_UNSUPPORTED_TRANSPORT:he ERROR-CODE value for the * @STUN_ERROR_UNSUPPORTED_TRANSPORT:he ERROR-CODE value for the
* "Unsupported Transport Protocol" error as defined in TURN Draft 12. * "Unsupported Transport Protocol" error as defined in TURN Draft 12.
* @STUN_ERROR_INVALID_IP: The ERROR-CODE value for the * @STUN_ERROR_INVALID_IP: The ERROR-CODE value for the
...@@ -802,8 +816,8 @@ StunMessageReturn stun_message_append_error (StunMessage * msg, ...@@ -802,8 +816,8 @@ StunMessageReturn stun_message_append_error (StunMessage * msg,
* provide us with the length of the STUN message. * provide us with the length of the STUN message.
* *
* Returns: The length of the valid STUN message in the buffer. * Returns: The length of the valid STUN message in the buffer.
* See #STUN_MESSAGE_BUFFER_INCOMPLETE * <para> See also: #STUN_MESSAGE_BUFFER_INCOMPLETE </para>
* See #STUN_MESSAGE_BUFFER_INVALID * <para> See also: #STUN_MESSAGE_BUFFER_INVALID </para>
*/ */
int stun_message_validate_buffer_length (const uint8_t *msg, size_t length); int stun_message_validate_buffer_length (const uint8_t *msg, size_t length);
......
...@@ -55,6 +55,19 @@ ...@@ -55,6 +55,19 @@
extern "C" { extern "C" {
# endif # endif
/**
* StunUsageBindReturn:
* @STUN_USAGE_BIND_RETURN_SUCCESS: The binding usage succeeded
* @STUN_USAGE_BIND_RETURN_ERROR: There was an unknown error in the bind usage
* @STUN_USAGE_BIND_RETURN_INVALID: The message is invalid and should be ignored
* @STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER: The binding request has an
* ALTERNATE-SERVER attribute
* @STUN_USAGE_BIND_RETURN_TIMEOUT: The binding was unsuccessful because it has
* timed out.
*
* Return value of stun_usage_bind_process() and stun_usage_bind_run() which
* allows you to see what status the function call returned.
*/
typedef enum { typedef enum {
STUN_USAGE_BIND_RETURN_SUCCESS, STUN_USAGE_BIND_RETURN_SUCCESS,
STUN_USAGE_BIND_RETURN_ERROR, STUN_USAGE_BIND_RETURN_ERROR,
...@@ -64,17 +77,72 @@ typedef enum { ...@@ -64,17 +77,72 @@ typedef enum {
} StunUsageBindReturn; } StunUsageBindReturn;
/**
* stun_usage_bind_create:
* @agent: The #StunAgent to use to create the binding request
* @msg: The #StunMessage to build
* @buffer: The buffer to use for creating the #StunMessage
* @buffer_len: The size of the @buffer
*
* Create a new STUN binding request to use with a STUN server.
* Returns: The length of the built message.
*/
size_t stun_usage_bind_create (StunAgent *agent, StunMessage *msg, size_t stun_usage_bind_create (StunAgent *agent, StunMessage *msg,
uint8_t *buffer, size_t buffer_len); uint8_t *buffer, size_t buffer_len);
/**
* stun_usage_bind_process:
* @msg: The #StunMessage to process
* @addr: A pointer to a #sockaddr structure to fill with the mapped address
* that the STUN server gives us
* @addrlen: The length of @addr
* @alternate_server: A pointer to a #sockaddr structure to fill with the
* address of an alternate server to which we should send our new STUN
* binding request, in case the currently used STUN server is requesting the use
* of an alternate server. This argument will only be filled if the return value
* of the function is #STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER
* @alternate_server_len: The length of @alternate_server
*
* Process a STUN binding response and extracts the mapped address from the STUN
* message. Also checks for the ALTERNATE-SERVER attribute.
* Returns: A #StunUsageBindReturn value.
* Note that #STUN_USAGE_BIND_RETURN_TIMEOUT cannot be returned by this function
*/
StunUsageBindReturn stun_usage_bind_process (StunMessage *msg, StunUsageBindReturn stun_usage_bind_process (StunMessage *msg,
struct sockaddr *addr, socklen_t *addrlen, struct sockaddr *addr, socklen_t *addrlen,
struct sockaddr *alternate_server, socklen_t *alternate_server_len); struct sockaddr *alternate_server, socklen_t *alternate_server_len);
/**
* stun_usage_bind_keepalive:
* @agent: The #StunAgent to use to build the message
* @msg: The #StunMessage to build
* @buf: The buffer to use for creating the #StunMessage
* @len: The size of the @buf
*
* Creates a STUN binding indication that can be used for a keepalive.
* Since this is an indication message, no STUN response will be generated
* and it can only be used as a keepalive message.
* Returns: The length of the message to send
*/
size_t stun_usage_bind_keepalive (StunAgent *agent, StunMessage *msg, size_t stun_usage_bind_keepalive (StunAgent *agent, StunMessage *msg,
uint8_t *buf, size_t len); uint8_t *buf, size_t len);
/**
* stun_usage_bind_run:
* @srv: A pointer to the #sockaddr structure representing the STUN server's
* address
* @srvlen: The length of @srv
* @addr: A pointer to a #sockaddr structure to fill with the mapped address
* that the STUN server gives us
* @addrlen: The length of @addr
*
* This is a convenience function that will do a synchronous Binding request to
* a server and wait for its answer. It will use the #StunUsageTrans and
* #StunUsageTimer usages to send the request and handle the response.
* Returns: A #StunUsageBindReturn.
* Possible return values are #STUN_USAGE_BIND_RETURN_SUCCESS,
* #STUN_USAGE_BIND_RETURN_ERROR and #STUN_USAGE_BIND_RETURN_TIMEOUT
*/
StunUsageBindReturn stun_usage_bind_run (const struct sockaddr *srv, StunUsageBindReturn stun_usage_bind_run (const struct sockaddr *srv,
socklen_t srvlen, struct sockaddr *addr, socklen_t *addrlen); socklen_t srvlen, struct sockaddr *addr, socklen_t *addrlen);
......
...@@ -47,12 +47,40 @@ ...@@ -47,12 +47,40 @@
extern "C" { extern "C" {
# endif # endif
/**
* StunUsageIceCompatibility:
* @STUN_USAGE_ICE_COMPATIBILITY_DRAFT19: The ICE compatibility with draft 19
* @STUN_USAGE_ICE_COMPATIBILITY_GOOGLE: The ICE compatibility with Google's
* implementation of ICE
* @STUN_USAGE_ICE_COMPATIBILITY_MSN: The ICE compatibility with MSN's
* implementation of ICE
*
* This enum defines which compatibility modes this ICE usage can use
*/
typedef enum { typedef enum {
STUN_USAGE_ICE_COMPATIBILITY_DRAFT19, STUN_USAGE_ICE_COMPATIBILITY_DRAFT19,
STUN_USAGE_ICE_COMPATIBILITY_GOOGLE, STUN_USAGE_ICE_COMPATIBILITY_GOOGLE,
STUN_USAGE_ICE_COMPATIBILITY_MSN, STUN_USAGE_ICE_COMPATIBILITY_MSN,
} StunUsageIceCompatibility; } StunUsageIceCompatibility;
/**
* StunUsageIceReturn:
* @STUN_USAGE_ICE_RETURN_SUCCESS: The function succeeded
* @STUN_USAGE_ICE_RETURN_ERROR: There was an unspecified error
* @STUN_USAGE_ICE_RETURN_INVALID: The message is invalid for processing
* @STUN_USAGE_ICE_RETURN_ROLE_CONFLICT: A role conflict was detected
* @STUN_USAGE_ICE_RETURN_INVALID_REQUEST: The message is an not a request
* @STUN_USAGE_ICE_RETURN_INVALID_METHOD: The method of the request is invalid
* @STUN_USAGE_ICE_RETURN_MEMORY_ERROR: The buffer size is too small to hold
* the STUN reply
* @STUN_USAGE_ICE_RETURN_INVALID_ADDRESS: The mapped address argument has
* an invalid address family
*
* Return value of stun_usage_ice_conncheck_process() and
* stun_usage_ice_conncheck_create_reply() which allows you to see what
* status the function call returned.
*/
typedef enum { typedef enum {
STUN_USAGE_ICE_RETURN_SUCCESS, STUN_USAGE_ICE_RETURN_SUCCESS,
STUN_USAGE_ICE_RETURN_ERROR, STUN_USAGE_ICE_RETURN_ERROR,
...@@ -65,7 +93,30 @@ typedef enum { ...@@ -65,7 +93,30 @@ typedef enum {
} StunUsageIceReturn; } StunUsageIceReturn;
/**
* stun_usage_ice_conncheck_create:
* @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
* @cand_use: Set to %TRUE to append the USE-CANDIDATE flag to the request
* @controlling: Set to %TRUE if you are the controlling agent or set to
* %FALSE if you are the controlled agent.
* @priority: The value of the PRIORITY attribute
* @tie: The value of the tie-breaker to put in the ICE-CONTROLLED or
* ICE-CONTROLLING attribute
* @compatibility: The compatibility mode to use for building the conncheck
* request
*
* Builds an ICE connectivity check STUN message.
* If the compatibility is not #STUN_USAGE_ICE_COMPATIBILITY_DRAFT19, the
* @cand_use, @controlling, @priority and @tie arguments are not used.
* Returns: The length of the message built.
*/
size_t size_t
stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg, stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg,
uint8_t *buffer, size_t buffer_len, uint8_t *buffer, size_t buffer_len,
...@@ -75,34 +126,54 @@ stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg, ...@@ -75,34 +126,54 @@ stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg,
uint64_t tie, StunUsageIceCompatibility compatibility); uint64_t tie, StunUsageIceCompatibility compatibility);
/**
* stun_usage_ice_conncheck_process:
* @msg: The #StunMessage to process
* @addr: A pointer to a #sockaddr structure to fill with the mapped address
* that the STUN connectivity check response contains
* @addrlen: The length of @addr
* @compatibility: The compatibility mode to use for processing the conncheck
* response
*
* Process an ICE connectivity check STUN message and retreive the
* mapped address from the message
* <para> See also stun_usage_ice_conncheck_priority() and
* stun_usage_ice_conncheck_use_candidate() </para>
* Returns: A #StunUsageIceReturn value
*/
StunUsageIceReturn stun_usage_ice_conncheck_process (StunMessage *msg, StunUsageIceReturn stun_usage_ice_conncheck_process (StunMessage *msg,
struct sockaddr *addr, socklen_t *addrlen, struct sockaddr *addr, socklen_t *addrlen,
StunUsageIceCompatibility compatibility); StunUsageIceCompatibility compatibility);
/** /**
* Tries to parse a STUN connectivity check (Binding request) and format a * stun_usage_ice_conncheck_create_reply:
* response accordingly. * @agent: The #StunAgent to use to build the response
* @req: The original STUN request to reply to
* @msg: The #StunMessage to build
* @buf: The buffer to use for creating the #StunMessage
* @plen: A pointer containing the size of the @buffer on input.
* Will contain the length of the message built on output.
* @src: A pointer to a #sockaddr structure containing the source address from
* which the request was received. Will be used as the mapped address in the
* response
* @srclen: The length of @addr
* @control: Set to %TRUE if you are the controlling agent or set to
* %FALSE if you are the controlled agent.
* @tie: The value of the tie-breaker to put in the ICE-CONTROLLED or
* ICE-CONTROLLING attribute
* @compatibility: The compatibility mode to use for building the conncheck
* response
* *
* @param buf [OUT] output buffer to write a Binding response to. May refer * Tries to parse a STUN connectivity check request and builds a
* to the same buffer space as the request message. * response accordingly.
* @param plen [IN/OUT] output buffer size on entry, response length on exit <note>
* @param msg pointer to the first byte of the binding request <para>
* @param src socket address the message was received from In case of error, the @msg is filled with the appropriate error response
* @param srclen byte length of the socket address to be sent and the value of @plen is set to the size of that message.
* @param username STUN username If @plen has a size of 0, then no error response should be sent.
* @param password HMAC secret password </para>
* @param control [IN/OUT] whether we are controlling ICE or not </note>
* @param tie tie breaker value for ICE role determination * Returns: A #StunUsageIceReturn value
*
* @return 0 if successful (@a rbuf contains a <b>non-error</b> response),
* EINVAL: malformatted request message or socket address,
* EAFNOSUPPORT: unsupported socket address family,
* EPROTO: unsupported request message type or parameter,
* ENOBUFS: insufficient response buffer space.
* EACCES: ICE role conflict occurred, please recheck the flag at @a control
*
* In case of error, the value at @a plen is set to the size of an error
* response, or 0 if no error response should be sent.
*/ */
StunUsageIceReturn StunUsageIceReturn
stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req, stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req,
...@@ -112,16 +183,20 @@ stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req, ...@@ -112,16 +183,20 @@ stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req,
StunUsageIceCompatibility compatibility); StunUsageIceCompatibility compatibility);
/** /**
* stun_usage_ice_conncheck_priority:
* @msg: The #StunMessage to parse
*
* Extracts the priority from a STUN message. * Extracts the priority from a STUN message.
* @param msg valid STUN message. * Returns: host byte order priority, or 0 if not specified.
* @return host byte order priority, or 0 if not specified.
*/ */
uint32_t stun_usage_ice_conncheck_priority (const StunMessage *msg); uint32_t stun_usage_ice_conncheck_priority (const StunMessage *msg);
/** /**
* Extracts the "use candidate" flag from a STUN message. * stun_usage_ice_conncheck_use_candidate:
* @param msg valid STUN message. * @msg: The #StunMessage to parse
* @return true if the flag is set, false if not. *
* Extracts the USE-CANDIDATE attribute flag from a STUN message.
* Returns: %TRUE if the flag is set, %FALSE if not.
*/ */
bool stun_usage_ice_conncheck_use_candidate (const StunMessage *msg); bool stun_usage_ice_conncheck_use_candidate (const StunMessage *msg);
......
...@@ -48,12 +48,31 @@ ...@@ -48,12 +48,31 @@
# include <time.h> # include <time.h>
#endif #endif
typedef struct stun_timer_s /**
{ * StunTimer:
*
* An opaque structure representing a STUN transaction retransmission timer
*/
typedef struct stun_timer_s StunTimer;
struct stun_timer_s {
struct timeval deadline; struct timeval deadline;
unsigned delay; unsigned delay;
} StunTimer; };
/**
* StunUsageTimerReturn:
* @STUN_USAGE_TIMER_RETURN_SUCCESS: The timer was refreshed successfully
* and there is nothing to be done
* @STUN_USAGE_TIMER_RETURN_RETRANSMIT: The timer expired and the message
* should be retransmitted now.
* @STUN_USAGE_TIMER_RETURN_TIMEOUT: The timer expired as well as all the
* retransmissions, the transaction timed out
*
* Return value of stun_usage_timer_refresh() which provides you with status
* information on the timer.
*/
typedef enum { typedef enum {
STUN_USAGE_TIMER_RETURN_SUCCESS, STUN_USAGE_TIMER_RETURN_SUCCESS,
STUN_USAGE_TIMER_RETURN_RETRANSMIT, STUN_USAGE_TIMER_RETURN_RETRANSMIT,
...@@ -65,20 +84,41 @@ extern "C" { ...@@ -65,20 +84,41 @@ extern "C" {
# endif # endif
/** /**
* stun_timer_start:
* @timer: The #StunTimer to start
*
* Starts a STUN transaction retransmission timer. * Starts a STUN transaction retransmission timer.
* @param timer structure for internal timer state * This should be called as soon as you send the message for the first time on
* a UDP socket
*/ */
void stun_timer_start (StunTimer *timer); void stun_timer_start (StunTimer *timer);
/**
* stun_timer_start_reliable:
* @timer: The #StunTimer to start
*
* 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
* a TCP socket
*/
void stun_timer_start_reliable (StunTimer *timer); void stun_timer_start_reliable (StunTimer *timer);
/** /**
* stun_timer_refresh:
* @timer: The #StunTimer to refresh
*
* Updates a STUN transaction retransmission timer. * Updates a STUN transaction retransmission timer.
* @param timer internal timer state * Returns: A #StunUsageTimerReturn telling you what to do next
* @return -1 if the transaction timed out,
* 0 if the transaction should be retransmitted,
* otherwise milliseconds left until next time out or retransmit.
*/ */
StunUsageTimerReturn stun_timer_refresh (StunTimer *timer); StunUsageTimerReturn stun_timer_refresh (StunTimer *timer);
/**
* stun_timer_remainder:
* @timer: The #StunTimer to query
*
* Query the timer on the time left before the next refresh should be done
* Returns: The time remaining for the timer to expire in milliseconds
*/
unsigned stun_timer_remainder (const StunTimer *timer); unsigned stun_timer_remainder (const StunTimer *timer);
# ifdef __cplusplus # ifdef __cplusplus
......
...@@ -86,6 +86,21 @@ typedef enum { ...@@ -86,6 +86,21 @@ typedef enum {
STUN_USAGE_TURN_COMPATIBILITY_MSN, STUN_USAGE_TURN_COMPATIBILITY_MSN,
} StunUsageTurnCompatibility; } StunUsageTurnCompatibility;
/**
* StunUsageTurnReturn:
* @STUN_USAGE_TURN_RETURN_RELAY_SUCCESS: The response was successful and a relay
* address is provided
* @STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS: The response was successful and a
* relay address as well as a mapped address are provided
* @STUN_USAGE_TURN_RETURN_ERROR: The response resulted in an error
* @STUN_USAGE_TURN_RETURN_INVALID: The response is not a valid response
* @STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER: The server requests the message
* to be sent to an alternate server
*
* Return value of stun_usage_turn_process() and
* stun_usage_turn_refresh_process() which allows you to see what status the
* function call returned.
*/
typedef enum { typedef enum {
STUN_USAGE_TURN_RETURN_RELAY_SUCCESS, STUN_USAGE_TURN_RETURN_RELAY_SUCCESS,
STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS, STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS,
...@@ -95,6 +110,40 @@ typedef enum { ...@@ -95,6 +110,40 @@ typedef enum {
} StunUsageTurnReturn; } StunUsageTurnReturn;
/**
* stun_usage_turn_create:
* @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
* @previous_response: If this is the first request you are sending, set this
* argument to NULL, if it's a subsequent request you are building, then set this
* argument to the response you have received. This argument is used for building
* long term credentials (using the REALM and NONCE attributes) as well as for
* getting the RESERVATION-TOKEN attribute when you previously requested an
* allocation which reserved two ports
* @request_ports: Specify how you want to request the allocated port(s).
* This is only used if the compatibility is set to
* #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
* <para>See #StunUsageTurnRequestPorts </para>
* @bandwidth: The bandwidth to request from the server for the allocation. If
* this value is negative, then no BANDWIDTH attribute is added to the request.
* This is only used if the compatibility is set to
* #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
* @lifetime: The lifetime of the allocation to request from the server. If
* this value is negative, then no LIFETIME attribute is added to the request.
* This is only used if the compatibility is set to
* #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
* @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
* @compatibility: The compatibility mode to use for building the Allocation
* request
*
* Create a new TURN Allocation request
* Returns: The length of the message to send
*/
size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg, size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg,
uint8_t *buffer, size_t buffer_len, uint8_t *buffer, size_t buffer_len,
StunMessage *previous_response, StunMessage *previous_response,
...@@ -104,6 +153,30 @@ size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg, ...@@ -104,6 +153,30 @@ size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg,
uint8_t *password, size_t password_len, uint8_t *password, size_t password_len,
StunUsageTurnCompatibility compatibility); StunUsageTurnCompatibility compatibility);
/**
* stun_usage_turn_create_refresh:
* @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
* @previous_response: If this is the first request you are sending, set this
* argument to NULL, if it's a subsequent request you are building, then set this
* argument to the response you have received. This argument is used for building
* long term credentials (using the REALM and NONCE attributes)
* @lifetime: The lifetime of the allocation to request from the server. If
* this value is negative, then no LIFETIME attribute is added to the request.
* This is only used if the compatibility is set to
* #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
* @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
* @compatibility: The compatibility mode to use for building the Allocation
* request
*
* Create a new TURN Refresh request
* Returns: The length of the message to send
*/
size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg, size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
uint8_t *buffer, size_t buffer_len, uint8_t *buffer, size_t buffer_len,
StunMessage *previous_response, int32_t lifetime, StunMessage *previous_response, int32_t lifetime,
...@@ -111,6 +184,32 @@ size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg, ...@@ -111,6 +184,32 @@ size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
uint8_t *password, size_t password_len, uint8_t *password, size_t password_len,
StunUsageTurnCompatibility compatibility); StunUsageTurnCompatibility compatibility);
/**
* stun_usage_turn_process:
* @msg: The message containing the response
* @relay_addr: A pointer to a #sockaddr structure to fill with the relay address
* that the TURN server allocated for us
* @relay_addrlen: The length of @relay_addr
* @addr: A pointer to a #sockaddr structure to fill with the mapped address
* that the STUN response contains.
* This argument will only be filled if the return value
* of the function is #STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS
* @addrlen: The length of @addr
* @alternate_server: A pointer to a #sockaddr structure to fill with the
* address of an alternate server to which we should send our new STUN
* Allocate request, in case the currently used TURN server is requesting the use
* of an alternate server. This argument will only be filled if the return value
* of the function is #STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER
* @alternate_server_len: The length of @alternate_server
* @bandwidth: A pointer to fill with the bandwidth the TURN server allocated us
* @lifetime: A pointer to fill with the lifetime of the allocation
* @compatibility: The compatibility mode to use for processing the Allocation
* response
*
* Process a TURN Allocate response and extract the necessary information from
* the message
* Returns: A #StunUsageTurnReturn value
*/
StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg, StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,
struct sockaddr *relay_addr, socklen_t *relay_addrlen, struct sockaddr *relay_addr, socklen_t *relay_addrlen,
struct sockaddr *addr, socklen_t *addrlen, struct sockaddr *addr, socklen_t *addrlen,
...@@ -118,6 +217,19 @@ StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg, ...@@ -118,6 +217,19 @@ StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,
uint32_t *bandwidth, uint32_t *lifetime, uint32_t *bandwidth, uint32_t *lifetime,
StunUsageTurnCompatibility compatibility); StunUsageTurnCompatibility compatibility);
/**
* stun_usage_turn_refresh_process:
* @msg: The message containing the response
* @lifetime: A pointer to fill with the lifetime of the allocation
* @compatibility: The compatibility mode to use for processing the Refresh
* response
*
* Process a TURN Refresh response and extract the necessary information from
* the message
* Returns: A #StunUsageTurnReturn value. A #STUN_USAGE_TURN_RETURN_RELAY_SUCCESS
* means the Refresh was successful, but no relay address is given (kept the same
* as for the original allocation)
*/
StunUsageTurnReturn stun_usage_turn_refresh_process (StunMessage *msg, StunUsageTurnReturn stun_usage_turn_refresh_process (StunMessage *msg,
uint32_t *lifetime, StunUsageTurnCompatibility compatibility); uint32_t *lifetime, StunUsageTurnCompatibility compatibility);
......
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