stun/usages/ice.h

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