stun/usages/ice.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2007 Nokia Corporation. All rights reserved.
   5  *  Contact: Rémi Denis-Courmont
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version
   8  * 1.1 (the "License"); you may not use this file except in compliance with
   9  * the License. You may obtain a copy of the License at
  10  * http://www.mozilla.org/MPL/
  11  *
  12  * Software distributed under the License is distributed on an "AS IS" basis,
  13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14  * for the specific language governing rights and limitations under the
  15  * License.
  16  *
  17  * The Original Code is the Nice GLib ICE library.
  18  *
  19  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  20  * Corporation. All Rights Reserved.
  21  *
  22  * Contributors:
  23  *   Rémi Denis-Courmont, Nokia
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of the
  26  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  27  * case the provisions of LGPL are applicable instead of those above. If you
  28  * wish to allow use of your version of this file only under the terms of the
  29  * LGPL and not to allow others to use your version of this file under the
  30  * MPL, indicate your decision by deleting the provisions above and replace
  31  * them with the notice and other provisions required by the LGPL. If you do
  32  * not delete the provisions above, a recipient may use your version of this
  33  * file under either the MPL or the LGPL.
  34  */
  35
  36 #ifndef STUN_CONNCHECK_H
  37 # define STUN_CONNCHECK_H 1
  38
  39 /**
  40  * @file ice.h
  41  * @brief STUN/ICE connectivity checks
  42  */
  43
  44 # include "stun/stunagent.h"
  45
  46 # ifdef __cplusplus
  47 extern "C" {
  48 # endif
  49
  50 typedef enum {
  51   STUN_USAGE_ICE_COMPATIBILITY_DRAFT19,
  52   STUN_USAGE_ICE_COMPATIBILITY_GOOGLE,
  53   STUN_USAGE_ICE_COMPATIBILITY_MSN,
  54 } StunUsageIceCompatibility;
  55
  56 typedef enum {
  57   STUN_USAGE_ICE_RETURN_SUCCESS,
  58   STUN_USAGE_ICE_RETURN_ERROR,
  59   STUN_USAGE_ICE_RETURN_RETRY,
  60   STUN_USAGE_ICE_RETURN_ROLE_CONFLICT,
  61   STUN_USAGE_ICE_RETURN_INVALID_REQUEST,
  62   STUN_USAGE_ICE_RETURN_INVALID_METHOD,
  63   STUN_USAGE_ICE_RETURN_MEMORY_ERROR,
  64   STUN_USAGE_ICE_RETURN_INVALID_ADDRESS,
  65 } StunUsageIceReturn;
  66
  67
  68
  69 size_t
  70 stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg,
  71     uint8_t *buffer, size_t buffer_len,
  72     const uint8_t *username, const size_t username_len,
  73     const uint8_t *password, const size_t password_len,
  74     bool cand_use, bool controlling, uint32_t priority,
  75     uint64_t tie, StunUsageIceCompatibility compatibility);
  76
  77
  78 StunUsageIceReturn stun_usage_ice_conncheck_process (StunMessage *msg,
  79     struct sockaddr *addr, socklen_t *addrlen,
  80     StunUsageIceCompatibility compatibility);
  81
  82 /**
  83  * Tries to parse a STUN connectivity check (Binding request) and format a
  84  * response accordingly.
  85  *
  86  * @param buf [OUT] output buffer to write a Binding response to. May refer
  87  * to the same buffer space as the request message.
  88  * @param plen [IN/OUT] output buffer size on entry, response length on exit
  89  * @param msg pointer to the first byte of the binding request
  90  * @param src socket address the message was received from
  91  * @param srclen byte length of the socket address
  92  * @param username STUN username
  93  * @param password HMAC secret password
  94  * @param control [IN/OUT] whether we are controlling ICE or not
  95  * @param tie tie breaker value for ICE role determination
  96  *
  97  * @return 0 if successful (@a rbuf contains a <b>non-error</b> response),
  98  * EINVAL: malformatted request message or socket address,
  99  * EAFNOSUPPORT: unsupported socket address family,
 100  * EPROTO: unsupported request message type or parameter,
 101  * ENOBUFS: insufficient response buffer space.
 102  * EACCES: ICE role conflict occurred, please recheck the flag at @a control
 103  *
 104  * In case of error, the value at @a plen is set to the size of an error
 105  * response, or 0 if no error response should be sent.
 106  */
 107 StunUsageIceReturn
 108 stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req,
 109     StunMessage *msg, uint8_t *buf, size_t *plen,
 110     const struct sockaddr *src, socklen_t srclen,
 111     bool *control, uint64_t tie,
 112     StunUsageIceCompatibility compatibility);
 113
 114 /**
 115  * Extracts the priority from a STUN message.
 116  * @param msg valid STUN message.
 117  * @return host byte order priority, or 0 if not specified.
 118  */
 119 uint32_t stun_usage_ice_conncheck_priority (const StunMessage *msg);
 120
 121 /**
 122  * Extracts the "use candidate" flag from a STUN message.
 123  * @param msg valid STUN message.
 124  * @return true if the flag is set, false if not.
 125  */
 126 bool stun_usage_ice_conncheck_use_candidate (const StunMessage *msg);
 127
 128 # ifdef __cplusplus
 129 }
 130 # endif
 131
 132 #endif