Tizen Native API  3.0

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]stateThe state of found service
[in]ssdp_serviceThe SSDP remote service handle
[in]user_dataThe 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]resultThe result of registration
[in]ssdp_serviceThe SSDP local service handle
[in]user_dataThe 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

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

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]targetThe SSDP local service's target. It may be a device type or a service type specified in UPnP forum (http://upnp.org)
[out]local_serviceThe SSDP local service handle
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot 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_NONESuccessful
SSDP_ERROR_NOT_SUPPORTEDNot supported

Deregisters the SSDP local service.

Since :
3.0
Remarks:
You must pass only local_service created using ssdp_create_local_service().
Parameters:
[in]local_serviceThe SSDP local service handle
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_NOT_SUPPORTEDNot supported

Destroys the SSDP local service handle.

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

Since :
3.0
Parameters:
[in]local_serviceThe SSDP local service handle
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_NOT_SUPPORTEDNot 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_NONESuccessful
SSDP_ERROR_OPERATION_FAILEDOperation failed
SSDP_ERROR_NOT_SUPPORTEDNot 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_serviceThe SSDP local service handle
[in]registered_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OPERATION_FAILEDOperation failed
SSDP_ERROR_NOT_SUPPORTEDNot supported
SSDP_ERROR_SERVICE_ALREADY_REGISTEREDService already registered
SSDP_ERROR_PERMISSION_DENIEDPermission 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]serviceThe SSDP service handle
[out]targetThe target of SSDP service
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot 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]serviceThe SSDP service handle
[out]urlThe URL of SSDP service
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot 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]serviceThe SSDP service handle
[out]usnThe USN of SSDP service
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot 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_serviceThe SSDP local service handle
[in]urlThe URL of SSDP local service
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot 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_serviceThe SSDP local service handle
[in]usnThe USN of SSDP local service
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot 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
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
Parameters:
[in]targetThe target to browse
[out]ssdp_browserThe SSDP browser handle
[in]found_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_OPERATION_FAILEDOperation failed
SSDP_ERROR_OUT_OF_MEMORYOut of memory
SSDP_ERROR_NOT_SUPPORTEDNot supported
SSDP_ERROR_PERMISSION_DENIEDPermission Denied

Stops browsing the SSDP remote service.

Since :
3.0
Parameters:
[in]ssdp_browserThe SSDP browser handle
Returns:
0 on success, otherwise negative error value
Return values:
SSDP_ERROR_NONESuccessful
SSDP_ERROR_NOT_INITIALIZEDNot initialized
SSDP_ERROR_SERVICE_NOT_FOUNDService not found
SSDP_ERROR_INVALID_PARAMETERInvalid parameter
SSDP_ERROR_NOT_SUPPORTEDNot supported