The SSDP API provides functions for network service discovery using SSDP.

Required Header

#include <ssdp.h>

Overview

SSDP allows your application to create and register a local service. You should deregister and destroy the created local service handle if it is not available. In addition, you can browse services on a network using SSDP API. You should stop browsing if you do not need it anymore.

Related Features

This API is related with the following features:

http://tizen.org/feature/network.service_discovery.ssdp
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions
int	ssdp_initialize (void)
	Initializes SSDP.
int	ssdp_deinitialize (void)
	Deinitializes SSDP.
int	ssdp_create_local_service (const char target, ssdp_service_h local_service)
	Creates a SSDP local service handle.
int	ssdp_destroy_local_service (ssdp_service_h local_service)
	Destroys the SSDP local service handle.
int	ssdp_service_set_usn (ssdp_service_h local_service, const char *usn)
	Sets the USN (Unique Service Name) of SSDP local service. The USN format is specified in UPnP forum (http://upnp.org).
int	ssdp_service_set_url (ssdp_service_h local_service, const char *url)
	Sets the URL (Uniform Resource Locator) for description of SSDP local service. See RFC 3986.
int	ssdp_service_get_target (ssdp_service_h service, char **target)
	Gets the target of SSDP service.
int	ssdp_service_get_usn (ssdp_service_h service, char **usn)
	Gets the USN of SSDP service.
int	ssdp_service_get_url (ssdp_service_h service, char **url)
	Gets the URL of SSDP service.
int	ssdp_register_local_service (ssdp_service_h local_service, ssdp_registered_cb registered_cb, void *user_data)
	Registers the SSDP local service for publishing.
int	ssdp_deregister_local_service (ssdp_service_h local_service)
	Deregisters the SSDP local service.
int	ssdp_start_browsing_service (const char target, ssdp_browser_h ssdp_browser, ssdp_found_cb found_cb, void *user_data)
	Starts browsing the SSDP remote service.
int	ssdp_stop_browsing_service (ssdp_browser_h ssdp_browser)
	Stops browsing the SSDP remote service.
Typedefs
typedef unsigned int	ssdp_service_h
	The SSDP service handle.
typedef unsigned int	ssdp_browser_h
	The SSDP browser handle.
typedef void(*	ssdp_registered_cb )(ssdp_error_e result, ssdp_service_h ssdp_local_service, void *user_data)
	Called when the registration of SSDP service is finished.
typedef void(*	ssdp_found_cb )(ssdp_service_state_e state, ssdp_service_h ssdp_remote_service, void *user_data)
	Called when a service has become available or unavailable.

Typedef Documentation

typedef unsigned int ssdp_browser_h

The SSDP browser handle.

Since :: 3.0

typedef void(* ssdp_found_cb)(ssdp_service_state_e state, ssdp_service_h ssdp_remote_service, void *user_data)

Called when a service has become available or unavailable.

Since :: 3.0

Parameters:

[in]	state	The state of found service
[in]	ssdp_service	The SSDP remote service handle
[in]	user_data	The user data passed from the request function

See also:: ssdp_start_browsing_service()

typedef void(* ssdp_registered_cb)(ssdp_error_e result, ssdp_service_h ssdp_local_service, void *user_data)

Called when the registration of SSDP service is finished.

Since :: 3.0

Parameters:

[in]	result	The result of registration
[in]	ssdp_local_service	The SSDP local service handle
[in]	user_data	The user data passed from the request function

See also:: ssdp_register_local_service()

typedef unsigned int ssdp_service_h

The SSDP service handle.

Since :: 3.0

Enumeration Type Documentation

enum ssdp_error_e

Enumeration for Network Service Discovery SSDP error code.

Since :: 3.0

Enumerator:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_PERMISSION_DENIED	Permission denied
SSDP_ERROR_INVALID_PARAMETER	Invalid function parameter
SSDP_ERROR_NOT_SUPPORTED	Not supported
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_OPERATION_FAILED	Operation failed
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_SERVICE_ALREADY_REGISTERED	Service already registered

enum ssdp_service_state_e

Enumeration for Network Service Discovery SSDP service browse state.

Since :: 3.0

Enumerator:

SSDP_SERVICE_STATE_AVAILABLE	A new service is available
SSDP_SERVICE_STATE_UNAVAILABLE	A service is not available

Function Documentation

int ssdp_create_local_service	(	const char *	target,
		ssdp_service_h *	local_service
	)

Creates a SSDP local service handle.

Since :: 3.0

Remarks:: You must release local_service using ssdp_destroy_local_service().

Parameters:

[in]	target	The SSDP local service's target. It may be a device type or a service type specified in UPnP forum (http://upnp.org)
[out]	local_service	The SSDP local service handle

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported

See also:: ssdp_destroy_local_service()

Precondition:: This API needs ssdp_initialize() before use.

int ssdp_deinitialize ( void )

Deinitializes SSDP.

Since :: 3.0

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_deregister_local_service ( ssdp_service_h local_service )

Deregisters the SSDP local service.

Since :: 3.0

Remarks:: You must pass only local_service created using ssdp_create_local_service().

Parameters:

[in] local_service The SSDP local service handle

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_destroy_local_service ( ssdp_service_h local_service )

Destroys the SSDP local service handle.

You must call ssdp_deregister_local_service() before destroying the local service.

Since :: 3.0

Parameters:

[in] local_service The SSDP local service handle

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_NOT_SUPPORTED	Not supported

See also:: ssdp_create_local_service()

int ssdp_initialize ( void )

Initializes SSDP.

Since :: 3.0

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_OPERATION_FAILED	Operation failed
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_register_local_service	(	ssdp_service_h	local_service,
		ssdp_registered_cb	registered_cb,
		void *	user_data
	)

Registers the SSDP local service for publishing.

You must set a USN and a URL of the local service before ssdp_register_local_service() is called.

Since :: 3.0

Remarks:: You must pass only local_service created using ssdp_create_local_service().

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Parameters:

[in]	local_service	The SSDP local service handle
[in]	registered_cb	The callback function to be called
[in]	user_data	The user data passed to the callback function

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OPERATION_FAILED	Operation failed
SSDP_ERROR_NOT_SUPPORTED	Not supported
SSDP_ERROR_SERVICE_ALREADY_REGISTERED	Service already registered
SSDP_ERROR_PERMISSION_DENIED	Permission Denied

Precondition:: This API needs ssdp_service_set_usn() and ssdp_service_set_url() before use.

int ssdp_service_get_target	(	ssdp_service_h	service,
		char **	target
	)

Gets the target of SSDP service.

Since :: 3.0

Remarks:: You must release target using free().

Parameters:

[in]	service	The SSDP service handle
[out]	target	The target of SSDP service

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_service_get_url	(	ssdp_service_h	service,
		char **	url
	)

Gets the URL of SSDP service.

Since :: 3.0

Remarks:: You must release url using free().

Parameters:

[in]	service	The SSDP service handle
[out]	url	The URL of SSDP service

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_service_get_usn	(	ssdp_service_h	service,
		char **	usn
	)

Gets the USN of SSDP service.

Since :: 3.0

Remarks:: You must release usn using free().

Parameters:

[in]	service	The SSDP service handle
[out]	usn	The USN of SSDP service

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_service_set_url	(	ssdp_service_h	local_service,
		const char *	url
	)

Sets the URL (Uniform Resource Locator) for description of SSDP local service. See RFC 3986.

Since :: 3.0

Remarks:: You must pass only unregistered local_service created using ssdp_create_local_service(). If local_service is already registered, you cannot set url.

Parameters:

[in]	local_service	The SSDP local service handle
[in]	url	The URL of SSDP local service

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_service_set_usn	(	ssdp_service_h	local_service,
		const char *	usn
	)

Sets the USN (Unique Service Name) of SSDP local service. The USN format is specified in UPnP forum (http://upnp.org).

Since :: 3.0

Remarks:: You must pass only unregistered local_service created using ssdp_create_local_service(). If local_service is already registered, you cannot set usn.

Parameters:

[in]	local_service	The SSDP local service handle
[in]	usn	The USN of SSDP local service

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported

int ssdp_start_browsing_service	(	const char *	target,
		ssdp_browser_h *	ssdp_browser,
		ssdp_found_cb	found_cb,
		void *	user_data
	)

Starts browsing the SSDP remote service.

ssdp_start_browsing_service() keeps browsing services until calling ssdp_stop_browsing_service().

Since :: 3.0

Remarks:: The ssdp_browser should be released using ssdp_stop_browsing_service().

Privilege Level:: public

Privilege:: http://tizen.org/privilege/internet

Parameters:

[in]	target	The target to browse
[out]	ssdp_browser	The SSDP browser handle
[in]	found_cb	The callback function to be called
[in]	user_data	The user data passed to the callback function

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_OPERATION_FAILED	Operation failed
SSDP_ERROR_OUT_OF_MEMORY	Out of memory
SSDP_ERROR_NOT_SUPPORTED	Not supported
SSDP_ERROR_PERMISSION_DENIED	Permission Denied

 #include <ssdp.h>
 ...
 static void found_cb(ssdp_service_state_e state, ssdp_service_h remote_service, void *user_data)
 {
    // handle found service
 }
 ...
 ssdp_browser_h browser = NULL;
 int ret = ssdp_start_browsing_service("upnp:rootdevice", &browser, found_cb, NULL);
 ...
 ret = ssdp_stop_browsing_service(browser);

int ssdp_stop_browsing_service ( ssdp_browser_h ssdp_browser )

Stops browsing the SSDP remote service.

Since :: 3.0

Parameters:

[in] ssdp_browser The SSDP browser handle

Returns:: 0 on success, otherwise negative error value

Return values:

SSDP_ERROR_NONE	Successful
SSDP_ERROR_NOT_INITIALIZED	Not initialized
SSDP_ERROR_SERVICE_NOT_FOUND	Service not found
SSDP_ERROR_INVALID_PARAMETER	Invalid parameter
SSDP_ERROR_NOT_SUPPORTED	Not supported

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation