Asynchronously perform a DNS query for records of a specified type.

Description

int php_getdns_general ( int $context , string $name , int $reqType , int $extensions , array $userArg , mixed &$transID )

This function provides an entry point into the getdns API library to asynchronously retrieve any valid responses to a query from the DNS; note that other namespaces in the context are not used. Most typical use cases for applications are probably satisifed via calls to php_getdns_address_sync(), which would replace getaddrinfo(). See php_getdns_general_sync() for a description of the response data structure.

Note that this function enqueues an event that must be processed to produce queries and return results. Calling php_context_run() after calling this function will ensure that all queued events are processed.

Parameters

context

The previously created DNS context that is to be used with this request.

name

The ASCII-based domain name to be looked up as a string. This can also be an IPv4 or IPv6 address for request types that take addresses instead of domain names, such as PTR. The values here follow the rules in section 2.1 of » RFC 4343 to allow non-ASCII octets and special characters in labels.

reqType

The RRtype for the query; the RRtype numbers are listed in the IANA registry. For example, to get the NS records reqType would be 2. This extension has defined constants for most of the RRtypes by name; the definition names all start with "GETDNS_RRTYPE_". For example, to get the NS records you can also set the reqType to GETDNS_RRTYPE_NS.

extensions

The extensions dictionary for this request; NULL or 0 (zero) if no extensions.

userArg

An indexed array that contains information used to control callback processing. The first element of the array must contain a character string representing the name of the PHP client function that will receive and process the result of the DNS query. Additional array elements are optional and may be included to be passed to the callback function. The callback function will receive the complete array for local processing with all elements included as specified.

The callback function should be declared as follows:

        function_name($dict, $callbackType, $userArg, $transID)
        // $dict: An int representing the dictionary containing the response.
        // $callbackType: The getdns callback type.
        // $userArg: The original user arguments provided by the caller.
        // $transID: A 16-character string in hex format that contains the identifier of the transaction being processed.

transID

A 16-character string value in hexadecimal format representing an unsigned 64-bit integer that is filled in by the function to identify the callback being made. This value is passed by reference and any existing value will be overwritten; an empty string ("") is acceptable on input. It can also be NULL, in which case it is ignored and no value is assigned. The php_getdns_cancel_callback() function uses the transID to determine which callback is to be cancelled.

Return Values

This function returns an integer response code. GETDNS_RETURN_GOOD indicates successful completion.