stun/usages/bind.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_BIND_H
  40 # define STUN_BIND_H 1
  41
  42 /**
  43  * SECTION:bind
  44  * @short_description: STUN Binding Usage
  45  * @include: stun/usages/bind.h
  46  * @stability: Stable
  47  *
  48  * The STUN Binding usage allows for easily creating and parsing STUN Binding
  49  * requests and responses. It offers both an asynchronous and a synchronous API
  50  * that uses the STUN timer usage.
  51  */
  52
  53
  54 #ifdef _WIN32
  55 #  include "../win32_common.h"
  56 #else
  57 # include <stdbool.h>
  58 # include <stdint.h>
  59 #endif
  60
  61 # include "stun/stunagent.h"
  62
  63 # ifdef __cplusplus
  64 extern "C" {
  65 # endif
  66
  67 /**
  68  * StunUsageBindReturn:
  69  * @STUN_USAGE_BIND_RETURN_SUCCESS: The binding usage succeeded
  70  * @STUN_USAGE_BIND_RETURN_ERROR: There was an unknown error in the bind usage
  71  * @STUN_USAGE_BIND_RETURN_INVALID: The message is invalid and should be ignored
  72  * @STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER: The binding request has an
  73  * ALTERNATE-SERVER attribute
  74  * @STUN_USAGE_BIND_RETURN_TIMEOUT: The binding was unsuccessful because it has
  75  * timed out.
  76  *
  77  * Return value of stun_usage_bind_process() and stun_usage_bind_run() which
  78  * allows you to see what status the function call returned.
  79  */
  80 typedef enum {
  81   STUN_USAGE_BIND_RETURN_SUCCESS,
  82   STUN_USAGE_BIND_RETURN_ERROR,
  83   STUN_USAGE_BIND_RETURN_INVALID,
  84   STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER,
  85   STUN_USAGE_BIND_RETURN_TIMEOUT,
  86 } StunUsageBindReturn;
  87
  88
  89 /**
  90  * stun_usage_bind_create:
  91  * @agent: The #StunAgent to use to create the binding request
  92  * @msg: The #StunMessage to build
  93  * @buffer: The buffer to use for creating the #StunMessage
  94  * @buffer_len: The size of the @buffer
  95  *
  96  * Create a new STUN binding request to use with a STUN server.
  97  * Returns: The length of the built message.
  98  */
  99 size_t stun_usage_bind_create (StunAgent *agent, StunMessage *msg,
 100     uint8_t *buffer, size_t buffer_len);
 101
 102 /**
 103  * stun_usage_bind_process:
 104  * @msg: The #StunMessage to process
 105  * @addr: A pointer to a #sockaddr structure to fill with the mapped address
 106  * that the STUN server gives us
 107  * @addrlen: The length of @add. rMust be set to the size of the @addr socket
 108  * address and will be set to the actual length of the socket address.
 109  * @alternate_server: A pointer to a #sockaddr structure to fill with the
 110  * address of an alternate server to which we should send our new STUN
 111  * binding request, in case the currently used STUN server is requesting the use
 112  * of an alternate server. This argument will only be filled if the return value
 113  * of the function is #STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER
 114  * @alternate_server_len: The length of @alternate_server. Must be set to
 115  * the size of the @alternate_server socket address and will be set to the
 116  * actual length of the socket address.
 117  *
 118  * Process a STUN binding response and extracts the mapped address from the STUN
 119  * message. Also checks for the ALTERNATE-SERVER attribute.
 120  * Returns: A #StunUsageBindReturn value.
 121  * Note that #STUN_USAGE_BIND_RETURN_TIMEOUT cannot be returned by this function
 122  */
 123 StunUsageBindReturn stun_usage_bind_process (StunMessage *msg,
 124     struct sockaddr *addr, socklen_t *addrlen,
 125     struct sockaddr *alternate_server, socklen_t *alternate_server_len);
 126
 127 /**
 128  * stun_usage_bind_keepalive:
 129  * @agent: The #StunAgent to use to build the message
 130  * @msg: The #StunMessage to build
 131  * @buf: The buffer to use for creating the #StunMessage
 132  * @len: The size of the @buf
 133  *
 134  * Creates a STUN binding indication that can be used for a keepalive.
 135  * Since this is an indication message, no STUN response will be generated
 136  * and it can only be used as a keepalive message.
 137  * Returns: The length of the message to send
 138  */
 139 size_t stun_usage_bind_keepalive (StunAgent *agent, StunMessage *msg,
 140     uint8_t *buf, size_t len);
 141
 142 /**
 143  * stun_usage_bind_run:
 144  * @srv: A pointer to the #sockaddr structure representing the STUN server's
 145  * address
 146  * @srvlen: The length of @srv
 147  * @addr: A pointer to a #sockaddr structure to fill with the mapped address
 148  * that the STUN server gives us
 149  * @addrlen: The length of @addr
 150  *
 151  * This is a convenience function that will do a synchronous Binding request to
 152  * a server and wait for its answer. It will create the socket transports and
 153  * use the #StunTimer usage to send the request and handle the response.
 154  * Returns: A #StunUsageBindReturn.
 155  * Possible return values are #STUN_USAGE_BIND_RETURN_SUCCESS,
 156  * #STUN_USAGE_BIND_RETURN_ERROR and #STUN_USAGE_BIND_RETURN_TIMEOUT
 157  */
 158 StunUsageBindReturn stun_usage_bind_run (const struct sockaddr *srv,
 159     socklen_t srvlen, struct sockaddr *addr, socklen_t *addrlen);
 160
 161 # ifdef __cplusplus
 162 }
 163 # endif
 164
 165 #endif