3.1.4.5 R_DnssrvUpdateRecord (Opnum 4)

  • Article

The R_DnssrvUpdateRecord method is used to add a new DNS record or modify/delete an existing DNS record at the server. This operation SHOULD<277> be supported.

 LONG R_DnssrvUpdateRecord(
   [in]                       handle_t                 hBindingHandle,
   [in, unique, string]       LPCWSTR                  pwszServerName,
   [in, unique, string]       LPCSTR                   pszZone,
   [in, string]               LPCSTR                   pszNodeName,
   [in, unique]               PDNS_RPC_RECORD          pAddRecord,
   [in, unique]               PDNS_RPC_RECORD          pDeleteRecord
 );

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

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

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

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

pAddRecord: A pointer to a structure of type DNS_RPC_RECORD (section 2.2.2.2.5) that contains information based on the operation being performed as specified below.

pDeleteRecord: A pointer to a structure of type DNS_RPC_RECORD (section 2.2.2.2.5) that contains information based on the operation being performed as specified below.

To add a record:

  • pAddRecord: The DNS RR data of the new record.

  • pDeleteRecord: MUST be set to NULL.

To delete a record:

  • pAddRecord: MUST be set to NULL.

  • pDeleteRecord: Individual DNS RR data of the record to be deleted.

To replace a record:

  • pAddRecord: New record data.

  • pDeleteRecord: Old record data.

To add an empty node:

  • pAddRecord: MUST be set to NULL.

  • pDeleteRecord: MUST be set to NULL.

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success or a non-zero Win32 error code if an error occurred. See [MS-ERREF] section 2.2 or section 2.2.1.1.5. All error values MUST be treated the same.

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.

  • The server SHOULD support pAddRecord and/or pDeleteRecord for the explicitly defined types in section 2.2.2.1.1.<278> If any of the passed record types are not supported by the server, return a failure.

  • If the pAddRecord is for an explicitly defined resource record type DNS_TYPE_CNAME (section 2.2.2.1.1), then delete any existing DNS_TYPE_CNAME record for the node specified in pszNodeName, before adding the record.

  • If the pAddRecord is for adding a new record to a dnsNode that has or had a static resource record (with TimeStamp at 0), then the new record is added as a static record.<279>

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

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

  • Locate the node indicated by pszNodeName in the zone indicated by pszZoneName. If no such node is found then return ERROR_SUCCESS.

  • If both pAddRecord and pDeleteRecord are NULL, then the server MUST add an empty node to the database if the node does not already exist. If the node already exists, the server MUST return ERROR_SUCCESS.

  • If pszZoneName is NULL or points to "..Cache" then the operation SHOULD be performed on the DNS server's cache and MAY be performed on the DNS server's set of root hint records.<280> If pszZoneName points to "..RootHints" then the operation MUST be performed on the DNS server's set of root hint records.

  • If pszZoneName points to a primary zone, attempt to perform addition/deletion/update of the record. If the operation is successful, increment the zone serial number using serial number arithmetic [RFC1982]. If the zone is directory server-integrated and the update causes new or modified records to be committed to the directory, the new zone serial number MUST also be written to the Serial field of the dnsRecord attribute (section 2.3.2.2). If the last record at the node is being deleted and the zone is stored in the directory server or is directory server-integrated, the DNS server MUST set the node's dnsTombstoned attribute to TRUE and the node's dnsRecord 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 a node indicated by pszNodeName already exists and has at least one record for which aging is disabled, then subsequent records added on the node will also have aging disabled.

  • If both pAddRecord and pDeleteRecord are not NULL and a resource record is being replaced, if the dwFlags field is not set to DNS_RPC_FLAG_RECORD_CREATE_PTR, the PTR record for the A/AAAA record being replaced is deleted. If the dwFlags field is set to DNS_RPC_FLAG_SUPPRESS_RECORD_UPDATE_PTR, the PTR record of the A/AAAA record being replaced is not deleted.

  • Return success or a failure to indicate the result of the attempted operation.