stun/usages/turn.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2008-2009 Collabora Ltd.
   5  *  Contact: Youness Alaoui
   6  * (C) 2007-2009 Nokia Corporation. All rights reserved.
   7  *  Contact: Rémi Denis-Courmont
   8  *
   9  * The contents of this file are subject to the Mozilla Public License Version
  10  * 1.1 (the "License"); you may not use this file except in compliance with
  11  * the License. You may obtain a copy of the License at
  12  * http://www.mozilla.org/MPL/
  13  *
  14  * Software distributed under the License is distributed on an "AS IS" basis,
  15  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  16  * for the specific language governing rights and limitations under the
  17  * License.
  18  *
  19  * The Original Code is the Nice GLib ICE library.
  20  *
  21  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  22  * Corporation. All Rights Reserved.
  23  *
  24  * Contributors:
  25  *   Youness Alaoui, Collabora Ltd.
  26  *   Rémi Denis-Courmont, Nokia
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of the
  29  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  30  * case the provisions of LGPL are applicable instead of those above. If you
  31  * wish to allow use of your version of this file only under the terms of the
  32  * LGPL and not to allow others to use your version of this file under the
  33  * MPL, indicate your decision by deleting the provisions above and replace
  34  * them with the notice and other provisions required by the LGPL. If you do
  35  * not delete the provisions above, a recipient may use your version of this
  36  * file under either the MPL or the LGPL.
  37  */
  38
  39 #ifndef STUN_TURN_H
  40 # define STUN_TURN_H 1
  41
  42 /**
  43  * SECTION:turn
  44  * @short_description: TURN Allocation Usage
  45  * @include: stun/usages/turn.h
  46  * @stability: Stable
  47  *
  48  * The STUN TURN usage allows for easily creating and parsing STUN Allocate
  49  * requests and responses used for TURN. The API allows you to create a new
  50  * allocation or refresh an existing one as well as to parse a response to
  51  * an allocate or refresh request.
  52  */
  53
  54
  55 #ifdef _WIN32
  56 #  include "../win32_common.h"
  57 #else
  58 # include <stdbool.h>
  59 # include <stdint.h>
  60 #endif
  61
  62 #ifdef _WIN32
  63 #include <winsock2.h>
  64 #else
  65 #include <sys/types.h>
  66 #include <sys/socket.h>
  67 #endif
  68
  69 # include "stun/stunagent.h"
  70
  71 # ifdef __cplusplus
  72 extern "C" {
  73 # endif
  74
  75 /**
  76  * StunUsageTurnRequestPorts:
  77  * @STUN_USAGE_TURN_REQUEST_PORT_NORMAL: Request a normal port
  78  * @STUN_USAGE_TURN_REQUEST_PORT_EVEN: Request an even port
  79  * @STUN_USAGE_TURN_REQUEST_PORT_EVEN_AND_RESERVE: Request an even port and
  80  * reserve the next higher port
  81  *
  82  * This enum is used to specify which port configuration you want when creating
  83  * a new Allocation
  84  */
  85 typedef enum {
  86   STUN_USAGE_TURN_REQUEST_PORT_NORMAL = 0,
  87   STUN_USAGE_TURN_REQUEST_PORT_EVEN = 1,
  88   STUN_USAGE_TURN_REQUEST_PORT_EVEN_AND_RESERVE = 2
  89 } StunUsageTurnRequestPorts;
  90
  91 /**
  92  * StunUsageTurnCompatibility:
  93  * @STUN_USAGE_TURN_COMPATIBILITY_DRAFT9: Use the specification compatible with
  94  * TURN Draft 09
  95  * @STUN_USAGE_TURN_COMPATIBILITY_GOOGLE: Use the specification compatible with
  96  * Google Talk's relay server
  97  * @STUN_USAGE_TURN_COMPATIBILITY_MSN: Use the specification compatible with
  98  * MSN TURN servers
  99  *
 100  * Specifies which TURN specification compatibility to use
 101  */
 102 typedef enum {
 103   STUN_USAGE_TURN_COMPATIBILITY_DRAFT9,
 104   STUN_USAGE_TURN_COMPATIBILITY_GOOGLE,
 105   STUN_USAGE_TURN_COMPATIBILITY_MSN,
 106   STUN_USAGE_TURN_COMPATIBILITY_OC2007,
 107   STUN_USAGE_TURN_COMPATIBILITY_RFC5766,
 108 } StunUsageTurnCompatibility;
 109
 110 /**
 111  * StunUsageTurnReturn:
 112  * @STUN_USAGE_TURN_RETURN_RELAY_SUCCESS: The response was successful and a relay
 113  * address is provided
 114  * @STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS: The response was successful and a
 115  * relay address as well as a mapped address are provided
 116  * @STUN_USAGE_TURN_RETURN_ERROR: The response resulted in an error
 117  * @STUN_USAGE_TURN_RETURN_INVALID: The response is not a valid response
 118  * @STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER: The server requests the message
 119  * to be sent to an alternate server
 120  *
 121  * Return value of stun_usage_turn_process() and
 122  * stun_usage_turn_refresh_process() which allows you to see what status the
 123  * function call returned.
 124  */
 125 typedef enum {
 126   STUN_USAGE_TURN_RETURN_RELAY_SUCCESS,
 127   STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS,
 128   STUN_USAGE_TURN_RETURN_ERROR,
 129   STUN_USAGE_TURN_RETURN_INVALID,
 130   STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER,
 131 } StunUsageTurnReturn;
 132
 133
 134 /**
 135  * stun_usage_turn_create:
 136  * @agent: The #StunAgent to use to build the request
 137  * @msg: The #StunMessage to build
 138  * @buffer: The buffer to use for creating the #StunMessage
 139  * @buffer_len: The size of the @buffer
 140  * @previous_response: If this is the first request you are sending, set this
 141  * argument to NULL, if it's a subsequent request you are building, then set this
 142  * argument to the response you have received. This argument is used for building
 143  * long term credentials (using the REALM and NONCE attributes) as well as for
 144  * getting the RESERVATION-TOKEN attribute when you previously requested an
 145  * allocation which reserved two ports
 146  * @request_ports: Specify how you want to request the allocated port(s).
 147  * This is only used if the compatibility is set to
 148  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 149  * <para>See #StunUsageTurnRequestPorts </para>
 150  * @bandwidth: The bandwidth to request from the server for the allocation. If
 151  * this value is negative, then no BANDWIDTH attribute is added to the request.
 152  * This is only used if the compatibility is set to
 153  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 154  * @lifetime: The lifetime of the allocation to request from the server. If
 155  * this value is negative, then no LIFETIME attribute is added to the request.
 156  * This is only used if the compatibility is set to
 157  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 158  * @username: The username to use in the request
 159  * @username_len: The length of @username
 160  * @password: The key to use for building the MESSAGE-INTEGRITY
 161  * @password_len: The length of @password
 162  * @compatibility: The compatibility mode to use for building the Allocation
 163  * request
 164  *
 165  * Create a new TURN Allocation request
 166  * Returns: The length of the message to send
 167  */
 168 size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg,
 169     uint8_t *buffer, size_t buffer_len,
 170     StunMessage *previous_response,
 171     StunUsageTurnRequestPorts request_ports,
 172     int32_t bandwidth, int32_t lifetime,
 173     uint8_t *username, size_t username_len,
 174     uint8_t *password, size_t password_len,
 175     StunUsageTurnCompatibility compatibility);
 176
 177 /**
 178  * stun_usage_turn_create_refresh:
 179  * @agent: The #StunAgent to use to build the request
 180  * @msg: The #StunMessage to build
 181  * @buffer: The buffer to use for creating the #StunMessage
 182  * @buffer_len: The size of the @buffer
 183  * @previous_response: If this is the first request you are sending, set this
 184  * argument to NULL, if it's a subsequent request you are building, then set this
 185  * argument to the response you have received. This argument is used for building
 186  * long term credentials (using the REALM and NONCE attributes)
 187  * @lifetime: The lifetime of the allocation to request from the server. If
 188  * this value is negative, then no LIFETIME attribute is added to the request.
 189  * This is only used if the compatibility is set to
 190  * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
 191  * @username: The username to use in the request
 192  * @username_len: The length of @username
 193  * @password: The key to use for building the MESSAGE-INTEGRITY
 194  * @password_len: The length of @password
 195  * @compatibility: The compatibility mode to use for building the Allocation
 196  * request
 197  *
 198  * Create a new TURN Refresh request
 199  * Returns: The length of the message to send
 200  */
 201 size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
 202     uint8_t *buffer, size_t buffer_len,
 203     StunMessage *previous_response, int32_t lifetime,
 204     uint8_t *username, size_t username_len,
 205     uint8_t *password, size_t password_len,
 206     StunUsageTurnCompatibility compatibility);
 207
 208
 209 size_t stun_usage_turn_create_permission (StunAgent *agent, StunMessage *msg,
 210     uint8_t *buffer, size_t buffer_len,
 211     uint8_t *username, size_t username_len,
 212     uint8_t *password, size_t password_len,
 213     uint8_t *realm, size_t realm_len,
 214     uint8_t *nonce, size_t nonce_len,
 215     struct sockaddr *peer,
 216     StunUsageTurnCompatibility compatibility);
 217
 218 /**
 219  * stun_usage_turn_process:
 220  * @msg: The message containing the response
 221  * @relay_addr: A pointer to a #sockaddr structure to fill with the relay address
 222  * that the TURN server allocated for us
 223  * @relay_addrlen: The length of @relay_addr
 224  * @addr: A pointer to a #sockaddr structure to fill with the mapped address
 225  * that the STUN response contains.
 226  * This argument will only be filled if the return value
 227  * of the function is #STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS
 228  * @addrlen: The length of @addr
 229  * @alternate_server: A pointer to a #sockaddr structure to fill with the
 230  * address of an alternate server to which we should send our new STUN
 231  * Allocate request, in case the currently used TURN server is requesting the use
 232  * of an alternate server. This argument will only be filled if the return value
 233  * of the function is #STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER
 234  * @alternate_server_len: The length of @alternate_server
 235  * @bandwidth: A pointer to fill with the bandwidth the TURN server allocated us
 236  * @lifetime: A pointer to fill with the lifetime of the allocation
 237  * @compatibility: The compatibility mode to use for processing the Allocation
 238  * response
 239  *
 240  * Process a TURN Allocate response and extract the necessary information from
 241  * the message
 242  * Returns: A #StunUsageTurnReturn value
 243  */
 244 StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,
 245     struct sockaddr *relay_addr, socklen_t *relay_addrlen,
 246     struct sockaddr *addr, socklen_t *addrlen,
 247     struct sockaddr *alternate_server, socklen_t *alternate_server_len,
 248     uint32_t *bandwidth, uint32_t *lifetime,
 249     StunUsageTurnCompatibility compatibility);
 250
 251 /**
 252  * stun_usage_turn_refresh_process:
 253  * @msg: The message containing the response
 254  * @lifetime: A pointer to fill with the lifetime of the allocation
 255  * @compatibility: The compatibility mode to use for processing the Refresh
 256  * response
 257  *
 258  * Process a TURN Refresh response and extract the necessary information from
 259  * the message
 260  * Returns: A #StunUsageTurnReturn value. A #STUN_USAGE_TURN_RETURN_RELAY_SUCCESS
 261  * means the Refresh was successful, but no relay address is given (kept the same
 262  * as for the original allocation)
 263  */
 264 StunUsageTurnReturn stun_usage_turn_refresh_process (StunMessage *msg,
 265     uint32_t *lifetime, StunUsageTurnCompatibility compatibility);
 266
 267
 268 # ifdef __cplusplus
 269 }
 270 # endif
 271
 272 #endif