Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
L
libnice
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Analytics
Analytics
CI / CD
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
cpp-libs
libnice
Commits
259d6efa
Commit
259d6efa
authored
Feb 23, 2009
by
Youness Alaoui
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Add documentation for libstun and fix some docs elsewhere
parent
b5d0c1fd
Changes
9
Expand all
Hide whitespace changes
Inline
Side-by-side
Showing
9 changed files
with
753 additions
and
132 deletions
+753
-132
docs/reference/libnice/Makefile.am
docs/reference/libnice/Makefile.am
+13
-5
docs/reference/libnice/libnice-docs.sgml
docs/reference/libnice/libnice-docs.sgml
+6
-0
docs/reference/libnice/libnice-sections.txt
docs/reference/libnice/libnice-sections.txt
+129
-70
stun/stunagent.h
stun/stunagent.h
+257
-18
stun/stunmessage.h
stun/stunmessage.h
+16
-2
stun/usages/bind.h
stun/usages/bind.h
+69
-1
stun/usages/ice.h
stun/usages/ice.h
+103
-28
stun/usages/timer.h
stun/usages/timer.h
+48
-8
stun/usages/turn.h
stun/usages/turn.h
+112
-0
No files found.
docs/reference/libnice/Makefile.am
View file @
259d6efa
...
@@ -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.
...
...
docs/reference/libnice/libnice-docs.sgml
View file @
259d6efa
...
@@ -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>
docs/reference/libnice/libnice-sections.txt
View file @
259d6efa
<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>
N
ICE_CANDIDATE_MAX_FOUNDATION
N
iceCandidate
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>
stun/stunagent.h
View file @
259d6efa
This diff is collapsed.
Click to expand it.
stun/stunmessage.h
View file @
259d6efa
...
@@ -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
);
...
...
stun/usages/bind.h
View file @
259d6efa
...
@@ -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
);
...
...
stun/usages/ice.h
View file @
259d6efa
...
@@ -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
);
...
...
stun/usages/timer.h
View file @
259d6efa
...
@@ -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
...
...
stun/usages/turn.h
View file @
259d6efa
...
@@ -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
);
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment