# API changes after 1.10

This is a list of API changes after libUPnP version 1.10. This page
contains explanation of these changes and what users need to do to migrate.

## Version 1.12

### list.h header changed

The `list.h` header was replace by a different version, now all symbols
are properly namespaced with a Upnp prefix. This header was never intended
to be used directly by libUPnP users, so not many should be affected.

As a side-effect of the header change, libUPnP no longer defines the
`true` and `bool` macros. Users that need those should define their
own or use `<stdbool.h>`. Additionally the following macros are no
longer defined:

- `prefetch`
- `container_of`
- `READ_ONCE`
- `WRITE_ONCE`

And various list-specific macros are gone.
For details see the discussion at the Github PRs [#128][gh-pr128] and [#129][gh-pr129].

[gh-pr128]: https://github.com/mrjimenez/pupnp/pull/128
[gh-pr129]: https://github.com/mrjimenez/pupnp/pull/129

### Removal of TRUE, FALSE macros and BOOL type

Previously `ixml.h` used to define `TRUE` and `FALSE` and declared a `BOOL` typedef.
Those macros and the typedef were removed in 10.12 in favor of just using `int` and
`1` and `0` for true and false.

If your code relied on these being available, the cleanets fix would be to use `<stdbool.h>`
instead. Alternatively if you can't use that or it would require too many changes to your
existing source code, you can define the macros and typedef in your headers:

```c
#ifndef __OBJC__ 
    typedef int BOOL;
#else
    /* When using Objective-C, include objc.h which defines BOOL */
    #include <objc/objc.h>
#endif

#define TRUE 1
#define FALSE 0
```

## Version 1.14

### UpnpInit() has been dropped

UpnpInit() has long been deprecated and has now been dropped. Please use UpnpInit2().

### Some include files have been renamed

When the template code was removed, a few files were renamed for consistency. The function calls remain the same, so the only necessary changes are in the include file names. The affected files are:

Original Name | New Name
--------------|---------
upnp/inc/ActionComplete.h | upnp/inc/UpnpActionComplete.h
upnp/inc/ActionRequest.h | upnp/inc/UpnpActionRequest.h
upnp/inc/Discovery.h | upnp/inc/UpnpDiscovery.h
upnp/inc/Event.h | upnp/inc/UpnpEvent.h
upnp/inc/EventSubscribe.h | upnp/inc/UpnpEventSubscribe.h
upnp/inc/ExtraHeaders.h | upnp/inc/UpnpExtraHeaders.h
upnp/inc/FileInfo.h | upnp/inc/UpnpFileInfo.h
upnp/inc/StateVarComplete.h | upnp/inc/UpnpStateVarComplete.h
upnp/inc/StateVarRequest.h | upnp/inc/UpnpStateVarRequest.h
upnp/inc/SubscriptionRequest.h | upnp/inc/UpnpSubscriptionRequest.h

## Version 1.18

### `Upnp_FunPtr` callback: `Event` parameter is no longer `const`

The `Event` parameter in the `Upnp_FunPtr` typedef has changed from
`const void *` to `void *`:

```c
/* 1.14.x (and earlier) */
typedef int (*Upnp_FunPtr)(Upnp_EventType EventType, const void *Event, void *Cookie);

/* 1.18.x and later */
typedef int (*Upnp_FunPtr)(Upnp_EventType EventType, void *Event, void *Cookie);
```

The `const` qualifier was accidentally introduced in 2010 when the typedef was
moved from `upnp.h` to `Callback.h`. It was semantically incorrect: for
`UPNP_CONTROL_ACTION_REQUEST` and `UPNP_CONTROL_GET_VAR_REQUEST`, the library
passes the Event structure to the callback so that the application can write
its response back into it — making it an in-out parameter, not a read-only one.

**Migration:** remove `const` from the `Event` parameter in your callback
implementations:

```c
/* before */
int my_callback(Upnp_EventType event_type, const void *event, void *cookie)

/* after */
int my_callback(Upnp_EventType event_type, void *event, void *cookie)
```

See [issue #528][gh-issue528] for the full history.

[gh-issue528]: https://github.com/pupnp/pupnp/issues/528
