Top | ![]() |
![]() |
![]() |
![]() |
GUPnPServiceProxy sends commands to a remote UPnP service and handles incoming event notifications. GUPnPServiceProxy implements the GUPnPServiceInfo interface.
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 |
The GUPnPServiceProxyAction in progress |
|
user_data |
User data |
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 |
GUPnPServiceProxyAction * gupnp_service_proxy_call_action (GUPnPServiceProxy *proxy
,GUPnPServiceProxyAction *action
,GCancellable *cancellable
,GError **error
);
Synchronously call the action
on the remote UPnP service.
proxy |
[transfer none] | |
action |
An action. |
[transfer none] |
cancellable |
A GCancellable which can be used to cancel the current action call. |
[allow-none] |
error |
[inout][optional][nullable] |
Since: 1.2.0
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.
proxy |
[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 |
[closure] |
Since: 1.2.0
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.
Since: 1.2.0
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
.
proxy |
||
action |
An action |
|
error |
The location where to store any error, or |
[inout][optional][nullable] |
... |
tuples of in parameter name, in parameter type, and in parameter
value, followed by |
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()
.
proxy |
||
action |
An action |
|
error |
The location where to store any error, or |
[inout][optional][nullable] |
var_args |
va_list of tuples of in parameter name, in parameter type, and in
parameter value, followed by |
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.
proxy |
[transfer none] | |
action |
An action |
|
in_names |
GList of 'in' parameter names (as strings). |
[element-type utf8][transfer none] |
in_values |
[element-type GValue][transfer none] | |
out_names |
GList of 'out' parameter names (as strings). |
[element-type utf8][transfer none] |
out_types |
[element-type GType][transfer none] | |
out_values |
GList of values
(as GValue) that line up with |
[element-type GValue][transfer full][out] |
error |
The location where to store any error, or |
[inout][optional][nullable] |
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.
proxy |
||
action |
An action |
|
callback |
The callback to call when sending the action has succeeded or failed. |
[scope async] |
user_data |
User data for |
|
... |
tuples of in parameter name, in parameter type, and in parameter
value, terminated with |
A GUPnPServiceProxyAction handle. This will be freed when
gupnp_service_proxy_cancel_action()
or
gupnp_service_proxy_end_action_valist()
.
[transfer none]
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()
.
proxy |
||
action |
An action |
|
callback |
(scope async) : The callback to call when sending the action has succeeded or failed |
|
user_data |
User data for |
|
var_args |
A va_list of tuples of in parameter name, in parameter type, and in parameter value |
A GUPnPServiceProxyAction handle. This will
be freed when calling gupnp_service_proxy_cancel_action()
or
gupnp_service_proxy_end_action_valist()
.
[transfer none]
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.
proxy |
[transfer none] | |
action |
An action |
|
in_names |
GList of 'in' parameter names (as strings). |
[element-type utf8][transfer none] |
in_values |
[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 |
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
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
.
proxy |
||
action |
A GUPnPServiceProxyAction handle |
|
error |
The location where to store any error, or |
[inout][optional][nullable] |
... |
tuples of out parameter name, out parameter type, and out parameter
value location, terminated with |
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()
.
proxy |
||
action |
A GUPnPServiceProxyAction handle |
|
error |
The location where to store any error, or |
[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 |
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.
proxy |
||
action |
A GUPnPServiceProxyAction handle |
|
error |
The location where to store any error, or |
[inout][optional][nullable] |
hash |
A GHashTable of out parameter name and initialised GValue pairs. |
[element-type utf8 GValue][inout][transfer none] |
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.
proxy |
||
action |
A GUPnPServiceProxyAction handle |
|
error |
The location where to store any error, or |
[inout][optional][nullable] |
out_names |
GList of 'out' parameter names (as strings). |
[element-type utf8][transfer none] |
out_types |
[element-type GType][transfer none] | |
out_values |
GList of values
(as GValue) that line up with |
[element-type GValue][transfer full][out] |
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.
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]
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]
proxy |
||
variable |
The variable to add notification for |
|
type |
The type of the variable |
|
callback |
The callback to call when |
[scope notified] |
user_data |
User data for |
|
notify |
Function to call when the notification is removed, or |
[allow-none] |
Since: 0.20.12
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.
proxy |
||
callback |
The callback to call when the peer issues any variable notification. |
[scope notified] |
user_data |
User data for |
|
notify |
A GDestroyNotify for |
[allow-none] |
Since: 0.20.12
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.
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.
void gupnp_service_proxy_set_subscribed (GUPnPServiceProxy *proxy
,gboolean subscribed
);
(Un)subscribes to this service.
gboolean
gupnp_service_proxy_get_subscribed (GUPnPServiceProxy *proxy
);
Returns if we are subscribed to this service.
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); |
action |
The name of a remote action to call |
|
... |
tuples of in parameter name, in parameter type, and in parameter
value, terminated with |
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); |
GUPnPServiceProxyAction *
gupnp_service_proxy_action_ref (GUPnPServiceProxyAction *action
);
void
gupnp_service_proxy_action_unref (GUPnPServiceProxyAction *action
);
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
.
action |
the action to modify |
|
key |
the name of the value to modify |
|
value |
the new value of |
|
error |
a return location for an GError. |
[nullable] |
Since: 1.4.0
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
.
action |
A GUPnPServiceProxyAction handle |
|
error |
The location where to store any error, or |
[inout][optional][nullable] |
... |
tuples of out parameter name, out parameter type, and out parameter
value location, terminated with |
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); } |
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 |
[inout][optional][nullable] |
Since: 1.2.0
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.
action |
A GUPnPServiceProxyAction handle |
|
out_names |
GList of 'out' parameter names (as strings). |
[element-type utf8][transfer none] |
out_types |
[element-type GType][transfer none] | |
out_values |
GList of values
(as GValue) that line up with |
[element-type GValue][transfer full][out] |
error |
The location where to store any error, or |
[inout][optional][nullable] |
Since: 1.2.0