3.1.4.2 R_DnssrvQuery (Opnum 1)

  • Article

The R_DnssrvQuery method queries the DNS server for information. The type of information queried for is specified by the client using the pszZone and pszOperation parameters. For the purpose of selecting an output structure type the server MUST consider the value of dwClientVersion (section 2.2.1.2.1) to be 0x00000000 when responding to this method.

 LONG R_DnssrvQuery(
   [in]                                    handle_t               hBindingHandle,
   [in, unique, string]                    LPCWSTR                pwszServerName,
   [in, unique, string]                    LPCSTR                 pszZone,
   [in, unique, string]                    LPCSTR                 pszOperation,
   [out]                                   PDWORD                 pdwTypeId,
   [out, switch_is(*pdwTypeId)]            DNSSRV_RPC_UNION*      ppData
 );

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

pwszServerName: The client can 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 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.

pszOperation: A pointer to a null-terminated character string that contains the name of the operation to be performed on the server. These are two sets of allowed values for pszOperation:

If pszZone is set to NULL, pszOperation MUST be either a property name listed in section 3.1.1.1, or it SHOULD<265> be the following.

Value

Meaning

"ServerInfo"

On output pdwTypeId SHOULD be set according to the value of the dwClientVersion field (section 2.2.1.2.1). If dwClientVersion is 0x00000000, then pdwTypeId SHOULD be set to DNSSRV_TYPEID_SERVER_INFO_W2K. If dwClientVersion is 0x00060000, then pdwTypeId SHOULD be set to DNSSRV_TYPEID_SERVER_INFO_DOTNET. If dwClientVersion is 0x00070000, then pdwTypeId SHOULD be set to  DNSSRV_TYPEID_SERVER_INFO<266> ppData MUST point to a structure of one of the types specified in DNS_RPC_SERVER_INFO (section 2.2.4.2.2), which SHOULD contain the configuration information for the DNS server, but MAY have some fields set to zero even when the related configuration value is nonzero.<267>

VirtualizationInstance

Gets the details of a virtualization instance in the DNS server. On success, the DNS server MUST set the dwTypeId parameter to DNSSRV_TYPEID_VIRTUALIZATION_INSTANCE (section 2.2.1.2.6), and MUST set the ppData point to a structure of type DNS_RPC_VIRTUALIZATION_INSTANCE (section 2.2.17.1.1).

If pszZone is not NULL, pszOperation MUST be either a property name listed in section 3.1.1.2, or one of the following.

Value

Meaning

"Zone"

On output the value pointed to by pdwTypeId SHOULD<268> be set to DNSSRV_TYPEID_ZONE and ppData MUST point to a structure of one of the types specified in DNS_RPC_ZONE (section 2.2.5.2.1), which contains abbreviated information about the zone pointed to by pszZone.

"ZoneInfo"

On output the value pointed to by pdwTypeId SHOULD<269> be set to DNSSRV_TYPEID_ZONE_INFOand ppData MUST point to a structure of one of the types specified in DNS_RPC_ZONE_INFO (section 2.2.5.2.4), which contains full information about the zone pointed to by pszZone.

pdwTypeId: A pointer to an integer that on success contains a value of type DNS_RPC_TYPEID (section 2.2.1.1.1) that indicates the type of data pointed to by ppData.

ppData: A DNSSRV_RPC_UNION(section 2.2.1.2.6) that contains a data-structure as indicated by dwTypeId.

Return Values: A Win32 error code indicating whether the operation completed successfully (0x00000000) or failed (any other value). See [MS-ERREF] section 2.2 or section 2.2.1.1.5.

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 (section 3.1) for the zone with name matching the value of pszZone. If a matching zone cannot be found return a failure.

  • Validate, as specified in section 3.1.6.1, that the client has permissions to perform the attempted operation. If pszZone is NULL then the DNS server MUST perform the Phase 2 authorization test using the DNS Server Configuration Access Control List. If pszZone is not NULL then 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 all operations. If the client does not have permission to perform the operation, the server MUST return a failure.

  • If pszZone is NULL, execute the operation indicated by the value of pszOperation specified as follows:

    • If pszOperation is ServerInfo, the server MUST return in ppData configuration information for the DNS server, and return success.

    • If pszOperation matches a property name listed in section 3.1.1.1.1, the server SHOULD<270> return DNSSRV_TYPEID_DWORD in pdwTypeId and return in ppData the value associated with that property, and return success. The server MAY return a nonzero error code.

    • If pszOperation matches a property name listed in section 3.1.1.1.2, the server SHOULD<271> return DNSSRV_TYPEID_ADDRARRAY in pdwTypeId, return in ppData the value associated with that property as a DNS_ADDR_ARRAY (section 2.2.3.2.1), and return success; it MAY instead return DNSSRV_TYPEID_ADDRARRAY in the pdwTypeId, return in ppData the value associated with that property as an IP4_ARRAY (section 2.2.3.2.1), and return success; or it MAY instead return a nonzero error code.<272>

    • If pszOperation matches a property name listed in section 3.1.1.1.3 that the server supports, the server MUST return DNSSRV_TYPEID_LPSTR for UTF-8 string properties or DNSSRV_TYPEID_LPWSTR for Unicode string properties in pdwTypeId, and return in ppData a pointer to the UTF-8 or Unicode string associated with that property, and return success.<273> If the property name is not supported, the server MUST return a nonzero error code.

    • If pszOperation matches a property name listed in section 3.1.1.1.4 that the server supports, the server MUST return DNSSRV_TYPEID_UTF8_STRING_LIST, and return in ppData the DNS_RPC_UTF8_STRING_LIST (section 2.2.1.2.3) associated with that property, and return success.

    • If pszOperation is VirtualizationInstance, the server MUST return in ppData details of the virtualization instance in a PDNS_RPC_VIRTUALIZATION_INSTANCE structure and return success. If a virtualization instance does not exist then return error DNS_ERROR_VIRTUALIZATION_INSTANCE_DOES_NOT_EXIST (9922).

  • If pszZone is not NULL, execute the operation indicated by the value of pszOperation, specified as follows:

    • If pszOperation is Zone, the server instead returns information about the zone in DNS_RPC_ZONE (section 2.2.5.2.1) format in ppData, and return success.

    • If pszOperation is ZoneInfo, the server instead returns information about the zone in DNS_RPC_ZONE_INFO (section 2.2.5.2.4) format in ppData, and return success.

    • If pszOperation matches a property name listed in section 3.1.1.2.1, the server MUST return DNSSRV_TYPEID_DWORD in pdwTypeId, return in ppData the value associated with that property, and return success.

    • If pszOperation matches a property name listed in section 3.1.1.2.2 that the server supports, the server SHOULD<274> return DNSSRV_TYPEID_ADDRARRAY in pdwTypeId, return in ppData the value associated with that property as a DNS_ADDR_ARRAY (section 2.2.3.2.3), and return success; or it MAY instead return DNSSRV_TYPEID_IPARRAY in pdwTypeId, return in ppData the value associated with that property as an IP4_ARRAY (section 2.2.3.1.1), and return success. If the property name is not supported, the server MUST return a nonzero error code.