1GUPNP-BINDING-TOOL(1) GUPnP GUPNP-BINDING-TOOL(1)
2
3
4
6 gupnp-binding-tool-1.6 - creates C convenience wrappers for UPnP
7 services
8
10 gupnp-binding-tool-1.6 [--prefix {PREFIX}] [--mode {client|server}]
11 {SCPD file}
12
14 gupnp-binding-tool-1.6 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
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.6 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.6 --prefix
107 igd --mode client WANIPConnection.xml.
108
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.6 --prefix
146 igd --mode server WANIPConnection.xml.
147
148
149
150GUPnP 1.6.6 GUPNP-BINDING-TOOL(1)