DESCRIPTION

The
getdns_service (3) and getdns_service_sync functions provide
public entry points into the getdns API library to retrieve
the SRV information given a name.

context

A pointer to the previously
created DNS context that is to be

used with this DNS request. see
getdns_context (3)

name

the service name to resolve

extensions

extensions for this request,
NULL if no extensions, see libgetdns (3) for a detailed
description of extensions

userarg

returned to the callback
function untouched, can be NULL

transaction_id

populated by the API and used to
identify the callback (for example to
getdns_cancel_callback), can be NULL, set to 0 if the
function fails

callbackfn

non-NULL pointer to a callback
function defined by the application, typically used to
process the response. Only the asynchronous signature
accepts a callback function, the synchronous signature does
not include a callback. See libgetdns (3) for a more
detailed discussion of callback functions.

response

A getdns_dict type is returned
in response and always contains at least three names:
replies_full (a list containing the DNS response as binary
data), replies_tree (a list containing the parsed DNS
response data) and status (an int). The storage associated
with this must be freed by a call to
getdns_free_sync_request_memory (3).

RETURN VALUES

Upon successful
completion the functions return GETDNS_RETURN_GOOD ,
otherwise the following error values are returned:

GETDNS_RETURN_BAD_CONTEXT
if the context pointer is invalid or the context has
internal deficiencies

GETDNS_RETURN_BAD_DOMAIN_NAME
if the domain name passed to the function is invalid

GETDNS_RETURN_EXTENSION_MISFORMAT
if the data type specified in one or more of the extensions
does not match the specifications

GETDNS_RETURN_GENERIC_ERROR
if some problem was encountered in the function not
addressed by one of the more specific return codes

GETDNS_RETURN_INVALID
PARAMETER if one or more parameters has an invalid
value

GETDNS_RETURN_MEMORY_ERROR
if unable to allocate the memory required

GETDNS_RETURN_NO_SUCH_EXTENSION
if one or more of the strings specified in the extensions
are not valid

The values of
status included in the response parameter are:

GETDNS_RESPSTATUS_GOOD
if at least one response was returned

GETDNS_RESPSTATUS_NO_NAME
if queries for the name yielded all negative responses

GETDNS_RESPSTATUS_ALL_TIMEOUT
if all queries for the name timed out

GETDNS_RESPSTATUS_NO_SECURE_ANSWERS
if only secure replies accepted (per context) and at least
one response was received but no DNS responses were secure
through DNSSEC

For a more
detailed explanation of the response object see
libgetdns (3)