# `getdns` response data

## Response data from queries

class `getdns.``Result`

  > A getdns query (`Context.address()`, `Context.hostname()`, `Context.service()`, and `Context.general()`) returns a Result object. A Result object is only returned from a query and may not be instantiated by the programmer. It is a read-only object. Contents may not be overwritten or deleted.

  It has no methods but includes the following attributes:

  `status`

    The `status` attribute contains the status code returned by the query. Note that it may be the case that the query can be successful but there are no data matching the query parameters. Programmers using this API will need to first check to see if the query itself was successful, then check for the records returned.

    The `status` attribute may have the following values:

    `getdns.``RESPSTATUS_GOOD`

      At least one response was returned

    `getdns.``RESPSTATUS_NO_NAME`

      Queries for the name yielded all negative responses

    `getdns.``RESPSTATUS_ALL_TIMEOUT`

      All queries for the name timed out

    `getdns.``RESPSTATUS_NO_SECURE_ANSWERS`

      The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC.

      `RESPSTATUS_ALL_BOGUS_ANSWERS`

      The context setting for getting only secure responses was specified, and at least one DNS response was received, but all received responses for the requested name were bogus.

  `answer_type`

    The `answer_type` attribute contains the type of data that are returned (i.e., the namespace). The `answer_type` attribute may have the following values:

    `getdns.``NAMETYPE_DNS`

      Normal DNS (RFC 1035)

    `getdns.``NAMETYPE_WINS`

      The WINS name service (some reference needed)

  `canonical_name`

    The value of `canonical_name` is the name that the API used for its lookup. It is in FQDN presentation format.

  `just_address_answers`

    If the call was `address()`, the attribute `just_address_answers` (a list) is non-null. The value of `just_address_answers` is a list that contains all of the A and AAAA records from the `answer` sections of any of the replies, in the order they appear in the replies. Each item in the list is a dict with at least two names: `address_type` (a string whose value is either “IPv4” or “IPv6”) and `address_data` (whose value is a string representation of an IP address). Note that the `dnssec_return_only_secure` extension affects what will appear in the just_address_answers list. Also note if later versions of the DNS return other address types, those types will appear in this list as well.

  `replies_full`

    The `replies_full` attribute is a Python dictionary containing the entire set of records returned by the query.

    The following lists the status codes for response objects. Note that, if the status is that there are no responses for the query, the lists in `replies_full` and `replies_tree` will have zero length.

    The top level of `replies_tree` can optionally have the following names: `canonical_name`, `intermediate_aliases` (a list), `answer_ipv4_address` `answer_ipv6_address`, and `answer_type` (an integer constant.).

    - The value of `canonical_name` is the name that the API used for its lookup. It is in FQDN presentation format.
    - The values in the `intermediate_aliases` list are domain names from any CNAME or unsynthesized DNAME found when resolving the original query. The list might have zero entries if there were no CNAMEs in the path. These may be useful, for example, for name comparisons when following the rules in RFC 6125.
    - The value of `answer_ipv4_address` and `answer_ipv6_address` are the addresses of the server from which the answer was received.
    - The value of `answer_type` is the type of name service that generated the response. The values are:

    If the call was `address()`, the top level of `replies_tree` has an additional name, `just_address_answers` (a list). The value of `just_address_answers` is a list that contains all of the A and AAAA records from the `answer` sections of any of the replies, in the order they appear in the replies. Each item in the list is a dict with at least two names: `address_type` (a string whose value is either “IPv4” or “IPv6”) and `address_data` (whose value is a string representation of an IP address). Note that the `dnssec_return_only_secure` extension affects what will appear in the just_address_answers list. Also note if later versions of the DNS return other address types, those types will appear in this list as well.

    The API can make service discovery through SRV records easier. If the call was `service()`, the top level of `replies_tree has` an additional name, `srv_addresses` (a list). The list is ordered by priority and weight based on the weighting algorithm in RFC 2782, lowest priority value first. Each element of the list is a dictionary that has at least two names: `port` and `domain_name`. If the API was able to determine the address of the target domain name (such as from its cache or from the Additional section of responses), the dict for an element will also contain `address_type` (whose value is currently either “IPv4” or “IPv6”) and `address_data` (whose value is a string representation of an IP address). Note that the `dnssec_return_only_secure` extension affects what will appear in the `srv_addresses` list.

  `validation_chain`

    The `validation_chain` attribute is a Python list containing the set of DNSSEC-related records needed for validation of a particular response. This set comes as validation_chain (a list) at the top level of the response object. This list includes all resource record dicts for all the resource records (DS, DNSKEY and their RRSIGs) that are needed to perform the validation from the root up.

  `call_reporting`

    A list of dictionaries containing call_debugging information, if requested in the query.

  `replies_tree`

    The names in each entry in the the `replies_tree` list for DNS responses include `header` (a dict), `question` (a dict), `answer` (a list), `authority` (a list), and `additional` (a list), corresponding to the sections in the DNS message format. The `answer`, `authority`, and `additional` lists each contain zero or more dicts, with each dict in each list representing a resource record.

    The names in the `header` dict are all the fields from RFC 1035#section-4.1.1. They are: `id`, `qr`, `opcode`, `aa`, `tc`, `rd`, `ra`, `z`, `rcode`, `qdcount`, `ancount`, `nscount`, and `arcount`. All are integers.

    The names in the `question` dict are the three fields from RFC 1035#section-4.1.2: `qname`, `qtype`, and `qclass`.

    Resource records are a bit different than headers and question sections in that the RDATA portion often has its own structure. The other names in the resource record dictionaries are `name`, `type`, `class`, `ttl`, and `rdata` (which is a dict); there is no name equivalent to the RDLENGTH field. The OPT resource record does not have the `class` and the `ttl` name, but instead provides `udp_payload_size`, `extended_rcode`, `version`, `do`, and `z`.

    The `rdata` dictionary has different names for each response type. There is a complete list of the types defined in the API. For names that end in “-obsolete” or “-unknown”, the data are the entire RDATA field. For example, the `rdata` for an A record has a name `ipv4_address`; the rdata for an SRV record has the names `priority`, `weight`, `port`, and `target`.

    Each rdata dict also has a `rdata_raw` element. This is useful for types not defined in this version of the API. It also might be of value if a later version of the API allows for additional parsers. Thus, doing a query for types not known by the API still will return a result: an `rdata` with just a `rdata_raw`.

    It is expected that later extensions to the API will give some DNS types different names. It is also possible that later extensions will change the names for some of the DNS types listed above.

    For example, a response to a Context.address() call for www.example.com would look something like this:

    {     # This is the response object
     "replies_full": [ <bindata of the first response>, <bindata of the second response> ],
     "just_address_answers":
     [
       {
         "address_type": <bindata of "IPv4">,
         "address_data": <bindata of 0x0a0b0c01>,
       },
       {
         "address_type": <bindata of "IPv6">,
         "address_data": <bindata of 0x33445566334455663344556633445566>
       }
     ],
     "canonical_name": <bindata of "www.example.com">,
     "answer_type": NAMETYPE_DNS,
     "intermediate_aliases": [],
     "replies_tree":
     [
       {     # This is the first reply
         "header": { "id": 23456, "qr": 1, "opcode": 0, ... },
         "question": { "qname": <bindata of "www.example.com">, "qtype": 1, "qclass": 1 },
         "answer":
         [
           {
             "name": <bindata of "www.example.com">,
             "type": 1,
             "class": 1,
             "ttl": 33000,
             "rdata":
             {
               "ipv4_address": <bindata of 0x0a0b0c01>
               "rdata_raw": <bindata of 0x0a0b0c01>
             }
           }
         ],
         "authority":
         [
           {
             "name": <bindata of "ns1.example.com">,
             "type": 1,
             "class": 1,
             "ttl": 600,
             "rdata":
             {
               "ipv4_address": <bindata of 0x65439876>
               "rdata_raw": <bindata of 0x65439876>
             }
           }
         ]
         "additional": [],
         "canonical_name": <bindata of "www.example.com">,
         "answer_type": NAMETYPE_DNS
       },
       {     # This is the second reply
         "header": { "id": 47809, "qr": 1, "opcode": 0, ... },
         "question": { "qname": <bindata of "www.example.com">, "qtype": 28, "qclass": 1 },
         "answer":
         [
           {
             "name": <bindata of "www.example.com">,
             "type": 28,
             "class": 1,
             "ttl": 1000,
             "rdata":
             {
               "ipv6_address": <bindata of 0x33445566334455663344556633445566>
               "rdata_raw": <bindata of 0x33445566334455663344556633445566>
             }
          }
         ],
         "authority": [  # Same as for other record... ]
         "additional": [],
       },
     ]
    }

## Return Codes

The return codes for all the functions are:

`getdns.``RETURN_GOOD`

  Good

`getdns.``RETURN_GENERIC_ERROR`

  Generic error

`getdns.``RETURN_BAD_DOMAIN_NAME`

  Badly-formed domain name in first argument

`getdns.``RETURN_BAD_CONTEXT`

  The context has internal deficiencies

`getdns.``RETURN_CONTEXT_UPDATE_FAIL`

  Did not update the context

`getdns.``RETURN_UNKNOWN_TRANSACTION`

  An attempt was made to cancel a callback with a transaction_id that is not recognized

`getdns.``RETURN_NO_SUCH_LIST_ITEM`

  A helper function for lists had an index argument that was too high.

`getdns.``RETURN_NO_SUCH_DICT_NAME`

  A helper function for dicts had a name argument that for a name that is not in the dict.

`getdns.``RETURN_WRONG_TYPE_REQUESTED`

  A helper function was supposed to return a certain type for an item, but the wrong type was given.

`getdns.``RETURN_NO_SUCH_EXTENSION`

  A name in the extensions dict is not a valid extension.

`getdns.``RETURN_EXTENSION_MISFORMAT`

  One or more of the extensions have a bad format.

`getdns.``RETURN_DNSSEC_WITH_STUB_DISALLOWED`

  A query was made with a context that is using stub resolution and a DNSSEC extension specified.

`getdns.``RETURN_MEMORY_ERROR`

  Unable to allocate the memory required.

`getdns.``RETURN_INVALID_PARAMETER`

  A required parameter had an invalid value.

`getdns.``RETURN_NOT_IMPLEMENTED`

  The requested API feature is not implemented.