GUPnPSimpleIgd

GUPnPSimpleIgd — A simple class to map ports on UPnP routers

Functions

#define GUPNP_SIMPLE_IGD_ERROR
#define GUPNP_TYPE_SIMPLE_IGD_ERROR
GUPnPSimpleIgd * gupnp_simple_igd_new ()
void gupnp_simple_igd_add_port ()
void gupnp_simple_igd_remove_port ()
gboolean gupnp_simple_igd_delete_all_mappings ()

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

#define GUPNP_SIMPLE_IGD_ERROR (gupnp_simple_igd_error_quark ())

GUPNP_TYPE_SIMPLE_IGD_ERROR

#define GUPNP_TYPE_SIMPLE_IGD_ERROR (gupnp_simple_igd_error_get_type())

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

Types and Values

struct GUPnPSimpleIgd

struct 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);

  void (*remove_port_local) (GUPnPSimpleIgd *self,
      const gchar *protocol,
      const gchar *local_ip,
      guint16 local_port);
} GUPnPSimpleIgdClass;

The Raw UDP component transmitter class

Members

GObjectClass parent_class;

Our parent

  

add_port ()

An implementation of the add_port function

  

remove_port ()

An implementation of the delete_port function

  

remove_port_local ()

    

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

Generated by GTK-Doc V1.21