Tizen Native API
5.5
|
The DNSSD API provides functions for network service discovery using DNSSD.
Required Header
#include <dns-sd.h>
Overview
DNSSD 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 DNSSD 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.dnssd
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 | dnssd_initialize (void) |
Initializes DNSSD. | |
int | dnssd_deinitialize (void) |
Deinitializes DNSSD. | |
int | dnssd_create_local_service (const char *service_type, dnssd_service_h *dnssd_service) |
Creates a DNSSD local service handle. | |
int | dnssd_destroy_local_service (dnssd_service_h dnssd_service) |
Destroys the DNSSD local service handle. | |
int | dnssd_service_set_name (dnssd_service_h local_service, const char *service_name) |
Sets the name of DNSSD local service. | |
int | dnssd_service_set_port (dnssd_service_h local_service, int port) |
Sets the port number of DNSSD local service. | |
int | dnssd_service_add_txt_record (dnssd_service_h local_service, const char *key, unsigned short length, const void *value) |
Adds the TXT record. | |
int | dnssd_service_remove_txt_record (dnssd_service_h local_service, const char *key) |
Removes the TXT record. | |
int | dnssd_service_set_record (dnssd_service_h local_service, unsigned short type, unsigned short length, const void *data) |
Sets/updates the DNS resource record. | |
int | dnssd_service_unset_record (dnssd_service_h local_service, unsigned short type) |
Unsets the DNS resource record. DNS resource record for the given type must be set using dnssd_service_set_record(). | |
int | dnssd_register_local_service (dnssd_service_h local_service, dnssd_registered_cb register_cb, void *user_data) |
Registers the DNSSD local service for publishing. | |
int | dnssd_deregister_local_service (dnssd_service_h local_service) |
Deregisters the DNSSD local service. | |
int | dnssd_start_browsing_service (const char *service_type, dnssd_browser_h *dnssd_service, dnssd_found_cb found_cb, void *user_data) |
Starts browsing the DNSSD remote service. | |
int | dnssd_stop_browsing_service (dnssd_browser_h dnssd_service) |
Stops browsing the DNSSD remote service. | |
int | dnssd_service_get_type (dnssd_service_h dnssd_service, char **service_type) |
Gets the type of DNSSD local/remote service. | |
int | dnssd_service_get_name (dnssd_service_h dnssd_service, char **service_name) |
Gets the name of DNSSD local/remote service. | |
int | dnssd_service_get_ip (dnssd_service_h dnssd_service, char **ip_v4_address, char **ip_v6_address) |
Gets the IP of DNSSD remote service. | |
int | dnssd_service_get_port (dnssd_service_h dnssd_service, int *port) |
Gets the port number of DNSSD local/remote service. | |
int | dnssd_service_get_all_txt_record (dnssd_service_h dnssd_service, unsigned short *length, void **value) |
Gets the TXT record. | |
Typedefs | |
typedef unsigned int | dnssd_service_h |
The DNSSD service handle. | |
typedef unsigned int | dnssd_browser_h |
The DNSSD Browser handle. | |
typedef void(* | dnssd_registered_cb )(dnssd_error_e result, dnssd_service_h local_service, void *user_data) |
Called when the registration of DNSSD service is finished. | |
typedef void(* | dnssd_found_cb )(dnssd_service_state_e service_state, dnssd_service_h remote_service, void *user_data) |
Called when a DNSSD service is found. |
Typedef Documentation
typedef unsigned int dnssd_browser_h |
The DNSSD Browser handle.
- Since :
- 3.0
typedef void(* dnssd_found_cb)(dnssd_service_state_e service_state, dnssd_service_h remote_service, void *user_data) |
Called when a DNSSD service is found.
remote_service is valid only when service_state is DNSSD_SERVICE_STATE_AVAILABLE or DNSSD_SERVICE_STATE_UNAVAILABLE. In case of service_state DNSSD_SERVICE_STATE_UNAVAILABLE, application can only use dnssd_service_get_type() and dnssd_service_get_name(). Other get functions can only be used when service_state is DNSSD_SERVICE_STATE_AVAILABLE.
- Since :
- 3.0
- Parameters:
-
[in] service_state The DNSSD service state of remote service [in] remote_service The DNSSD remote service handle [in] user_data The user data passed from the request function
- See also:
- dnssd_start_browsing_service()
typedef void(* dnssd_registered_cb)(dnssd_error_e result, dnssd_service_h local_service, void *user_data) |
Called when the registration of DNSSD service is finished.
- Since :
- 3.0
- Parameters:
-
[in] result The result of registration.
DNSSD_ERROR_NONE Successful
DNSSD_ERROR_NAME_CONFLICT Name Conflict
DNSSD_ERROR_ALREADY_REGISTERED Already Registered[in] local_service The DNSSD local service handle [in] user_data The user data passed from the request function
- See also:
- dnssd_register_local_service()
typedef unsigned int dnssd_service_h |
The DNSSD service handle.
- Since :
- 3.0
Enumeration Type Documentation
enum dnssd_error_e |
Enumeration for Network Service Discovery DNSSD error code.
- Since :
- 3.0
- Enumerator:
Enumeration for Network Service Discovery DNSSD browse state.
- Since :
- 3.0
- Enumerator:
Function Documentation
int dnssd_create_local_service | ( | const char * | service_type, |
dnssd_service_h * | dnssd_service | ||
) |
Creates a DNSSD local service handle.
- Since :
- 3.0
- Remarks:
- You must release dnssd_service using dnssd_destroy_local_service().
- Parameters:
-
[in] service_type The DNSSD service type. It is expressed as type followed by protocol, separated by a dot(e.g. "_ftp._tcp"). It must begin with an underscore, followed by 1-15 characters which may be letters, digits, or hyphens. The transport protocol must be "_tcp" or "_udp". New service types should be registered at http://www.dns-sd.org/ServiceTypes.html. [out] dnssd_service The DNSSD local handle
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_OUT_OF_MEMORY Out of memory DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- See also:
- dnssd_destroy_local_service()
- Precondition:
- This API needs dnssd_initialize() before use
int dnssd_deinitialize | ( | void | ) |
Deinitializes DNSSD.
- Since :
- 3.0
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_INVALID_OPERATION Invalid Operation
- Precondition:
- DNS-SD service must be initialized by dnssd_initialize().
int dnssd_deregister_local_service | ( | dnssd_service_h | local_service | ) |
Deregisters the DNSSD local service.
- Since :
- 3.0
- Remarks:
- You must pass only local services registered using dnssd_register_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- Precondition:
- This API needs dnssd_register_local_service() before use.
int dnssd_destroy_local_service | ( | dnssd_service_h | dnssd_service | ) |
Destroys the DNSSD local service handle.
Destroying a local service doesn't deregister local service. If local service was registered using dnssd_register_local_service(), then it must be deregistered using dnssd_deregister_local_service() before destroying the local service.
- Since :
- 3.0
- Remarks:
- You must destroy only local services created using dnssd_create_local_service().
- Parameters:
-
[in] dnssd_service The DNSSD local service handle
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_initialize | ( | void | ) |
Initializes DNSSD.
- Since :
- 3.0
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_NOT_SUPPORTED Not Supported
int dnssd_register_local_service | ( | dnssd_service_h | local_service, |
dnssd_registered_cb | register_cb, | ||
void * | user_data | ||
) |
Registers the DNSSD local service for publishing.
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/internet
- Parameters:
-
[in] local_service The DNSSD local service handle [in] register_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:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_OPERATION_FAILED Operation failed DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized DNSSD_ERROR_PERMISSION_DENIED Permission Denied
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_service_add_txt_record | ( | dnssd_service_h | local_service, |
const char * | key, | ||
unsigned short | length, | ||
const void * | value | ||
) |
Adds the TXT record.
TXT record gives additional information about the service. Some services discovered via dnssd_start_browsing_service() may need more than just IP address and port number to completely identify the service instance. For example, A web server typically has multiple pages, each identified by its own URL. So additional data is stored in a TXT record. Check Section 6 of http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt for details. TXT record of known service types can be found at http://www.dns-sd.org/ServiceTypes.html. TXT record is stored in a structured form using key/value pairs.
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle [in] key The key of the TXT record. A null-terminated string which only contains printable ASCII values (0x20-0x7E), excluding '=' (0x3D). Keys should be 9 characters or fewer excluding NULL. Keys are case insensitive. Keys for known service types can be found at http://www.dns-sd.org/ServiceTypes.html. For details, see section 6.4 of http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt. [in] length The length of the value of the TXT record in bytes. The total size of a typical DNS-SD TXT record is intended to be small (upto 200 bytes). For details, see section 6.2 of http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt [in] value The value of the TXT record. It can be any binary value. For value that represents textual data, UTF-8 is STRONGLY recommended. For value that represents textual data, value_length should NOT include the terminating null (if any) at the end of the string. If NULL, then "key" will be added with no value. If non-NULL but value_length is zero, then "key=" will be added with empty value. For details see section 6.5 of http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_ALREADY_REGISTERED Already Registered DNSSD_ERROR_NOT_INITIALIZED Not Initialized DNSSD_ERROR_OUT_OF_MEMORY Out of Memory
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_service_get_all_txt_record | ( | dnssd_service_h | dnssd_service, |
unsigned short * | length, | ||
void ** | value | ||
) |
Gets the TXT record.
TXT record gives additional information about the service. Some services discovered via dnssd_start_browsing_service() may need more than just IP address and port number to completely identify the service instance. For example, a web server typically has multiple pages, each identified by its own URL. So additional data is stored in a TXT record. Check Section 6 of http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt for details. TXT record of known service types can be found at http://www.dns-sd.org/ServiceTypes.html. TXT record is stored in a structured form using key/value pairs.
- Since :
- 3.0
- Remarks:
- You must release value using free().
- Parameters:
-
[in] dnssd_service The DNSSD local/remote service handle [out] length The length of the value of the TXT record in bytes [out] value The value of the TXT record
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_OUT_OF_MEMORY Out of Memory DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized
int dnssd_service_get_ip | ( | dnssd_service_h | dnssd_service, |
char ** | ip_v4_address, | ||
char ** | ip_v6_address | ||
) |
Gets the IP of DNSSD remote service.
- Since :
- 3.0
- Remarks:
- You must release ip_v4_address, ip_v6_address using free().
- Parameters:
-
[in] dnssd_service The DNSSD remote service handle [out] ip_v4_address The IP version 4 address of DNSSD service. If there is no IPv4 Address, then it would contain NULL and should not be freed [out] ip_v6_address The IP version 6 address of DNSSD service. If there is no IPv6 Address, then it would contain NULL and should not be freed
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_OUT_OF_MEMORY Out of Memory DNSSD_ERROR_NOT_INITIALIZED Not Initialized
int dnssd_service_get_name | ( | dnssd_service_h | dnssd_service, |
char ** | service_name | ||
) |
Gets the name of DNSSD local/remote service.
- Since :
- 3.0
- Remarks:
- You must release service_name using free().
- Parameters:
-
[in] dnssd_service The DNSSD local/remote service handle [out] service_name The name of DNSSD service
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_OUT_OF_MEMORY Out of Memory DNSSD_ERROR_NOT_INITIALIZED Not Initialized
int dnssd_service_get_port | ( | dnssd_service_h | dnssd_service, |
int * | port | ||
) |
Gets the port number of DNSSD local/remote service.
- Since :
- 3.0
- Parameters:
-
[in] dnssd_service The DNSSD service local/remote handle [out] port The port number of DNSSD service
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_NOT_INITIALIZED Not Initialized
int dnssd_service_get_type | ( | dnssd_service_h | dnssd_service, |
char ** | service_type | ||
) |
Gets the type of DNSSD local/remote service.
- Since :
- 3.0
- Remarks:
- You must release service_type using free().
- Parameters:
-
[in] dnssd_service The DNSSD local/remote service handle [out] service_type The type of DNSSD service. It is expressed as type followed by protocol, separated by a dot(e.g. "_ftp._tcp"). It must begin with an underscore, followed by 1-15 characters which may be letters, digits, or hyphens. The transport protocol must be "_tcp" or "_udp". New service types should be registered at http://www.dns-sd.org/ServiceTypes.html
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_OUT_OF_MEMORY Out of Memory DNSSD_ERROR_NOT_INITIALIZED Not Initialized
int dnssd_service_remove_txt_record | ( | dnssd_service_h | local_service, |
const char * | key | ||
) |
Removes the TXT record.
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle [in] key The key of the TXT record to be removed
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_service_set_name | ( | dnssd_service_h | local_service, |
const char * | service_name | ||
) |
Sets the name of DNSSD local service.
Application should set name after creating local service using dnssd_create_local_service() and before registering the local service using dnssd_register_local_service().
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle [in] service_name The name of DNSSD local service
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_OUT_OF_MEMORY Out of Memory DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_service_set_port | ( | dnssd_service_h | local_service, |
int | port | ||
) |
Sets the port number of DNSSD local service.
Application should set port after creating local service using dnssd_create_local_service() and before registering the local service using dnssd_register_local_service().
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle [in] port The port number of DNSSD local service
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_service_set_record | ( | dnssd_service_h | local_service, |
unsigned short | type, | ||
unsigned short | length, | ||
const void * | data | ||
) |
Sets/updates the DNS resource record.
If the resource record for the type has been previously added using dnssd_service_set_record(), then the record will be updated. DNS resource record can be set only after local_service is registered using dnssd_register_local_service(). Data is added using dnssd_service_add_txt_record() and then obtained using dnssd_service_get_all_txt_record() to pass here.
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle [in] type The resource record type. For details see, RFC 1035 and RFC 2782 [in] length The length of the resource record in bytes [in] data The data contained in resource record to be added
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_OPERATION_FAILED Operation failed DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_ALREADY_REGISTERED Already Registered DNSSD_ERROR_NOT_INITIALIZED Not Initialized DNSSD_ERROR_OUT_OF_MEMORY Out of Memory
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_service_unset_record | ( | dnssd_service_h | local_service, |
unsigned short | type | ||
) |
Unsets the DNS resource record. DNS resource record for the given type must be set using dnssd_service_set_record().
- Since :
- 3.0
- Remarks:
- You must pass only local services created using dnssd_create_local_service().
- Parameters:
-
[in] local_service The DNSSD local service handle [in] type The resource record type. For details, see RFC 1035 and RFC 2782
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_OPERATION_FAILED Operation failed DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- See also:
- dnssd_create_local_service()
- Precondition:
- This API needs dnssd_create_local_service() before use.
int dnssd_start_browsing_service | ( | const char * | service_type, |
dnssd_browser_h * | dnssd_service, | ||
dnssd_found_cb | found_cb, | ||
void * | user_data | ||
) |
Starts browsing the DNSSD remote service.
found_cb would be called only if there are any services available of service_type provided in the argument. Application will keep browsing for available/unavailable services until it calls dnssd_stop_browsing_service().
- Since :
- 3.0
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/internet
- Parameters:
-
[in] service_type The DNSSD service type to browse. It is expressed as type followed by protocol, separated by a dot(e.g. "_ftp._tcp"). It must begin with an underscore, followed by 1-15 characters which may be letters, digits, or hyphens. The transport protocol must be "_tcp" or "_udp". New service types should be registered at http://www.dns-sd.org/ServiceTypes.html [out] dnssd_service The DNSSD browse service 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:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized DNSSD_ERROR_PERMISSION_DENIED Permission Denied
- Precondition:
- This API needs dnssd_initialize() before use.
int dnssd_stop_browsing_service | ( | dnssd_browser_h | dnssd_service | ) |
Stops browsing the DNSSD remote service.
- Since :
- 3.0
- Parameters:
-
[in] dnssd_service The DNSSD browse service handle returned by dnssd_start_browsing_service()
- Returns:
0
on success, otherwise negative error value
- Return values:
-
DNSSD_ERROR_NONE Successful DNSSD_ERROR_INVALID_PARAMETER Invalid parameter DNSSD_ERROR_NOT_SUPPORTED Not Supported DNSSD_ERROR_SERVICE_NOT_RUNNING Service Not Running DNSSD_ERROR_NOT_INITIALIZED Not Initialized
- Precondition:
- This API needs dnssd_start_browsing_service() before use.