Herqq
|
Herqq UPnP Library (thereafter HUPnP) is a collection of reusable classes that provide UPnP connectivity conforming to the UPnP Device Architecture version 1.1.
Above everything else, HUPnP is designed to be simple to use and robust in operation. HUPnP does its best to enable you, the user, to focus on the business logic of your domain, rather than to the details of UPnP. However, not everything can be hidden and some UPnP knowledge is required to fully understand the system mechanics and the terms used in this documentation. To fill such gaps you can check the aforementioned UDA specification and other documents available at the UPnP Forum.
HUPnP is tightly integrated into the Qt Framework and follows closely the very same design principles and programming practices Qt follows. You will get the most out of HUPnP by using it alongside with Qt. You can use HUPnP from other environments as well, assuming the appropriate Qt headers and libraries are available.
First, it is important to point out that at the moment HUPnP is officially distributed in source code only. If you come across a binary of HUPnP, it is not made by the author of HUPnP. Second, HUPnP uses the QtSoap library under the LGPLv2.1 license. The QtSoap library is distributed along the HUPnP in source code and the library is built into a shared library during the compilation of HUPnP.
In order to use HUPnP, you need to build it first. By far the simplest way to do this is to download the Qt SDK, install it, start QtCreator and open the HUPnP project file herqq.pro located in the root of the HUPnP package. To build HUPnP from the command-line you need to run:
qmake -recursive herqq.pro
to create the make files. You'll find the herqq.pro
project file under the project's root directory.make
to build HUPnP andmake
install
to install HUPnP. This step is optional and can be omitted if you do not want to install the HUPnP headers and binaries anywhere. See Deployment for further information.The build produces two shared libraries to which you need to link in order to use HUPnP. Currently, static linking is not an option. The created libraries are placed in bin
directory and they are named [lib]HUPnP[-majVer.minVer.patchVer].x
and [lib]QtSolutions_SOAP-2.7.x
, where ".x"
is the platform dependent suffix for shared libraries. In addition, your compiler must be aware of the HUPnP includes, which can be found in the include
directory. It is very important that you do not directly include anything that is not found in the include
directory. In any case, once your compiler finds the HUPnP includes and your linker finds the HUPnP shared library, you are good to go.
Before starting to use HUPnP, there are a few things you have to know.
HUPnP follows similar include pattern to that of Qt. When you want to use a a class in HUPnP, you have to use
#include <HClassName>
where HClassName
matches the name of the class you wish to use exactly.
Some of the key classes in HUPnP are always instantiated by HUPnP and the instances are always destroyed by HUPnP. You should never delete these. The API documentation of HUPnP is clear about object ownership and these classes are identified in documentation.
HUpnp introduce a number of types, functions, enums and type definitions under the root namespace Herqq
. For instance, all the HUPnP core types can be found under the namespace Herqq::Upnp.
In several occasions, you do not need to include the full HUPnP type definitions for your code to work. More specifically, if the compiler doesn't need to see the layout of a HUPnP type to compile your code, you should only forward-declare such HUPnP types. In that case, you can include the HUpnp
file, which provides forward-declarations to every public HUPnP type and function.
In many situations it is useful to see some log output to have some idea what is going on under the hood, especially when something appears to be malfunctioning. You can enable logging in HUPnP by calling the function Herqq::Upnp::SetLoggingLevel() with a desired level argument. Include HUpnp
to use the Herqq::Upnp::SetLoggingLevel().
You can run make
install
after compiling the project to copy the public headers and created dynamic libraries into hupnp/deploy
folder. More specifically, hupnp/deploy/include
will contain all the public headers and hupnp/deploy/lib/
will contain the dynamic libraries. Alternatively, you can run qmake -recursive "PREFIX = /usr"
before running make
install
to install the headers and binaries under the /usr/include
and /usr/lib
respectively. This may be useful to you in case you do not want to include the full HUPnP source tree with your software. You can run make
uninstall
to remove HUPnP from the selected location.
Until the first stable release (1.0) is made, HUPnP follows a versioning practise where the major component is always zero, the minor component is incremented whenever an API or ABI breaking change is introduced and the patch component is increment upon each update that preserves the API and ABI.
By including HUpnpInfo
, you can call hupnpCoreVersion() to query the exact version of a HUPnP Core library at runtime. At compile-time you can use the macros HUPNP_CORE_MAJOR_VERSION, HUPNP_CORE_MINOR_VERSION, HUPNP_CORE_PATCH_VERSION and HUPNP_CORE_VERSION for checking the version of the API.
Often the best explanation is demonstration. So without further ado, the following links should get you started.
For more detailed information, you can check
From there, the API reference is the way to go.