Tizen Native API  5.0
SSDP

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:

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