'\" t
.\"     Title: gupnp-binding-tool-1.2
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/19/2021
.\"    Manual: GUPnP
.\"    Source: GUPnP 1.4.0
.\"  Language: English
.\"
.TH "GUPNP\-BINDING\-TOOL" "1" "09/19/2021" "GUPnP 1\&.4\&.0" "GUPnP"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gupnp-binding-tool-1.2 \- creates C convenience wrappers for UPnP services
.SH "SYNOPSIS"
.HP \w'\fBgupnp\-binding\-tool\-1\&.2\fR\ 'u
\fBgupnp\-binding\-tool\-1\&.2\fR [\-\-prefix\ {PREFIX}] [\-\-mode\ {client|server}] {SCPD\ file}
.SH "DESCRIPTION"
.PP
\fBgupnp\-binding\-tool\-1\&.2\fR
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\&.
.PP
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\&.
.SH "CLIENT SIDE BINDINGS"
.PP
As an example, this action:
.sp
.if n \{\
.RS 4
.\}
.nf
<action>
  <name>DeletePortMapping</name>
  <argumentList>
    <argument>
      <name>NewRemoteHost</name>
      <direction>in</direction>
      <relatedStateVariable>RemoteHost</relatedStateVariable>
    </argument>
    <argument>
      <name>NewExternalPort</name>
      <direction>in</direction>
      <relatedStateVariable>ExternalPort</relatedStateVariable>
    </argument>
    <argument>
      <name>NewProtocol</name>
      <direction>in</direction>
      <relatedStateVariable>PortMappingProtocol</relatedStateVariable>
    </argument>
  </argumentList>
</action>
.fi
.if n \{\
.RE
.\}
.PP
Will generate the following synchronous client\-side (control point) function:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
As can be seen, the arguments have the correct types and are prefixed with the argument direction\&.
.PP
\fBgupnp\-binding\-tool\-1\&.2\fR
generates both synchronous and asynchronous wrappers\&. The
\fBigd_delete_port_mapping\fR
example above is the synchronous form, the asynchronous form is as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
The asynchronous form (implemented using
\fBgupnp_service_proxy_begin_action()\fR
and
\fBgupnp_service_proxy_end_action()\fR) will return without blocking and later invoke the callback from the main loop when the reply is received\&.
.PP
The tool also creates bindings for state variable notifications\&. This state variable definition:
.sp
.if n \{\
.RS 4
.\}
.nf
<stateVariable sendEvents="yes">
  <name>ExternalIPAddress</name>
  <dataType>string</dataType>
</stateVariable>
.fi
.if n \{\
.RE
.\}
.PP
will create this client binding that can be used to get notifications on "ExternalIPAddress" changes:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
All of the examples were produced with
gupnp\-binding\-tool\-1\&.2 \-\-prefix igd \-\-mode client WANIPConnection\&.xml\&.
.SH "SERVER SIDE BINDINGS"
.PP
The corresponding server bindings for the same UPnP action (DeletePortMapping) look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
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)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
All of the examples were produced with
gupnp\-binding\-tool\-1\&.2 \-\-prefix igd \-\-mode server WANIPConnection\&.xml\&.