GUPnPServiceProxy

## GUPnPServiceProxy GUPnPServiceProxy — Proxy class for remote services. |

## Synopsis

    struct              GUPnPServiceProxy;
                        GUPnPServiceProxyAction;
    void                (*GUPnPServiceProxyActionCallback)  (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             gpointer user_data);
    void                (*GUPnPServiceProxyNotifyCallback)  (GUPnPServiceProxy *proxy,
                                                             const char *variable,
                                                             GValue *value,
                                                             gpointer user_data);
    gboolean            gupnp_service_proxy_send_action     (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             ...);
    gboolean            gupnp_service_proxy_send_action_valist
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             va_list var_args);
    gboolean            gupnp_service_proxy_send_action_hash
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             GHashTable *in_hash,
                                                             GHashTable *out_hash);
    gboolean            gupnp_service_proxy_send_action_list
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             GList *in_names,
                                                             GList *in_values,
                                                             GList *out_names,
                                                             GList *out_types,
                                                             GList **out_values);
    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data,
                                                             ...);
    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action_valist
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data,
                                                             va_list var_args);
    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action_hash
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data,
                                                             GHashTable *hash);
    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action_list
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GList *in_names,
                                                             GList *in_values,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data);
    gboolean            gupnp_service_proxy_end_action      (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             ...);
    gboolean            gupnp_service_proxy_end_action_valist
                                                            (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             va_list var_args);
    gboolean            gupnp_service_proxy_end_action_hash (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             GHashTable *hash);
    gboolean            gupnp_service_proxy_end_action_list (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             GList *out_names,
                                                             GList *out_types,
                                                             GList **out_values);
    void                gupnp_service_proxy_cancel_action   (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action);
    gboolean            gupnp_service_proxy_add_notify      (GUPnPServiceProxy *proxy,
                                                             const char *variable,
                                                             GType type,
                                                             GUPnPServiceProxyNotifyCallback callback,
                                                             gpointer user_data);
    gboolean            gupnp_service_proxy_remove_notify   (GUPnPServiceProxy *proxy,
                                                             const char *variable,
                                                             GUPnPServiceProxyNotifyCallback callback,
                                                             gpointer user_data);
    void                gupnp_service_proxy_set_subscribed  (GUPnPServiceProxy *proxy,
                                                             gboolean subscribed);
    gboolean            gupnp_service_proxy_get_subscribed  (GUPnPServiceProxy *proxy);

## Object Hierarchy

      GObject
       +----GUPnPServiceInfo
             +----GUPnPServiceProxy

## Properties

      "subscribed"               gboolean              : Read / Write

## Signals

      "subscription-lost"                              : Run Last

## Description

GUPnPServiceProxy sends commands to a remote UPnP service and handles incoming event notifications. GUPnPServiceProxy implements the GUPnPServiceInfo interface.

## Details

### struct GUPnPServiceProxy

    struct GUPnPServiceProxy;

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

### GUPnPServiceProxyAction

    typedef struct _GUPnPServiceProxyAction GUPnPServiceProxyAction;

Opaque structure for holding in-progress action data.

### GUPnPServiceProxyActionCallback ()

    void                (*GUPnPServiceProxyActionCallback)  (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             gpointer user_data);

Callback notifying that `action` on `proxy` has returned and `gupnp_service_proxy_end_action()` etc can be called.

`proxy` : | The GUPnPServiceProxy `action` is called from
`action` : | The GUPnPServiceProxyAction in progress
`user_data` : | User data

### GUPnPServiceProxyNotifyCallback ()

    void                (*GUPnPServiceProxyNotifyCallback)  (GUPnPServiceProxy *proxy,
                                                             const char *variable,
                                                             GValue *value,
                                                             gpointer user_data);

Callback notifying that the state variable `variable` on `proxy` has changed to `value`.

`proxy` : | The GUPnPServiceProxy the notification originates from
`variable` : | The name of the variable being notified
`value` : | The GValue of the variable being notified
`user_data` : | User data

### gupnp_service_proxy_send_action ()

    gboolean            gupnp_service_proxy_send_action     (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             ...);

Sends action `action` with parameters `Varargs` to the service exposed by `proxy` synchronously. If an error occurred, `error` will be set. In case of a UPnPError the error code will be the same in `error`.

`proxy` : | A GUPnPServiceProxy
`action` : | An action
`error` : | The location where to store any error, or `NULL`
Returns : | `TRUE` if sending the action was succesful.

### gupnp_service_proxy_send_action_valist ()

    gboolean            gupnp_service_proxy_send_action_valist
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             va_list var_args);

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

`proxy` : | A GUPnPServiceProxy
`action` : | An action
`error` : | The location where to store any error, or `NULL`
`var_args` : | va_list of tuples of in parameter name, in parameter type, and in parameter value, followed by `NULL`, and then tuples of out parameter name, out parameter type, and out parameter value location
Returns : | `TRUE` if sending the action was succesful.

### gupnp_service_proxy_send_action_hash ()

    gboolean            gupnp_service_proxy_send_action_hash
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             GHashTable *in_hash,
                                                             GHashTable *out_hash);

See `gupnp_service_proxy_send_action()`; this version takes a pair of GHashTables for runtime determined parameter lists.

`proxy` : | A GUPnPServiceProxy
`action` : | An action
`error` : | The location where to store any error, or `NULL`
`in_hash` : | A GHashTable of in parameter name and GValue pairs. [element-type utf8 GValue][transfer none]
`out_hash` : | A GHashTable of out parameter name and initialized GValue pairs. [inout][element-type utf8 GValue][transfer full]
Returns : | `TRUE` if sending the action was succesful.

### gupnp_service_proxy_send_action_list ()

    gboolean            gupnp_service_proxy_send_action_list
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GError **error,
                                                             GList *in_names,
                                                             GList *in_values,
                                                             GList *out_names,
                                                             GList *out_types,
                                                             GList **out_values);

The synchronous variant of gupnp_service_proxy_begin_action_list and gupnp_service_proxy_end_action_list.

`proxy` : | (transfer none) : A GUPnPServiceProxy
`action` : | An action
`error` : | The location where to store any error, or `NULL`
`in_names` : | GList of 'in' parameter names (as strings). [element-type utf8][transfer none]
`in_values` : | GList of values (as GValue) that line up with `in_names`. [element-type GValue][transfer none]
`out_names` : | GList of 'out' parameter names (as strings). [element-type utf8][transfer none]
`out_types` : | GList of types (as GType) that line up with `out_names`. [element-type GType][transfer none]
`out_values` : | GList of values (as GValue) that line up with `out_names` and `out_types`. [element-type GValue][transfer full][out]
Returns : | `TRUE` if sending the action was succesful.

### gupnp_service_proxy_begin_action ()

    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data,
                                                             ...);

Sends action `action` with parameters `Varargs` to the service exposed by `proxy` asynchronously, calling `callback` on completion. From `callback`, call `gupnp_service_proxy_end_action()` to check for errors, to retrieve return values, and to free the GUPnPServiceProxyAction.

`proxy` : | A GUPnPServiceProxy
`action` : | An action
`callback` : | The callback to call when sending the action has succeeded or failed. [scope async]
`user_data` : | User data for `callback`
Returns : | A GUPnPServiceProxyAction handle. This will be freed when `gupnp_service_proxy_cancel_action()` or `gupnp_service_proxy_end_action_valist()`. [transfer none]

### gupnp_service_proxy_begin_action_valist ()

    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action_valist
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data,
                                                             va_list var_args);

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

`proxy` : | A GUPnPServiceProxy
`action` : | An action
`callback` : | (scope async) : The callback to call when sending the action has succeeded or failed
`user_data` : | User data for `callback`
`var_args` : | A va_list of tuples of in parameter name, in parameter type, and in parameter value
Returns : | A GUPnPServiceProxyAction handle. This will be freed when calling `gupnp_service_proxy_cancel_action()` or `gupnp_service_proxy_end_action_valist()`. [transfer none]

### gupnp_service_proxy_begin_action_hash ()

    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action_hash
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data,
                                                             GHashTable *hash);

See `gupnp_service_proxy_begin_action()`; this version takes a GHashTable for runtime generated parameter lists.

`proxy` : | A GUPnPServiceProxy
`action` : | An action
`callback` : | The callback to call when sending the action has succeeded or failed. [scope async]
`user_data` : | User data for `callback`
`hash` : | A GHashTable of in parameter name and GValue pairs
Returns : | A GUPnPServiceProxyAction handle. This will be freed when calling `gupnp_service_proxy_cancel_action()` or `gupnp_service_proxy_end_action_hash()`. [transfer none]

### gupnp_service_proxy_begin_action_list ()

    GUPnPServiceProxyAction * gupnp_service_proxy_begin_action_list
                                                            (GUPnPServiceProxy *proxy,
                                                             const char *action,
                                                             GList *in_names,
                                                             GList *in_values,
                                                             GUPnPServiceProxyActionCallback callback,
                                                             gpointer user_data);

A variant of gupnp_service_proxy_begin_action that takes lists of in-parameter names, types and values.

`proxy` : | A GUPnPServiceProxy. [transfer none]
`action` : | An action
`in_names` : | GList of 'in' parameter names (as strings). [element-type utf8][transfer none]
`in_values` : | GList of values (as GValue) that line up with `in_names`. [element-type GValue][transfer none]
`callback` : | (scope async) : The callback to call when sending the action has succeeded or failed
`user_data` : | User data for `callback`
Returns : | A GUPnPServiceProxyAction handle. This will be freed when calling gupnp_service_proxy_cancel_action or gupnp_service_proxy_end_action_list. [transfer none]

### gupnp_service_proxy_end_action ()

    gboolean            gupnp_service_proxy_end_action      (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             ...);

Retrieves the result of `action`. The out parameters in `Varargs` will be filled in, and if an error occurred, `error` will be set. In case of a UPnPError the error code will be the same in `error`.

`proxy` : | A GUPnPServiceProxy
`action` : | A GUPnPServiceProxyAction handle
`error` : | The location where to store any error, or `NULL`
Returns : | `TRUE` on success.

### gupnp_service_proxy_end_action_valist ()

    gboolean            gupnp_service_proxy_end_action_valist
                                                            (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             va_list var_args);

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

`proxy` : | A GUPnPServiceProxy
`action` : | A GUPnPServiceProxyAction handle
`error` : | The location where to store any error, or `NULL`
`var_args` : | A va_list of tuples of out parameter name, out parameter type, and out parameter value location. The out parameter values should be freed after use
Returns : | `TRUE` on success.

### gupnp_service_proxy_end_action_hash ()

    gboolean            gupnp_service_proxy_end_action_hash (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             GHashTable *hash);

See `gupnp_service_proxy_end_action()`; this version takes a GHashTable for runtime generated parameter lists.

`proxy` : | A GUPnPServiceProxy
`action` : | A GUPnPServiceProxyAction handle
`error` : | The location where to store any error, or `NULL`
`hash` : | A GHashTable of out parameter name and initialised GValue pairs. [element-type utf8 GValue][inout][transfer none]
Returns : | `TRUE` on success.

### gupnp_service_proxy_end_action_list ()

    gboolean            gupnp_service_proxy_end_action_list (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action,
                                                             GError **error,
                                                             GList *out_names,
                                                             GList *out_types,
                                                             GList **out_values);

A variant of gupnp_service_proxy_end_action that takes lists of out-parameter names, types and place-holders for values. The returned list in `out_values` must be freed using g_list_free and each element in it using g_value_unset and g_slice_free.

Return value : `TRUE` on success.

`proxy` : | A GUPnPServiceProxy
`action` : | A GUPnPServiceProxyAction handle
`error` : | The location where to store any error, or `NULL`
`out_names` : | GList of 'out' parameter names (as strings). [element-type utf8][transfer none]
`out_types` : | GList of types (as GType) that line up with `out_names`. [element-type GType][transfer none]
`out_values` : | GList of values (as GValue) that line up with `out_names` and `out_types`. [element-type GValue][transfer full][out]

### gupnp_service_proxy_cancel_action ()

    void                gupnp_service_proxy_cancel_action   (GUPnPServiceProxy *proxy,
                                                             GUPnPServiceProxyAction *action);

Cancels `action`, freeing the `action` handle.

`proxy` : | A GUPnPServiceProxy
`action` : | A GUPnPServiceProxyAction handle

### gupnp_service_proxy_add_notify ()

    gboolean            gupnp_service_proxy_add_notify      (GUPnPServiceProxy *proxy,
                                                             const char *variable,
                                                             GType type,
                                                             GUPnPServiceProxyNotifyCallback callback,
                                                             gpointer user_data);

Sets up `callback` to be called whenever a change notification for `variable` is recieved.

`proxy` : | A GUPnPServiceProxy
`variable` : | The variable to add notification for
`type` : | The type of the variable
`callback` : | The callback to call when `variable` changes. [scope async]
`user_data` : | User data for `callback`
Returns : | `TRUE` on success.

### gupnp_service_proxy_remove_notify ()

    gboolean            gupnp_service_proxy_remove_notify   (GUPnPServiceProxy *proxy,
                                                             const char *variable,
                                                             GUPnPServiceProxyNotifyCallback callback,
                                                             gpointer user_data);

Cancels the variable change notification for `callback` and `user_data`.

`proxy` : | A GUPnPServiceProxy
`variable` : | The variable to add notification for
`callback` : | The callback to call when `variable` changes. [scope call]
`user_data` : | User data for `callback`
Returns : | `TRUE` on success.

### gupnp_service_proxy_set_subscribed ()

    void                gupnp_service_proxy_set_subscribed  (GUPnPServiceProxy *proxy,
                                                             gboolean subscribed);

(Un)subscribes to this service.

Note that the relevant messages are not immediately sent but queued. If you want to unsubcribe from this service because the application is quitting, rely on automatic synchronised unsubscription on object destruction instead.

`proxy` : | A GUPnPServiceProxy
`subscribed` : | `TRUE` to subscribe to this service

### gupnp_service_proxy_get_subscribed ()

    gboolean            gupnp_service_proxy_get_subscribed  (GUPnPServiceProxy *proxy);

Returns if we are subscribed to this service.

`proxy` : | A GUPnPServiceProxy
Returns : | `TRUE` if we are subscribed to this service, otherwise `FALSE`.

## Property Details

### The `"subscribed"` property

      "subscribed"               gboolean              : Read / Write

Whether we are subscribed to this service.

Default value: FALSE

## Signal Details

### The `"subscription-lost"` signal

    void                user_function                      (GUPnPServiceProxy *proxy,
                                                            gpointer           error,
                                                            gpointer           user_data)      : Run Last

Emitted whenever the subscription to this service has been lost due to an error condition.

`proxy` : | The GUPnPServiceProxy that received the signal
`error` : | A pointer to a GError describing why the subscription has been lost
`user_data` : | user data set when the signal handler was connected.