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