Overview

When creating the new library, the goal was to keep the API intact, as much as feasible.

The main modifications with consequences:

  • The IXML XML DOM package is not supplied or used any more. This has consequences in several places.

  • The asynchronous interface has been removed.

The suppression of libixml has forced changes where IXML elements were present in the interfaces (e.g. DOM trees). These elements have been replaced with C++ data elements, or XML text.

The IXML removal is of course an issue if your program relies on it a lot. In many cases however, IXML is mostly used by the client programs to create the arguments for the libupnp calls which have IXML DOM objects as parameters. The modified calls in npupnp will actually simplify the code in most cases.

The following lists the main API changes.

struct Upnp_Action_Request

struct Upnp_Action_Request (or its equivalent in libupnp 1.8) is used in the device interface to communicate an action request to the client code and retrieve the result. In libupnp, this structure has two IXML DOM tree members to transport the request and the response arguments.

The IXML_Document fields (ActionRequest, ActionResult) are replaced with STL vectors of pairs of strings (name/values). Additionally, the original XML string describing the action is supplied as input (in case there is additional information in it, besides the argument/value pairs), and the response can be supplied as an XML string.

This affects the device library callback when the event type is UPNP_CONTROL_ACTION_REQUEST.

struct Upnp_Event

The IXML_Document ChangedVariables field has been replaced with an STL std::map of the changed values, indexed by variable name.

This affects the control point library callback when the event type is UPNP_EVENT_RECEIVED.

struct File_Info

The libupnp struct File_Info has a dynamically allocated ixml DOMString member for the content type value. In libupnp, this is replaced by an std::string.

libupnp has had a variety of ways for the client to set HTTP headers in the struct File_Info, so that the libupnp WEB server sets them in the HTTP response. The Extra_Headers feature has been replaced by two STL maps:

  • request_headers contains the HTTP headers received with the request.

  • response_headers allow the application to set specific headers to be sent back to the Control Point.

UpnpSendAction()

The Action and Response arguments have been changed from IXML DOM trees to STL vectors of pairs of strings.

UpnpAcceptSubscriptionEx()

This used DOM tree objects to pass the initial set of variable values. The call has been replaced with UpnpAcceptSubscriptionXML(), which uses an XML propertyset std::string. The UpnpAcceptSubscription() call, which uses char** arrays for the names and values is still available.

UpnpNotifyEx()

Same change for the UpnpNotifyEx() → UpnpNotifyXML() calls which are used to dispatch state change events.

UpnpDownloadUrlItem()

This now uses std::string instead of dynamically allocated buffers.

The UpnpDownloadXmlDoc() which downloaded an XML document then parsed it into an IXML DOM tree does not exist any more.