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