1GUPNP-BINDING-TOOL(1)                GUPnP               GUPNP-BINDING-TOOL(1)
2
3
4

NAME

6       gupnp-binding-tool-1.2 - creates C convenience wrappers for UPnP
7       services
8

SYNOPSIS

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

DESCRIPTION

14       gupnp-binding-tool-1.2 takes a SCPD file and generates convenience C
15       functions which call the actual GUPnP functions. The client-side
16       bindings can be seen as a service-specific version of the
17       GUPnPServiceProxy API and the service-side bindings are the same for
18       GUPnPService.
19
20       These generated functions are less verbose and also safer as function
21       call parameters are correctly typed. Action, variable and query names
22       are easier to get correct with bindings (or at least the errors will be
23       compile-time errors instead of run-time), and are also available in
24       editor autocompletion.
25

CLIENT SIDE BINDINGS

27       As an example, this action:
28
29           <action>
30             <name>DeletePortMapping</name>
31             <argumentList>
32               <argument>
33                 <name>NewRemoteHost</name>
34                 <direction>in</direction>
35                 <relatedStateVariable>RemoteHost</relatedStateVariable>
36               </argument>
37               <argument>
38                 <name>NewExternalPort</name>
39                 <direction>in</direction>
40                 <relatedStateVariable>ExternalPort</relatedStateVariable>
41               </argument>
42               <argument>
43                 <name>NewProtocol</name>
44                 <direction>in</direction>
45                 <relatedStateVariable>PortMappingProtocol</relatedStateVariable>
46               </argument>
47             </argumentList>
48           </action>
49
50       Will generate the following synchronous client-side (control point)
51       function:
52
53           static inline gboolean
54           igd_delete_port_mapping (GUPnPServiceProxy *proxy,
55                                    const gchar *in_new_remote_host,
56                                    const guint in_new_external_port,
57                                    const gchar *in_new_protocol,
58                                    GError **error);
59
60       As can be seen, the arguments have the correct types and are prefixed
61       with the argument direction.
62
63       gupnp-binding-tool-1.2 generates both synchronous and asynchronous
64       wrappers. The igd_delete_port_mapping example above is the synchronous
65       form, the asynchronous form is as follows:
66
67           typedef void (*igd_delete_port_mapping_reply) (GUPnPServiceProxy *proxy,
68                                                          GError *error,
69                                                          gpointer userdata);
70
71           static inline GUPnPServiceProxyAction *
72           igd_delete_port_mapping_async (GUPnPServiceProxy *proxy,
73                                          const gchar *in_new_remote_host,
74                                          const guint in_new_external_port,
75                                          const gchar *in_new_protocol,
76                                          igd_delete_port_mapping_reply callback,
77                                          gpointer userdata);
78
79       The asynchronous form (implemented using
80       gupnp_service_proxy_begin_action() and
81       gupnp_service_proxy_end_action()) will return without blocking and
82       later invoke the callback from the main loop when the reply is
83       received.
84
85       The tool also creates bindings for state variable notifications. This
86       state variable definition:
87
88           <stateVariable sendEvents="yes">
89             <name>ExternalIPAddress</name>
90             <dataType>string</dataType>
91           </stateVariable>
92
93       will create this client binding that can be used to get notifications
94       on "ExternalIPAddress" changes:
95
96           typedef void
97           (*igd_external_ip_address_changed_callback) (GUPnPServiceProxy *proxy,
98                                                        const gchar *external_ip_address,
99                                                        gpointer userdata);
100
101           static inline gboolean
102           igd_external_ip_address_add_notify (GUPnPServiceProxy *proxy,
103                                               igd_external_ip_address_changed_callback callback,
104                                               gpointer userdata);
105
106       All of the examples were produced with gupnp-binding-tool-1.2 --prefix
107       igd --mode client WANIPConnection.xml.
108

SERVER SIDE BINDINGS

110       The corresponding server bindings for the same UPnP action
111       (DeletePortMapping) look like this:
112
113           void
114           igd_delete_port_mapping_action_get (GUPnPServiceAction *action,
115                                               gchar **in_new_remote_host,
116                                               guint *in_new_external_port,
117                                               gchar **in_new_protocol);
118
119           gulong
120           igd_delete_port_mapping_action_connect (GUPnPService *service,
121                                                   GCallback callback,
122                                                   gpointer userdata);
123
124       The generated *_action_connect() function can be used to connect the
125       action handler. The *_action_get() and *_action_set() functions can
126       then be used inside the action handler to get/set action variables. If
127       notified variables are modified, the *_variable_notify() should be used
128       to send the notifications (see below).
129
130           typedef gchar *(*igd_external_ip_address_query_callback) (GUPnPService *service,
131                                                                     gpointer userdata);
132
133           gulong
134           igd_external_ip_address_query_connect (GUPnPService *service,
135                                                  igd_external_ip_address_query_callback callback,
136                                                  gpointer userdata);
137           void
138           igd_external_ip_address_variable_notify (GUPnPService *service,
139                                                    const gchar *external_ip_address);
140
141       The *_query_connect() function can be used to connect the
142       service-specific query handler. The return value of the handler is the
143       returned state variable value.
144
145       All of the examples were produced with gupnp-binding-tool-1.2 --prefix
146       igd --mode server WANIPConnection.xml.
147
148
149
150GUPnP 1.4.3                                              GUPNP-BINDING-TOOL(1)
Impressum