GUPnPServiceProxy: GUPnP Reference Manual

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

## Functions

void | (*GUPnPServiceProxyActionCallback) ()
void | (*GUPnPServiceProxyNotifyCallback) ()
GUPnPServiceProxyAction * | gupnp_service_proxy_call_action ()
void | gupnp_service_proxy_call_action_async ()
GUPnPServiceProxyAction * | gupnp_service_proxy_call_action_finish ()
gboolean | gupnp_service_proxy_send_action ()
gboolean | gupnp_service_proxy_send_action_valist ()
gboolean | gupnp_service_proxy_send_action_list ()
GUPnPServiceProxyAction * | gupnp_service_proxy_begin_action ()
GUPnPServiceProxyAction * | gupnp_service_proxy_begin_action_valist ()
GUPnPServiceProxyAction * | gupnp_service_proxy_begin_action_list ()
gboolean | gupnp_service_proxy_end_action ()
gboolean | gupnp_service_proxy_end_action_valist ()
gboolean | gupnp_service_proxy_end_action_hash ()
gboolean | gupnp_service_proxy_end_action_list ()
void | gupnp_service_proxy_cancel_action ()
gboolean | gupnp_service_proxy_add_notify ()
gboolean | gupnp_service_proxy_add_notify_full ()
gboolean | gupnp_service_proxy_add_raw_notify ()
gboolean | gupnp_service_proxy_remove_notify ()
gboolean | gupnp_service_proxy_remove_raw_notify ()
void | gupnp_service_proxy_set_subscribed ()
gboolean | gupnp_service_proxy_get_subscribed ()
GUPnPServiceProxyAction * | gupnp_service_proxy_action_new ()
GUPnPServiceProxyAction * | gupnp_service_proxy_action_new_from_list ()
GUPnPServiceProxyAction * | gupnp_service_proxy_action_ref ()
void | gupnp_service_proxy_action_unref ()
gboolean | gupnp_service_proxy_action_set ()
gboolean | gupnp_service_proxy_action_get_result ()
gboolean | gupnp_service_proxy_action_get_result_hash ()
gboolean | gupnp_service_proxy_action_get_result_list ()

## Types and Values

| GUPnPServiceProxy
| GUPnPServiceProxyAction

## Description

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

## Functions

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

#### Parameters

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

#### Parameters

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_call_action ()

    GUPnPServiceProxyAction *
    gupnp_service_proxy_call_action (GUPnPServiceProxy *proxy,
                                     GUPnPServiceProxyAction *action,
                                     GCancellable *cancellable,
                                     GError **error);

Synchronously call the `action` on the remote UPnP service.

#### Parameters

proxy | A GUPnPServiceProxy. | [transfer none]
action | An action. | [transfer none]
cancellable | A GCancellable which can be used to cancel the current action call. | [allow-none]
error | Return location for a GError, or `NULL`. | [inout][optional][nullable]

#### Returns

`NULL` on error, `action` if successful.

[nullable][transfer none]

Since: 1.2.0

### gupnp_service_proxy_call_action_async ()

    void
    gupnp_service_proxy_call_action_async (GUPnPServiceProxy *proxy,
                                           GUPnPServiceProxyAction *action,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Start a call on the remote UPnP service using the pre-configured `action` . Use `gupnp_service_proxy_call_action_finish()` in the `callback` to finalize the call and `gupnp_service_proxy_action_get_result()`, `gupnp_service_proxy_action_get_result_hash()` or `gupnp_service_proxy_action_get_result_list()` to extract the result of the remote call.

#### Parameters

proxy | A GUPnPServiceProxy. | [transfer none]
action | A GUPnPServiceProxyAction to call. | [transfer none]
cancellable | A GCancellable which can be used to cancel the current action call. | [allow-none]
callback | A GAsyncReadyCallback to call when the action is finished. | [scope async]
user_data | User data for `callback` . | [closure]

Since: 1.2.0

### gupnp_service_proxy_call_action_finish ()

    GUPnPServiceProxyAction *
    gupnp_service_proxy_call_action_finish
                                   (GUPnPServiceProxy *proxy,
                                    GAsyncResult *result,
                                    GError **error);

Finish an asynchronous call initiated with `gupnp_service_proxy_call_action_async()`.

Note: This will only signalize transport errors to the caller, such as the action being cancelled or lost connection etc. SOAP call errors are only returned by `gupnp_service_proxy_action_get()` and such.

#### Parameters

proxy | a GUPnPServiceProxy |
result | a GAsyncResult |
error | Return location for a GError, or `NULL`. | [inout][optional][nullable]

#### Returns

`NULL`, if the call had an error, the action otherwise.

[nullable][transfer none]

Since: 1.2.0

### gupnp_service_proxy_send_action ()

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

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

Use `gupnp_service_proxy_action_new()` and `gupnp_service_proxy_call_action()`

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

#### Parameters

proxy | A GUPnPServiceProxy |
action | An action |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
... | 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, terminated with `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);

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

See `gupnp_service_proxy_send_action()`.

#### Parameters

proxy | A GUPnPServiceProxy |
action | An action |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
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_list ()

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

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

Use `gupnp_service_proxy_action_new_from_list()` and `gupnp_service_proxy_call_action()`

The synchronous variant of gupnp_service_proxy_begin_action_list and gupnp_service_proxy_end_action_list.

#### Parameters

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]
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]
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]

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

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

Use `gupnp_service_proxy_action_new()` and `gupnp_service_proxy_call_action_async()`

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.

#### Parameters

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` |
... | tuples of in parameter name, in parameter type, and in parameter value, terminated with `NULL` |

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

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

See `gupnp_service_proxy_begin_action()`.

#### Parameters

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_list ()

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

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

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

#### Parameters

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]

Since: 0.14.0

### gupnp_service_proxy_end_action ()

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

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

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 an UPnP error the error code will be the same in `error` .

#### Parameters

proxy | A GUPnPServiceProxy |
action | A GUPnPServiceProxyAction handle |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
... | tuples of out parameter name, out parameter type, and out parameter value location, terminated with `NULL`. The out parameter values should be freed after use |

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

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

See `gupnp_service_proxy_end_action()`.

#### Parameters

proxy | A GUPnPServiceProxy |
action | A GUPnPServiceProxyAction handle |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
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,
                                         GHashTable *hash,
                                         GError **error);

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

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

#### Parameters

proxy | A GUPnPServiceProxy |
action | A GUPnPServiceProxyAction handle |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
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,
                                         GList *out_names,
                                         GList *out_types,
                                         GList **out_values,
                                         GError **error);

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

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.

#### Parameters

proxy | A GUPnPServiceProxy |
action | A GUPnPServiceProxyAction handle |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
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);

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

Use the GCancellable passed to `gupnp_service_proxy_call_action_async()` or `gupnp_service_proxy_call_action()`

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

#### Parameters

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.

[skip]

#### Parameters

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_add_notify_full ()

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

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

[rename-to gupnp_service_proxy_add_notify]

#### Parameters

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 notified]
user_data | User data for `callback` |
notify | Function to call when the notification is removed, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success.

Since: 0.20.12

### gupnp_service_proxy_add_raw_notify ()

    gboolean
    gupnp_service_proxy_add_raw_notify (GUPnPServiceProxy *proxy,
                                        GUPnPServiceProxyNotifyCallback callback,
                                        gpointer user_data,
                                        GDestroyNotify notify);

Get a notification for anything that happens on the peer. `value` in `callback` will be of type G_TYPE_POINTER and contain the pre-parsed xmlDoc. Do NOT free or modify this document.

#### Parameters

proxy | A GUPnPServiceProxy |
callback | The callback to call when the peer issues any variable notification. | [scope notified]
user_data | User data for `callback` |
notify | A GDestroyNotify for `user_data` . | [allow-none]

#### Returns

`TRUE` on success.

Since: 0.20.12

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

Up to version 0.20.9 this function must not be called directlya or indirectly from a GUPnPServiceProxyNotifyCallback associated with this service proxy, even if it is for another variable. In later versions such calls are allowed.

#### Parameters

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_remove_raw_notify ()

    gboolean
    gupnp_service_proxy_remove_raw_notify (GUPnPServiceProxy *proxy,
                                           GUPnPServiceProxyNotifyCallback callback,
                                           gpointer user_data);

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

This function must not be called directly or indirectly from a GUPnPServiceProxyNotifyCallback associated with this service proxy, even if it is for another variable.

#### Parameters

proxy | A GUPnPServiceProxy |
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.

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.

#### Parameters

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.

#### Parameters

proxy | A GUPnPServiceProxy |

#### Returns

`TRUE` if we are subscribed to this service, otherwise `FALSE`.

### gupnp_service_proxy_action_new ()

    GUPnPServiceProxyAction *
    gupnp_service_proxy_action_new (const char *action,
                                    ...);

Prepares action `action` with parameters `Varargs` to be sent off to a remote service later with `gupnp_service_proxy_call_action()` or `gupnp_service_proxy_call_action_async()`.

After the action call has finished, the results of the call may be retrived from the GUPnPServiceProxyAction by using `gupnp_service_proxy_action_get_result()`, `gupnp_service_proxy_action_get_result_list()` or `gupnp_service_proxy_action_get_result_hash()`

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    GUPnPServiceProxyAction *action =
            gupnp_service_proxy_action_new ("GetVolume",
                                            // Parameters
                                            "InstanceID", G_TYPE_INT, 0,
                                            "Channel", G_TYPE_STRING, "Master",
                                            NULL);

    GError *error = NULL;
    gupnp_service_proxy_call_action (proxy, action, NULL, &error);
    if (error != NULL) {
            g_warning ("Failed to call GetVolume: %s", error->message);
            g_clear_error (&error);

            return;
    }

    guint16 volume = 0;
    if (!gupnp_service_proxy_action_get_result (action,
                                                &error,
                                                "CurrentVolume", G_TYPE_UINT, &volume,
                                                NULL)) {
            g_message ("Current Volume: %u", volume);
    }

    gupnp_service_proxy_action_unref (action);

#### Parameters

action | The name of a remote action to call |
... | tuples of in parameter name, in parameter type, and in parameter value, terminated with `NULL` |

#### Returns

A newly created GUPnPServiceProxyAction

### gupnp_service_proxy_action_new_from_list ()

    GUPnPServiceProxyAction *
    gupnp_service_proxy_action_new_from_list
                                   (const char *action,
                                    GList *in_names,
                                    GList *in_values);

Prepares action `action` with parameters `in_names` and `in_values` to be sent off to a remote service later with `gupnp_service_proxy_call_action()` or `gupnp_service_proxy_call_action_async()`. This is mainly useful for language bindings.

After the action call has finished, the results of the call may be retrived from the GUPnPServiceProxyAction by using `gupnp_service_proxy_action_get_result()`, `gupnp_service_proxy_action_get_result_list()` or `gupnp_service_proxy_action_get_result_hash()`

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    GList *in_args = NULL;
    in_args = g_list_append (in_args, "InstanceID");
    in_args = g_list_append (in_args, "Unit");
    in_args = g_list_append (in_args, "Target");

    GValue instance = G_VALUE_INIT;
    g_value_set_int (&instance, 0);
    GValue unit = G_VALUE_INIT;
    g_value_set_static_string (&unit, "ABS_TIME");
    GValue target = G_VALUE_INIT;
    g_value_set_static_string (&target, "00:00:00.000");

    GList *in_values = NULL;
    in_values = g_list_append (in_values, &instance);
    in_values = g_list_append (in_values, &unit);
    in_values = g_list_append (in_values, &target);

    GUPnPServiceProxyAction *action =
            gunp_service_proxy_action_new_from_list ("Seek", in_args, in_values);

    GError *error = NULL;
    gupnp_service_proxy_call_action_async (proxy, action, NULL, on_action_finished, NULL);
    gupnp_service_proxy_action_unref (action);

#### Parameters

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]

#### Returns

A newly created GUPnPServiceProxyAction

### gupnp_service_proxy_action_ref ()

    GUPnPServiceProxyAction *
    gupnp_service_proxy_action_ref (GUPnPServiceProxyAction *action);

### gupnp_service_proxy_action_unref ()

    void
    gupnp_service_proxy_action_unref (GUPnPServiceProxyAction *action);

### gupnp_service_proxy_action_set ()

    gboolean
    gupnp_service_proxy_action_set (GUPnPServiceProxyAction *action,
                                    const char *key,
                                    const GValue *value,
                                    GError **error);

Update the value of `key` to `value` .

`key` needs to already exist in `action` .

#### Parameters

action | the action to modify |
key | the name of the value to modify |
value | the new value of `key` |
error | a return location for an GError. | [nullable]

#### Returns

true if successfully modified, false otherwise

Since: 1.4.0

### gupnp_service_proxy_action_get_result ()

    gboolean
    gupnp_service_proxy_action_get_result (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 an UPnP error the error code will be the same in `error` .

#### Parameters

action | A GUPnPServiceProxyAction handle |
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]
... | tuples of out parameter name, out parameter type, and out parameter value location, terminated with `NULL`. The out parameter values should be freed after use |

#### Returns

`TRUE` on success.

### gupnp_service_proxy_action_get_result_hash ()

    gboolean
    gupnp_service_proxy_action_get_result_hash
                                   (GUPnPServiceProxyAction *action,
                                    GHashTable *out_hash,
                                    GError **error);

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

The `out_hash` needs to be pre-initialized with key value pairs denoting the argument to retrieve and an empty GValue initialized to hold the wanted type with `g_value_init()`.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    void on_action_finished(GObject *object, GAsyncResult *res, gpointer user_data)
    {
        GUPnPServiceProxyAction *action;
        GError *error;

        action = gupnp_service_proxy_call_action_finish (GUPNP_SERVICE_PROXY (object),
                                                         res,
                                                         &error);

        if (error != NULL) {
                 g_print ("Call failed: %s", error->message);
                 g_clear_error (&error);
                 return;
        }

        GValue play_mode = G_VALUE_INIT;
        g_value_init(&play_mode, G_TYPE_STRING);
        GValue rec_quality_mode = G_VALUE_INIT;
        g_value_init(&rec_quality_mode, G_TYPE_STRING);

        GHashTable *out_args = g_hash_table_new (g_str_hash, g_str_equal);
        g_hash_table_insert(out_args, "PlayMode", &play_mode);
        g_hash_table_insert(out_args, "RecQualityMode", &rec_quality_mode);

        if (!gupnp_service_proxy_action_get_result_hash (action,
                                                         out_args,
                                                         &error)) {
                 g_print ("Getting results failed: %s", error->message);
                 g_clear_error (&error);
                 return;
        }

        g_value_unset (&play_mode);
        g_value_unset (&rec_quality_mode);

        g_hash_table_unref (out_args);
    }

#### Parameters

action | A GUPnPServiceProxyAction handle |
out_hash | A GHashTable of out parameter name and initialised GValue pairs. | [element-type utf8 GValue][inout][transfer none]
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]

#### Returns

`TRUE` on success.

Since: 1.2.0

### gupnp_service_proxy_action_get_result_list ()

    gboolean
    gupnp_service_proxy_action_get_result_list
                                   (GUPnPServiceProxyAction *action,
                                    GList *out_names,
                                    GList *out_types,
                                    GList **out_values,
                                    GError **error);

A variant of `gupnp_service_proxy_action_get_result()` 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_free.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    void on_action_finished(GObject *object, GAsyncResult *res, gpointer user_data)
    {
        GUPnPServiceProxyAction *action;
        GError *error;

        action = gupnp_service_proxy_call_action_finish (GUPNP_SERVICE_PROXY (object),
                                                         res,
                                                         &error);

        if (error != NULL) {
                 g_print ("Call failed: %s", error->message);
                 g_clear_error (&error);
                 return;
        }

        GList *out_args = NULL;
        out_args = g_list_append (out_args, "PlayMode");
        out_args = g_list_append (out_args, "RecQualityMode");
        GList *out_types = NULL;
        out_types = g_list_append (out_types, GSIZE_TO_POINTER (G_TYPE_STRING));
        out_types = g_list_append (out_types, GSIZE_TO_POINTER (G_TYPE_STRING));
        GList *out_values = NULL;

        if (!gupnp_service_proxy_action_get_result_list (action,
                                                         out_args,
                                                         out_types,
                                                         &out_values,
                                                         &error)) {
                 g_print ("Getting results failed: %s", error->message);
                 g_clear_error (&error);
                 return;
        }

        GList *iter = out_values;
        while (iter != NULL) {
            GValue *value = iter->data;
            g_print ("Result: %s\n", g_value_get_string (value));
            g_value_unset (value);
            g_free (value);
            iter = g_list_remove_link (iter, iter);
        }
        g_list_free (out_values);
    }

Return value : `TRUE` on success.

#### Parameters

action | A GUPnPServiceProxyAction handle |
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]
error | The location where to store any error, or `NULL`. | [inout][optional][nullable]

Since: 1.2.0

## Types and Values

### GUPnPServiceProxy

    typedef struct _GUPnPServiceProxy GUPnPServiceProxy;

### GUPnPServiceProxyAction

    typedef struct _GUPnPServiceProxyAction GUPnPServiceProxyAction;

Opaque structure for holding in-progress action data.