1 
2 /*
3  * This file is part of the Nice GLib ICE library.
4  *
5  * (C) 2008-2009 Collabora Ltd.
6  *  Contact: Youness Alaoui
7  * (C) 2007-2009 Nokia Corporation. All rights reserved.
8  *  Contact: Rémi Denis-Courmont
9  *
10  * The contents of this file are subject to the Mozilla Public License Version
11  * 1.1 (the "License"); you may not use this file except in compliance with
12  * the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS" basis,
16  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17  * for the specific language governing rights and limitations under the
18  * License.
19  *
20  * The Original Code is the Nice GLib ICE library.
21  *
22  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
23  * Corporation. All Rights Reserved.
24  *
25  * Contributors:
26  *   Youness Alaoui, Collabora Ltd.
27  *   Rémi Denis-Courmont, Nokia
28  *
29  * Alternatively, the contents of this file may be used under the terms of the
30  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
31  * case the provisions of LGPL are applicable instead of those above. If you
32  * wish to allow use of your version of this file only under the terms of the
33  * LGPL and not to allow others to use your version of this file under the
34  * MPL, indicate your decision by deleting the provisions above and replace
35  * them with the notice and other provisions required by the LGPL. If you do
36  * not delete the provisions above, a recipient may use your version of this
37  * file under either the MPL or the LGPL.
38  */
39 
40 #ifndef STUN_CONNCHECK_H
41 # define STUN_CONNCHECK_H 1
42 
43 /**
44  * SECTION:ice
45  * @short_description: STUN ICE Usage
46  * @include: stun/usages/ice.h
47  * @stability: Stable
48  *
49  * The STUN ICE usage allows for easily creating and parsing STUN Binding
50  * requests and responses used for ICE connectivity checks. The API allows you
51  * to create a connectivity check message, parse a response or create a reply
52  * to an incoming connectivity check request.
53  */
54 
55 # include "stun/stunagent.h"
56 
57 # ifdef __cplusplus
58 extern "C" {
59 # endif
60 
61 /**
62  * StunUsageIceCompatibility:
63  * @STUN_USAGE_ICE_COMPATIBILITY_RFC5245: The ICE compatibility with RFC 5245
64  * @STUN_USAGE_ICE_COMPATIBILITY_GOOGLE: The ICE compatibility with Google's
65  * implementation of ICE
66  * @STUN_USAGE_ICE_COMPATIBILITY_MSN: The ICE compatibility with MSN's
67  * implementation of ICE
68  * @STUN_USAGE_ICE_COMPATIBILITY_MSICE2: The ICE compatibility with [MS-ICE2]
69  * specification
70  * @STUN_USAGE_ICE_COMPATIBILITY_DRAFT19: The ICE compatibility with draft 19
71  * @STUN_USAGE_ICE_COMPATIBILITY_WLM2009: An alias
72  * for @STUN_USAGE_ICE_COMPATIBILITY_MSICE2
73  *
74  * This enum defines which compatibility modes this ICE usage can use
75  *
76  * <warning>@STUN_USAGE_ICE_COMPATIBILITY_DRAFT19 and
77  * @STUN_USAGE_ICE_COMPATIBILITY_WLM2009 are deprecated and should not be used
78  * in newly-written code. They are kept for compatibility reasons and represent
79  * the same compatibilities as @STUN_USAGE_ICE_COMPATIBILITY_RFC5245 and
80  * @STUN_USAGE_ICE_COMPATIBILITY_MSICE2 respectively.</warning>
81  */
82 typedef enum {
83   STUN_USAGE_ICE_COMPATIBILITY_RFC5245,
84   STUN_USAGE_ICE_COMPATIBILITY_GOOGLE,
85   STUN_USAGE_ICE_COMPATIBILITY_MSN,
86   STUN_USAGE_ICE_COMPATIBILITY_MSICE2,
87   STUN_USAGE_ICE_COMPATIBILITY_DRAFT19 = STUN_USAGE_ICE_COMPATIBILITY_RFC5245,
88   STUN_USAGE_ICE_COMPATIBILITY_WLM2009 = STUN_USAGE_ICE_COMPATIBILITY_MSICE2,
89 } StunUsageIceCompatibility;
90 
91 
92 /**
93  * StunUsageIceReturn:
94  * @STUN_USAGE_ICE_RETURN_SUCCESS: The function succeeded
95  * @STUN_USAGE_ICE_RETURN_ERROR: There was an unspecified error
96  * @STUN_USAGE_ICE_RETURN_INVALID: The message is invalid for processing
97  * @STUN_USAGE_ICE_RETURN_ROLE_CONFLICT: A role conflict was detected
98  * @STUN_USAGE_ICE_RETURN_INVALID_REQUEST: The message is an not a request
99  * @STUN_USAGE_ICE_RETURN_INVALID_METHOD: The method of the request is invalid
100  * @STUN_USAGE_ICE_RETURN_MEMORY_ERROR: The buffer size is too small to hold
101  * the STUN reply
102  * @STUN_USAGE_ICE_RETURN_INVALID_ADDRESS: The mapped address argument has
103  * an invalid address family
104  * @STUN_USAGE_ICE_RETURN_NO_MAPPED_ADDRESS: The response is valid but no
105  * MAPPED-ADDRESS or XOR-MAPPED-ADDRESS attribute was found
106  *
107  * Return value of stun_usage_ice_conncheck_process() and
108  * stun_usage_ice_conncheck_create_reply() which allows you to see what
109  * status the function call returned.
110  */
111 typedef enum {
112   STUN_USAGE_ICE_RETURN_SUCCESS,
113   STUN_USAGE_ICE_RETURN_ERROR,
114   STUN_USAGE_ICE_RETURN_INVALID,
115   STUN_USAGE_ICE_RETURN_ROLE_CONFLICT,
116   STUN_USAGE_ICE_RETURN_INVALID_REQUEST,
117   STUN_USAGE_ICE_RETURN_INVALID_METHOD,
118   STUN_USAGE_ICE_RETURN_MEMORY_ERROR,
119   STUN_USAGE_ICE_RETURN_INVALID_ADDRESS,
120   STUN_USAGE_ICE_RETURN_NO_MAPPED_ADDRESS,
121 } StunUsageIceReturn;
122 
123 
124 /**
125  * stun_usage_ice_conncheck_create:
126  * @agent: The #StunAgent to use to build the request
127  * @msg: The #StunMessage to build
128  * @buffer: The buffer to use for creating the #StunMessage
129  * @buffer_len: The size of the @buffer
130  * @username: The username to use in the request
131  * @username_len: The length of @username
132  * @password: The key to use for building the MESSAGE-INTEGRITY
133  * @password_len: The length of @password
134  * @cand_use: Set to %TRUE to append the USE-CANDIDATE flag to the request
135  * @controlling: Set to %TRUE if you are the controlling agent or set to
136  * %FALSE if you are the controlled agent.
137  * @priority: The value of the PRIORITY attribute
138  * @tie: The value of the tie-breaker to put in the ICE-CONTROLLED or
139  * ICE-CONTROLLING attribute
140  * @candidate_identifier: The foundation value to put in the
141  * CANDIDATE-IDENTIFIER attribute
142  * @compatibility: The compatibility mode to use for building the conncheck
143  * request
144  *
145  * Builds an ICE connectivity check STUN message.
146  * If the compatibility is not #STUN_USAGE_ICE_COMPATIBILITY_RFC5245, the
147  * @cand_use, @controlling, @priority and @tie arguments are not used.
148  * If the compatibility is not #STUN_USAGE_ICE_COMPATIBILITY_MSICE2, the
149  * @candidate_identifier argument is not used.
150  * Returns: The length of the message built.
151  */
152 size_t
153 stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg,
154     uint8_t *buffer, size_t buffer_len,
155     const uint8_t *username, const size_t username_len,
156     const uint8_t *password, const size_t password_len,
157     bool cand_use, bool controlling, uint32_t priority,
158     uint64_t tie, const char *candidate_identifier,
159     StunUsageIceCompatibility compatibility);
160 
161 
162 /**
163  * stun_usage_ice_conncheck_process:
164  * @msg: The #StunMessage to process
165  * @addr: A pointer to a #sockaddr structure to fill with the mapped address
166  * that the STUN connectivity check response contains
167  * @addrlen: The length of @addr
168  * @compatibility: The compatibility mode to use for processing the conncheck
169  * response
170  *
171  * Process an ICE connectivity check STUN message and retrieve the
172  * mapped address from the message
173  * <para> See also stun_usage_ice_conncheck_priority() and
174  * stun_usage_ice_conncheck_use_candidate() </para>
175  * Returns: A #StunUsageIceReturn value
176  */
177 StunUsageIceReturn stun_usage_ice_conncheck_process (StunMessage *msg,
178     struct sockaddr_storage *addr, socklen_t *addrlen,
179     StunUsageIceCompatibility compatibility);
180 
181 /**
182  * stun_usage_ice_conncheck_create_reply:
183  * @agent: The #StunAgent to use to build the response
184  * @req: The original STUN request to reply to
185  * @msg: The #StunMessage to build
186  * @buf: The buffer to use for creating the #StunMessage
187  * @plen: A pointer containing the size of the @buffer on input.
188  * Will contain the length of the message built on output.
189  * @src: A pointer to a #sockaddr structure containing the source address from
190  * which the request was received. Will be used as the mapped address in the
191  * response
192  * @srclen: The length of @addr
193  * @control: Set to %TRUE if you are the controlling agent or set to
194  * %FALSE if you are the controlled agent.
195  * @tie: The value of the tie-breaker to put in the ICE-CONTROLLED or
196  * ICE-CONTROLLING attribute
197  * @compatibility: The compatibility mode to use for building the conncheck
198  * response
199  *
200  * Tries to parse a STUN connectivity check request and builds a
201  * response accordingly.
202  <note>
203    <para>
204      In case of error, the @msg is filled with the appropriate error response
205      to be sent and the value of @plen is set to the size of that message.
206      If @plen has a size of 0, then no error response should be sent.
207    </para>
208  </note>
209  * Returns: A #StunUsageIceReturn value
210  */
211 StunUsageIceReturn
212 stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req,
213     StunMessage *msg, uint8_t *buf, size_t *plen,
214     const struct sockaddr_storage *src, socklen_t srclen,
215     bool *control, uint64_t tie,
216     StunUsageIceCompatibility compatibility);
217 
218 /**
219  * stun_usage_ice_conncheck_priority:
220  * @msg: The #StunMessage to parse
221  *
222  * Extracts the priority from a STUN message.
223  * Returns: host byte order priority, or 0 if not specified.
224  */
225 uint32_t stun_usage_ice_conncheck_priority (const StunMessage *msg);
226 
227 /**
228  * stun_usage_ice_conncheck_use_candidate:
229  * @msg: The #StunMessage to parse
230  *
231  * Extracts the USE-CANDIDATE attribute flag from a STUN message.
232  * Returns: %TRUE if the flag is set, %FALSE if not.
233  */
234 bool stun_usage_ice_conncheck_use_candidate (const StunMessage *msg);
235 
236 # ifdef __cplusplus
237 }
238 # endif
239 
240 #endif
241