3.1.4.4 R_DnssrvEnumRecords (Opnum 3)

  • Article

The R_DnssrvEnumRecords method enumerates DNS records on the server.

 LONG R_DnssrvEnumRecords(
   [in]                                    handle_t             hBindingHandle,
   [in, unique, string]                    LPCWSTR              pwszServerName,
   [in, unique, string]                    LPCSTR               pszZone,
   [in, unique, string]                    LPCSTR               pszNodeName,
   [in, unique, string]                    LPCSTR               pszStartChild,
   [in]                                    WORD                 wRecordType,
   [in]                                    DWORD                fSelectFlag,
   [in, unique, string]                    LPCSTR               pszFilterStart,
   [in, unique, string]                    LPCSTR               pszFilterStop,
   [out]                                   PDWORD               pdwBufferLength,
   [out, size_is(, *pdwBufferLength)]      PBYTE*               ppBuffer
 );

hBindingHandle: An RPC binding handle to the server. Details concerning binding handles are specified in [C706] section 2.3.

pwszServerName: The client SHOULD pass a pointer to the FQDN of the target server as a null-terminated UTF-16LE character string. The server MUST ignore this value.

pszZone: A pointer to a null-terminated character string that contains the name of the zone to be queried. For operations specific to a particular zone, this field MUST contain the name of the zone in UTF-8 format. For all other operations, this field MUST be NULL.

pszNodeName: A pointer to a null-terminated character string that contains the node name at which to modify a record. A string that is not dot-terminated indicates a name relative to the zone root. A value of "@" indicates the zone root itself. A dot-terminated string indicates the name is an FQDN.

pszStartChild: A pointer to a null-terminated character string that contains the name of the child node at which to start enumeration. A NULL value indicates to start a new record enumeration. The client application can pass the last retrieved child node of pszNodeName to continue a previous enumeration.

wRecordType: An integer value that indicates the type of record to enumerate. Any value can be used, as specified in DNS_RECORD_TYPE (section 2.2.2.1.1). The query-only value DNS_TYPE_ALL indicates all types of records.

fSelectFlag: An integer value that specifies what records are included in the response. Any combination of the values below MUST be supported. Values not listed below MUST be ignored.

Value

Meaning

DNS_RPC_VIEW_AUTHORITY_DATA

0x00000001

Include records from authoritative zones.

DNS_RPC_VIEW_CACHE_DATA

0x00000002

Include records from the DNS server's cache.

DNS_RPC_VIEW_GLUE_DATA

0x00000004

Include glue records.

DNS_RPC_VIEW_ROOT_HINT_DATA

0x00000008

Include root hint records.

DNS_RPC_VIEW_ADDITIONAL_DATA

0x00000010

Include additional records.

DNS_RPC_VIEW_NO_CHILDREN

0x00010000

Do not include any records from child nodes.

DNS_RPC_VIEW_ONLY_CHILDREN

0x00020000

Include only children nodes of the specified node in the results. For example: if a zone, "example.com", has child nodes, "a.example.com" and "b.example.com", calling R_DnssrcEnumRecords(…,"example.com", "example.com", NULL, DNS_TYPE_ALL, DNS_RPC_VIEW_ONLY_CHILDREN, …, …, …, …) will return DNS_RPC_NODES for "a" and "b".

pszFilterStart: Reserved for future use only. This MUST be set to NULL by clients and ignored by servers.

pszFilterStop: Reserved for future use only. This MUST be set to NULL by clients and ignored by servers.

pdwBufferLength: A pointer to an integer that on success contains the length of the buffer pointed to by ppBuffer.

ppBuffer: A pointer to a pointer that on success points to a buffer containing the enumerated records. The buffer is a series of structures beginning with a DNS_RPC_NODE structure (section 2.2.2.2.3). The records for the node will be represented by a series of DNS_RPC_RECORD (section 2.2.2.2.5) structures. The number of DNS_RPC_RECORD structures following a DNS_RPC_NODE structure is given by the wRecordCount member of DNS_RPC_NODE.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success or a non-zero Win32 error code if an error occurred. See [MS-ERREF] section 2.2 or section 2.2.1.1.5. All error values MUST be treated the same, except that if the return code is ERROR_MORE_DATA (0x000000EA) then the enumeration contains more results than can fit into a single RPC buffer. In this case the client application can call this method again passing the last retrieved child as the pszStartChild argument to retrieve the next set of results.

When processing this call, the server MUST do the following:

  • If the Global Server State (section 3.1) is not "Running", return a failure.

  • Check that the input parameters conform to the syntax requirements above, and if not return a failure.

  • If pszZone is not NULL, search the DNS Zone Table for a zone with a name matching the value of pszZone. If a matching zone cannot be found, return a failure. If pszZone is NULL, assume for the operations below that pszZone specifies the cache zone.

  • Validate, as specified in section 3.1.6.1, that the client has permissions to perform the attempted operation. The DNS server MUST perform the Phase 2 authorization test using the Zone Access Control List for the zone specified by pszZone. Read privilege MUST be tested for this operation. If the client does not have permission to perform the operation, the server MUST return a failure.

  • Locate the node indicated by pszNodeName in the zone indicated by pszZoneName. If no such node is found, then return DNS_ERROR_NAME_DOES_NOT_EXIST (9714) and set the output buffer length to zero.

  • If pszStartChild is non-NULL it indicates that this call is in continuation of an earlier call to R_DnssrvEnumRecords (section 3.1.4.4) that returned ERROR_MORE_DATA (0x000000EA), hence the server MUST attempt to locate this node and return failure if it cannot be found. The server MUST then continue the enumeration from there.

  • Return output records that meet the criteria specified by the value of fSelectFlag, in parameters pointed to by pdwBufferLength and ppBuffer, and return success. If these criteria are met--the zone is stored in a directory server; the DsMinimumBackgroundLoadThreads server property (section 3.1.1.1.1) is not 0x00000000; the zone is currently loading in the background; and the node indicated by pszNodeName has not yet been loaded into memory--the DNS server MUST behave as if the requested data does not exist in the zone.

  • The server MUST return matching records for any wType value that is explicitly defined in the DNS_RECORD_TYPE structure. The server MUST also respond to type values exceeding 0x0031 that have matching records.