Items to get a network address for UPnP devices and control points. More...

PUPNP_Api int	UpnpInit2 (const char *IfName, unsigned short DestPort)
	Initializes the Linux SDK for UPnP Devices.

PUPNP_Api int	UpnpFinish (void)
	Terminates the Linux SDK for UPnP Devices.

PUPNP_Api in_port_t	UpnpGetServerPort (void)
	Returns the internal server IPv4 UPnP listening port.

PUPNP_Api unsigned short	UpnpGetServerPort6 (void)
	Returns the internal server IPv6 link-local (LLA) UPnP listening port.

PUPNP_Api unsigned short	UpnpGetServerUlaGuaPort6 (void)
	Returns the internal server IPv6 ULA or GUA UPnP listening port.

PUPNP_Api char *	UpnpGetServerIpAddress (void)
	Returns the local IPv4 listening ip address.

PUPNP_Api char *	UpnpGetServerIp6Address (void)
	Returns the IPv6 link-local listening ip address.

PUPNP_Api char *	UpnpGetServerUlaGuaIp6Address (void)
	Returns the IPv6 unique-local or globally-unique listening ip address.

PUPNP_Api int	UpnpRegisterRootDevice (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle *const Hnd)
	Registers one root- or logical-device object with the UPnP Library to get a handle for it.

PUPNP_Api int	UpnpRegisterRootDevice2 (const Upnp_DescType descriptionType, const char const description_const, const size_t bufferLen, const int config_baseURL, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle *const Hnd)
	Registers one root- or logical-device object with the UPnP Library with additional description and get a handle for it.

PUPNP_Api int	UpnpRegisterRootDevice3 (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle *const Hnd, const int AddressFamily)
	Registers one UPnP device object for a specific address family with the UPnP library and get a handle for it.

PUPNP_Api int	UpnpRegisterRootDevice4 (const char const DescUrl, const Upnp_FunPtr Fun, const void const Cookie, UpnpDevice_Handle const Hnd, const int AddressFamily, const char const LowerDescUrl)
	Same as UpnpRegisterRootDevice3() with additional argument to specify a description URL.

PUPNP_Api int	UpnpUnRegisterRootDevice (UpnpDevice_Handle Hnd)
	Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4.

PUPNP_Api int	UpnpUnRegisterRootDeviceLowPower (UpnpDevice_Handle Hnd, int PowerState, int SleepPeriod, int RegistrationState)
	Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4 for Low Power.

PUPNP_Api int	UpnpRegisterClient (Upnp_FunPtr Fun, const void Cookie, UpnpClient_Handle Hnd)
	Registers a control point application with the UPnP Library.

PUPNP_Api int	UpnpUnRegisterClient (UpnpClient_Handle Hnd)
	Unregisters a control point application, unsubscribing all active subscriptions.

PUPNP_Api int	UpnpSetContentLength (UpnpClient_Handle Hnd, size_t contentLength)
	Sets the content-length that the SDK will process on an incoming SOAP requests or responses.

PUPNP_Api int	UpnpSetMaxContentLength (size_t contentLength)
	Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.

Detailed Description

Items to get a network address for UPnP devices and control points.

Addressing is Step 0 of UPnP networking. Through addressing, devices and control points get a network address. Addressing enables discovery (Step 1) where control points find interesting device(s), description (Step 2) where control points learn about device capabilities, control (Step 3) where a control point sends commands to device(s), eventing (Step 4) where control points listen to state changes in device(s), and presentation (Step 5) where control points display a user interface for device(s).

Function Documentation

◆ UpnpInit2()

PUPNP_Api int UpnpInit2	(	const char *	IfName,
		unsigned short	DestPort
	)

Initializes the Linux SDK for UPnP Devices.

This function must be called before any other API function can be called. It should be called only once. Subsequent calls to this API return a UPNP_E_INIT error code.

Optionally, the application can specify an interface name (in the case of a multi-homed configuration) and a port number to use for all UPnP operations. Since a port number can be used only by one process, multiple processes using the SDK must specify different port numbers.

If unspecified, the SDK will use the first suitable interface and an arbitrary port.

This call is synchronous.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to initialize the SDK.
UPNP_E_INIT: The SDK is already initialized.
UPNP_E_INIT_FAILED: The SDK initialization failed for an unknown reason.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_LISTEN: An error occurred listening to a socket.
UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
UPNP_E_INTERNAL_ERROR: An internal error ocurred.
UPNP_E_INVALID_INTERFACE: IfName is invalid or does not have a valid IPv4 or IPv6 addresss configured.

Parameters

[in]	IfName	Argument to select the local interface to connect to the network, that can be: nullptr to use best choise from the operating system for an ip address of a local network adapter. Local network adapter name, e.g. "eth0", "xl0", "Local Area Connection". Local network adapter index number as string, e.g. "2". Ip address of a local network adapter. Link local addresses are only accepted with scope id to be unique, e.g. "[fe80::1%eth0]", or "[fe80::1%2]". A loopback address, e.g. "[::1]", or any of "127.0.0.0/8", most used "127.0.0.1". String "loopback" (all lower case) to use the best one of loopback addresses, e.g. "[::1]", or "127.0.0.1". This is useful when coding ip-version independent.
[in]	DestPort	Local Port to listen for incoming connections. 0 will pick an arbitrary free port.

Definition at line 594 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpFinish()

PUPNP_Api int UpnpFinish ( void )

Terminates the Linux SDK for UPnP Devices.

Checks for pending jobs and threads
Unregisters either the client or device
Shuts down the Timer Thread
Stops the Mini Server
Uninitializes the Thread Pool
For Win32 cleans up Winsock Interface
Cleans up mutex objects

This function must be the last API function called. It should be called only once. Subsequent calls to this API return a UPNP_E_FINISH error code.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or it is not initialized.

Definition at line 684 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpGetServerPort()

PUPNP_Api in_port_t UpnpGetServerPort ( void )

Returns the internal server IPv4 UPnP listening port.

If '0' is used as the port number in UpnpInit2(), then this function can be used to retrieve the actual port allocated to the SDK.

Returns

On success: The port on which an internal server is listening for IPv4 UPnP related requests.
On error: 0 is returned if UpnpInit2() has not succeeded.

Definition at line 756 of file upnpapi.cpp.

◆ UpnpGetServerPort6()

PUPNP_Api unsigned short UpnpGetServerPort6 ( void )

Returns the internal server IPv6 link-local (LLA) UPnP listening port.

If '0' is used as the port number in UpnpInit2(), then this function can be used to retrieve the actual port allocated to the SDK.

Returns

On success: The port on which an internal server is listening for IPv6 link-local (LLA) UPnP related requests.
On error: 0 is returned if UpnpInit2() has not succeeded.

Definition at line 763 of file upnpapi.cpp.

◆ UpnpGetServerUlaGuaPort6()

PUPNP_Api unsigned short UpnpGetServerUlaGuaPort6 ( void )

Returns the internal server IPv6 ULA or GUA UPnP listening port.

If '0' is used as the port number in UpnpInit2(), then this function can be used to retrieve the actual port allocated to the SDK.

Returns

On success: The port on which an internal server is listening for IPv6 ULA or GUA UPnP related requests.
On error: 0 is returned if UpnpInit2() has not succeeded.

Definition at line 774 of file upnpapi.cpp.

◆ UpnpGetServerIpAddress()

PUPNP_Api char * UpnpGetServerIpAddress ( void )

Returns the local IPv4 listening ip address.

If nullptr is used as the interface in UpnpInit2(), then this function can be used to retrieve the actual interface address on which device is running.

Returns

On success: The IPv4 address on which an internal server is listening for UPnP related requests.
On error: nullptr is returned if UpnpInit2() has not succeeded.

Definition at line 785 of file upnpapi.cpp.

◆ UpnpGetServerIp6Address()

PUPNP_Api char * UpnpGetServerIp6Address ( void )

Returns the IPv6 link-local listening ip address.

If nullptr is used as the interface in UpnpInit2(), then this function can be used to retrieve the actual interface address on which device is running.

Returns

On success: The IPv6 link-local address (LLA) on which an internal server is listening for UPnP related requests.
On error: nullptr is returned if UpnpInit2() has not succeeded.

Definition at line 792 of file upnpapi.cpp.

◆ UpnpGetServerUlaGuaIp6Address()

PUPNP_Api char * UpnpGetServerUlaGuaIp6Address ( void )

Returns the IPv6 unique-local or globally-unique listening ip address.

If nullptr is used as the interface in UpnpInit2(), then this function can be used to retrieve the actual interface address on which device is running.

Returns

On success: The IPv6 unique-local or globally-unique address (ULA or GUA) on which an internal server is listening for UPnP related requests.
On error: nullptr is returned if UpnpInit2() has not succeeded.

Definition at line 803 of file upnpapi.cpp.

◆ UpnpRegisterRootDevice()

PUPNP_Api int UpnpRegisterRootDevice	(	const char *const	DescUrl,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd
	)

Registers one root- or logical-device object with the UPnP Library to get a handle for it.

A root- or logical-device object cannot make any other API calls until it registers using this function. To register a control point see UpnpRegisterClient() to get a control point handle to perform control point functionality.

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns. A registered root device needs to be unregistered with UpnpUnRegisterRootDevice() after using.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_DESC: The description document was not a valid device description.
UPNP_E_INVALID_URL: The URL for the description document is not valid.
UPNP_E_INVALID_PARAM: Either Callback or Hnd is not a valid pointer or DescURL is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.

Parameters

[in]	DescUrl	Pointer to a string containing the description URL for this root device instance.
[in]	Fun	Pointer to the callback function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new device handle.

Definition at line 866 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpRegisterRootDevice2()

PUPNP_Api int UpnpRegisterRootDevice2	(	const Upnp_DescType	descriptionType,
		const char *const	description_const,
		const size_t	bufferLen,
		const int	config_baseURL,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd
	)

Registers one root- or logical-device object with the UPnP Library with additional description and get a handle for it.

Similar to UpnpRegisterRootDevice(), except that it also allows the description document to be specified as a file or a memory buffer. The description can also be configured to have the correct IP and port address.

For the configuration to be functional, the internal web server MUST be present. In addition, the web server MUST be activated (using UpnpSetWebServerRootDir()) before calling this function. The only condition where the web server can be absent is if the description document is specified as a URL and no configuration is required (i.e. config_baseURL = 0.)

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns. A registered root device needs to be unregistered with UpnpUnRegisterRootDevice() after using.

Examples of using the valid three different types of description documents:

1) Description specified as a URL:
      descriptionType == UPNPREG_URL_DESC
      description is the URL
      bufferLen = 0 (ignored)
2) Description specified as a file:
      descriptionType == UPNPREG_FILENAME_DESC
      description is a filename
      bufferLen = 0 (ignored)
3) Description specified as a memory buffer:
      descriptionType == UPNPREG_BUF_DESC
      description is pointer to a memory buffer
      bufferLen == length of memory buffer

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_DESC: The description document is not a valid device description.
UPNP_E_INVALID_PARAM: Either callback Fun or Hnd is not a valid pointer or description_const is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.
UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the internal buffer.
UPNP_E_FILE_NOT_FOUND: The description file could not be found.
UPNP_E_FILE_READ_ERROR: An error occurred reading the description file.
UPNP_E_INVALID_URL: The URL to the description document is invalid.
UPNP_E_EXT_NOT_XML: The URL to the description document or file should have a .xml extension.
UPNP_E_NO_WEB_SERVER: The internal web server has been compiled out; the SDK cannot configure itself from the description document.

Parameters

[in]	descriptionType	The type of the description document.
[in]	description_const	Treated as a URL, file name or memory buffer depending on description type.
[in]	bufferLen	The length of memory buffer if passing a description in a buffer, otherwise it is ignored.
[in]	config_baseURL	If nonzero, `URLBase` of description document is configured and the description is served using the internal web server.
[in]	Fun	Pointer to the callback function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new device handle.

Definition at line 1020 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpRegisterRootDevice3()

PUPNP_Api int UpnpRegisterRootDevice3	(	const char *const	DescUrl,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd,
		const int	AddressFamily
	)

Registers one UPnP device object for a specific address family with the UPnP library and get a handle for it.

A UPnP device object cannot make any other API calls until it registers using this function. To register a control point see UpnpRegisterClient() to get a control point handle to perform control point functionality.

This is a synchronous call and does not generate any callbacks. Callbacks can occur as soon as this function returns. A registered root device needs to be unregistered with UpnpUnRegisterRootDevice() after using.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_DESC: The description document was not a valid device description.
UPNP_E_INVALID_URL: The URL for the description document is not valid.
UPNP_E_INVALID_PARAM: Either callback Fun or Hnd is not a valid pointer or DescURL is a nullptr.
UPNP_E_NETWORK_ERROR: A network error occurred.
UPNP_E_SOCKET_WRITE: An error or timeout occurred writing to a socket.
UPNP_E_SOCKET_READ: An error or timeout occurred reading from a socket.
UPNP_E_SOCKET_BIND: An error occurred binding a socket.
UPNP_E_SOCKET_CONNECT: An error occurred connecting the socket.
UPNP_E_OUTOF_SOCKET: Too many sockets are currently allocated.
UPNP_E_OUTOF_MEMORY: There are insufficient resources to register this root device.

Parameters

[in]	DescUrl	Pointer to a string containing the description URL fo this root device instance.
[in]	Fun	Pointer to the callback function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new device handle.
[in]	AddressFamily	Address family of this device. Can be AF_INET for an IPv4 device, or AF_INET6 for an IPv6 device. Defaults to AF_INET.

Definition at line 1311 of file upnpapi.cpp.

◆ UpnpRegisterRootDevice4()

PUPNP_Api int UpnpRegisterRootDevice4	(	const char *const	DescUrl,
		const Upnp_FunPtr	Fun,
		const void *const	Cookie,
		UpnpDevice_Handle *const	Hnd,
		const int	AddressFamily,
		const char *const	LowerDescUrl
	)

Same as UpnpRegisterRootDevice3() with additional argument to specify a description URL.

This function can be used to specify a dedicated description URL LowerDescUrl to be returned for legacy control points.

Parameters

[in]	DescUrl	.
[in]	Fun	.
[in]	Cookie	.
[out]	Hnd	.
[in]	AddressFamily	.
[in]	LowerDescUrl	This is a pointer to a string containing the description URL to be returned for legacy control points for this root device instance.

Definition at line 1320 of file upnpapi.cpp.

◆ UpnpUnRegisterRootDevice()

PUPNP_Api int UpnpUnRegisterRootDevice ( UpnpDevice_Handle Hnd )

Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4.

After this call, the UpnpDevice_Handle is no longer valid. For all advertisements that have not yet expired, the SDK sends a device unavailable message automatically.

This is a synchronous call and generates no callbacks. Once this call returns, the SDK will no longer generate callbacks to the application.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

[in] Hnd The handle of the root device instance to unregister.

Definition at line 1331 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpUnRegisterRootDeviceLowPower()

PUPNP_Api int UpnpUnRegisterRootDeviceLowPower	(	UpnpDevice_Handle	Hnd,
		int	PowerState,
		int	SleepPeriod,
		int	RegistrationState
	)

Unregisters a root device registered with UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpRegisterRootDevice4 for Low Power.

After this call, the UpnpDevice_Handle is no longer valid. For all advertisements that have not yet expired, the SDK sends a device unavailable message automatically.

This is a synchronous call and generates no callbacks. Once this call returns, the SDK will no longer generate callbacks to the application.

This function allow a device to specify the SSDP extensions defined by UPnP Low Power.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.

Parameters

[in]	Hnd	The handle of the root device instance to unregister.
	PowerState	PowerState as defined by UPnP Low Power.
	SleepPeriod	SleepPeriod as defined by UPnP Low Power.
	RegistrationState	RegistrationState as defined by UPnP Low Power.

Definition at line 1337 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpRegisterClient()

PUPNP_Api int UpnpRegisterClient	(	Upnp_FunPtr	Fun,
		const void *	Cookie,
		UpnpClient_Handle *	Hnd
	)

Registers a control point application with the UPnP Library.

A control point application cannot make any other API calls until it registers using this function.

UpnpRegisterClient() is a synchronous call and generates no callbacks. Callbacks can occur as soon as this function returns.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_PARAM: Either callback Fun or Hnd is not a valid pointer.
UPNP_E_OUTOF_MEMORY: Insufficient resources exist to register this control point.

Parameters

[in]	Fun	Pointer to a function for receiving asynchronous events.
[in]	Cookie	Pointer to user data returned with the callback function when invoked.
[out]	Hnd	Pointer to a variable to store the new control point handle.

Definition at line 1409 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpUnRegisterClient()

PUPNP_Api int UpnpUnRegisterClient ( UpnpClient_Handle Hnd )

Unregisters a control point application, unsubscribing all active subscriptions.

This function unregisters a client registered with UpnpRegisterClient(). After this call, the UpnpClient_Handle is no longer valid. The UPnP Library generates no more callbacks after this function returns.

UpnpUnRegisterClient() is a synchronous call and generates no callbacks.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.
UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.

Parameters

[in] Hnd The handle of the control point instance to unregister.

Definition at line 1458 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UpnpSetContentLength()

PUPNP_Api int UpnpSetContentLength	(	UpnpClient_Handle	Hnd,
		size_t	contentLength
	)

Sets the content-length that the SDK will process on an incoming SOAP requests or responses.

Deprecated:: Warning: The Handle argument provided here is not used, so the effect of this function is global to the SDK (= same as UpnpSetMaxContentLength()). Use UpnpSetMaxContentLength() instead.

Parameters

[in]	Hnd	The handle of the device instance for which the coincoming content length needs to be set.
[in]	contentLength	Permissible content length

Definition at line 3666 of file upnpapi.cpp.

Here is the call graph for this function:

◆ UpnpSetMaxContentLength()

PUPNP_Api int UpnpSetMaxContentLength ( size_t contentLength )

Sets the maximum content-length that the SDK will process on an incoming SOAP requests or responses.

This API allows devices that have memory constraints to exhibit consistent behaviour if the size of the incoming SOAP message exceeds the memory that device can allocate.

If set to 0 then checking will be disabled.

The default maximum content-length is DEFAULT_SOAP_CONTENT_LENGTH = 16K bytes.

Returns

An integer representing one of the following:

UPNP_E_SUCCESS: The operation completed successfully.
UPNP_E_FINISH: The SDK is already terminated or is not initialized.

Parameters

[in] contentLength The maximum permissible content length for incoming SOAP actions, in bytes.

Definition at line 3696 of file upnpapi.cpp.

UPnPsdk 0.1 Universal Plug and Play +, Software Development Kit