GUPnPService

## GUPnPService GUPnPService — Class for service implementations. |

## Synopsis

    struct              GUPnPService;
                        GUPnPServiceAction;
    const char *        gupnp_service_action_get_name       (GUPnPServiceAction *action);
    GList *             gupnp_service_action_get_locales    (GUPnPServiceAction *action);
    void                gupnp_service_action_get            (GUPnPServiceAction *action,
                                                             ...);
    void                gupnp_service_action_get_valist     (GUPnPServiceAction *action,
                                                             va_list var_args);
    void                gupnp_service_action_get_value      (GUPnPServiceAction *action,
                                                             const char *argument,
                                                             GValue *value);
    GValue *            gupnp_service_action_get_gvalue     (GUPnPServiceAction *action,
                                                             const char *argument,
                                                             GType type);
    GList *             gupnp_service_action_get_values     (GUPnPServiceAction *action,
                                                             GList *arg_names,
                                                             GList *arg_types);
    void                gupnp_service_action_set            (GUPnPServiceAction *action,
                                                             ...);
    void                gupnp_service_action_set_valist     (GUPnPServiceAction *action,
                                                             va_list var_args);
    void                gupnp_service_action_set_value      (GUPnPServiceAction *action,
                                                             const char *argument,
                                                             const GValue *value);
    void                gupnp_service_action_set_values     (GUPnPServiceAction *action,
                                                             GList *arg_names,
                                                             GList *arg_values);
    void                gupnp_service_action_return         (GUPnPServiceAction *action);
    void                gupnp_service_action_return_error   (GUPnPServiceAction *action,
                                                             guint error_code,
                                                             const char *error_description);
    SoupMessage *       gupnp_service_action_get_message    (GUPnPServiceAction *action);
    guint               gupnp_service_action_get_argument_count
                                                            (GUPnPServiceAction *action);
    void                gupnp_service_notify                (GUPnPService *service,
                                                             ...);
    void                gupnp_service_notify_valist         (GUPnPService *service,
                                                             va_list var_args);
    void                gupnp_service_notify_value          (GUPnPService *service,
                                                             const char *variable,
                                                             const GValue *value);
    void                gupnp_service_freeze_notify         (GUPnPService *service);
    void                gupnp_service_thaw_notify           (GUPnPService *service);
    void                gupnp_service_signals_autoconnect   (GUPnPService *service,
                                                             gpointer user_data,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GUPnPServiceInfo
             +----GUPnPService

      GBoxed
       +----GUPnPServiceAction

## Properties

      "root-device"              GUPnPRootDevice*      : Read / Write / Construct Only

## Signals

      "action-invoked"                                 : Has Details
      "notify-failed"                                  : Run Last
      "query-variable"                                 : Has Details

## Description

GUPnPService allows for handling incoming actions and state variable notification. GUPnPService implements the GUPnPServiceInfo interface.

## Details

### struct GUPnPService

    struct GUPnPService;

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

### GUPnPServiceAction

    typedef struct _GUPnPServiceAction GUPnPServiceAction;

Opaque structure for holding in-progress action data.

### gupnp_service_action_get_name ()

    const char *        gupnp_service_action_get_name       (GUPnPServiceAction *action);

Get the name of `action`.

`action` : | A GUPnPServiceAction
Returns : | The name of `action`

### gupnp_service_action_get_locales ()

    GList *             gupnp_service_action_get_locales    (GUPnPServiceAction *action);

Get an ordered (preferred first) GList of locales preferred by the client. Free list and elements after use.

`action` : | A GUPnPServiceAction
Returns : | A GList of char* locale names. [element-type utf8][transfer full]

### gupnp_service_action_get ()

    void                gupnp_service_action_get            (GUPnPServiceAction *action,
                                                             ...);

Retrieves the specified action arguments.

`action` : | A GUPnPServiceAction
`...` : | tuples of argument name, argument type, and argument value location, terminated with `NULL`.

### gupnp_service_action_get_valist ()

    void                gupnp_service_action_get_valist     (GUPnPServiceAction *action,
                                                             va_list var_args);

See `gupnp_service_action_get()`; this version takes a va_list for use by language bindings.

`action` : | A GUPnPServiceAction
`var_args` : | va_list of tuples of argument name, argument type, and argument value location.

### gupnp_service_action_get_value ()

    void                gupnp_service_action_get_value      (GUPnPServiceAction *action,
                                                             const char *argument,
                                                             GValue *value);

Retrieves the value of `argument` into `value`.

`action` : | A GUPnPServiceAction
`argument` : | The name of the argument to retrieve
`value` : | The GValue to store the value of the argument, initialized to the correct type. [inout]

### gupnp_service_action_get_gvalue ()

    GValue *            gupnp_service_action_get_gvalue     (GUPnPServiceAction *action,
                                                             const char *argument,
                                                             GType type);

Retrieves the value of `argument` into a GValue of type `type` and returns it. The method exists only and only to satify PyGI, please use gupnp_service_action_get_value and ignore this if possible.

`action` : | A GUPnPServiceAction
`argument` : | The name of the argument to retrieve
`type` : | The type of argument to retrieve
Returns : | Value as GValue associated with `action`. g_value_unset and g_slice_free it after usage. Rename To: gupnp_service_action_get_value. [transfer full]

### gupnp_service_action_get_values ()

    GList *             gupnp_service_action_get_values     (GUPnPServiceAction *action,
                                                             GList *arg_names,
                                                             GList *arg_types);

A variant of gupnp_service_action_get that uses GList instead of varargs.

`action` : | A GUPnPServiceAction
`arg_names` : | (element-type utf8) : A GList of argument names as string
`arg_types` : | A GList of argument types as GType. [element-type GType]
Returns : | The values as GList of GValue. g_list_free the returned list and g_value_unset and g_slice_free each element. [element-type GValue][transfer full]

### gupnp_service_action_set ()

    void                gupnp_service_action_set            (GUPnPServiceAction *action,
                                                             ...);

Sets the specified action return values.

`action` : | A GUPnPServiceAction
`...` : | tuples of return value name, return value type, and actual return value, terminated with `NULL`.

### gupnp_service_action_set_valist ()

    void                gupnp_service_action_set_valist     (GUPnPServiceAction *action,
                                                             va_list var_args);

See `gupnp_service_action_set()`; this version takes a va_list for use by language bindings.

`action` : | A GUPnPServiceAction
`var_args` : | va_list of tuples of return value name, return value type, and actual return value.

### gupnp_service_action_set_value ()

    void                gupnp_service_action_set_value      (GUPnPServiceAction *action,
                                                             const char *argument,
                                                             const GValue *value);

Sets the value of `argument` to `value`.

`action` : | A GUPnPServiceAction
`argument` : | The name of the return value to retrieve
`value` : | The GValue to store the return value

### gupnp_service_action_set_values ()

    void                gupnp_service_action_set_values     (GUPnPServiceAction *action,
                                                             GList *arg_names,
                                                             GList *arg_values);

Sets the specified action return values.

`action` : | A GUPnPServiceAction
`arg_names` : | A GList of argument names. [element-type utf8][transfer none]
`arg_values` : | The GList of values (as GValues) that line up with `arg_names`. [element-type GValue][transfer none]

### gupnp_service_action_return ()

    void                gupnp_service_action_return         (GUPnPServiceAction *action);

Return succesfully.

`action` : | A GUPnPServiceAction

### gupnp_service_action_return_error ()

    void                gupnp_service_action_return_error   (GUPnPServiceAction *action,
                                                             guint error_code,
                                                             const char *error_description);

Return `error_code`.

`action` : | A GUPnPServiceAction
`error_code` : | The error code
`error_description` : | The error description, or `NULL` if `error_code` is one of GUPNP_CONTROL_ERROR_INVALID_ACTION, GUPNP_CONTROL_ERROR_INVALID_ARGS, GUPNP_CONTROL_ERROR_OUT_OF_SYNC or GUPNP_CONTROL_ERROR_ACTION_FAILED, in which case a description is provided automatically.

### gupnp_service_action_get_message ()

    SoupMessage *       gupnp_service_action_get_message    (GUPnPServiceAction *action);

Get the SoupMessage associated with `action`. Mainly intended for applications to be able to read HTTP headers received from clients.

`action` : | A GUPnPServiceAction
Returns : | SoupMessage associated with `action`. Unref after using it. [transfer full]

### gupnp_service_action_get_argument_count ()

    guint               gupnp_service_action_get_argument_count
                                                            (GUPnPServiceAction *action);

Get the number of IN arguments from the `action` and return it.

`action` : | A GUPnPServiceAction
Returns : | The number of IN arguments from the `action`.

### gupnp_service_notify ()

    void                gupnp_service_notify                (GUPnPService *service,
                                                             ...);

Notifies listening clients that the properties listed in `Varargs` have changed to the specified values.

`service` : | A GUPnPService
`...` : | Tuples of variable name, variable type, and variable value, terminated with `NULL`.

### gupnp_service_notify_valist ()

    void                gupnp_service_notify_valist         (GUPnPService *service,
                                                             va_list var_args);

See `gupnp_service_notify()`; this version takes a va_list for use by language bindings.

`service` : | A GUPnPService
`var_args` : | A va_list of tuples of variable name, variable type, and variable value, terminated with `NULL`.

### gupnp_service_notify_value ()

    void                gupnp_service_notify_value          (GUPnPService *service,
                                                             const char *variable,
                                                             const GValue *value);

Notifies listening clients that `variable` has changed to `value`.

`service` : | A GUPnPService
`variable` : | The name of the variable to notify
`value` : | The value of the variable

### gupnp_service_freeze_notify ()

    void                gupnp_service_freeze_notify         (GUPnPService *service);

Causes new notifications to be queued up until `gupnp_service_thaw_notify()` is called.

`service` : | A GUPnPService

### gupnp_service_thaw_notify ()

    void                gupnp_service_thaw_notify           (GUPnPService *service);

Sends out any pending notifications, and stops queuing of new ones.

`service` : | A GUPnPService

### gupnp_service_signals_autoconnect ()

    void                gupnp_service_signals_autoconnect   (GUPnPService *service,
                                                             gpointer user_data,
                                                             GError **error);

A convenience function that attempts to connect all possible "action-invoked" and "query-variable" signals to appropriate callbacks for the service `service`. It uses service introspection and GModule's introspective features. It is very simillar to `gtk_builder_connect_signals()` except that it attempts to guess the names of the signal handlers on its own.

For this function to do its magic, the application must name the callback functions for "action-invoked" signals by striping the CamelCase off the action names and either prepend "on_" or append "_cb" to them. Same goes for "query-variable" signals, except that "query_" should be prepended to the variable name. For example, callback function for `GetSystemUpdateID` action should be either named as "get_system_update_id_cb" or "on_get_system_update_id" and callback function for the query of "SystemUpdateID" state variable should be named `query_system_update_id_cb` or `on_query_system_update_id`.

### Note

This function will not work correctly if GModule is not supported on the platform or introspection is not available for `service`.

### Warning

This function can not and therefore does not guarantee that the resulting signal connections will be correct as it depends heavily on a particular naming schemes described above.

`service` : | A GUPnPService
`user_data` : | the data to pass to each of the callbacks
`error` : | return location for a GError, or `NULL`

## Property Details

### The `"root-device"` property

      "root-device"              GUPnPRootDevice*      : Read / Write / Construct Only

The containing GUPnPRootDevice.

## Signal Details

### The `"action-invoked"` signal

    void                user_function                      (GUPnPService       *service,
                                                            GUPnPServiceAction *action,
                                                            gpointer            user_data)      : Has Details

Emitted whenever an action is invoked. Handler should process `action` and must call either `gupnp_service_action_return()` or `gupnp_service_action_return_error()`.

`service` : | The GUPnPService that received the signal
`action` : | The invoked GUPnPServiceAction
`user_data` : | user data set when the signal handler was connected.

### The `"notify-failed"` signal

    void                user_function                      (GUPnPService *service,
                                                            gpointer      callback_url,
                                                            gpointer      reason,
                                                            gpointer      user_data)         : Run Last

Emitted whenever notification of a client fails.

`service` : | The GUPnPService that received the signal
`callback_url` : | A GList of callback URLs. [type GList][element-type SoupURI]
`reason` : | A pointer to a GError describing why the notify failed. [type GError]
`user_data` : | user data set when the signal handler was connected.

### The `"query-variable"` signal

    void                user_function                      (GUPnPService *service,
                                                            gchar        *variable,
                                                            gpointer      value,
                                                            gpointer      user_data)      : Has Details

Emitted whenever `service` needs to know the value of `variable`. Handler should fill `value` with the value of `variable`.

`service` : | The GUPnPService that received the signal
`variable` : | The variable that is being queried
`value` : | The location of the GValue of the variable. [type GValue][inout]
`user_data` : | user data set when the signal handler was connected.