# Herqq UPnP (HUPnP) Reference Documentation

## 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 client, 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.

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 `HUPnP.x` and `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/bin/` will contain the dynamic libraries. This may be useful to you in case you do not want to include the full HUPnP source tree with your software.

## Getting Started

Often the best explanation is demonstration. So without further ado, the following links should get you started.

- Tutorial for Building a UPnP Device shows how to build your own UPnP device using HUPnP.
- The API documentation of Herqq::Upnp::HControlPoint shows how to discover and use UPnP devices on the network.
- The API documentation of Herqq::Upnp::HDeviceHost shows how to host a Herqq::Upnp::HDevice. This is how you setup a UPnP device to be found and used by UPnP control points.

For more detailed information, you can check

- Device Model for the details of the HUPnP device model and
- Device Hosting for the details of hosting a device.

From there, the API reference is the way to go.