GUPnPServiceProxy: GUPnP Reference Manual

GUPnPServiceProxy

GUPnPServiceProxy — Proxy class for remote services.

Functions

void	(*GUPnPServiceProxyActionCallback) ()
void	(*GUPnPServiceProxyNotifyCallback) ()
gboolean	gupnp_service_proxy_send_action ()
gboolean	gupnp_service_proxy_send_action_valist ()
gboolean	gupnp_service_proxy_send_action_hash ()
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_hash ()
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 ()

Properties

gboolean

subscribed

Read / Write

Signals

void

subscription-lost

Run Last

Types and Values

struct	GUPnPServiceProxy
	GUPnPServiceProxyAction

Object Hierarchy

    GObject
    ╰── GUPnPServiceInfo
        ╰── GUPnPServiceProxy

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

Parameters

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

See gupnp_service_proxy_send_action().

Parameters

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

gupnp_service_proxy_send_action_hash has been deprecated since version 0.20.9 and should not be used in newly-written code.

Use gupnp_service_proxy_send_action() or gupnp_service_proxy_send_action_list()

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

Do not use this function in newly written code; it cannot guarantee the order of arguments and thus breaks interaction with many devices.

[skip]

Parameters

proxy	A GUPnPServiceProxy
action	An action
error	The location where to store any error, or `NULL`.	[allow-none]
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.

[skip]

Parameters

proxy	A GUPnPServiceProxy
action	An action
error	The location where to store any error, or `NULL`.	[allow-none]
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.

Since: 0.13.3

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.

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

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

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

gupnp_service_proxy_begin_action_hash has been deprecated since version 0.20.9 and should not be used in newly-written code.

Use gupnp_service_proxy_send_action() or gupnp_service_proxy_send_action_list()

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

Do not use this function in newly written code; it cannot guarantee the order of arguments and thus breaks interaction with many devices.

[skip]

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`
hash	A GHashTable of in parameter name and GValue pairs.	[element-type utf8 GValue]

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.

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

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 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`.	[allow-none]
...	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);

See gupnp_service_proxy_end_action().

Parameters

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

Parameters

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][out caller-allocates][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.

[skip]

Parameters

proxy	A GUPnPServiceProxy
action	A GUPnPServiceProxyAction handle
error	The location where to store any error, or `NULL`.	[allow-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 on success.

gupnp_service_proxy_cancel_action ()

void
gupnp_service_proxy_cancel_action (GUPnPServiceProxy *proxy,
                                   GUPnPServiceProxyAction *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.

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.

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.

Types and Values

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.

Property Details

The `“subscribed”` property

  “subscribed”               gboolean

Whether we are subscribed to this service.

Flags: Read / Write

Default value: FALSE

Signal Details

The `“subscription-lost”` signal

void
user_function (GUPnPServiceProxy *proxy,
               gpointer           error,
               gpointer           user_data)

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

Parameters

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

Flags: Run Last