File: README.md

package info (click to toggle)
pupnp-1.8 1:1.8.4-2
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 3,416 kB
  • sloc: ansic: 31,588; xml: 1,173; makefile: 338; sh: 34
file content (470 lines) | stat: -rw-r--r-- 16,773 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
# Portable SDK for UPnP\* Devices (libupnp)

Copyright (c) 2000-2003 Intel Corporation - All Rights Reserved.

Copyright (c) 2005-2006 RĂ©mi Turboult <r3mi@users.sourceforge.net>

Copyright (c) 2006 Michel Pfeiffer and others <virtual_worlds@gmx.de>

See LICENSE for details.

## Table of Contents

1. Release List
2. Release Contents
3. Package Contents
4. System Requirements
5. Build Instructions
6. Install/Uninstall Instructions
7. Product Release Notes
8. New Features
9. Support and Contact Information
10. IXML support for scripting languages


## 1. Release List

Release Number | Date | History
---------------|------|--------
0.9.0  | 2000-08-01 | [UPnP SDK for Linux][UPnP SDK for Linux]
0.9.1  | 2000-08-17 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.0.0  | 2000-08-31 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.0.1  | 2000-10-13 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.0.2  | 2001-02-07 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.0.3  | 2001-06-12 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.0.4  | 2001-08-15 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.2.1  | 2003-02-13 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.2.1a | 2003-11-08 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.3.0  | 2006-03-04 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.3.1  | 2006-03-05 | [UPnP SDK for Linux][UPnP SDK for Linux]
1.4.0  | 2006-06-12 | [Portable UPnP SDK][Portable UPnP SDK]
1.4.1  | 2006-08-11 | [Portable UPnP SDK][Portable UPnP SDK]
1.4.2  | 2007-02-16 | [Portable UPnP SDK][Portable UPnP SDK]
1.4.3  | 2007-03-06 | [Portable UPnP SDK][Portable UPnP SDK]
1.4.4  | 2007-04-17 | [Portable UPnP SDK][Portable UPnP SDK]
1.4.5  | 2007-04-28 | [Portable UPnP SDK][Portable UPnP SDK]
1.4.6  | 2007-04-30 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.0  | 2007-06-23 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.1  | 2007-11-08 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.2  | 2007-12-10 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.3  | 2007-12-26 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.4  | 2008-01-26 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.5  | 2008-02-02 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.6  | 2008-04-25 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.7  | 2010-10-04 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.8  | 2010-10-21 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.9  | 2010-11-07 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.10 | 2011-01-30 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.11 | 2011-02-07 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.12 | 2011-02-08 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.13 | 2011-03-17 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.14 | 2011-11-17 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.15 | 2012-01-25 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.16 | 2012-03-21 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.17 | 2012-04-03 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.18 | 2013-01-29 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.19 | 2013-11-15 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.20 | 2016-07-07 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.21 | 2016-12-21 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.22 | 2017-05-30 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.23 | 2017-11-19 | [Portable UPnP SDK][Portable UPnP SDK]
1.6.24 | 2017-11-19 | [Portable UPnP SDK][Portable UPnP SDK]
1.8.0  | 2017-01-04 | [Portable UPnP SDK][Portable UPnP SDK]
1.8.1  | 2017-05-24 | [Portable UPnP SDK][Portable UPnP SDK]
1.8.2  | 2017-11-12 | [Portable UPnP SDK][Portable UPnP SDK]
1.8.3  | 2017-11-12 | [Portable UPnP SDK][Portable UPnP SDK]

[UPnP SDK for Linux]: https://sourceforge.net/projects/upnp/
[Portable UPnP SDK]: https://sourceforge.net/projects/pupnp/

## 2. Release Contents

The Portable SDK for UPnP Devices is an SDK for development of UPnP device 
and control point applications.  It consists of the core UPnP 
protocols along with a UPnP-specific eXtensible Markup Language (XML) parser 
supporting the Document Object Model (DOM) Level 2 API and an optional, 
integrated mini web server for serving UPnP related documents.


## 3. Package Contents

The SDK for UPnP Devices contains the following:

Path/File | Description
----------------|-------------------------------------------------------------
README    	| This file.  Contains the installation and build instructions.
LICENSE   	| The licensing terms the SDK is distributed under.
NEWS		| Changes and new features.
ixml\doc	| The files for generating the XML parser documentation from the source code.
ixml\inc	| The public include files required to use the XML parser.
ixml\src	| The source code to the XML parser library.
upnp\doc	| The files for generating the SDK documentation from the source code.
upnp\inc	| The public include files required to use the SDK.
upnp\src      	| The source files comprising the SDK, libupnp.so.
upnp\sample	| A sample device and control point application, illustrating the usage of the SDK.


## 4. System Requirements

The SDK for UPnP Devices is designed to compile and run under several
operating systems.  It does, however, have dependencies on some
packages that may not be installed by default.  All packages that it
requires are listed below.

libpthread  The header and library are installed as part of the glibc-devel
            package (or equivalent).

Additionally, the documentation for the SDK can be auto-generated from 
the upnp.h header file using DOC++, a documentation system for C, C++, 
IDL, and Java\*.  DOC++ generates the documentation in HTML or TeX format.
Using some additional tools, the TeX output can be converted into a
PDF file.  To generate the documentation these tools are required:

DOC++     | The homepage for DOC\+\+ is http://docpp.sourceforge.net/. The current version as of this release of the SDK is version 3.4.9. DOC\+\+ is the only requirement for generating the HTML documentation.
----------|--------------------------------------------------------------
LaTeX/TeX | To generate the PDF documentation, LaTeX and TeX tools are necessary. The tetex and tetex-latex packages provide these tools.
dvips     | dvips converts the DVI file produced by LaTeX into a PostScript\* file. The tetex-dvips package provides this tool.
ps2pdf    | The final step to making the PDF is converting the PostStript\* into Portable Document Format.  The ghostscript package provides this tool.

For the UPnP library to function correctly, networking must be configured
properly for multicasting.  To do this:

```
% route add -net 239.0.0.0 netmask 255.0.0.0 eth0
```

where 'eth0' is the network adapter that the UPnP library will use.  Without
this addition, device advertisements and control point searches will not
function.


## 5. Build Instructions

### CORE LIBRARIES

The in the examples below, replace `$(LIBUPNP)` with "libupnp-x.y.z",
with x, y, and z corresponding to the version of the library that you have.

All pieces of the SDK are configured and built from the `$(LIBUPNP)` directory. 

Note: On a git checkout, you need to run `./bootstrap` to generate the configure script.

```
% cd $(LIBUPNP)
% ./configure
% make
```

will build a version of the binaries without debug support, and with default 
options enabled (see below for options available at configure time).

```
% cd $(LIBUPNP)
% ./configure CFLAGS="-DSPARC_SOLARIS -mtune=<cputype> -mcpu=<cputype>"
% make
```

will build a Sparc Solaris version of the binaries without debug support
and with default options enabled (see below for options available at
configure time). Please note: <cputype> has to be replaced by a token that
fits to your platform and CPU (e.g. "supersparc").

To build the documentation, assuming all the necessary tools are installed 
(see section 3) :

To generate the HTML documentation:

```
% cd $(LIBUPNP)
% make html
```

To generate the PDF file:

```
% cd $(LIBUPNP)
% make pdf
```

A few options are available at configure time. Use "./configure --help"
to display a complete list of options. Note that these options 
may be combined in any order.
After installation, the file <upnp/upnpconfig.h> will provide a summary
of the optional features that have been included in the library.

```
% cd $(LIBUPNP)
% ./configure --enable-debug
% make 
```

will build a debug version with symbols support.

To build the library with the optional, integrated mini web server (note
that this is the default):

```
% cd $(LIBUPNP)
% ./configure --enable-webserver
% make 
```

To build without:

```
% cd $(LIBUPNP)
% ./configure --disable-webserver
% make 
```

The SDK also contains some additional helper APIs, declared in
inc/tools/upnptools.h.  If these additional tools are not required, they can
be compiled out:

```
% cd $(LIBUPNP)
% ./configure --disable-tools
% make 
```

By default, the tools are included in the library.

To further remove code that is not required, the library can be build with or 
with out the control point (client) or device specific code.  To remove this
code:

```
% cd $(LIBUPNP)
% ./configure --disable-client
% make 
```

to remove client only code or:

```
% cd $(LIBUPNP)
% ./configure --disable-device
% make 
```

to remove device only code.

By default, both client and device code is included in the library.  The
integrated web server is automatically removed when configuring with 
--disable-device.

To build the library without large-file support (enabled by default) :

```
% cd $(LIBUPNP)
% ./configure --disable-largefile
% make 
```


To remove all the targets, object files, and built documentation:

```
% cd $(LIBUPNP)
% make clean
```


### CROSS COMPILATION

To cross compile the SDK, a special "configure" directive is all that is
required:

```
% cd $(LIBUPNP)
% ./configure --host=arm-linux
% make
```

This will invoke the "arm-linux-gcc" cross compiler to build the library.


### SAMPLES

The SDK contains two samples: a TV device application and a control point
that talks with the TV device.  They are found in the $(LIBUPNP)/upnp/sample 
directory.  

To build the samples (note: this is the default behaviour):

```
% cd $(LIBUPNP)
% ./configure --enable-samples
% make
```

will build the sample device "$(LIBUPNP)/upnp/tv_device" and
sample control point "$(LIBUPNP)/upnp/tv_ctrlpt". 
Note : the sample device won't be built if --disable-device has been 
configured, and the sample control point won't be build if --disable-client 
has been configured.

To run the sample device, you need to create a tvdevice directory and move
the web directory there, giving: "$(LIBUPNP)/upnp/sample/tvdevice/web".
To run the sample invoke from the command line as follows:

```
% cd $(LIBUPNP)/upnp/sample/tvdevice
% ../tv_device
```


### SOLARIS BUILD

The building process for the Solaris operating system is similar to the one
described above. Only the call to ./configure has to be done using an
additional parameter:

```
% ./configure CFLAGS="-mcpu=<cputype> -mtune=<cputype> -DSPARC_SOLARIS"
```

where <cputype> has to be replaced by the appropriate CPU tuning flag (e.g.
"supersparc"). Afterwards

```
% make
% make install
```

can be called as described above.


### WINDOWS BUILD

In order to build libupnp under Windows the pthreads-w32 package is required.
You can download a self-extracting ZIP file from the following location:

ftp://sources.redhat.com/pub/pthreads-win32/pthreads-w32-2-7-0-release.exe
or possibly newer versions if available.

Execute the self-extracting archive and copy the Pre-build.2 folder to the
top level source folder.
Rename Pre-build.2 to pthreads. 
Open the provided workspace build\libupnp.dsw with Visual C++ 6.0 and select
Build->Build libupnp.dll (F7)
In the build directory there are also VC8, VC9 and VC10 folders containing
solution files for Visual Studio 2005/2008/2010 respectively.

If you use newer versions to build libupnp, eg Visual Studio 2003 or later,
then you need to rebuild the pthreads package so it uses the same VC runtime
as libupnp to prevent cross boundary runtime problems
(see http://msdn.microsoft.com/en-us/library/ms235460%28v=VS.100%29.aspx).
Just replace the files in the Pre-build.2 folder (renamed to pthreads as
mentioned above) with the newly build versions.
If you also use a newer version of pthreads-win32 then you should also
replace the header files in that directory structure (obviously).

For building a static library instead of a DLL and for using the static
pthreads-w32 library following switches need to be defined additionally:

UPNP_STATIC_LIB - for creating a statically linkable UPnP-library
PTW32_STATIC_LIB - for using the static pthreads32 library


## 6. Install/Uninstall Instructions

### Install

The top-level makefile for the UPnP SDK contains rules to install the 
necessary components.  To install the SDK, as root:

```
% make install
```

### Uninstall

Likewise, the top-level makefile contains an uninstall rule, reversing 
the steps in the install:

```
% make uninstall
```


## 7. Product Release Notes

The SDK for UPnP Devices v1.2.1a has these known issues:

* The UPnP library may not work with older versions of gcc and libstdc++,
  causing a segmentation fault when the library loads.  It is recommended
  that gcc version 2.9 or later be used in building library.
* The UPnP library does not work the glibc 2.1.92-14 that ships with
  Red Hat 7.0.  For the library to function, you must updated the glibc
  and glibc-devel packages to 2.1.94-3 or later.  There is some issue with
  libpthreads that has been resolved in the 2.1.94 version.

## 8. New Features

See NEWS file.


## 9. Support and Contact Information

Intel is not providing support for the SDK for UPnP Devices. Mailing lists
and discussion boards can be found at http://www.libupnp.org/.

If you find this SDK useful, please send an email to upnp@intel.com and let
us know.


\* Other brands, names, and trademarks are the property of their respective 
owners.


## 10. IXML support for scriptinglanguages

The treestructure of XML documents created by IXML is hard to maintain when
creating a binding for a scripting language. Even when many elements may 
never be used on the script side, it requires copying the entire tree 
structure once you start accessing elements several levels deep.
Hence scriptsupport was added. To enable it compile while 
IXML_HAVE_SCRIPTSUPPORT has been defined (enabled by default). 
This allows control using only a list instead of a tree-like
structure, and only nodes actually accessed need to be created instead of
all the nodes in the tree.

Here's how its supposed to work;
* The scriptsupport allows you to add a callback when a node is freed on 
  the C side, so appropriate action can be taken on the script side, see
  function ixmlSetBeforeFree().
* Instead of recreating the tree structure, an intermediate object should
  be created only for the nodes actually accessed. The object should be
  containing a pointer to the node and a 'valid flag' which is initially 
  set to TRUE (the valid flag, can simply be the pointer to the node being 
  NULL or not). Before creating the intermediate object, the custom tag 
  'ctag' can be used to check whether one was already created.
* the node object gets an extra 'void\* ctag' field, a custom tag to make a
  cross reference to the script side intermediate object. It can be set
  using ixmlNode_setCTag(), and read using ixmlNode_getCTag(). Whenever
  a new intermediate object is created, the ctag of the coirresponding
  node should be set to point to this intermediate object.
* The tree structure traversal is done on the C side (looking up parents, 
  children and siblings)
* Every intermediate object created should be kept in a list (preferably a 
  key-value list, where the key is the pointer to the node and the value is 
  the pointer to the intermediate object)
* when the callback is called, the node should be looked up in the list, 
  the flag set to false, the pointer to the C-side node be cleared and on
  the C-side the ctag should be cleared.
* whenever the intermediate object is accessed and its flag is set to False, 
  an error should be thrown that the XML document has been closed.

Freeing resources can be done in 2 ways, C side by simply calling the free 
node methods, or script side by the garbage collector of the scriptengine. 
Scriptside steps;
* if the valid flag is set to False (XML document is closed), then the 
  intermediate object can be destroyed, no further action
* if the node has a parent, then the intermediate object can be destroyed 
  after the ctag on the corresponding node has been cleared. Nothing needs
  to be freed on the C-side.
* if the node has no parent, then the node must be freed on the C side by 
  calling the corresponding free node methods. This will result in a chain 
  of callbacks closing the node and all underlying nodes.