libpurple/stun.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef _PURPLE_STUN_H_
  23 #define _PURPLE_STUN_H_
  24 /**
  25  * SECTION:stun
  26  * @section_id: libpurple-stun
  27  * @short_description: <filename>stun.h</filename>
  28  * @title: STUN API
  29  */
  30
  31 /******************************************************************************
  32  * STUN API
  33  *****************************************************************************/
  34
  35 typedef struct _PurpleStunNatDiscovery PurpleStunNatDiscovery;
  36
  37 /**
  38  * PurpleStunStatus:
  39  * @PURPLE_STUN_STATUS_UNDISCOVERED: No request has been published
  40  * @PURPLE_STUN_STATUS_UNKNOWN: No STUN server reachable
  41  * @PURPLE_STUN_STATUS_DISCOVERING: The request has been sent to the server
  42  * @PURPLE_STUN_STATUS_DISCOVERED: The server has responded
  43  *
  44  * The status of a #PurpleStunNatDiscovery
  45  */
  46 typedef enum {
  47         PURPLE_STUN_STATUS_UNDISCOVERED = -1,
  48         PURPLE_STUN_STATUS_UNKNOWN,
  49         PURPLE_STUN_STATUS_DISCOVERING,
  50         PURPLE_STUN_STATUS_DISCOVERED
  51 } PurpleStunStatus;
  52
  53 /**
  54  * PurpleStunNatType:
  55  * @PURPLE_STUN_NAT_TYPE_PUBLIC_IP: No NAT
  56  * @PURPLE_STUN_NAT_TYPE_UNKNOWN_NAT: NAT is unknown
  57  * @PURPLE_STUN_NAT_TYPE_FULL_CONE: NAT is a full cone
  58  * @PURPLE_STUN_NAT_TYPE_RESTRICTED_CONE: NAT is a restricted cone
  59  * @PURPLE_STUN_NAT_TYPE_PORT_RESTRICTED_CONE: NAT is a port restricted cone
  60  * @PURPLE_STUN_NAT_TYPE_SYMMETRIC: NAT is symmetric
  61  *
  62  * The type of NAT that was discovered.
  63  */
  64 typedef enum {
  65         PURPLE_STUN_NAT_TYPE_PUBLIC_IP,
  66         PURPLE_STUN_NAT_TYPE_UNKNOWN_NAT,
  67         PURPLE_STUN_NAT_TYPE_FULL_CONE,
  68         PURPLE_STUN_NAT_TYPE_RESTRICTED_CONE,
  69         PURPLE_STUN_NAT_TYPE_PORT_RESTRICTED_CONE,
  70         PURPLE_STUN_NAT_TYPE_SYMMETRIC
  71 } PurpleStunNatType;
  72
  73 /**
  74  * PurpleStunNatDiscovery:
  75  * @status: The #PurpleStunStatus
  76  * @type: The #PurpleStunNatType
  77  * @publicip: The public ip
  78  * @servername: The name of the stun server
  79  * @lookup_time: The time when the lookup occurred
  80  *
  81  * A data type representing a STUN lookup.
  82  */
  83 struct _PurpleStunNatDiscovery {
  84         PurpleStunStatus status;
  85         PurpleStunNatType type;
  86         char publicip[16];
  87         char *servername;
  88         time_t lookup_time;
  89 };
  90
  91 typedef void (*PurpleStunCallback) (PurpleStunNatDiscovery *);
  92
  93 G_BEGIN_DECLS
  94
  95 /**
  96  * purple_stun_discover:
  97  * @cb: The callback to call when the STUN discovery is finished if the
  98  *           discovery would block.  If the discovery is done, this is NOT
  99  *           called.
 100  *
 101  * Starts a NAT discovery. It returns a PurpleStunNatDiscovery if the discovery
 102  * is already done. Otherwise the callback is called when the discovery is over
 103  * and NULL is returned.
 104  *
 105  * Returns: a #PurpleStunNatDiscovery which includes the public IP and the type
 106  *          of NAT or NULL if discovery would block
 107  */
 108 PurpleStunNatDiscovery *purple_stun_discover(PurpleStunCallback cb);
 109
 110 void purple_stun_init(void);
 111
 112 G_END_DECLS
 113
 114 #endif /* _PURPLE_STUN_H_ */