stun/usages/ice.h

   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