GUPnPContext: GUPnP Reference Manual

## GUPnPContext GUPnPContext — Context object wrapping shared networking bits. |

## Functions

GUPnPContext * | gupnp_context_new ()
const char * | gupnp_context_get_host_ip ()
guint | gupnp_context_get_port ()
SoupServer * | gupnp_context_get_server ()
SoupSession * | gupnp_context_get_session ()
void | gupnp_context_set_subscription_timeout ()
guint | gupnp_context_get_subscription_timeout ()
const char * | gupnp_context_get_default_language ()
void | gupnp_context_set_default_language ()
void | gupnp_context_add_server_handler ()
void | gupnp_context_remove_server_handler ()
void | gupnp_context_host_path ()
gboolean | gupnp_context_host_path_for_agent ()
void | gupnp_context_unhost_path ()
GUPnPAcl * | gupnp_context_get_acl ()
void | gupnp_context_set_acl ()

## Properties

GUPnPAcl * | acl | Read / Write / Construct
gchar * | default-language | Read / Write / Construct
guint | port | Read / Write / Construct Only
SoupServer * | server | Read
SoupSession * | session | Read
guint | subscription-timeout | Read / Write / Construct Only

## Types and Values

struct | GUPnPContext

## Object Hierarchy

        GObject
        ╰── GSSDPClient
            ╰── GUPnPContext

## Implemented Interfaces

GUPnPContext implements GInitable.

## Description

GUPnPContext wraps the networking bits that are used by the various GUPnP classes. It automatically starts a web server on demand.

For debugging, it is possible to see the messages being sent and received by exporting `GUPNP_DEBUG`.

## Functions

### gupnp_context_new ()

    GUPnPContext *
    gupnp_context_new (GMainContext *main_context,
                       const char *iface,
                       guint port,
                       GError **error);

Create a new GUPnPContext with the specified `main_context` , `iface` and `port` .

#### Parameters

main_context | Deprecated: 0.17.2: Always set to `NULL`. If you want to use a different context, use `g_main_context_push_thread_default()`. | [allow-none]
iface | The network interface to use, or `NULL` to auto-detect. | [allow-none]
port | Port to run on, or 0 if you don't care what port is used. |
error | A location to store a GError, or `NULL` |

#### Returns

A new GUPnPContext object, or `NULL` on an error

### gupnp_context_get_host_ip ()

    const char *
    gupnp_context_get_host_ip (GUPnPContext *context);

`gupnp_context_get_host_ip` has been deprecated since version 0.12.7 and should not be used in newly-written code.

The "host-ip" property has moved to the base class GSSDPClient so newer applications should use gssdp_client_get_host_ip instead.

Get the IP address we advertise ourselves as using.

#### Parameters

context | A GUPnPContext |

#### Returns

The IP address. This string should not be freed.

### gupnp_context_get_port ()

    guint
    gupnp_context_get_port (GUPnPContext *context);

`gupnp_context_get_port` is deprecated and should not be used in newly-written code.

Get the port that the SOAP server is running on.

#### Parameters

context | A GUPnPContext |

#### Returns

The port the SOAP server is running on.

### gupnp_context_get_server ()

    SoupServer *
    gupnp_context_get_server (GUPnPContext *context);

Get the SoupServer HTTP server that GUPnP is using.

#### Parameters

context | A GUPnPContext |

#### Returns

The SoupServer used by GUPnP. Do not unref this when finished.

[transfer none]

### gupnp_context_get_session ()

    SoupSession *
    gupnp_context_get_session (GUPnPContext *context);

Get the SoupSession object that GUPnP is using.

#### Parameters

context | A GUPnPContext |

#### Returns

The SoupSession used by GUPnP. Do not unref this when finished.

[transfer none]

Since: 0.12.3

### gupnp_context_set_subscription_timeout ()

    void
    gupnp_context_set_subscription_timeout
                                   (GUPnPContext *context,
                                    guint timeout);

Sets the event subscription timeout to `timeout` . Use 0 if you don't want subscriptions to time out. Note that any client side subscriptions will automatically be renewed.

#### Parameters

context | A GUPnPContext |
timeout | Event subscription timeout in seconds |

### gupnp_context_get_subscription_timeout ()

    guint
    gupnp_context_get_subscription_timeout
                                   (GUPnPContext *context);

Get the event subscription timeout (in seconds), or 0 meaning there is no timeout.

#### Parameters

context | A GUPnPContext |

#### Returns

The event subscription timeout in seconds.

### gupnp_context_get_default_language ()

    const char *
    gupnp_context_get_default_language (GUPnPContext *context);

Get the default Content-Language header for this context.

#### Parameters

context | A GUPnPContext |

#### Returns

The default content of the Content-Language header.

[transfer none]

Since: 0.17.0

### gupnp_context_set_default_language ()

    void
    gupnp_context_set_default_language (GUPnPContext *context,
                                        const char *language);

Set the default language for the Content-Length header to `language` .

If the client sends an Accept-Language header the UPnP HTTP server is required to send a Content-Language header in return. If there are no files hosted in languages which match the requested ones the Content-Language header is set to this value. The default value is "en".

#### Parameters

context | A GUPnPContext |
language | A language tag as defined in RFC 2616 3.10 |

Since: 0.17.0

### gupnp_context_add_server_handler ()

    void
    gupnp_context_add_server_handler (GUPnPContext *context,
                                      gboolean use_acl,
                                      const char *path,
                                      SoupServerCallback callback,
                                      gpointer user_data,
                                      GDestroyNotify destroy);

Add a SoupServerCallback to the GUPnPContext's SoupServer.

#### Parameters

context | a GUPnPContext |
use_acl | `TRUE`, if the path should query the GUPnPContext::acl before serving the resource, `FALSE` otherwise. |
path | the toplevel path for the handler. |
callback | callback to invoke for requests under `path` |
user_data | the user_data passed to `callback` |
destroy | A GDestroyNotify for `user_data` or `NULL` if none. | [allow-none]

Since: 0.20.11

### gupnp_context_remove_server_handler ()

    void
    gupnp_context_remove_server_handler (GUPnPContext *context,
                                         const char *path);

Remove a SoupServerCallback from the GUPnPContext's SoupServer.

#### Parameters

context | a GUPnPContext |
path | the toplevel path for the handler. |

Since: 0.20.11

### gupnp_context_host_path ()

    void
    gupnp_context_host_path (GUPnPContext *context,
                             const char *local_path,
                             const char *server_path);

Start hosting `local_path` at `server_path` . Files with the path `local_path.LOCALE` (if they exist) will be served up when LOCALE is specified in the request's Accept-Language header.

#### Parameters

context | A GUPnPContext |
local_path | Path to the local file or folder to be hosted |
server_path | Web server path where `local_path` should be hosted |

### gupnp_context_host_path_for_agent ()

    gboolean
    gupnp_context_host_path_for_agent (GUPnPContext *context,
                                       const char *local_path,
                                       const char *server_path,
                                       GRegex *user_agent);

Use this method to serve different local path to specific user-agent(s). The path `server_path` must already be hosted by `context` .

#### Parameters

context | A GUPnPContext |
local_path | Path to the local file or folder to be hosted |
server_path | Web server path already being hosted |
user_agent | The user-agent as a GRegex. |

#### Returns

`TRUE` on success, `FALSE` otherwise.

Since: 0.13.3

### gupnp_context_unhost_path ()

    void
    gupnp_context_unhost_path (GUPnPContext *context,
                               const char *server_path);

Stop hosting the file or folder at `server_path` .

#### Parameters

context | A GUPnPContext |
server_path | Web server path where the file or folder is hosted |

### gupnp_context_get_acl ()

    GUPnPAcl *
    gupnp_context_get_acl (GUPnPContext *context);

#### Parameters

context | A GUPnPContext |

#### Returns

The access control list associated with this context or `NULL` if no acl is set.

[transfer none]

Since: 0.20.11

### gupnp_context_set_acl ()

    void
    gupnp_context_set_acl (GUPnPContext *context,
                           GUPnPAcl *acl);

#### Parameters

context | A GUPnPContext |
acl | The new access control list or `NULL` to remove the current list. | [allow-none]

Since: 0.20.11

## Types and Values

### struct GUPnPContext

    struct GUPnPContext;

This struct contains private data only, and should be accessed using the functions below.

## Property Details

### The `“acl”` property

      “acl”                      GUPnPAcl *

An access control list.

Flags: Read / Write / Construct

Since: 0.20.11

### The `“default-language”` property

      “default-language”         gchar *

The content of the Content-Language header id the client sends Accept-Language and no language-specific pages to serve exist. The property defaults to 'en'.

Flags: Read / Write / Construct

Default value: "en"

Since: 0.17.0

### The `“port”` property

      “port”                     guint

The port to run on. Set to 0 if you don't care what port to run on.

Flags: Read / Write / Construct Only

Default value: 0

### The `“server”` property

      “server”                   SoupServer *

The SoupServer HTTP server used by GUPnP.

Flags: Read

### The `“session”` property

      “session”                  SoupSession *

The SoupSession object used by GUPnP.

Flags: Read

### The `“subscription-timeout”` property

      “subscription-timeout”     guint

The preferred subscription timeout: the number of seconds after which subscriptions are renewed. Set to '0' if subscriptions are never to time out.

Flags: Read / Write / Construct Only

Allowed values: <= 604800

Default value: 1800