GUPnPSimpleIgd: GUPnP IGD Reference Manual

## GUPnPSimpleIgd GUPnPSimpleIgd — A simple class to map ports on UPnP routers |

## Functions

GUPnPSimpleIgd * | gupnp_simple_igd_new ()
void | gupnp_simple_igd_add_port ()
void | gupnp_simple_igd_remove_port ()
gboolean | gupnp_simple_igd_delete_all_mappings ()
void | gupnp_simple_igd_remove_port_local ()

## Properties

gpointer | main-context | Read

## Signals

gboolean | context-available | Run Last
void | error-mapping-port | Has Details
void | mapped-external-port | Run Last

## Types and Values

struct | GUPnPSimpleIgd
| GUPnPSimpleIgdClass
#define | GUPNP_SIMPLE_IGD_ERROR
enum | GUPnPSimpleIgdError

## Object Hierarchy

        GObject
        ╰── GUPnPSimpleIgd
            ╰── GUPnPSimpleIgdThread

## 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.

Every call to this object, including its creation, MUST always be done using the same thread local GMainContext pushed via `g_main_context_push_thread_default()`;

## Functions

### gupnp_simple_igd_new ()

    GUPnPSimpleIgd *
    gupnp_simple_igd_new (void);

This creates a new GUPnpSimpleIgd object using the special GMainContext

#### 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()`, `gupnp_simple_igd_remove_port_local()` 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.

#### Parameters

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.

#### Parameters

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()` |

### gupnp_simple_igd_delete_all_mappings ()

    gboolean
    gupnp_simple_igd_delete_all_mappings (GUPnPSimpleIgd *self);

Removes all mappings and prevents other from being formed Should only be called by the dispose function of subclasses

#### Parameters

self | a GUPnPSimpleIgd |

#### Returns

`TRUE` if the object can be disposed, `FALSE` otherwise

### gupnp_simple_igd_remove_port_local ()

    void
    gupnp_simple_igd_remove_port_local (GUPnPSimpleIgd *self,
                                        const gchar *protocol,
                                        const gchar *local_ip,
                                        guint16 local_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.

#### Parameters

self | The GUPnPSimpleIgd object |
protocol | the protocol "UDP" or "TCP" as given to `gupnp_simple_igd_add_port()` |
local_ip | The local ip on the internal device as was to `gupnp_simple_igd_add_port()` |
local_port | The port to try to open on the internal device as given to `gupnp_simple_igd_add_port()` |

## Types and Values

### struct GUPnPSimpleIgd

    struct GUPnPSimpleIgd;

All members are private, access them using methods and properties

### GUPnPSimpleIgdClass

    typedef struct _GUPnPSimpleIgdClass GUPnPSimpleIgdClass;

`add_port` : An implementation of the add_port function `remove_port` : An implementation of the delete_port function `remove_local_port` : An implementation of the remove_local_port function

The Raw UDP component transmitter class

### GUPNP_SIMPLE_IGD_ERROR

    #define GUPNP_SIMPLE_IGD_ERROR (gupnp_simple_igd_error_quark ())

The error domain for GUPnP Simple IGD

### enum GUPnPSimpleIgdError

Errors coming out of the GUPnPSimpleIGD object.

#### Members

GUPNP_SIMPLE_IGD_ERROR_EXTERNAL_ADDRESS | Error getting the external address of the router |

## Property Details

### The `“main-context”` property

      “main-context”             gpointer

This GMainContext will be used for all async activities.

Flags: Read

## Signal Details

### The `“context-available”` signal

    gboolean
    user_function (GUPnPSimpleIgd *self,
                   GObject        *context,
                   gpointer        user_data)

This is to allow the application to control which GUPnPContext this client should use. If the application connects to this signal, it controls if a context will be used by changing the return value of the signal handler.

#### Parameters

self | GUPnPSimpleIgd that emitted the signal |
context | a GUPnPContext |
user_data | user data set when the signal handler was connected. |

#### Returns

FALSE if the context should be used or TRUE if it should be ignored

Flags: Run Last

### The `“error-mapping-port”` signal

    void
    user_function (GUPnPSimpleIgd *self,
                   GError         *error,
                   gchar          *proto,
                   guint           external_port,
                   gchar          *local_ip,
                   guint           local_port,
                   gchar          *description,
                   gpointer        user_data)

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

#### Parameters

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. |

Flags: Has Details

### 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)

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

#### Parameters

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 | IP address that the router should forward the packets to. It could be the address of another machine on the local network |
local_port | the local port |
description | the user's selected description |
user_data | user data set when the signal handler was connected. |

Flags: Run Last