Man Linux: Main Page and Category List

NAME

       gupnp-binding-tool - creates C convenience wrappers for UPnP services

SYNOPSIS

       gupnp-binding-tool [--prefix {PREFIX}] [--mode {client|server}]
                          {SCPD file}

DESCRIPTION

       gupnp-binding-tool 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:

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

       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 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:

           <stateVariable sendEvents="yes">
             <name>ExternalIPAddress</name>
             <dataType>string</dataType>
           </stateVariable>

       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 --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 --prefix igd
       --mode server WANIPConnection.xml.

COPYRIGHT

       Copyright © 2007, 2008, 2009 OpenedHand Ltd, Nokia Corporation

       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 their Web site or by writing to:

                     The Free Software Foundation, Inc.,
                     59 Temple Place - Suite 330,
                     Boston, MA 02111-1307,
                     USA