3.1.4.1 R_DnssrvOperation (Opnum 0)
The R_DnssrvOperation method is used to invoke a set of server functions specified by pszOperation.
-
LONG R_DnssrvOperation( [in] handle_t hBindingHandle, [in, unique, string] LPCWSTR pwszServerName, [in, unique, string] LPCSTR pszZone, [in] DWORD dwContext, [in, unique, string] LPCSTR pszOperation, [in] DWORD dwTypeId, [in, switch_is(dwTypeId)] DNSSRV_RPC_UNION pData );
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 string MUST contain the name of the zone in UTF-8 format or a multizone operation string (given in the table that follows) that indicates that the operation is performed on multiple zones, but only if dwContext is zero. If dwContext is not zero, then the value of pszZone MUST be ignored. For all other operations this value MUST be set to NULL. When pszZone is NULL, the valid operations are in the first table under the pszOperation section that follows, or are a property name listed in section 3.1.1.1.2, 3.1.1.1.3, or 3.1.1.1.4. If this value is not NULL, then this value will be used by certain operations as specified in the second table for pszOperation that follows.
-
The following table shows what values are used to request that the operation be performed on multiple zones, using ZONE_REQUEST_FILTERS values (section 2.2.5.1.4).
-
Value
Meaning
"..AllZones"
ZONE_REQUEST_PRIMARY |
ZONE_REQUEST_SECONDARY |
ZONE_REQUEST_AUTO |
ZONE_REQUEST_FORWARD |
ZONE_REQUEST_REVERSE |
ZONE_REQUEST_FORWARDER |
ZONE_REQUEST_STUB |
ZONE_REQUEST_DS |
ZONE_REQUEST_NON_DS |
ZONE_REQUEST_DOMAIN_DP |
ZONE_REQUEST_FOREST_DP |
ZONE_REQUEST_CUSTOM_DP |
ZONE_REQUEST_LEGACY_DP
"..AllZonesAndCache"
ZONE_REQUEST_PRIMARY |
ZONE_REQUEST_SECONDARY |
ZONE_REQUEST_CACHE |
ZONE_REQUEST_AUTO |
ZONE_REQUEST_FORWARD |
ZONE_REQUEST_REVERSE |
ZONE_REQUEST_FORWARDER |
ZONE_REQUEST_STUB |
ZONE_REQUEST_DS |
ZONE_REQUEST_NON_DS |
ZONE_REQUEST_DOMAIN_DP |
ZONE_REQUEST_FOREST_DP |
ZONE_REQUEST_CUSTOM_DP |
ZONE_REQUEST_LEGACY_DP
"..AllPrimaryZones"
ZONE_REQUEST_PRIMARY
"..AllSecondaryZones"
ZONE_REQUEST_SECONDARY
"..AllForwardZones"
ZONE_REQUEST_FORWARD
"..AllReverseZones"
ZONE_REQUEST_REVERSE
"..AllDsZones"
ZONE_REQUEST_DS
"..AllNonDsZones"
ZONE_REQUEST_NON_DS
"..AllPrimaryReverseZones"
ZONE_REQUEST_REVERSE | ZONE_REQUEST_PRIMARY
"..AllPrimaryForwardZones"
ZONE_REQUEST_FORWARD | ZONE_REQUEST_PRIMARY
"..AllSecondaryReverseZones"
ZONE_REQUEST_REVERSE | ZONE_REQUEST_SECONDARY
"..AllSecondaryForwardZones"
ZONE_REQUEST_FORWARD | ZONE_REQUEST_SECONDARY
dwContext: A value used to specify multizone operations in ZONE_REQUEST_FILTERS (section 2.2.5.1.4) format or zero if the operation is not meant to apply to multiple zones. If pszZone is not NULL and matches the name of a zone hosted by the DNS server then the value of dwContext MUST be ignored.
pszOperation: A pointer to a null-terminated ASCII character string that contains the name of 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.2, 3.1.1.1.3 or 3.1.1.1.4, or SHOULD<215> be one of the following.
-
Value
Meaning
ResetDwordProperty
Update the value of a (name, value) pair in the DNS server configuration. On input, dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM, and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5) that specifies the name of a property listed in section 3.1.1.1.1 and a new value for that property.
Restart
The server SHOULD restart the DNS server process. dwTypeId and pData MUST be ignored by the server.<216>
ClearDebugLog
Clear the debug log. dwTypeId and pData MUST be ignored by the server.
ClearCache
Delete all cached records from the cache zone or cache scope memory. dwTypeId and pData MUST be ignored by the server.
WriteDirtyZones
Write all zones that are stored in local persistent storage to local persistent storage if the zone's Dirty Flag (section 3.1.1) is set to TRUE. dwTypeId and pData MUST be ignored by the server.
ZoneCreate
Create a zone. On input, dwTypeId SHOULD<217> be set to DNSSRV_TYPEID_ZONE_CREATE. pData MUST point to a structure of one of the types specified in DNS DNS_RPC_ZONE_CREATE_INFO (section 2.2.5.2.7) that contains all parameters of a new zone to be created by the DNS server, and pData MUST conform to the description corresponding to the value of dwTypeId (section 2.2.1.1.1) If pData points to a DNS_ZONE_TYPE_CACHE or DNS_ZONE_TYPE_SECONDARY_CACHE record, the server MUST return a nonzero error. If pData points to a DNS_ZONE_TYPE_STUB, DNS_ZONE_TYPE_SECONDARY, or DNS_ZONE_TYPE_FORWARDER record, the server MAY return a nonzero error, but SHOULD return success.<218>
ClearStatistics
Clears server statistics data on the DNS server. dwTypeId and pData MUST be ignored by the server.
EnlistDirectoryPartition
On input dwTypeId MUST be set to DNSSRV_TYPEID_ENLIST_DP, and the pData MUST point to a DNS_RPC_ENLIST_DP (section 2.2.7.2.5) structure. This operation allows application directory partitions to be added to or deleted from the Application Directory Partition Table, and also allows the DNS server to be directed to add or remove itself from the replication scope of an existing application directory partition.
StartScavenging
Initiate a resource record scavenging cycle on the DNS server. dwTypeId, and pData MUST be ignored by the server.
AbortScavenging
Terminate a resource record scavenging cycle on the DNS server. dwTypeId and pData MUST be ignored by the server.
AutoConfigure
On input, dwTypeId SHOULD be set to DNSSRV_TYPEID_AUTOCONFIGURE, in which case pData MUST point to a structure of type DNS_RPC_AUTOCONFIGURE (section 2.2.8.2.1)<219>; dwTypeId MAY instead be set to DNSSRV_TYPEID_DWORD in which case pData MUST point to a DWORD in DNS_RPC_AUTOCONFIG (section 2.2.8.1.1) format.
ExportSettings
Export DNS settings on the DNS server to a file on the DNS server. dwTypeId SHOULD be set to DNSSRV_TYPEID_LPWSTR, and pData MUST be ignored by the server.
PrepareForDemotion
Prepares for demotion by removing references to this DNS server from all zones stored in the directory server. dwTypeId and pData MUST be ignored by the server.
PrepareForUninstall
This operation does nothing on the DNS server. dwTypeId and pData MUST be ignored by the server.
DeleteNode
On input dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM, and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5) that contains the FQDN of the node pointed to by pszNodeName in the DNS server's cache to be deleted and a Boolean flag in dwParam to indicate if the node subtree is to be deleted.
DeleteRecordSet
On input dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM, and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5). That structure contains the FQDN of the node to be deleted, which is cached on the DNS server, and the type of record set in the dwParam member, which indicates whether the entire set of this type is to be deleted. The type MUST be a DNS_RECORD_TYPE value (section 2.2.2.1.1) or 0x00FF, which specifies all types.
WriteBackFile
Write all information for root hints back to persistent storage. dwTypeId and pData MUST be ignored by the server.
ListenAddresses
On input, dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, which contains a list of new IP addresses on which the DNS server can listen. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and MAY accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY.<220>
Forwarders
On input dwTypeId SHOULD be set to DNSSRV_TYPEID_FORWARDERS<221>, and pData MUST point to a structure of one of the types specified in DNS_RPC_FORWARDERS (section 2.2.5.2.10), which contains information about new IP addresses to which the DNS server can forward queries.
LogFilePath
On input dwTypeId MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to a Unicode string that contains an absolute or relative pathname or filename for the debug log file on the DNS server.
LogIPFilterList
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY, and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, which contains a list of new IP addresses used for debug log filter. The DNS server will write to the debug log only for traffic to/from these IP addresses. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and MAY accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY.<222>
ForestDirectoryPartitionBaseName
The DNS server MUST return an error.
DomainDirectoryPartitionBaseName
The DNS server MUST return an error.
GlobalQueryBlockList
Update the list of single-label names for which queries are blocked. Query names that match this list, in any primary zone, will be blocked. On input dwTypeId MUST be set to DNSSRV_TYPEID_UTF8_STRING_LIST, and pData MUST point to a structure of type DNS_RPC_UTF8_STRING_LIST (section 2.2.1.2.3).
BreakOnReceiveFrom
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, that contains a list of new IP addresses for which the DNS server will execute a breakpoint if a packet is received from these IP addresses. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and MAY accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY.<223>
BreakOnUpdateFrom
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY, and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, that contains a list of new IP addresses for which the DNS server will execute a breakpoint if an update is received from these IP addresses. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and MAY accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY.<224>
ServerLevelPluginDll
On input dwTypeId MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to a Unicode string that contains an absolute pathname for server side plug-in binary on the DNS server or an empty Unicode string.
ActiveRefreshAllTrustPoints
Schedules an immediate RFC 5011 active refresh for all trust points, regardless of the time of the last active refresh. The dwTypeId and pData parameters MUST be set to zero/NULL by the client and MUST be ignored by the server.<225>
CreateServerScope
Creates a server scope on the DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_LPWSTR. pData MUST point to a Unicode string that contains the name of the server scope to be created.<226>
DeleteServerScope
Deletes a server scope on the DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_LPWSTR. pData MUST point to a Unicode string that contains the name of the server scope to be deleted.<227>
CreateClientSubnetRecord
Creates a client subnet record on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_CLIENT_SUBNET_RECORD, and pData MUST point to a structure of type DNS_RPC_CLIENT_SUBNET_RECORD.
DeleteClientSubnetRecord
Deletes a client subnet record on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to a NULL-terminated Unicode string containing the name of the client subnet record to be deleted.
DeleteSubnetsInRecord
Updates a client subnet record on a DNS server by deleting the IP/IPv6 Subnets from the Client Subnet Record. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_CLIENT_SUBNET_RECORD, and pData MUST point to a structure of type DNS_RPC_CLIENT_SUBNET_RECORD.
AddSubnetsInRecord
Updates a client subnet record on a DNS server by adding the IP/IPv6 Subnets to the Client Subnet Record. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_CLIENT_SUBNET_RECORD, and pData MUST point to a structure of type DNS_RPC_CLIENT_SUBNET_RECORD.
ResetClientSubnetRecord
Resets a client subnet record on a DNS server by deleting the existing IP/IPv6 Subnets and adding the IP/IPv6 Subnets specific to the client subnet record. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_CLIENT_SUBNET_RECORD, and pData MUST point to a structure of type DNS_RPC_CLIENT_SUBNET_RECORD.
CreatePolicy
Creates a DNS Policy at the server level on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_POLICY, and pData MUST point to a structure of type DNS_RPC_POLICY.
DeletePolicy
Deletes a DNS Policy at the server level on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to NULL-terminated Unicode string containing the name of the DNS Policy.
UpdatePolicy
Updates a DNS Policy at the server level on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_POLICY, and pData MUST point to a structure of type DNS_RPC_POLICY.
SetRRL
Sets Response Rate Limiting parameters at the server level on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_RRL, and pData MUST point to a structure of type DNS_RPC_RRL_PARAMS.
CreateVirtualizationInstance
Creates a virtualization instance on the DNS server, under which zones can be created later. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_VIRTUALIZATION_INSTANCE (section 2.2.1.2.6), and the pData parameter MUST point to a structure of type DNS_RPC_VIRTUALIZATION_INSTANCE (section 2.2.1.2.6).
DeleteVirtualizationInstance
Removes a virtualization instance on the DNS server. This also removes the zones and zone scopes under the virtualization instance as well. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_VIRTUALIZATION_INSTANCE, and pData MUST point to a structure of type DNS_RPC_VIRTUALIZATION_INSTANCE. The value of dwFlags in DNS_RPC_VIRTUALIZATION_INSTANCE if set to DNS_RPC_FLAG_PRESERVE_ZONE_FILE, the DNS server deletes the zones under the virtualization instance but keeps the zone files. By default a DNS server removes the zone files of zones under a virtualization instance when the virtualization instance is removed.
UpdateVirtualizationInstance
Modifies the members of the virtualization instance on the DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_VIRTUALIZATION_INSTANCE, and pData MUST point to a structure of type DNS_RPC_VIRTUALIZATION_INSTANCE. The members of DNS_RPC_VIRTUALIZATION_INSTANCE to be modified is determined by bits in member dwFlags, which can be DNS_RPC_FLAG_FRIENDLY_NAME or DNS_RPC_FLAG_DESC (section 3.1.4.1)
-
If pszZone is not NULL, and pszOperation does not match a property name listed in sections 3.1.1.2.2 or 3.1.1.2.3, then pszOperation SHOULD<228> be one of the following:
-
Value
Meaning
ResetDwordProperty
Update the value of a DNS Zone integer property. On input dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5), which contains the name of a property listed in section 3.1.1.2.1 for the zone pointed to by pszZone and a new value for that property.<229>
ZoneTypeReset
Change the zone's type, for example to convert a secondary zone into a primary zone. On input dwTypeId SHOULD be set to DNSSRV_TYPEID_ZONE_CREATE, and pData SHOULD point to a structure of one of the types specified in DNS_RPC_ZONE_CREATE_INFO (section 2.2.5.2.7), which contains the new configuration information for the zone. dwTypeId MAY be set to DNSSRV_TYPEID_ZONE_CREATE_W2K or DNSSRV_TYPEID_ZONE_CREATE_DOTNET.<230> The server MUST return a nonzero error if the conversion is not implemented.
PauseZone
Pause activities for the zone pointed to by pszZone on the DNS server, and do not use this zone to answer queries or take updates until it is resumed. dwTypeId, and pData MUST be ignored by the server.
ResumeZone
Resume activities for the zone pointed to by pszZone on the DNS server; the zone thus becomes available to answer queries and take updates. dwTypeId and pData MUST be ignored by the server.
DeleteZone
Delete the zone pointed to by pszZone on the DNS server. dwTypeId and pData MUST be ignored by the server.
ReloadZone
Reloads data for the zone pointed to by pszZone on the DNS server from persistent storage. dwTypeId, and pData MUST be ignored by the server.
RefreshZone
Force a refresh of the secondary zone pointed to by pszZone on the DNS server, from primary zone server. For this operation pszZone MUST point to a secondary zone only. dwTypeId and pData MUST be ignored by the server.
ExpireZone
Force a refresh of the secondary zone pointed to by pszZone on the DNS server, from primary zone server. For this operation pszZone MUST point to a secondary zone only. dwTypeId and pData MUST be ignored by the server.
IncrementVersion
Same as "WriteBackFile".
WriteBackFile
If the zone has uncommitted changes, write back all information for the zone pointed to by pszZone to persistent storage, and notify any secondary DNS servers. dwTypeId and pData MUST be ignored by the server.
DeleteZoneFromDs
Delete the zone pointed to by pszZone from the directory server. dwTypeId, and pData MUST be ignored by the server.
UpdateZoneFromDs
Refresh data for the zone pointed to by pszZone from the directory server. dwTypeId, and pData MUST be ignored by the server.
ZoneExport
Export zone data to a given file on the DNS server. On input dwTypeId MUST be set to DNSSRV_TYPEID_ZONE_EXPORT, and pData MUST point to a structure of type DNS_RPC_ZONE_EXPORT_INFO (section 2.2.5.2.8) that contains a file name pointed to by pszZoneExportFile.
ZoneChangeDirectoryPartition
Move a zone to a given application directory partition. On input dwTypeId MUST be set to DNSSRV_TYPEID_ZONE_CHANGE_DP, and pData MUST point to structure of type DNS_RPC_ZONE_CHANGE_DP (section 2.2.7.2.6), which contains the new application directory partition name pointed to by pszDestPartition.
DeleteNode
Delete a node. On input dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM, and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5), which contains the FQDN of the node pointed to by pszNodeName present in the zone pointed to by pszZone on the DNS server to be deleted and a Boolean flag in dwParam to indicate if the node's subtree is to be deleted.
DeleteRecordSet
Delete all the DNS records of a particular type at a particular node from the DNS server's cache. On input dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM, and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5). That structure contains the FQDN of the node to be deleted and the DNS record type in the dwParam member. The type MUST be a DNS_RECORD_TYPE value (section 2.2.2.1.1) or 0x00FF, which specifies all types.
ForceAgingOnNode
On input dwTypeId MUST be set to DNSSRV_TYPEID_NAME_AND_PARAM, and pData MUST point to a structure of type DNS_RPC_NAME_AND_PARAM (section 2.2.1.2.5), which contains a node name in pszNodeName, and a Boolean flag in dwParam to indicate whether aging is performed on all nodes in the subtree. All DNS records at the specified node in the zone named by pszZone will have their aging time stamp set to the current time. If subtree aging is specified by dwParam than all DNS records at all nodes that are children of this node will also have their aging time stamps set to the current time.
DatabaseFile
On input dwTypeId SHOULD be set to DNSSRV_TYPEID_ZONE_DATABASE<231>, and pData MUST point to a structure of one of the types specified in DNS_RPC_ZONE_DATABASE (section 2.2.5.2.6), which specifies whether the zone is directory server integrated by setting fDsIntegrated to TRUE, and if it is not then pszFileName MUST point to a Unicode string containing the absolute pathname of a file on the DNS server to which the zone database is stored.
MasterServers
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY, and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, which contains a list of IP addresses of new primary DNS servers for the zone pointed to by pszZone. This operation is valid only for secondary zones present on the server. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and SHOULD accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY. If the input data of either type is accepted and the DNS server is directory-server integrated, the value of pData SHOULD be written to the directory server.<232>
LocalMasterServers
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY, and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, which contains a list of IP addresses of new local primary DNS servers for the zone pointed to by pszZone. This operation is valid only for stub zones present on the server, and if configured, this value overrides any primary DNS server configured in the directory server. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and SHOULD accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY.<233>
SecondaryServers
On input dwTypeId SHOULD<234> be set to DNSSRV_TYPEID_ZONE_SECONDARIES, and pData MUST point to a structure of one of the types specified in DNS_RPC_ZONE_SECONDARIES (section 2.2.5.2.5), which contains information about secondary DNS servers for the zone pointed to by pszZone.
ScavengeServers
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY, and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, which contains a list of IP addresses of new servers that can run scavenging on the zone pointed to by pszZone. This operation is valid only for directory server integrated zones. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY, and DNS_ADDR_ARRAY, and SHOULD accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY. If the input data of either type is accepted and the DNS server is directory server-integrated, the value of pData SHOULD be written to the directory server.<235>
AllowNSRecordsAutoCreation
On input dwTypeId MUST be set to DNSSRV_TYPEID_IPARRAY or DNSSRV_TYPEID_ADDRARRAY and pData MUST point to a structure of type IP4_ARRAY (section 2.2.3.2.1) or DNS_ADDR_ARRAY (section 2.2.3.2.3) respectively, which contains a list of IP addresses of new servers that can auto-create NS records for the zone pointed to by pszZone. This operation is valid only for directory server integrated zones. The server SHOULD accept DNSSRV_TYPEID_ADDRARRAY and DNS_ADDR_ARRAY, and SHOULD accept DNSSRV_TYPEID_IPARRAY and IP4_ARRAY. If the input data of either type is accepted and the DNS server is directory server-integrated, the value of pData SHOULD be written to the directory server.<236>
BreakOnNameUpdate
On input dwTypeId MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to a Unicode string that contains the FQDN of the node for which if an update is received the DNS server will execute a breakpoint.
SignZone
Sign a zone using DNSSEC, thus making the zone online-signed. The dwTypeId and pData parameters MUST be set to zero/NULL by the client and MUST be ignored by the server.
UnsignZone
Unsign a zone signed via online signing and remove all DNSSEC data from the zone. The dwTypeId and pData parameters MUST be set to zero/NULL by the client and MUST be ignored by the server.
ResignZone
Refreshes all DNSSEC data in an online-signed zone. The dwTypeId and pData parameters MUST be set to zero/NULL by the client and MUST be ignored by the server.
PerformZoneKeyRollover
Queues a signing key descriptor for key rollover. On input, dwTypeId MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to a Unicode string representation of the GUID of the signing key descriptor to be queued for rollover.
PokeZoneKeyRollover
Instructs the DNS server to stop waiting for DS records [RFC4034] in the parent zone to be updated and to proceed with key rollover as specified by [RFC4641]. On input, dwTypeId MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to a Unicode string representation of the GUID of the signing key descriptor to be queued for rollover.
RetrieveRootTrustAnchors
Retrieves the root trust anchors from the XML file specified by the RootTrustAnchorsURL server property (section 3.1.1.1.3) and adds any valid DS records to the root trust anchors. The dwTypeId and pData parameters MUST be set to zero/NULL by the client and MUST be ignored by the server. The pszZone parameter MUST be set to the string "TrustAnchors" to indicate the name of the zone.
TransferKeymasterRole
Transfers the key master role to the current server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_DWORD, and pData MUST point to one of the values defined in the following paragraphs.
CreateZoneScope
Creates a zone scope in the specified zone or a cache scope in the specified cache zone. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_ZONE_SCOPE_CREATE. pData MUST point to a structure of the type DNS_RPC_ZONE_SCOPE_CREATE_INFO_V1 (section 2.2.13.1.2.1) that contains all the parameters needed to create the zone scope or cache scope. pszZone MUST be the name of the zone in which the zone scope is to be created or be specified as "..cache" for a cache scope.<237>
DeleteZoneScope
Deletes a zone scope from the specified zone or a cache scope from a specified cache zone. The dwTypeId MUST be set to DNSSRV_TYPEID_LPWSTR. pData MUST point to the name of the zone scope or cache scope that is to be deleted. pszZone MUST be the name of the zone from which the zone scope is to be deleted or set to "..cache" for a cache scope.<238>
CreatePolicy
Creates a DNS Policy for the specified zone or a cache zone on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_POLICY, and pData MUST point to a structure of type DNS_RPC_POLICY.
DeletePolicy
Deletes a DNS Policy for the specified zone or a cache zone on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_LPWSTR, and pData MUST point to NULL-terminated Unicode string containing the name of the DNS Policy.
UpdatePolicy
Updates a DNS Policy for the specified zone or a cache zone on a DNS server. The dwTypeId parameter MUST be set to DNSSRV_TYPEID_POLICY, and pData MUST point to a structure of type DNS_RPC_POLICY.
dwTypeId: A DNS_RPC_TYPEID (section 2.2.1.1.1) value that indicates the type of input data pointed to by pData.
pData: Input data of type DNSSRV_RPC_UNION (section 2.2.1.2.6), which contains a data structure as specified by dwTypeId.
Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success or a nonzero Win32 error code value 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.
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) record for the zone with a name matching the value of pszZone. If a matching zone cannot be found, search the list of multizone operation strings for a name matching the value of pszZone. If a matching name 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. Write privilege MUST be tested for all operations with the following exceptions:
If pszOperation is ZoneCreate, and if the zone will be created in the directory service, then Read privilege MUST be tested for.
If pszOperation is CreateZoneScope, and if the zone scope will be created in the directory service, then Read privilege MUST be tested for.
If pszOperation is DeleteZone, and if the zone is stored in the directory service, then Read privilege MUST be tested for.
If pszOperation is DeleteZoneScope, and if the zone scope is stored in the directory service, then Read privilege MUST be tested for.
If pszOperation is EnlistDirectoryPartition or ExportSettings, then Read privilege MUST be tested for.
If the client does not have permission to perform the operation, return a failure.
If dwContext is not zero or pszZone matches a multizone operation string, then find all zone records in the DNS Zone Table matching the specified multizone filter value.
If pszZone is NULL and dwContext is zero, execute the operation indicated by the value of pszOperation, as follows:
If pszOperation is ResetDwordProperty, the server MUST verify that the property name matches a writable property name listed in section 3.1.1.1.1 for which the server supports the ResetDwordProperty operation and if not return an error. It SHOULD further verify that the value specified is either within the property's specified allowable range (including zero if it is specified that zero is allowed) and if not return an error. If the value is zero and zero is listed as a flag value for the default in section 3.1.1.1.1, the server SHOULD update the value of the property to be the default for the property and return success. The server MAY fail to verify these restrictions.<239> Otherwise, update the value of the property to be the new value specified and return success.<240> All properties are writable unless "this property is read-only" is specified in the property description in section 3.1.1.1.1.
If pszOperation matches a property name in section 3.1.1.1.2, 3.1.1.1.3, or 3.1.1.1.4 for which the server supports this value reset operation, the server MUST update the value of the property to be the new value specified in pData and return success. If pszOperation matches a property name that the server does not support, the server MUST simply return failure.<241>
If pszOperation is Restart, the server MUST restart the DNS server, and return success.
During the restart operation, the DNS server MUST try to reload each zone scope (if present) in a zone, one by one from the database. If the DNS server fails to load any of the scopes of the zone, it MAY log an error event and pursue the next scope and subsequently next zone.<242> No error MUST be returned to the user in the event of failure.
If pszOperation is ClearDebugLog, the server MUST copy the DNS log file specified by the DNS server's "LogFilePath" (section 3.1.1.1.3) property to the implementation-specific backup directory, if the directory already exists, and overwrite an existing backup directory log file if needed. If the directory does not exist, the copy action MUST NOT be performed. Then, the server MUST delete the current contents of the DNS log file, and return success. The server MUST return success even if file operations on the DNS log file fail.<243>
If pszOperation is ClearCache, the server MUST delete all records cached by the DNS server in the cache zone from memory. If a cache scope is specified, delete all records only from that cache scope. If the server is configured to use directory server, the server MUST search for the cache zone (with the LDAP search operation), create (LDAP add) the zone if it doesn't exist, load (LDAP search) any default cache records into the local copy of the cache, and return success. If any of these LDAP operations fails, the server MUST return failure.
If pszOperation is WriteDirtyZones, the server MUST, for each primary zone or cache zone on the server:
Do nothing, if the zone's Dirty Flag (section 3.1.1) is set to FALSE and the zone is not configured with any zone scopes or the zone is not stored in a file.
If the zone's Dirty Flag is set to TRUE, write the uncommitted information for the zone to the zone's file, send DNS notify ([RFC1996]) messages to all other servers hosting the zones, if they exist, and continue processing zones. If the zone specified is the cache zone, the server SHOULD write the root hints to their permanent storage. If the root hints are stored on the directory server and DownlevelDCsInDomain is nonzero, the server MUST check whether the root hints are empty. If the root hints are empty, the root hints MUST NOT be written to their permanent storage. Otherwise, if the root hints are stored on the directory server the server MUST use LDAP add, delete, and search operations to replace the root hints on the directory server. If there is a failure in writing the root hints records to the directory server, then the server MUST retry the write operation twice.
If the zone is configured with scopes, then for each scope the operation attempts to write the scope data to their respective scope database files, if the scope's Dirty Flag (section 3.1.1) is set to TRUE. If any errors occur during this operation, then the operation SHOULD be continued with the next scope in the list and the appropriate error events SHOULD be logged.
When all zones have been processed, the server SHOULD return success, regardless of the success or failure of any processing operation.<244>
If pszOperation is ZoneCreate, the server MUST attempt to create a new zone entry in the DNS Zone Table using the parameters specified in pData, and return success or failure based on the result.
If the zone already exists, the server MUST return a failure.
If the zone to be created will use the directory server for persistent storage, the server MUST identify the correct application directory partition for the zone.
If dwFlags has the DNS_ZONE_CREATE_FOR_DCPROMO bit set, this partition MUST be the DNS domain application directory partition.
If dwFlags has the DNS_ZONE_CREATE_FOR_DCPROMO_FOREST bit set, this partition MUST be the DNS forest application directory partition.
Otherwise, if the pszDpFqdn field is populated, this partition MUST be set to the value of that field.
Or else, this partition MUST be set to the directory partition that represents the default naming context. (See the description of the DNS_DP_LEGACY value in section 3.1.1.2.1).<245>
The server MUST perform an LDAP search to verify the existence of this application directory partition, and return a failure if it does not exist, with the following exceptions:
If dwFlags is set to DNS_ZONE_CREATE_FOR_DCPROMO and the DNS domain application directory partition does not exist or is not available, the server MUST replace the chosen partition with the directory partition that represents the default naming context.
If dwFlags is set to DNS_ZONE_CREATE_FOR_DCPROMO_FOREST and the DNS forest application directory partition does not exist or is not available, the server MUST replace the chosen partition with the directory partition that represents the default naming context.
Once the existence of the chosen application directory partition has been verified, the server MUST then perform an LDAP search on that application directory partition to determine whether the zone already exists, and if so, return a failure.
If the zone does not exist in the chosen application directory partition, the server MUST create a dnsZone object (section 2.3) for the zone and its default records, represented as dnsNode objects (section 2.3), in the chosen application directory partition using LDAP add operations and return success.
If dwFlags is set to DNS_ZONE_CREATE_FOR_DCPROMO, but the zone is being created in the directory partition representing the default naming context, the DcPromo Flag in the dnsZone object MUST be set to DCPROMO_CONVERT_DOMAIN. (See DcPromo Flag (section 2.3.2.1.2))
If dwFlags is set to DNS_ZONE_CREATE_FOR_DCPROMO_FOREST, but the zone is being created in the directory partition representing the default naming context, the DcPromo Flag in the dnsZone object MUST be set to DCPROMO_CONVERT_FOREST. (See DcPromo Flag (section 2.3.2.1.2))
If there is a failure in writing the records to the directory server, then the server MUST retry the write operation twice.
If any of these LDAP operations cannot be completed, even after retries where specified, then the server MUST return failure.
If pszOperation is ClearStatistics, the server MUST clear internal server statistics, and return success.
If pszOperation is EnlistDirectoryPartition, the server SHOULD<246> perform an application directory partition operation as specified by the contents of the input DNS_RPC_ENLIST_DP (section 2.2.7.2.5) structure. The procedures for these operations are described below:
If pszOperation is EnlistDirectoryPartition, and the DNS_DP_OP_CREATE_FOREST or DNS_DP_OP_CREATE_DOMAIN operations are specified by the contents of the input DNS_RPC_ENLIST_DP structure, the server SHOULD:
Check its local state to determine whether the partition specified by dwOperation is already present, and if so, the server MUST check its local state to determine whether it is not enlisted in the partition, and if so, connect to the directory server that is the FSMO role owner of the domain naming master FSMO role and perform an LDAP modify operation to add or remove the local server's name from the enlistment list (distinguished name "msDS-NC-Replica-Locations" RODCs use "msDS-NC-RO-Replica-Locations").<247>. If, based on the local state, the partition already exists and this server is enlisted or any of the above LDAP operations cannot be completed, then the server MUST return a failure.
Or, if based on the server's local state, the partition does not exist in the Application Directory Partition Table, create (but not enlist itself in) the partition object using LDAP add commands and add the partition object to the Application Directory Partition Table, returning a failure if either of these operations fails to complete successfully.
Poll the directory server for the partitions and enlistment status using LDAP search operations (to update the local state) and return success. If any LDAP operation cannot be completed, then the server MUST return a failure.
If pszOperation is EnlistDirectoryPartition, and the DNS_DP_OP_ENLIST or DNS_DP_OP_UNENLIST operations are specified by the contents of the input DNS_RPC_ENLIST_DP structure, the server SHOULD:
Check whether the application directory partition specified is either the domain global partition or the forest global partition and whether the operation specified is not DNS_DP_OP_ENLIST, and if the preceding conditions are true, the server MUST return a failure.
Check whether, instead, the operation specified is DNS_DP_OP_ENLIST and the partition specified is the domain or forest global partition, and if so, the server MUST connect to the directory server that is the FSMO role owner of the Domain naming master FSMO role and perform an LDAP modify operation to add or remove the local server's name from the enlistment list (distinguished name "msDS-NC-Replica-Locations" (RODCs use "msDS-NC-RO-Replica-Locations"<248>)) and return success.
Check whether the application directory partition specified is neither the domain global partition nor the forest global partition, and if so, the server MUST:
Poll the directory server for the partitions and enlistment status using LDAP search operations (to update the local Application Directory Partition Table), and then:
Check the local Application Directory Partition Table for the requested partition, and if the partition does not exist, return a failure.
Otherwise, the server MUST check whether the server is already enlisted and the operation is DNS_DP_OP_ENLIST or the server is already unenlisted and the operation is DNS_DO_OP_UNENLIST, and if so, return a failure.
Otherwise, the server MUST connect to the directory server that is the FSMO role owner of the Domain naming master FSMO role, and perform an LDAP modify operation to add or remove (for DNS_DP_OP_ENLIST and DNS_DP_OP_UNENLIST, respectively) the local server's name from the enlistment list (distinguished name "msDS-NC-Replica-Locations" (RODCs use "msDS-NC-RO-Replica-Locations")), and return success.
If any of the above LDAP operations cannot be completed, then the server MUST return a failure.
If the zone was successfully loaded then the DNS server MUST set the zone's Shutdown flag to zero (section 2.2.5.2.2).
If pszOperation is EnlistDirectoryPartition, and the DNS_DP_OP_CREATE operation is specified by the contents of the input DNS_RPC_ENLIST_DP structure, the server SHOULD:
Check whether the application directory partition specified is either the domain global partition or the forest global partition, and if so, perform the procedure described above for DNS_DP_OP_CREATE_DOMAIN or DNS_DP_OP_CREATE_FOREST, respectively.
Otherwise, poll the directory server for the partitions and enlistment status using LDAP search operations (to update the local Application Directory Partition Table), and then check the local Application Directory Partition Table for the requested partition. If the partition already exists, the server MUST return a failure.
Otherwise, the server MUST connect to the directory server and create the partition (an LDAP domainDNS object) using the LDAP add operation, poll the directory server for the partitions and enlistment status, update the local Application Directory Partition Table, attempt to create the MicrosoftDNS object using LDAP add operations, and return success.
If any of the above LDAP operations other than the creation of the MicrosoftDNS object cannot be completed, then the server MUST return a failure.
If pszOperation is EnlistDirectoryPartition, and the DNS_DP_OP_DELETE operation is specified by the contents of the input DNS_RPC_ENLIST_DP structure, the server SHOULD:
Poll the directory server for the partitions and enlistment status using LDAP search operations (to update the local Application Directory Partition Table), and then check the local Application Directory Partition Table for the requested partition. If the partition does not exist, the server MUST return a failure.
Otherwise, the server MUST connect to the directory server that is the FSMO role owner of the Domain naming master FSMO role and perform an LDAP delete operation on the distinguished name of the crossRef object of the specified application directory partition, and if successful, again poll the directory server to update the local Application Directory Partition Table and return success.
If any of the above LDAP operations fails, then the server MUST return a failure. Any LDAP delete operation MUST have no client-side time limit. The server MUST NOT retry any failed LDAP operation.
If pszOperation is StartScavenging, the server MUST initiate a resource record scavenging cycle on the DNS server, and return success.
If pszOperation is AbortScavenging, the server MUST terminate a resource record scavenging cycle on the DNS server if one is currently in progress, and return success.
If pszOperation is AutoConfigure, the server SHOULD perform DNS server autoconfiguration as specified by the contents of the input DNS_RPC_AUTOCONFIGURE (section 2.2.8.2.1) structure, and return success or failure based on the results of this operation.<249> To perform DNS server autoconfiguration, the server SHOULD:
Configure forwarders, if specified by the input flags and if the server does not currently have any forwarders configured. The list of forwarders is built by querying other servers that host the domain specified in the input arguments and by attempting to copy their forwarder list using the ServerInfo feature of the R_DnssrvQuery (section 3.1.4.2) operation. If forwarders cannot be copied from another server, the list of forwarders is copied from the local machine's DNS client's list of DNS servers.
Configure root hints, if specified by the input flags. The list of root hints is built by querying the each DNS server on each local network adapter for the root DNS name.
Perform self-pointing, if either of the following is true:
The DNS server is directory services-integrated and is the first DNS server in the directory services forest, and the DNS_RPC_AUTOCONFIG_INTERNAL_ZONES flag is set.
Any of the DNS_RPC_AUTOCONFIG_INTERNAL_SELFPOINT, DNS_RPC_AUTOCONFIG_INTERNAL_SELFPOINT_PREPEND, or DNS_RPC_AUTOCONFIG_INTERNAL_SELFPOINT_APPEND flags are set.
To perform self-pointing, for each enabled network adapter and for each enabled IP stack (IPv4 or IPv6) on that adapter, the server SHOULD do one of the following:
If the DNS_RPC_AUTOCONFIG_INTERNAL_SELFPOINT flag is set, replace the adapter's IP stack's DNS servers list with the loopback address.
If the DNS_RPC_AUTOCONFIG_INTERNAL_SELFPOINT_PREPEND flag is set and the loopback address is not already present, insert the loopback address at the start of the adapter's IP stack's DNS server list.
Otherwise, if the loopback address is not already present, insert the loopback address at the end of the adapter's IP stack's DNS server list.
Otherwise, make no change to the adapter's IP stack's DNS server list.
Create the forest root domain and its "_msdcs" subdomain, if specified by the input flags, and the directory service domain name of this DNS server matches the directory services forest root domain name, and the domains do not already exist. These two domains are created using LDAP add operations, followed by additional LDAP add operations to install the default records for those domains. If there is a failure in writing the records to the directory server, then the server MUST retry the write operation twice.
If any operation (including LDAP operations) fails, continue processing but record the fact that a failure occurred. At the end of processing, if the DNS_RPC_AUTOCONFIG_INTERNAL_RETURN_ERRORS input flag (section 2.2.8.1.1) is set, return an error; otherwise, return success.
If pszOperation is ExportSettings, the server SHOULD<250> export DNS settings to a file on the DNS server, and return success.
If pszOperation is PrepareForDemotion, the server SHOULD<251> prepare the DNS server for demotion by removing references to this DNS server from all zones stored in the directory server, and return success.
If pszOperation is PrepareForUninstall, the server SHOULD<252> do nothing, and return success.
If pszOperation is DeleteNode, the server MUST check whether the specified node is empty or does not currently exist and return ERROR_SUCCESS if so. Otherwise it MUST delete all DNS records at the node pointed to by pszNodeName from the DNS server's cache. It MUST also delete all DNS records in the node's subtree if specified by the Boolean flag pointed to by dwParam field in pData, and return success. If the dwParam field in pData is set to FALSE and the node contains subtrees, both the node and its subtrees MUST NOT be deleted and a success status is returned. If the zone is directory server-integrated, the DNS server MUST set the node's DNS Node Tombstone State (section 3.1.1) to TRUE by setting the value of the dnsTombstoned attribute to TRUE, and writing a DNS_RPC_RECORD_TS (section 2.2.2.2.4.23) in the dnsRecord attribute.
If pszOperation is DeleteRecordSet, the server MUST check whether the specified node is empty or does not currently exist and return ERROR_SUCCESS if so. Otherwise it MUST delete all DNS records of the type specified by the dwParam field in pData from the node pointed to by pszNodeName in the DNS server's cache and return success. If this operation deletes the last record from the node and the zone is directory server-integrated, the DNS server MUST set the node's DNS Node Tombstone State (section 3.1.1) to TRUE by setting the value of the dnsTombstoned attribute to TRUE and writing a DNS_RPC_RECORD_TS (section 2.2.2.2.4.23) in the dnsRecord attribute.
If pszOperation is WriteBackFile, the server SHOULD write the root hints to their permanent storage. If the root hints are stored on the directory server and DownlevelDCsInDomain is nonzero, the server MUST check whether the root hints are empty. If the root hints are empty, the root hints MUST NOT be written to their permanent storage. Otherwise, if the root hints are stored on the directory server, the server MUST use LDAP add, delete, and search operations to replace the root hints on the directory server and return success, regardless of the success or failure of these operations. If there is a failure in writing the root hints records to the directory server, then the server MUST retry the write operation twice, and still return success, even if the retries fail.<253>
If pszOperation is LogFilePath, the server MUST store the value passed in pData to be returned, unchanged, in future server information queries. Further, if pData is a NULL pointer or it points to an empty string, the server MUST replace pData's present value with the path to the default implementation specific log file. Finally, the server MUST attempt to create and/or open for write the file specified by the string. If the string is a filename or relative path, the server MUST attempt to create the file relative to the default implementation specific log file path.<254> If the file is opened successfully, then the server MUST commence logging to file and return success. Otherwise, it MUST disable logging to file and return a failure.
If pszOperation is ListenAddresses, the server MUST search the incoming array for loopback, multicast, or broadcast addresses, and if any are found, return a failure. Otherwise, the server MUST remove any addresses from the input that are not IPv4 addresses and create a backup copy of the current listen addresses. Then the server MUST attempt to listen on the network interfaces specified by the new listen addresses from the incoming array, and if this attempt fails, the server MUST restore the previous listen addresses and return a failure. Otherwise, the server MUST attempt to update the SOA records for its authoritative zones with the new listen addresses and MUST return success even if the attempt fails. If a zone is directory services-integrated, the server MUST use the LDAP search, add, and delete operations to update the SOA records and return success even if there were unsuccessful LDAP calls. If there is a failure in modifying the records on the directory server, then the server MUST retry the write operation twice, and still return success even if the retries fail.
If pszOperation is ServerLevelPluginDll, the server MUST store the value passed in pData and return SUCCESS, indicating only that the value was successfully received. The server MUST NOT validate the value passed, nor attempt to load the DLL, until the server is restarted. When the server restarts, if the value stored for ServerLevelPluginDll is not an empty string, the server MUST attempt to load the DLL specified. If the DLL fails to load for any reason, the server MUST fail to start. If the DLL has been loaded, then whenever the server is required to invoke the DLL query function, the server MUST invoke the query function of the DLL with a query name and type and add any resulting records to the server's cache. Whenever the server processes a query, if the DLL has been loaded, the server MUST invoke the query function of the DLL in the following conditions:
If a query cannot be answered with the information already present in the server's zone database and cache, then prior to recursing (if applicable), invoke the DLL query function and try again to answer the query from local data.
If a response SHOULD have records in its additional section but no such records are in the server's cache or zone database, invoke the DLL query function and attempt again to find records for the additional section.
If pszOperation is ActiveRefreshAllTrustPoints, the server MUST schedule an RFC 5011 active refresh for all configured trust points (if any) and return success.
If pszOperation is DeleteServerScope, the server MUST:
If the server scope specified in pData does not exist, return DNS_ERROR_SCOPE_DOES_NOT_EXIST (9959).
If the server scope is being used by a DNS Policy (section 2.2.15.2.2), return DNS_ERROR_SERVERSCOPE_IS_REFERENCED (9988).
The DNS server MUST attempt to delete the server scope in the DNS server, and return success or failure based on the result.
If pszOperation is CreateClientSubnetRecord, the server MUST:
If the Client Subnet Record already exists, return DNS_ERROR_CLIENT_SUBNET_DOES_EXIST (9976).
The DNS server MUST attempt to create a new Client Subnet Record entry in the DNS server using the parameters specified in pData, and return success or failure based on the result.
If pszOperation is DeleteClientSubnetRecord, the server MUST:
If the Client Subnet Record specified in pData does not exist, return DNS_ERROR_CLIENT_SUBNET_DOES_NOT_EXIST (9976).
If the Client Subnet Record is being used by a DNS Policy in its Client Subnet Record criteria, then the DNS server MUST return DNS_ERROR_CLIENT_SUBNET_IS_ACCESSED (9975).
The DNS server MUST attempt to delete the Client Subnet Record entry in the DNS server, and return success or failure based on the result.
If pszOperation is DeleteSubnetsInRecord, the server MUST:
If the Client Subnet Record specified in pData does not exist, return DNS_ERROR_CLIENT_SUBNET_DOES_NOT_EXIST (9976).
If the IP/IPv6 Subnets specified in pData do not exist in the Client Subnet Record on the DNS server, return DNS_ERROR_SUBNET_DOES_NOT_EXIST (9978).
If deletion of the IP/IPv6 subnets results in the Client Subnet Record not having an IP or IPv6 subnet, return DNS_ERROR_ADDRESS_REQUIRED (9573).
The DNS server MUST attempt to delete the IP/IPv6 Subnets in the Client Subnet Record on the DNS server, and return success or failure based on the result.
If pszOperation is AddSubnetsInRecord, the server MUST:
If the Client Subnet Record specified in pData does not exist, return DNS_ERROR_CLIENT_SUBNET_DOES_NOT_EXIST (9976).
If the IP/IPv6 Subnets specified in pData exists in the Client Subnet Record on the DNS server, return DNS_ERROR_SUBNET_DOES_EXIST (9978).
The DNS server MUST attempt to add the IP/IPv6 Subnets in the Client Subnet Record on the DNS server, and return success or failure based on the result.
If pszOperation is ResetClientSubnetRecord, the server MUST:
If the Client Subnet Record specified in pData does not exist, return DNS_ERROR_CLIENT_SUBNET_DOES_NOT_EXIST (9976).
If no IP or IPv6 subnets are specified, return DNS_ERROR_ADDRESS_REQUIRED (9573).
The DNS server MUST delete the existing IP/IPv6 Subnets in the Client Subnet Record and add the IP/IPv6 Subnets specified in pData in the Client Subnet Record on the DNS server, and return success or failure based on the result.
If pszOperation is CreatePolicy, the server MUST:
The DNS server validates whether the DNS Policy parameters specified in pData are valid. If the parameters are invalid the server returns DNS_ERROR_POLICY_INVALID_SETTINGS (9974). See DNS Policy Validation (section 3.1.8.3) for details.
If the DNS Policy pdata parameter dwProcessingOrder is greater than the highest Processing Order in the given level and appliesOn, return DNS_ERROR_POLICY_INVALID_SETTINGS (9974).
If the DNS Policy pdata parameter pwszPolicyName already exists, return DNS_ERROR_POLICY_ALREADY_EXISTS (9971). The policy name check is done for the policies configured on the server level.
If the value weight in pContentList is 0, as defined in DNS_RPC_POLICY_CONTENT (section 2.2.15.2.2), the DNS server returns DNS_ERROR_POLICY_INVALID_WEIGHT (9981). Allowed values for weight are any positive number from 1 to 0xFFFFFFFF.
If DNS Policy pdata parameter dwProcessingOrder is 0, reset the processing order to the last processing order for the given level and appliesOn.
Create the new DNS Policy in the DNS server, and return success or failure based on the result. This DNS Policy is applicable to the DNS operations at the server level.
If DNS Policy pdata parameter dwProcessingOrder is same as an existing DNS Policy in the given level and appliesOn, update this new policy to have this new processing order and increment all DNS Policies whose processing order is equal to or greater than this processing order by 1.
If pszOperation is DeletePolicy, the server MUST:
If the DNS Policy name specified in pData does not exist in the DNS server, return DNS_ERROR_POLICY_DOES_NOT_EXIST (9972).
Delete the DNS Policy in the DNS server, and return success or failure based on the result.
Reset the processing order of all policies whose processing order is greater than the processing order of the deleted policy by 1 for the given level and appliesOn.
If pszOperation is UpdatePolicy, the server MUST:
If the DNS Policy name specified in the pwszPolicyName of pData does not exist in the server level policies of the DNS server, return DNS_ERROR_POLICY_DOES_NOT_EXIST (9972).
If the flags member of DNS_RPC_POLICY has DNS_RPC_FLAG_POLICY_PROCESSING_ORDER set, the processing order of the DNS policy is changed to the new processing order given in input pData. The processing order of other DNS Policies at the server level for the given appliesOn is adjusted accordingly.
If the flags member of DNS_RPC_POLICY has DNS_RPC_FLAG_POLICY_CONDITION set then the Condition of the DNS Policy is changed to the condition specified in the input pData.
If the flags member of DNS_RPC_POLICY has DNS_RPC_FLAG_POLICY_CONTENT set then the content of the DNS Policy is changed to the content specified in pData.
If any criteria flags specified in Criteria Constants are set, criteria values are removed from the DNS Policy and new criteria values specified in pData are set.
Delete the DNS Policy on the DNS server, and return success or failure based on the result.
If pszOperation is SetRRL, the server MUST do the following. All fields are defined in section 2.2.16.2.1:
Validate the DNS RRL parameters specified in pData and return one of the following error codes if the DNS RRL parameters specified in pData are invalid:
If the dwLeakRate field is invalid, return DNS_ERROR_RRL_INVALID_LEAK_RATE (9916).
If the dwTCRate is field is invalid, return DNS_ERROR_RRL_INVALID_TC_RATE (9915).
If the dwWindowSize field is invalid, return DNS_ERROR_RRL_INVALID_WINDOW_SIZE (9912).
If the dwIPv4PrefixLength field is invalid, return DNS_ERROR_RRL_INVALID_IPV4_PREFIX (9913).
If the dwIPv6PrefixLength field is invalid, return DNS_ERROR_RRL_INVALID_IPV6_PREFIX (9914).
If the dwLeakRate field is less than dwTCRate and none of the fields are 0, return DNS_ERROR_RRL_LEAK_RATE_LESSTHAN_TC_RATE (9917).
Set the RRL parameters in the DNS server based on the passed flag value. Update values only for parameters for which the flag is set. Return success or failure based on the result.
If the fSetDefault value is set, ignore all other parameters and reset all parameters except the RRL mode to default values.
If pszOperation is CreateVirtualizationInstance, the server MUST do the following.
Verify that the length of pwszVirtualizationID does not exceed the maximum allowed. If the maximum is exceeded, then the DNS server MUST return error DNS_ERROR_INVAILD_VIRTUALIZATION_INSTANCE_NAME (9924). If a virtualization instance in the DNS server already exists with same pwszVirtualizationID, then the DNS server MUST return the error DNS_ERROR_VIRTUALIZATION_INSTANCE_ALREADY_EXISTS (9921).
On success, the DNS server creates a virtualization instance; otherwise, return failure.
If pszOperation is DeleteVirtualizationInstance, the server MUST do the following.
Check whether a virtualization instance exists in the DNS server with the name pwszVirtualizationID. If it does not, the DNS server MUST return the error DNS_ERROR_VIRTUALIZATION_INSTANCE_DOES_NOT_EXIST (9922).
If a virtualization instance already exists, then the DNS server MUST delete all zone and zone scopes under the virtualization instance.
If dwFlag is set to DNS_RPC_FLAG_PRESERVE_ZONE_FILE in input DNS_RPC_VIRTUALIZATION_INSTANCE, then the DNS server MUST keep the zone files of the zones and zone scopes under the virtualization instance intact. Otherwise, zone files of zones and zone scopes under the virtualization instance MUST be deleted.
On success, the DNS server removes the virtualization instance given by that name. Otherwise, an error is returned.
If pszOperation is UpdateVirtualizationInstance, the server MUST do the following.
Check whether the length of pwszVirtualizationID is more than the maximum allowed, then return the error DNS_ERROR_INVAILD_VIRTUALIZATION_INSTANCE_NAME (9924).
Check whether a virtualization instance already exists in the DNS server by the name pwszVirtualizationID. If it does not, return the error DNS_ERROR_VIRTUALIZATION_INSTANCE_DOES_NOT_EXIST (9922).
If a virtualization instance already exists, then the DNS server MUST update those properties of the virtualization instance as given by dwFlags of input DNS_RPC_VIRTUALIZATION_INSTANCE (section 2.2.17.1.1). Otherwise, an error is returned.
If pszZone is not NULL and is not a valid multizone operation string, then the server MUST return a failure if it does not contain a zone with the name matching the string pointed to by pszZone. If pszZone is not NULL or if the value of dwContext specifies a multizone operation, the server MUST execute the operation indicated by the value of pszOperation individually for each zone specified by the values of dwContext and pszZone. If a zone operation is performed with a filter in dwContext or a multizone operation string in pszZone, and no zones match the specified filter or satisfy the multizone operation string, the server MUST return ERROR_SUCCESS (0x00000000). If the operation is executed for more than one zone, then for each matching zone, the specified operation MUST be executed with pszZone replaced with the name of the matching zone. If any of these multiple operations return an error, the server MUST return an error; otherwise, the server MUST return success. For any operation, if the specified zone is marked as "AutoCreated", the DNS server MUST return an error.
If pszOperation is ResetDwordProperty, the server MUST verify that the property name matches a property name listed in section 3.1.1.2.1 for which the server supports the ResetDwordProperty operation and return an error if there is no match. If the property is specified as "read-only" in section 3.1.1.2.1, the server MUST return an error. If the zone specified is a cache zone, the server MUST return an error. It MUST further verify that the value specified is within the property's allowable range (if specified) and if not return an error. When the property specified is Boolean and the value to be set is greater than 0x00000001, the server MUST replace the value with 0x00000001. If the property name is "AllowUpdate", the server MUST return an error when the zone specified is not Active Directory-integrated and the requested value is ZONE_UPDATE_SECURE, or when the zone specified is not a primary zone. If the property name is "AllowUpdate" and the value is not ZONE_UPDATE_OFF (section 2.2.6.1.1), then the server SHOULD invoke the NetlogonControl2Ex method with function code NETLOGON_CONTROL_FORCE_DNS_REG on the Netlogon protocol implementation on the local domain controller (DC). (See [MS-NRPC] section 3.5.4.9.1.)<255> If the property name is "Aging", the property value is TRUE, and the zone's Aging state is FALSE, then the server MUST reset the zone's Aging time by updating the dwAvailForScavengeTime (section 2.2.5.2.4.1) value to the current time value, incremented by dwRefreshInterval (section 2.2.5.2.4.1).<256> If the value is zero and zero is listed as a flag value for the default in section 3.1.1.2.1, the server MUST update the value of the property to be the default for that property, and return success. Otherwise, the server MUST update the value of the property for the zone to be the new value specified, and return success.<257>
If pszOperation matches a property name listed in section 3.1.1.2.2 or section 3.1.1.2.3 for which the server supports this property reset operation, the server MUST update the value of the property for the zone to be the new value specified, and return success.<258> Otherwise, the server MUST return a nonzero error code.
If pszOperation is ZoneTypeReset, the server MUST:
Check whether the requested zone type, directory server integration, and (if applicable) application directory partition match the zone's present state, and if so, return success.
Check whether the zone is directory server integrated and currently in the process of loading, and if so, return a failure.
Verify, if the requested zone type is primary, that:
There is a complete copy of the zone on the server (that is, the zone is not a forwarder or stub zone).
If the fDSIntegrated flag is TRUE:
If the zone is a primary zone, that it is not empty.
If the zone is currently directory-server-integrated, it is already stored in the requested by pszDpFqdn, and is not a secondary or cache zone.
If the zone is currently not directory-server-integrated, it is either a cache zone or a primary zone.
If the fDSIntegrated flag is FALSE, that:
A copy of the zone is present in local persistent storage.
The zone is not shutdown, or empty.
If any of the verifications fails, return a failure.
Check whether the requested zone type is secondary, and if so, reset the fDSIntegrated flag of the present zone to false.
Otherwise, the server MUST, in accordance with the operation specified:
If the zone is directory server integrated,<259> use LDAP search operations to find the zone's dnsZone, dnsZoneScope, and dnsNode objects (section 2.3) and copy the appropriate zone properties and data to a file. Set the zone and each of its scopes' Zone GUID properties to NULL.
If the zone is not directory server integrated, copy the zone and its scopes' properties and data to the directory server using LDAP add operations (adding appropriate dnsZone, dnsZoneScope, and dnsNode objects to the directory server). If there is a failure in writing the zone records to the directory server, then the server MUST retry the write operation twice.
Reset the type information to the requested type.
Delete the original zone (using LDAP delete operations to remove the zone's dnsZone, dnsZoneScope, and dnsNode objects if necessary), and return success, or if any of the LDAP operations has failed, even after retries were specified, then return a failure. If deleting the zone from the directory server, the server MUST first attempt up to 4 times to rename the zone being deleted to a temporary name. Regardless of whether the rename is successful, the server MUST then attempt to delete the zone using LDAP delete operations with one of the following conditions for any LDAP error returned ([MS-ERREF] section 2.4):
Retry up to 300 times if LDAP_ADMIN_LIMIT_EXCEEDED (0x0B) is returned.,
Never retry if LDAP_INSUFFICIENT_RIGHTS (0x32) is returned.
Retry up to 30 times for any other LDAP error.
If pszOperation is PauseZone, the server MUST set the zone's Paused flag to TRUE and return success. The same operation MUST be performed for all the existing zone scopes of the zone.
If pszOperation is ResumeZone, the server MUST set the zone's Paused flag to FALSE and return success. The same operation MUST be performed for all the existing zone scopes of the zone.
If pszOperation is DeleteZone, the server MUST delete the zone pointed to by pszZone from the server's local memory only and ensure that the zone will not be loaded at the next reboot and return success. This operation does not modify the zone as it appears in the directory server if it exists there.
The DNS server MUST also delete the associated scopes of that zone. If the zone is file-backed, the database file of the scopes MUST not be deleted.
If pszOperation is ReloadZone, the server MUST check whether the zone pointed to by pszZone is directory server-integrated and is already in the process of loading, and if so, return a failure. Otherwise, if the zone's Dirty Flag (section 3.1.1) is set to TRUE, then the server MUST do the following:
If the zone is a cache zone, and the zone is directory server-integrated and there are root hints in the zone, the server SHOULD write root hints to their permanent storage and overwrite existing directory server root hints through the use of the DNS_ZONE_LOAD_OVERWRITE_DS flag (section 2.2.5.2.7.1). If the root hints are stored on the directory server and DownlevelDCsInDomain is nonzero, the server MUST check whether the root hints are empty. If the root hints are empty, the root hints MUST NOT be written to their permanent storage. Otherwise, if the root hints are stored on the directory server, the server MUST search for and delete the root hints on the directory server using LDAP search and delete commands and write the new root hints to the cache zone on the directory server using LDAP add and modify commands. If there is a failure in writing the root hints records to the directory server, then the server MUST retry the write operation twice.<260>
Otherwise, if the zone is not a read-only zone, write a copy of the zone to a file and send a DNS notification to peer or secondary DNS servers, if any.
If this zone has scopes configured, all the data of the scopes MUST be written one by one to the corresponding scope files if the scope's Dirty Flag (section 3.1.1) is set to TRUE. If writing to any of the scopes encounters an issue, an error event SHOULD be logged and an error code returned.
Then the server MUST do the following:
If the zone is a secondary zone, check that it has been stored to a file, and if not, return a failure.
If the zone is directory server-integrated, use the LDAP search operation to load the zone's dnsZone and dnsNode objects (section 2.3) from the directory server into memory and return success. If the zone has scopes, the DNS server MUST try to load the scope's dnsZoneScope and dnsNode objects one by one. If any scopes fail to load from the file, an event SHOULD be logged and an error returned.
Otherwise, load the zone from the file, and return success. If the zone has scopes, then the DNS server MUST try to load the scopes one by one. If any of the scope fails to load from the file, an event SHOULD be logged and an error returned.
If any of the above LDAP operations fails, even after retries, where specified, then return a failure.
If pszOperation is RefreshZone, and the zone specified is a secondary zone, is not currently transferring from the primary server, and at least 15 seconds has elapsed since the Time of Last SOA check (section 3.1.1) of the primary zone, then the server MUST force a refresh of the secondary zone pointed to by pszZone, from the primary DNS server, and return success. Otherwise, the server MUST return an error.
If pszOperation is ExpireZone, the server MUST force refresh of the secondary zone pointed to by pszZone by contacting the primary DNS server to refresh, and return success.
If pszOperation is IncrementVersion,, the server MUST return a failure if the zone is not a primary or cache zone, and it MUST return success if the zone's Dirty Flag (section 3.1.1) is set to FALSE or the zone is not stored in a file. Otherwise, the server MUST write the uncommitted information to the file, send DNS notify [RFC1996] messages to all other servers hosting the zones, if they exist, and return success. If the zone specified is the cache zone, the server SHOULD write the root hints to their permanent storage. If the root hints are stored on the directory server and DownlevelDCsInDomain is nonzero, the server MUST check whether the root hints are empty. If the root hints are empty, the root hints MUST NOT be written to their permanent storage. Otherwise, if the root hints are stored on the directory server, the server MUST use LDAP add, delete, and search operations to replace the root hints on the directory server, and return success, regardless of the success or failure of these operations. If there is a failure in writing the root hints records to the directory server, then the server MUST retry the write operation twice, and still return success even if the retries fail.<261>
If pszOperation is WriteBackFile, the server MUST return a failure if the zone is not a primary or cache zone, and it MUST return success if the zone's Dirty Flag (section 3.1.1) is set to FALSE and it does not have any scopes configured or the zone is not stored in a file. Otherwise, the server MUST write the uncommitted information to the file, send DNS notify ([RFC1996]) messages to all other servers hosting the zones, if they exist, and return success, regardless of the success or failure of these operations. If the zone has scopes, the data of the scopes MUST be written to their corresponding scope files if the scope's Dirty Flag (section 3.1.1) is set to TRUE. If the server fails to write the data for any of the scopes it SHOULD log an error event and return the error code. If the operation results in updates only in the scope files and not the zone file, then DNS notify ([RFC1996]) messages SHOULD NOT be sent. If the zone specified is the cache zone, the server SHOULD write the root hints to their permanent storage. If the root hints are stored on the directory server and DownlevelDCsInDomain is nonzero, the server MUST check whether the root hints are empty. If the root hints are empty, the root hints MUST NOT be written to their permanent storage. Otherwise, if the root hints are stored on the directory server, the server MUST use LDAP add, delete, and search operations to replace the root hints on the directory server, and return success, regardless of the success or failure of these operations. If there is a failure in writing the root hints records to the directory server, then the server MUST retry the write operation twice, and still return success even if the retries fail.<262>
If pszOperation is DeleteZoneFromDs, the server MUST leave the zone, represented by a dnsZone object (section 2.3), intact and return a failure if the specified zone is not directory service-integrated. Otherwise, the server MUST locate the zone and its records, represented by dnsNode objects (section 2.3) using LDAP search operations. The server MUST rename the dnsZone object by prepending "..Deleted-" (or "..Deleted.<random number>-" if "..Deleted-" already exists) to the zone's name. The server MUST then attempt to delete the zone and its records using LDAP delete operations with one of the following conditions for any LDAP error returned ([MS-ERREF] section 2.4):
Retry up to 300 times if LDAP_ADMIN_LIMIT_EXCEEDED (0x0B) is returned.
Never retry if LDAP_INSUFFICIENT_RIGHTS (0x32) is returned.
Retry up to 30 times for any other LDAP error returned.
If the deletion from the directory server was successful, then the server MUST delete the local memory copy of the zone and return success. If any of these LDAP operations cannot be completed, even after retries where specified, then the server MUST return a failure.
If pszOperation is UpdateZoneFromDs, the server MUST:
Verify that the zone is not currently loading if it is a directory server integrated zone; otherwise, return a failure.
Refresh data for the zone from the directory server, and return success or failure depending on the result of this operation.
If pszOperation is ZoneExport, the server SHOULD:
Verify that the zone is not currently loading if it is a directory server integrated zone; otherwise, return a failure.
Export zone data for the zone to a file on the DNS server specified by pszZoneExportFile in pData, and return success or failure depending on the result of this operation, but MAY<263> simply return a failure.
If pszOperation is ZoneChangeDirectoryPartition, the server MUST:
Verify that the specified zone is not currently loading; otherwise, return a failure.
Verify that the application directory partition specified by pszDestPartition (section 2.2.7.2.6) in pData is already known to the server; otherwise, return a failure.
Verify that the specified zone is not already in the destination application directory partition; otherwise, return success.<264>
Create a backup copy of the zone properties (the dnsZone object) in local storage using LDAP search operations, and then create a temporary dnsZone object in the new application directory partition with the zone properties from the backup copy, using LDAP add operations. If a failure occurs, the server MUST delete the temporary zone using the LDAP search and delete operations and return a failure.
Copy the records (dnsNode objects) of the old zone to the temporary zone by enumerating the old zone's records using an LDAP search operation and by writing the new records to the temporary zone using LDAP add operations. If there is a failure in writing the records to the directory server, then the server MUST retry the write operation twice. If the search fails or the new records cannot be written, then the server MUST attempt to delete the temporary zone using the LDAP search and delete operations with the following conditions for any LDAP error returned [MS-ERREF] section 2.4):
Retry up to 300 times if LDAP_ADMIN_LIMIT_EXCEEDED (0x0B) is returned.
Never retry if LDAP_INSUFFICIENT_RIGHTS (0x32) is returned.
Retry up to 30 times for any other LDAP error.
Return a failure.
Rename the temporary zone to the final zone name using the LDAP rename operation. Delete the original zone's dnsZone and dnsNode objects using the LDAP search and delete operations. If the LDAP rename operation fails, the server MUST attempt to delete the temporary zone with the following conditions for any LDAP error returned [MS-ERREF] section 2.4):
Retry up to 300 times if LDAP_ADMIN_LIMIT_EXCEEDED (0x0B) is returned.
Never retry if LDAP_INSUFFICIENT_RIGHTS (0x32) is returned.
Retry up to 30 times for any other LDAP error returned.
Return a failure. Otherwise, the server MUST return a success.
If pszOperation is DeleteNode, then:
If the node does not exist, the server MUST return success.
Otherwise, if the node specified is not in a primary zone, a cache zone, a cache scope, or a zone scope of a primary file backed zone, or the node is the root node for a zone, the server MUST return failure.
Otherwise, if the zone containing the specified node is not directory server-integrated, the server MUST delete the node pointed to by pszNodeName from the zone, MUST delete all DNS records in the node's subtree if the Boolean flag pointed to by the dwParam field in pData is set to TRUE, and return success.
Otherwise,
If the Boolean flag pointed to by the dwParam field in pData is set to TRUE, the server MUST poll the directory server for zone changes, using LDAP search operations.
If the Boolean flag pointed to by the dwParam field in pData is set to FALSE and the node contains subtrees, both the node and its subtrees MUST NOT be deleted and a success status MUST be returned.
If the node to be deleted is not a cache node, then the server MUST locate the node's dnsNode object (section 2.3) and its children using LDAP search operations, and then perform LDAP modify operations to set each node's dnsTombstoned attribute to TRUE and each node's dnsRecord (section 2.3.2.2) attribute to contain a DNS_RPC_RECORD_TS record (section 2.2.2.2.4.23) with an EntombedTime value equal to the current time expressed as the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC).
If any of these LDAP operations fails, the server MUST attempt to roll back the previous operations using LDAP modify operations and return failure. If, during an attempt to roll back the deletions, any LDAP operation fails, the server MUST retry up to 2 times, and return failure.
If pszOperation is DeleteRecordSet, and the node does not exist or the node exists but does not contain any records, represented as dnsNode objects (section 2.3) of the type specified by the dwParam field in pData the server MUST return success. If the zone is directory server-integrated, the server MUST verify with an LDAP search that the node and/or records don't exist before returning success. Otherwise, the server MUST delete the record set of the type specified by dwParam field in pData (using LDAP modify operations when the zone is directory server-integrated) and return success. If deleting the record set would delete all records for the node and the zone is stored in the directory server, the DNS server MUST set the node's dnsTombstoned attribute to TRUE and each node's dnsRecord (section 2.3.2.2) attribute to contain a DNS_RPC_RECORD_TS record (section 2.2.2.2.4.23) with an EntombedTime value equal to the current time expressed as the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC). If any of these LDAP operations fails, the server MUST return failure.
If pszOperation is ForceAgingOnNode, the zone's "Aging" (section 3.1.1.2.1) property is TRUE, and the node pointed to by pszNodeNameexists, the server MUST enable aging on the node name pointed to by pszNodeName in the zone and MUST enable aging on the node's subtree if specified by the dwParam value in pData and return success. Otherwise, the server MUST return a failure.
If pszOperation is AllowNSRecordsAutoCreation, the server MUST verify that the zone referenced is a primary zone and that it is a directory service-integrated zone and that it is not in the process of loading. If the verification fails, the server MUST return a failure. If the verification succeeds, the server MUST replace the list of IP addresses for which NS records will be automatically created with the list specified by pData, in the properties for the zone specified by pszZone, and use the LDAP modify operation to write all of the zone's properties to the copy of the zone on the directory server. Then, if any of the server's IP addresses are present in the new list of IP addresses and an NS record for the server is not present in the root of the zone, the server MUST add an NS record for the server to the zone, using the LDAP add operation. If there is a failure in writing the record to the directory server, then the server MUST retry the write operation twice. If none of the server's IP addresses are present in the new list of IP addresses and an NS record for the server is present in the root of the zone, the server MUST delete the NS record for the server from the zone, using the LDAP delete operation. Finally, if any of these LDAP operations could not be completed, even after retries where specified, then the server MUST return a failure; otherwise, the server MUST return success.
If pszOperation is DatabaseFile, the server MUST:
Verify that the zone pointed to by pszZone exists; that if the fDsIntegrated field of the DNS_RPC_ZONE_DATABASE structure is set to TRUE, the zone is directory services-integrated, and is not in the process of loading; and that if fDsIntegrated is set to FALSE, the zone is not directory services-integrated. If any of these verifications fail, the server MUST return a failure.
Check whether pszFilename is not NULL and fDsIntegrated is TRUE, and if so, return a failure.
Check whether pszFilename is NULL and fDsIntegrated is TRUE, and if so, return success.
Check whether pszFilename is NULL and fDsIntegrated is FALSE, and if so, create the default database file for the zone and configure the zone to use that file, and return success.
Check whether pszFilename is not NULL and fDsIntegrated is FALSE, and if so, create the database file specified by pszFilename for the zone and configure the zone to use that file, and return success, or return a failure if the file name could not be created as specified.
If pszOperation is SignZone, the server MUST:
Verify that the zone pointed to by pszZone exists, that the zone's IsSigned property is FALSE, that the zone is a Primary zone, and that the zone's Keymaster property is set to TRUE. If any of these verifications fails, the server MUST return a failure.
Check whether the EnableOnlineSigning server property is TRUE. If it is FALSE and the zone is directory services-integrated, the server MUST return a failure.
Add appropriate DNSSEC records to the zone according to the entries in the zone's signing key descriptor list and [RFC4035], and return failure if any operation fails.
If the zone has scopes, the server MUST initiate signing on the zone scopes. If any of the scope signing fails, the zone MUST be marked as unsigned, an appropriate event is logged, and an error code is returned.
Set the zone's IsSigned flag to TRUE, and return success.
If pszOperation is UnsignZone, the server MUST:
Verify that the zone pointed to by pszZone exists, that the zone's IsSigned property is TRUE, that the zone is a Primary zone, and that the zone's Keymaster property is set to TRUE. If any of these verifications fails, the server MUST return a failure.
Check whether the EnableOnlineSigning server property is TRUE. If it is FALSE and the zone is directory services-integrated, the server MUST return a failure.
Remove all DNSSEC records of type DNSKEY, RRSIG, NSEC, and NSEC3 from the zone, and return failure if any operation fails.
If the zone has scopes, the server MUST unsign all the scopes one by one. If any of the scopes fails to be unsigned the value of the zone IsSigned property MUST be kept unchanged, an appropriate event is logged, and an error code is returned.
Set the zone's IsSigned flag to FALSE, and return success.
If pszOperation is ResignZone, the server MUST:
Verify that the zone pointed to by pszZone exists, that the zone's IsSigned property is TRUE, that the zone is a Primary zone, and that the zone's Keymaster property is set to TRUE. If any of these verifications fails, the server MUST return a failure.
Check whether the EnableOnlineSigning server property is TRUE. If it is FALSE and the zone is directory services-integrated, the server MUST return a failure.
Regenerate all DNSSEC records in the zone as done for the SignZone operation, and return failure if any operation fails.
If the zone has scopes, the server MUST start the re-sign operation on them. If any of the scopes fail to re-sign, the value of the zone IsSigned property MUST be kept unchanged, an appropriate event SHOULD be logged, and an error code MUST be returned.
Return success.
If pszOperation is PerformZoneKeyRollover, the server MUST:
Verify that the zone pointed to by pszZone exists, that the zone's IsSigned property is TRUE, that the zone is a Primary zone, and that the zone's Keymaster property is set to TRUE. If any of these verifications fails, the server MUST return a failure.
Find the signing key descriptor indicated by pData in the zone's signing key descriptor list. If the signing key descriptor is not in this list, the server MUST return a failure.
Put the specified signing key descriptor into the zone's rollover queue, and return success.
If pszOperation is PokeZoneKeyRollover, the server MUST:
Verify that the zone pointed to by pszZone exists, that the zone's IsSigned property is TRUE, that the zone is a Primary zone, and that that the zone's Keymaster property is set to TRUE. If any of these verifications fails, the server MUST return a failure.
Find the signing key descriptor indicated by pData in the zone's signing key descriptor list. If the signing key descriptor is not in this list, the server MUST return a failure.
If the dwCurrentRolloverStatus member of the DNS_RPC_SKD_STATE structure for this signing key descriptor is not DNS_SKD_STATUS_KSK_WAITING_FOR_DS_UPDATE, the server MUST return a failure.
Otherwise, the DNS server MUST advance the dwCurrentRolloverStatus member of the DNS_RPC_SKD_STATE structure for this signing key descriptor to DNS_SKD_STATUS_KSK_WAITING_FOR_DS_TTL and proceed with key rollover for this signing key descriptor as specified in [RFC4641], and return success.
If pszOperation is RetrieveRootTrustAnchors, the server MUST:
Verify that:
The zone pointed to by pszZone is the Trust Anchors zone.
The server is not a read-only server.
The EnableDnsSec server property (section 3.1.1.1.1) is TRUE.
The RootTrustAnchorsURL property (section 3.1.1.1.3) is not NULL, that the scheme is "https", and that the host and url-path are nonempty (see [RFC1738]).
If any of these verifications fails, return a failure. Otherwise, the server MUST:
Create the Trust Anchors zone if it does not exist. If the creation fails, return an error.
Open an HTTPS connection to the host and port defined by the RootTrustAnchorsURL property. If the connection fails or times out, return an error.
Retrieve the XML document specified by the url-path or return an error.
Parse the XML document strictly according to the schema defined in [draft-jabley-dnssec-trust-anchor-03]. If the XML document deviates from the schema, return an error.
For each DS trust anchor specified by the XML document, verify that the algorithm and digest type are supported by the server, and that the length of the digest is valid. If the DS trust anchor is unsupported, continue to the next DS trust anchor. If none of the trust anchors are supported, return an error. If the trust anchor is supported and the digest length is invalid, return an error. Otherwise, add the trust anchor to a list of pending trust anchors.
Add each trust anchor in the pending list of trust anchors to the root node of the Trust Anchors zone. If the add attempt fails, return an error.
Schedule an immediate RFC 5011 active refresh for all trust points, and return success.
If pszOperation is TransferKeymasterRole, the server MUST:
Verify that dwTypeId is DNSSRV_TYPEID_DWORD and that pData points to one of the following values. If any of these verifications fails, the server MUST return a failure.
Value
Meaning
DNS_ZONE_TRANSFER_KEYMASTER_ROLE
0x00000001
Assign the key master role to the current server only if the zone is currently signed and the current server has access to the private key material corresponding to the signing key descriptors for the zone.
DNS_ZONE_SEIZE_KEYMASTER_ROLE
0x00000002
Force assignment of the key master role to the current server, allowing assignment on unsigned zones or zones with no signing key descriptors. If the zone has signing key descriptors, this operation MUST return a failure if private key material for all signing key descriptors is not accessible by the current server.
DNS_ZONE_POLL_KEYMASTER_ROLE
0x00000003
Requests that the server refresh the key master zone flags by reading from the directory service.
DNS_ZONE_SEIZE_KEYMASTER_ROLE_WITHOUT_KEY_CHECKS
0x00000004
Force assignment of the key master role to the current server, without checking to see whether private key material is accessible by the current server.
Verify that the zone pointed to by pszZone exists, that the zone is a Primary zone that is directory services-integrated, and that the zone is not read-only. If any of these verifications fails, the server MUST return a failure.
If the value of pData is DNS_ZONE_TRANSFER_KEYMASTER_ROLE or DNS_ZONE_SEIZE_KEYMASTER_ROLE or DNS_ZONE_SEIZE_KEYMASTER_ROLE_WITHOUT_KEY_CHECKS, the server MUST:
Verify that the IsSigned property of the zone (section 3.1.1.2.1) is TRUE or that the value of pData is DNS_ZONE_SEIZE_KEYMASTER_ROLE. If not, return a failure.
For an AD-backed zone, refresh the list of key master servers from the directory service or, if this operation fails, return a failure.
Return success if the IsKeymaster property of the zone (section 3.1.1.2.1) is TRUE and the value of pData is DNS_ZONE_TRANSFER_KEYMASTER_ROLE.
For an AD-backed zone, check whether the value of pData is DNS_ZONE_TRANSFER_KEYMASTER_ROLE or DNS_ZONE_SEIZE_KEYMASTER_ROLE and the zone has one or more signing key descriptors and, if so, verify that the private key material is available for each of the signing key descriptors.
For a file-backed zone, check whether the value of pData is DNS_ZONE_SEIZE_KEYMASTER_ROLE and the zone has one or more signing key descriptors and, if so, verify that the private key material is available for each of the signing key descriptors.
For an AD-backed zone, query the directory service for the value of the current key master. If this operation fails, and the value of pData is DNS_ZONE_TRANSFER_KEYMASTER_ROLE, return a failure.
For an AD-backed zone, check whether the value of pData is DNS_ZONE_TRANSFER_KEYMASTER_ROLE and, if so, verify that the query in the preceding step returned a value for the current key master, and that the current key master is marked as a key master by invoking the R_DnssrvQuery2 operation (section 3.1.4.7) on the current key master. The pszZone value used MUST match the value of pszZone passed to this operation, and pszOperation MUST be set to "IsKeymaster". If the current key master returns an error or FALSE, return a failure.
For an AD-backed zone, refresh the zone properties from the directory service. If this operation fails, the server MUST ignore the failure.
For an AD-backed zone, perform an LDAP modify operation to add the DN of the zone to the msDNS-KeymasterZones attribute of the server settings object ("CN=DNS Settings,CN=<server_name>,CN=Servers,CN=<site_name>, CN=Sites,CN=Configuration,DC=<domain name>") or, if this operation fails, return a failure.
For an AD-backed zone, perform an LDAP delete operation to delete the DN of the zone from the msDNS-KeymasterZones attribute of the previous key master server settings object ("CN=DNS Settings,CN=<previous_keymaster_server_name>,CN=Servers,CN=<site_name>, CN=Sites,CN=Configuration,DC=<domain name>") or, if this operation fails, return a failure.
For an AD-backed zone, check whether the value of pData is DNS_ZONE_TRANSFER_KEYMASTER_ROLE and, if so, perform the TransferKeymasterRole operation on the previous key master, with all parameters matching those passed to the current operation except that pData MUST point to DNS_ZONE_POLL_KEYMASTER_ROLE. If this operation fails, the server MUST ignore the failure.
Return success.
If the value of pData is DNS_ZONE_POLL_KEYMASTER_ROLE, the server MUST:
Open an LDAP connection to the Domain Naming Master FSMO role holder or to the local directory service if an LDAP connection to the Domain Naming Master FSMO role holder cannot be opened.
Perform an LDAP search operation to retrieve the value of the msDNS-KeymasterZones attribute of the DNS server settings object ("CN=DNS Settings,CN=<server_name>,CN=Servers,CN=<site_name>, CN=Sites,CN=Configuration,DC=<domain name>") and, if the operation fails, return a failure.
The DNS server MUST iterate each zone in the DNS Zone Table (section 3.1.1.2) and for each zone:
If the zone is not directory service-integrated, ignore it.
Otherwise, if the zone is present in the msDNS-KeymasterZones attribute and the zone's IsKeymaster property (see section 3.1.1.2.1) is not TRUE or if the zone is not present in the msDNS-KeymasterZones attribute and the zone's IsKeymaster property is TRUE:
Set the zone's IsKeymaster property (section 3.1.1.2.1) to TRUE if the zone is present in the msDNS-KeymasterZones attribute or to FALSE if the zone is not present in the msDNS-KeymasterZones attribute.
Retrieve the FQDN of the zone's current key master: if the zone's IsKeymaster property is TRUE, set the zone's Keymaster property to the FQDN of the local host; otherwise, perform an LDAP search using the search filter "(&(msDNS-KeymasterZones=<zone name>)(objectCategory=msDNS-ServerSettings))" and set the zone's Keymaster property to the dnsHostName attribute value found on the parent object of the object returned by this search.
If pszOperation is CreateZonescope, the server MUST:
Verify that the zone pointed to by pszZone exists, that it is not an autocreated zone, that it is a non-reverse lookup zone, and that a scope does not exist with the given scope name in the specified zone. If any of these verifications fails, the server MUST return a failure. For cache scopes, if the scope does exist in the cache, the server MUST return a failure.
Create the zone scope or cache scope with the given scope name and return success if the creation is successful, otherwise return a failure.
If the zone uses directory server for persistent storage, the server MUST:
Perform an LDAP search in the dnsZone object of the zone to determine whether the scope already exists, and if so, return failure.
Create the zone scope in the same application directory partition.
Using LDAP add operations:
Create a dnsZoneScopeContainer object with name "ZoneScopeContainer" in the zone's dnsZone object (if it does not already exist).
Create a dnsZoneScope object in the dnsZoneScopeContainer object.
If pszOperation is DeleteZonescope, the server MUST:
Verify that the zone pointed to by pszZone exists, that it is not an autocreated zone, that it is a non-reverse lookup zone, and that a scope does exist with the given scope name in the specified zone. If any of these verifications fails, the server MUST return a failure. For a cache scope, delete the scope if it exists; otherwise the server MUST return a failure.
If the zone scope or cache scope specified in pData does not exist, return DNS_ERROR_SCOPE_DOES_NOT_EXIST (9959).
If the zone scope or cache scope is being used by a DNS Policy (section 2.2.15.2.2), then the DNS server MUST return DNS_ERROR_ZONESCOPE_IS_REFERENCED (9989).
The DNS server MUST attempt to delete the zone scope or cache scope in the DNS server, and return success or failure based on the result.
If pszOperation is CreatePolicy, the server MUST:
The DNS server checks whether the zone specified by pszZone exists and, if not, returns DNS_ERROR_ZONE_DOES_NOT_EXIST (9601).
The DNS server validates whether the DNS Policy parameters specified in pData are valid. If the parameters are invalid, return DNS_ERROR_POLICY_INVALID_SETTINGS (9974). For details, see DNS Policy Validation (section 3.1.8.3).
If the DNS Policy pData parameter dwProcessingOrder is greater than the highest Processing Order in the given level and appliesOn for the zone, return DNS_ERROR_POLICY_INVALID_SETTINGS (9974).
If the DNS Policy name as specified in the pData parameter pwszPolicyName already exists, return DNS_ERROR_POLICY_ALREADY_EXISTS (9971). The policy name check is done for the policies configured on the zone.
If the value weight in pContentList is 0, as explained in DNS_RPC_POLICY_CONTENT (section 2.2.15.2.2), the DNS server returns DNS_ERROR_POLICY_INVALID_WEIGHT (9981). Allowed values for weight are any positive number from 1 to 0xFFFFFFFF.
If DNS Policy pData parameter dwProcessingOrder is 0 then reset the processing order to the last processing order for the specified level and appliesOn in the zone.
Create the new DNS Policy on the DNS server, and return success or failure based on the result. This DNS Policy is applicable to the DNS operations at the zone level for that zone.
If the DNS Policy pData parameter dwProcessingOrder is the same as an existing DNS Policy in the specified level and appliesOn of the zone, update this new policy to use the new processing order. All DNS Policies whose processing order is equal to or greater than this processing order are incremented by 1.
If pszOperation is DeletePolicy, the server MUST:
If the zone specified by pszZone does not exist, return DNS_ERROR_ZONE_DOES_NOT_EXIST (9601).
If the DNS Policy name specified in pData does not exist in the zone, return DNS_ERROR_POLICY_DOES_NOT_EXIST (9972).
Delete the DNS Policy in the zone of the DNS server, and return success or failure based on the result.
Increment the processing order of all policies whose processing order is greater than the processing order of the deleted policy by 1 for the given level and appliesOn in the zone.
If pszOperation is UpdatePolicy, the server MUST:
If the zone given by pszZone does not exist, return DNS_ERROR_ZONE_DOES_NOT_EXIST (9601).
If the DNS Policy name specified in the member pwszPolicyName of pData does not exist in the specified zone policies of the DNS server, return DNS_ERROR_POLICY_DOES_NOT_EXIST (9972).
If the flags member of DNS_RPC_POLICY has DNS_RPC_FLAG_POLICY_PROCESSING_ORDER set, update the processing order of the DNS policy to the new processing order specified in the input pData. Adjust the processing order of other DNS Policies at that zone for the given appliesOn accordingly.
If the flags member of DNS_RPC_POLICY has DNS_RPC_FLAG_POLICY_CONDITION set, then update the Condition of the DNS Policy to the condition specified in the input pData.
If the flags member of DNS_RPC_POLICY has DNS_RPC_FLAG_POLICY_CONTENT set, then update the content of the DNS Policy to the content specified in pData.
If any criteria flags as specified in Criteria Constants are set, remove the criteria values from the DNS Policy and set new criteria values as specified in pData.
Delete the DNS Policy on the DNS server, and return success or failure based on the result.