stun/conncheck.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 # include "stun/bind.h"
  40
  41 # ifdef __cplusplus
  42 extern "C" {
  43 # endif
  44
  45 /**
  46  * @file conncheck.h
  47  * @brief STUN/ICE connectivity checks
  48  */
  49
  50 /**
  51  * Starts a connectivity check using STUN Binding discovery.
  52  *
  53  * @param context pointer to an opaque pointer that will be passed to
  54  * stun_bind_resume() afterward
  55  * @param fd socket to use for discovery, or -1 to create one
  56  * @param srv STUN server socket address
  57  * @param srvlen STUN server socket address length
  58  * @param username nul-terminated username for authentication
  59  * (need not be kept valid after return)
  60  * @param password nul-terminated shared secret (ICE password)
  61  * (need not be kept valid after return)
  62  * @param cand_use whether to include a USE-CANDIDATE flag
  63  * @param priority host-byte order PRIORITY value
  64  * @param controlling whether we are in controlling (true) or
  65  * controlled (false) state
  66  * @param tie control tie breaker value (host-byte order)
  67  *
  68  * @return 0 on success, a standard error value otherwise.
  69  */
  70 int stun_conncheck_start (stun_bind_t **restrict context, int fd,
  71                         const struct sockaddr *restrict srv, socklen_t srvlen,
  72                           const char *username, const char *password,
  73                           bool cand_use, bool controlling, uint32_t priority,
  74                           uint64_t tie);
  75
  76 /**
  77  * Tries to parse a STUN connectivity check (Binding request) and format a
  78  * response accordingly.
  79  *
  80  * @param buf [OUT] output buffer to write a Binding response to. May refer
  81  * to the same buffer space as the request message.
  82  * @param plen [IN/OUT] output buffer size on entry, response length on exit
  83  * @param msg pointer to the first byte of the binding request
  84  * @param src socket address the message was received from
  85  * @param srclen byte length of the socket address
  86  * @param password HMAC secret password
  87  * @param control [IN/OUT] whether we are controlling ICE or not
  88  * @param tie tie breaker value for ICE role determination
  89  *
  90  * @return same as stun_bind_reply() with one additionnal error code:
  91  * EACCES: ICE role conflict occured, please recheck the flag at @a control
  92  *
  93  * @note @a buf and @a msg <b>must not</b> collide.
  94  */
  95 int
  96 stun_conncheck_reply (uint8_t *buf, size_t *restrict plen, const uint8_t *msg,
  97                       const struct sockaddr *restrict src, socklen_t srclen,
  98                       const char *pass, bool *restrict control, uint64_t tie);
  99
 100 /**
 101  * Extracts the username from a STUN message.
 102  * @param msg pointer to the first byte of the binding request
 103  * @param buf where to store the username as a nul-terminated string
 104  * @param buflen byte length of @a buf buffer
 105  *
 106  * @return @a buf on success, NULL on error
 107  */
 108 char *stun_conncheck_username (const uint8_t *restrict msg,
 109                                char *restrict buf, size_t buflen);
 110
 111 /**
 112  * Extracts the priority from a STUN message.
 113  * @param msg valid STUN message.
 114  * @return host byte order priority, or 0 if not specified.
 115  */
 116 uint32_t stun_conncheck_priority (const uint8_t *msg);
 117
 118 /**
 119  * Extracts the "use candidate" flag from a STUN message.
 120  * @param msg valid STUN message.
 121  * @return true if the flag is set, false if not.
 122  */
 123 bool stun_conncheck_use_candidate (const uint8_t *msg);
 124
 125 # ifdef __cplusplus
 126 }
 127 # endif
 128
 129 #endif