Step 1: Discovery

Items for control points to find UPnP device(s) with SSDP the Simple Service Discovery Protocol. More...

PUPNP_Api int	UpnpSearchAsync (UpnpClient_Handle Hnd, int Mx, const char *Target_const, const void *Cookie_const)
	Searches for devices matching the given search target.
PUPNP_Api int	UpnpSendAdvertisement (UpnpDevice_Handle Hnd, int Exp)
	Sends out the discovery announcements for all devices and services contained within one root device.
PUPNP_Api int	UpnpSendAdvertisementLowPower (UpnpDevice_Handle Hnd, int Exp, int PowerState, int SleepPeriod, int RegistrationState)
	Sends out the discovery announcements for all devices and services contained within one root device.

Detailed Description

Items for control points to find UPnP device(s) with SSDP the Simple Service Discovery Protocol.

Discovery is Step 1 in UPnP networking. Discovery comes after addressing (Step 0) where devices get a network address. Through discovery, control points find interesting device(s). Discovery enables 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

UpnpSearchAsync()

PUPNP_Api int UpnpSearchAsync	(	UpnpClient_Handle	Hnd,
		int	Mx,
		const char *	Target_const,
		const void *	Cookie_const
	)

Searches for devices matching the given search target.

The function returns immediately and the SDK calls the default callback function, registered during the UpnpRegisterClient() call, for each matching root device, device, or service. The application specifies the search type by the Target parameter.

This function searches for the devices for the provided maximum time. It is an asynchronous function. It schedules a search job and returns. The client is notified about the search results after search timer.

Note that there is no way for the SDK to distinguish which client instance issued a particular search. Therefore, the client can get search callbacks that do not match the original criteria of the search. Also, the application will receive multiple callbacks for each search.

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.
• UPNP_E_INVALID_PARAM: Target is a nullptr.

Parameters

[in]	Hnd	The handle of the client performing the search.
[in]	Mx	The time, in seconds, to wait for responses. If the time is greater than MAX_SEARCH_TIME then the time is set to MAX_SEARCH_TIME. If the time is less than MIN_SEARCH_TIME then the time is set to MIN_SEARCH_TIME.
[in]	Target_const	The search target as defined in the UPnP Device Architecture v1.0 specification.
[in]	Cookie_const	The user data to pass when the callback function is invoked.

Definition at line 1823 of file upnpapi.cpp.

Here is the call graph for this function:

UpnpSendAdvertisement()

PUPNP_Api int UpnpSendAdvertisement	(	UpnpDevice_Handle	Hnd,
		int	Exp
	)

Sends out the discovery announcements for all devices and services contained within one root device.

Each announcement is made with the same expiration time.

This is a synchronous call.

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.
• UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.

Parameters

[in]	Hnd	The device handle for which to send out the announcements.
[in]	Exp	The expiration age, in seconds, of the announcements. If the expiration age is less than 1 then the expiration age is set to DEFAULT_MAXAGE. If the expiration age is less than or equal to AUTO_ADVERTISEMENT_TIME * 2 then the expiration age is set to ( AUTO_ADVERTISEMENT_TIME + 1 ) * 2.

Definition at line 1718 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

UpnpSendAdvertisementLowPower()

PUPNP_Api int UpnpSendAdvertisementLowPower	(	UpnpDevice_Handle	Hnd,
		int	Exp,
		int	PowerState,
		int	SleepPeriod,
		int	RegistrationState
	)

Sends out the discovery announcements for all devices and services contained within one root device.

Each announcement is made with the same expiration time.

This is a synchronous call.

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.
• UPNP_E_OUTOF_MEMORY: There are insufficient resources to send future advertisements.

Parameters

[in]	Hnd	The device handle for which to send out the announcements.
[in]	Exp	The expiration age, in seconds, of the announcements. If the expiration age is less than 1 then the expiration age is set to DEFAULT_MAXAGE. If the expiration age is less than or equal to AUTO_ADVERTISEMENT_TIME * 2 then the expiration age is set to ( AUTO_ADVERTISEMENT_TIME + 1 ) * 2.
[in]	PowerState	PowerState as defined by UPnP Low Power.
[in]	SleepPeriod	SleepPeriod as defined by UPnP Low Power.
[in]	RegistrationState	RegistrationState as defined by UPnP Low Power.

Definition at line 1724 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function: