'\" t
.\" Title: gupnp-binding-tool
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 08/04/2020
.\" Manual: Reference
.\" Source: GUPnP 1.0.5
.\" Language: English
.\"
.TH "GUPNP\-BINDING\-TOOL" "1" "08/04/2020" "GUPnP 1\&.0\&.5" "Reference"
.\" -----------------------------------------------------------------
.\" * 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 \- creates C convenience wrappers for UPnP services
.SH "SYNOPSIS"
.HP \w'\fBgupnp\-binding\-tool\fR\ 'u
\fBgupnp\-binding\-tool\fR [\-\-prefix\ {PREFIX}] [\-\-mode\ {client|server}] {SCPD\ file}
.SH "DESCRIPTION"
.PP
\fBgupnp\-binding\-tool\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
DeletePortMapping
NewRemoteHost
in
RemoteHost
NewExternalPort
in
ExternalPort
NewProtocol
in
PortMappingProtocol
.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\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
ExternalIPAddress
string
.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 \-\-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 \-\-prefix igd \-\-mode server WANIPConnection\&.xml\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2007, 2008, 2009 OpenedHand Ltd, Nokia Corporation
.br
.PP
Permission is granted to copy, distribute and/or modify this document under the terms of the
GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the
GNU Free Documentation License
from the Free Software Foundation by visiting
\m[blue]\fBtheir Web site\fR\m[]
or by writing to:
.sp
.if n \{\
.RS 4
.\}
.nf
Free Software Foundation
51 Franklin Street, Fifth Floor
Boston, MA 02110-1335,
USA
.fi
.if n \{\
.RE
.\}
.sp
.sp