GUPnPContext: GUPnP Reference Manual

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

## Functions

GUPnPContext * | gupnp_context_new ()
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 ()
char * | gupnp_context_rewrite_uri ()

## Types and Values

| GUPnPContext

## 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 (const char *iface,
                       guint port,
                       GError **error);

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

#### Parameters

iface | The network interface to use, or `NULL` to auto-detect. | [nullable]
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`. | [inout][optional][nullable]

#### Returns

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

### gupnp_context_get_port ()

    guint
    gupnp_context_get_port (GUPnPContext *context);

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

### gupnp_context_set_default_language ()

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

Set the default language for the Content-Language 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.18.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. | [nullable]

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.

`note` : Paths added to the HTTP server using `gupnp_context_host_path()` are not subject to handling by GUPnPAcl.

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

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

Access the GUPnPAcl associated with this client. If there isn't any, retturns `NULL`. The returned ACL must not be freed.

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

Attach or remove the assoicated access control list to this context. If `acl` is `NULL`, the current access control list will be removed.

#### Parameters

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

Since: 0.20.11

### gupnp_context_rewrite_uri ()

    char *
    gupnp_context_rewrite_uri (GUPnPContext *context,
                               const char *uri);

Utility function to re-write an uri to the IPv6 link-local form which has the zone index appended to the IP address.

#### Parameters

context | a GUPnPContext |
uri | an uri to rewrite if necessary |

#### Returns

A re-written version of the `uri` if the context is on a link-local IPv6 address, a copy of the `uri` otherwise or `NULL` if `uri` was invalid

Since: 1.2.0

## Types and Values

### GUPnPContext

    typedef struct _GUPnPContext GUPnPContext;