home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / upnp.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  4.6 KB  |  132 lines
  1. /**
  2.  * @file upnp.h Universal Plug N Play API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25.  
  26. #ifndef _PURPLE_UPNP_H_
  27. #define _PURPLE_UPNP_H_
  28.  
  29. typedef struct _UPnPMappingAddRemove UPnPMappingAddRemove;
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. /**************************************************************************/
  36. /** @name UPnP API                                                        */
  37. /**************************************************************************/
  38. /*@{*/
  39.  
  40. /* typedef struct _PurpleUPnPRequestData PurpleUPnPRequestData; */
  41.  
  42. typedef void (*PurpleUPnPCallback) (gboolean success, gpointer data);
  43.  
  44.  
  45. /**
  46.  * Initialize UPnP
  47.  */
  48. void purple_upnp_init(void);
  49.  
  50.  
  51. /**
  52.  * Sends a discovery request to search for a UPnP enabled IGD that
  53.  * contains the WANIPConnection service that will allow us to recieve the
  54.  * public IP address of the IGD, and control it for forwarding ports.
  55.  * The result will be cached for further use.
  56.  *
  57.  * @param cb an optional callback function to be notified when the UPnP
  58.  *           discovery is complete
  59.  * @param cb_data Extra data to be passed to the callback
  60.  */
  61. void purple_upnp_discover(PurpleUPnPCallback cb, gpointer cb_data);
  62.  
  63. #if 0
  64. /**
  65.  * Retrieve the current UPnP control info, if there is any available.
  66.  * This will only be filled in if purple_upnp_discover() had been called,
  67.  * and finished discovering.
  68.  *
  69.  * @return The control URL for the IGD we'll use to use the IGD services
  70.  */
  71. const PurpleUPnPControlInfo* purple_upnp_get_control_info(void);
  72. #endif
  73.  
  74. /**
  75.  * Gets the IP address from a UPnP enabled IGD that sits on the local
  76.  * network, so when getting the network IP, instead of returning the
  77.  * local network IP, the public IP is retrieved.  This is a cached value from
  78.  * the time of the UPnP discovery.
  79.  *
  80.  * @return The IP address of the network, or NULL if something went wrong
  81.  */
  82. const gchar* purple_upnp_get_public_ip(void);
  83.  
  84. /**
  85.  * Cancel a pending port mapping request initiated with either
  86.  * purple_upnp_set_port_mapping() or purple_upnp_remove_port_mapping().
  87.  *
  88.  * @param mapping_data The data returned when you initiated the UPnP mapping request.
  89.  */
  90. void purple_upnp_cancel_port_mapping(UPnPMappingAddRemove *mapping_data);
  91.  
  92. /**
  93.  * Maps Ports in a UPnP enabled IGD that sits on the local network to
  94.  * this purple client. Essentially, this function takes care of the port
  95.  * forwarding so things like file transfers can work behind NAT firewalls
  96.  *
  97.  * @param portmap The port to map to this client
  98.  * @param protocol The protocol to map, either "TCP" or "UDP"
  99.  * @param cb an optional callback function to be notified when the mapping
  100.  *           addition is complete
  101.  * @param cb_data Extra data to be passed to the callback
  102.  *
  103.  * @return Data which can be passed to purple_upnp_port_mapping_cancel() to cancel
  104.  */
  105. UPnPMappingAddRemove *purple_upnp_set_port_mapping(unsigned short portmap, const gchar* protocol,
  106.         PurpleUPnPCallback cb, gpointer cb_data);
  107.  
  108. /**
  109.  * Deletes a port mapping in a UPnP enabled IGD that sits on the local network
  110.  * to this purple client. Essentially, this function takes care of deleting the
  111.  * port forwarding after they have completed a connection so another client on
  112.  * the local network can take advantage of the port forwarding
  113.  *
  114.  * @param portmap The port to delete the mapping for
  115.  * @param protocol The protocol to map to. Either "TCP" or "UDP"
  116.  * @param cb an optional callback function to be notified when the mapping
  117.  *           removal is complete
  118.  * @param cb_data Extra data to be passed to the callback
  119.  *
  120.  * @return Data which can be passed to purple_upnp_port_mapping_cancel() to cancel
  121.  */
  122. UPnPMappingAddRemove *purple_upnp_remove_port_mapping(unsigned short portmap,
  123.         const gchar* protocol, PurpleUPnPCallback cb, gpointer cb_data);
  124.  
  125. /*@}*/
  126.  
  127. #ifdef __cplusplus
  128. }
  129. #endif
  130.  
  131. #endif /* _PURPLE_UPNP_H_ */
  132.