gupnp-binding-tool-@GUPNP_API_VERSION@
1
GUPnP
gupnp-binding-tool-@GUPNP_API_VERSION@
creates C convenience wrappers for UPnP services
gupnp-binding-tool-@GUPNP_API_VERSION@
--prefix PREFIX
--mode client|server
SCPD file
Description
gupnp-binding-tool-@GUPNP_API_VERSION@ takes a SCPD file and generates convenience C functions
which call the actual GUPnP functions. The client-side bindings can be seen
as a service-specific version of the GUPnPServiceProxy API and the
service-side bindings are the same for GUPnPService.
These generated functions are less verbose and also safer as function call
parameters are correctly typed. Action, variable and query names are easier
to get correct with bindings (or at least the errors will be compile-time
errors instead of run-time), and are also available in editor
autocompletion.
Client side bindings
As an example, this action:
DeletePortMapping
NewRemoteHost
in
RemoteHost
NewExternalPort
in
ExternalPort
NewProtocol
in
PortMappingProtocol
]]>
Will generate the following synchronous client-side (control point)
function:
static inline gboolean
igd_delete_port_mapping (GUPnPServiceProxy *proxy,
const gchar *in_new_remote_host,
const guint in_new_external_port,
const gchar *in_new_protocol,
GError **error);
As can be seen, the arguments have the correct types and are prefixed with
the argument direction.
gupnp-binding-tool-@GUPNP_API_VERSION@ generates both synchronous and
asynchronous wrappers. The igd_delete_port_mapping example
above is the synchronous form, the asynchronous form is as follows:
typedef void (*igd_delete_port_mapping_reply) (GUPnPServiceProxy *proxy,
GError *error,
gpointer userdata);
static inline GUPnPServiceProxyAction *
igd_delete_port_mapping_async (GUPnPServiceProxy *proxy,
const gchar *in_new_remote_host,
const guint in_new_external_port,
const gchar *in_new_protocol,
igd_delete_port_mapping_reply callback,
gpointer userdata);
The asynchronous form (implemented using
gupnp_service_proxy_begin_action() and
gupnp_service_proxy_end_action()) will return without
blocking and later invoke the callback from the main loop when the reply
is received.
The tool also creates bindings for state variable notifications. This state
variable definition:
ExternalIPAddress
string
]]>
will create this client binding that can be used to get notifications on
"ExternalIPAddress" changes:
typedef void
(*igd_external_ip_address_changed_callback) (GUPnPServiceProxy *proxy,
const gchar *external_ip_address,
gpointer userdata);
static inline gboolean
igd_external_ip_address_add_notify (GUPnPServiceProxy *proxy,
igd_external_ip_address_changed_callback callback,
gpointer userdata);
All of the examples were produced with gupnp-binding-tool-@GUPNP_API_VERSION@
--prefix igd --mode client WANIPConnection.xml.
Server side bindings
The corresponding server bindings for the same UPnP action
(DeletePortMapping) look like this:
void
igd_delete_port_mapping_action_get (GUPnPServiceAction *action,
gchar **in_new_remote_host,
guint *in_new_external_port,
gchar **in_new_protocol);
gulong
igd_delete_port_mapping_action_connect (GUPnPService *service,
GCallback callback,
gpointer userdata);
The generated *_action_connect() function can be used to connect the action
handler. The *_action_get() and *_action_set() functions can then
be used inside the action handler to get/set action variables. If notified
variables are modified, the *_variable_notify() should be used to send
the notifications (see below).
typedef gchar *(*igd_external_ip_address_query_callback) (GUPnPService *service,
gpointer userdata);
gulong
igd_external_ip_address_query_connect (GUPnPService *service,
igd_external_ip_address_query_callback callback,
gpointer userdata);
void
igd_external_ip_address_variable_notify (GUPnPService *service,
const gchar *external_ip_address);
The *_query_connect() function can be used to connect the service-specific
query handler. The return value of the handler is the returned state
variable value.
All of the examples were produced with gupnp-binding-tool-@GUPNP_API_VERSION@
--prefix igd --mode server WANIPConnection.xml.