Herqq

Herqq UPnP (HUPnP) Reference Documentation for Version 1.0

Introduction

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.

Setting Up

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.

Attention:
At the moment, HUPnP uses a modified version of QtSoap version 2.7. This is because the original version 2.7 contains few severe bugs in regard to thread-safety. Until the errors are fixed in the official QtSoap release, the users of HUPnP must use the modified version distributed with 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:

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.

Attention:
You do not need to include the QtSoap includes. HUPnP does not expose the types declared in QtSoap.

Important notes

Before starting to use HUPnP, there are a few things you have to know.

#include

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.

Memory management

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.

The HUpnp include file

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.

Logging

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().

Deployment

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.

Versioning

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.

Getting Started

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.