GUPnPSimpleIgd

GUPnPSimpleIgd — A simple class to map ports on UPnP routers

Synopsis

                    GUPnPSimpleIgd;
                    GUPnPSimpleIgdClass;
#define             GUPNP_SIMPLE_IGD_ERROR
enum                GUPnPSimpleIgdError;
GUPnPSimpleIgd*     gupnp_simple_igd_new                (GMainContext *main_context);
void                gupnp_simple_igd_add_port           (GUPnPSimpleIgd *self,
                                                         const gchar *protocol,
                                                         guint16 external_port,
                                                         const gchar *local_ip,
                                                         guint16 local_port,
                                                         guint32 lease_duration,
                                                         const gchar *description);
void                gupnp_simple_igd_remove_port        (GUPnPSimpleIgd *self,
                                                         const gchar *protocol,
                                                         guint external_port);

Object Hierarchy

  GObject
   +----GUPnPSimpleIgd
         +----GUPnPSimpleIgdThread

Properties

  "main-context"             gpointer              : Read / Write / Construct Only
  "request-timeout"          guint                 : Read / Write

Signals

  "error-mapping-port"                             : Run Last / Has Details
  "mapped-external-port"                           : Run Last

Description

This simple class allows applications to map ports on UPnP routers. It implements the basic functionalities to map ports to external ports. It also allows implementations to know the external port from the router's perspective.

Details

GUPnPSimpleIgd

typedef struct _GUPnPSimpleIgd GUPnPSimpleIgd;

All members are private, access them using methods and properties

GUPnPSimpleIgdClass

typedef struct {
  GObjectClass parent_class;

  /*virtual functions */

  void (*add_port) (GUPnPSimpleIgd *self,
      const gchar *protocol,
      guint16 external_port,
      const gchar *local_ip,
      guint16 local_port,
      guint32 lease_duration,
      const gchar *description);

  void (*remove_port) (GUPnPSimpleIgd *self,
      const gchar *protocol,
      guint external_port);
} GUPnPSimpleIgdClass;

The Raw UDP component transmitter class

GObjectClass parent_class; Our parent
add_port () An implementation of the add_port function
remove_port () An implementation of the delete_port function

GUPNP_SIMPLE_IGD_ERROR

#define GUPNP_SIMPLE_IGD_ERROR (gupnp_simple_igd_get_error_domain ())

The GError domain for error coming out of GUPnpSimpleIGD

enum GUPnPSimpleIgdError

typedef enum {
  GUPNP_SIMPLE_IGD_ERROR_EXTERNAL_ADDRESS,
} GUPnPSimpleIgdError;

Errors coming out of the GUPnPSimpleIGD object.

GUPNP_SIMPLE_IGD_ERROR_EXTERNAL_ADDRESS Error getting the external address of the router

gupnp_simple_igd_new ()

GUPnPSimpleIgd*     gupnp_simple_igd_new                (GMainContext *main_context);

This creates a new GUPnpSimpleIgd object using the special GMainContext

main_context : the GMainContext to use (may be NULL for the default main context)
Returns : a new GUPnPSimpleIgd

gupnp_simple_igd_add_port ()

void                gupnp_simple_igd_add_port           (GUPnPSimpleIgd *self,
                                                         const gchar *protocol,
                                                         guint16 external_port,
                                                         const gchar *local_ip,
                                                         guint16 local_port,
                                                         guint32 lease_duration,
                                                         const gchar *description);

This adds a port to the router's forwarding table. The mapping will be automatically refreshed by this object until it is either removed with gupnp_simple_igd_remove_port() or the object disapears.

If there is a problem, the "error-mapping-port" signal will be emitted. If a router is found and a port is mapped correctly, "mapped-external-port" will be emitted. These signals may be emitted multiple times if there are multiple routers present.

self : The GUPnPSimpleIgd object
protocol : the protocol "UDP" or "TCP"
external_port : The port to try to open on the external device, 0 means to try a random port if the same port as the local port is already taken
local_ip : The IP address to forward packets to (most likely the local ip address)
local_port : The local port to forward packets to
lease_duration : The duration of the lease (it will be auto-renewed before it expires). This is in seconds.
description : The description that will appear in the router's table

gupnp_simple_igd_remove_port ()

void                gupnp_simple_igd_remove_port        (GUPnPSimpleIgd *self,
                                                         const gchar *protocol,
                                                         guint external_port);

This tries to remove a port entry from the routers that was previously added with gupnp_simple_igd_add_port(). There is no indicated of success or failure it is a best effort mechanism. If it fails, the bindings will disapears after the lease duration set when the port where added.

self : The GUPnPSimpleIgd object
protocol : the protocol "UDP" or "TCP" as given to gupnp_simple_igd_add_port()
external_port : The port to try to open on the external device as given to gupnp_simple_igd_add_port()

Property Details

The "main-context" property

  "main-context"             gpointer              : Read / Write / Construct Only

This GMainContext will be used for all async activities.

The "request-timeout" property

  "request-timeout"          guint                 : Read / Write

After this timeout, the request is considered to have failed andis dropped (in seconds).

Default value: 5

Signal Details

The "error-mapping-port" signal

void                user_function                      (GUPnPSimpleIgd *self,
                                                        gpointer        error,
                                                        gchar          *proto,
                                                        guint           external_port,
                                                        gchar          *local_ip,
                                                        guint           local_port,
                                                        gchar          *description,
                                                        gpointer        user_data)          : Run Last / Has Details

This means that mapping a port on a specific IGD has failed (it may still succeed on other IGDs on the network).

self : GUPnPSimpleIgd that emitted the signal
error : a GError
proto : The requested protocol
external_port : the external port requested in gupnp_simple_igd_add_port()
local_ip : internal ip this is forwarded to
local_port : the local port
description : the passed description
user_data : user data set when the signal handler was connected.

The "mapped-external-port" signal

void                user_function                      (GUPnPSimpleIgd *self,
                                                        gchar          *proto,
                                                        gchar          *external_ip,
                                                        gchar          *replaces_external_ip,
                                                        guint           external_port,
                                                        gchar          *local_ip,
                                                        guint           local_port,
                                                        gchar          *description,
                                                        gpointer        user_data)                 : Run Last

This signal means that an IGD has been found that that adding a port mapping has succeeded.

self : GUPnPSimpleIgd that emitted the signal
proto : the requested protocol ("UDP" or "TCP")
external_ip : the external IP
replaces_external_ip : if this mapping replaces another mapping, this is the old external IP
external_port : the external port that was allocated
local_ip : internal ip this is forwarded to
local_port : the local port
description : the user's selected description
user_data : user data set when the signal handler was connected.
Generated by GTK-Doc V1.10