tfDnsUpdatePrereq

Table of Contents >> Application Reference >> Dynamic DNS Update

#include <trsocket.h>

int tfDnsUpdatePrereq	(
	ttDnsUpdateHandle dnsUpdateHandle,
	int prereqType,
	const char * domainNamePtr,
	unsigned int rrType,
	const char * dataPtr,
	int dataLength,
	int dataType
	);

Function Description

Set a prerequisite condition to be sent as part of a DNS update request. The DNS server uses the current contents of the master zone file to determine whether a prerequisite is true or false. Only if all prerequisites are true does the server commit the update. Otherwise, an error reply is returned to the requestor. This function can be called zero or more times to set different conditions prior to sending the request. Prerequisites help to resolve conflicts between multiple hosts requesting to update the same resource record. The supported prerequisite types are listed in the Prerequisite Types section below (details can be found in RFC 2136).

Depending on the prerequisite type, the data at dataPtr can provided in a convenient form (e.g. ASCII string), then encoded, as required by the server, prior to transmission. The incoming data format and the encoding algorithm are determined by the dataType parameter. See the Data Types section below.

Parameters

• dnsUpdateHandle

  A DNS update descriptor handle returned by tfDnsUpdateOpen().

• prereqType

  The prerequisite type (see the Prerequisite Types section below).

• domainNamePtr

  The domain name to match (NUL terminated ASCII string, e.g. "www.example.com").

• rrType

  The DNS resource record type to match (e.g. TM_DNS_RR_TYPE_A, TM_DNS_RR_TYPE_PTR). This parameter is ignored for some prerequisite types.

• dataPtr

  The RDATA to match. Specify NULL for any data. This parameter is ignored for some prerequisite types.

• dataLength

  If dataPtr is not NULL, this is the length of data at dataPtr. If dataPtr is a NUL terminated ASCII string, you can set dataLength to -1 (depending on dataType, see the Data Types section below).

• dataType

  If dataPtr is not NULL, this specifies the type of data at dataPtr and how to encode the data in the outbound request message (see the Data Types section below).

Prerequisite Types

• TM_DNS_UPDATE_PREREQ_NXDOMAIN

  Domain name is not in use. No resource record of any type must exist for domainNamePtr. Parameters rrType, dataPtr, dataLength and dataType are ignored.

• TM_DNS_UPDATE_PREREQ_YXDOMAIN

  Domain name is in use. At least one resource record must exist for domainNamePtr. Parameters rrType, dataPtr, dataLength and dataType are ignored.

• TM_DNS_UPDATE_PREREQ_NXRRSET

  RRset does not exist. No resource record of type rrType must exist for domainNamePtr. Parameters dataPtr, dataLength and dataType are ignored.

• TM_DNS_UPDATE_PREREQ_YXRRSET

  RRset exists. At least one resource record of type rrType must exist for domainNamePtr. If parameter dataPtr is not NULL, this is considered a value dependent condition. With a value dependent condition, the set of resource records with name domainNamePtr and type rrType must have members with the same RDATAs as data dataPtr for all such prerequisites you specify. In other words, if www.example.com has 2 different IPv4 addresses, you can't just check one address—you must provide prerequisites for both addresses or the update will fail.

Data Types

• TM_DNS_UPDATE_DATA_BINARY

  Data at dataPtr is binary with length dataLength. The data will be sent without modification.

• TM_DNS_UPDATE_DATA_DOMAIN

  Data at dataPtr is a domain name encoded as an ASCII string (e.g. "www.example.com"). The data will be converted to binary form before being sent (see RFC 1035 section 3.1). If dataLength is -1, the string must be NUL terminated and the length will be derived from the string length.

• TM_DNS_UPDATE_DATA_IPV4

  Data at dataPtr is an IPv4 address encoded as an ASCII string (e.g. "192.168.1.20"). The data will be converted to a 32-bit binary value before being sent. If dataLength is -1, the string must be NUL terminated and the length will be derived from the string length.

• TM_DNS_UPDATE_DATA_IPV6

  Data at dataPtr is an IPv6 address encoded as an ASCII string (e.g. "2001:db8::6f"). The data will be converted to a 128-bit binary value before being sent. If dataLength is -1, the string must be NUL terminated and the length will be derived from the string length.

• TM_DNS_UPDATE_DATA_TEXT

  Data at dataPtr is plain text encoded as an ASCII string (e.g. "Hello World!"). The data will be encoded as a character-string (prefixed with a single length byte: see RFC 1035 section 3.3). If dataLength is -1, the string must be NUL terminated and the length will be derived from the string length.

Returns

• TM_ENOERROR

  Success.

• TM_EINVAL

  Invalid descriptor handle, domain name or prerequisite type.

• TM_EPERM

  Cannot change the descriptor while tfDnsUpdateSend() is in progress.

• TM_ENOBUFS

  Insufficient memory.

Table of Contents >> Application Reference >> Dynamic DNS Update