This appendix describes the DHCP extension dictionary entries and the application program interface (API) to the extension dictionary. It describes the data items available in the request and response dictionaries, and the calls to use when accessing dictionaries from Tcl extensions and shared libraries.
Extension Dictionary Entries
A dictionary is a data structure that contains key-value pairs. There are two types of dictionaries: the attribute dictionaries the request and response dictionaries use, and the environment dictionary. This section describes the request and response dictionaries; the environment dictionary entries are described in the "Tcl Environment Dictionary Methods" section.
Decoded DHCP Packet Data Items
The decoded DHCP packet data items represent the information in the DHCP packet, and are available in both the request and response dictionaries. These dictionaries provide access to considerably more internal server data structures than just the decoded request and decoded response.
All of the options followed by an asterisk (*) are multiple, which means that there may be more than one value associated with each option. In the DHCP/BOOTP packet, all of these data items appear in the same option. However, in the extension interface, these multiple data items are accessible through indexing.
You can access options that do not have names in Table C-2 as option-n, where n is the option number. All fields are read/write. Table C-1 describes the field values for the options.
blob (the first byte must be the type byte, with 0 for RFC 1035 encoding, and 1 for IP address encoding, for which the address must be in network order)
ccc-as-backoff-retry- blob
4
12-byte blob (3 unsigned 4-byte integers, which must be in network order); configures the Kerberos AS-REQ/AS-REP timeout, backoff, and retry mechanism
ccc-ap-backoff-retry- blob
5
12-byte blob (3 unsigned 4-byte integers, which must be in network order); configures the Kerberos AP-REQ/AP-REP timeout, backoff, and retry mechanism
ccc-kerberos-realm
6
variable-length blob (an RFC 1035 style name); a Kerberos realm name is required
ccc-use-tgt
7
1-byte unsigned integer boolean; indicates whether to use a Ticket Granting Ticket (TGT) when obtaining a service ticket for one of the application servers
ccc-provisioning-timer
8
1-byte unsigned integer; defines the maximum time allowed for the provisioning process to complete
ccc-ticket-control-mask
9
2-byte unsigned integer, in host order
ccc-kdc-addresses-blob
10
variable-length (multiple of 4) IP address, in network order
cisco-subnet-allocation
220
blob (structured)
cisco-vpn-id
221
blob (structured)
cookie-servers*
8
IP address
default-ip-ttl
23
8-bit unsigned int
default-tcp-ttl
37
8-bit unsigned int
dhcp-class-identifier
60
string
dhcp-client-identifier
61
blob (sequence of bytes)
dhcp-lease-time
51
int
dhcp-max-message-size
57
16-bit unsigned integer
dhcp-message
56
string
dhcp-message-type
53
blob (sequence of bytes)
dhcp-option-overload
52
blob (sequence of bytes)
dhcp-parameter-request-list*
55
8-bit unsigned integer
dhcp-parameter-request- list-blob
55
blob (sequence of bytes)
dhcp-rebinding-time
59
int
dhcp-renewal-time
58
int
dhcp-requested-address
50
IP address
dhcp-server-identifier
54
IP address
dhcp-user-class-id
77
string
domain-name
15
string
domain-name-servers*
6
IP address
extensions-path
18
string
finger-servers*
73
IP address
font-servers*
48
IP address
host-name
12
string
ieee802.3-encapsulation
36
8-bit unsigned integer
impress-servers*
10
IP address
interface-mtu
26
16-bit unsigned integer
ip-forwarding
19
byte-valued boolean
irc-servers*
74
IP address
log-servers*
7
IP address
lpr-servers*
9
IP address
mask-supplier
30
byte-valued boolean
max-dgram-reassembly
22
16-bit unsigned integer
merit-dump
14
string
mobile-ip-home-agents*
68
IP address
name-servers*
5
IP address
netbios-dd-servers*
45
IP address
netbios-name-servers*
44
IP address
netbios-node-type
46
blob (sequence of bytes)
netbios-scope
47
string
nis+-servers*
65
IP address
nis+domain
64
string
nis-domain
40
string
nis-servers*
41
IP address
nntp-servers*
71
IP address
non-local-source-routing
20
byte-valued boolean
ntp-servers*
42
IP address
path-mtu-aging-timeout
24
int
path-mtu-patheau-tables*
25
16-bit unsigned integer
perform-mask-discovery
29
byte-valued boolean
policy-filters*
21
IP address (there can be two policy filters, each one having its own IP address)
pop3-servers*
70
IP address
relay-agent-info
82 suboption:
blob (sequence of bytes)
relay-agent-circuit-id
1
(deprecated in favor of relay-agent-circuit-id-data)
relay-agent-circuit-id- data
1
blob (does not require the suboption number as the first byte); accesses and manipulates the relay-agent-circuit-id data from a DHCP request or response
relay-agent-remote-id
2
(deprecated in favor of relay-agent-remote-id-data)
relay-agent-remote-id- data
2
blob (does not require the suboption number as the first byte); accesses and manipulates the relay-agent-remote-id data from a DHCP request or response
relay-agent-device-class
4
(deprecated in favor of relay-agent-device-class-data)
relay-agent-device- class-data
4
4-byte unsigned integer; represents the device class, or individual attributes of the cable modem (RFC 3256)
When the value of dump-packet is set to 1, Network Registrar dumps the current decoded DHCP/BOOTP packet to the log file. An extension can put the value 1 into this data item at multiple points in its execution. This may be useful when debugging extensions.
mac-address
blob
MAC address that came in the client packet. The first byte is the hardware type, the second is the hardware length, and the remaining (up to 16) is the information from the chaddr read just after post-packet-decode. This is a useful aggregation of the htype, hlen, and chaddr fields of the DHCP packet. When read it is constructed from these fields; when written it is placed into these fields.
Request Dictionary
Table C-4 lists the data items that you can set in the request dictionary at any time. The DHCP server reads them at various times. Unless indicated otherwise, all operations are read/write.
Table C-4 Request Dictionary Specific Data Items
Data Item
Value
allow-bootp
int
If set to 1, allows BOOTP for any scope for this request. Read during scope selection and while checking for lease acceptability.
allow-dhcp
int
If set to a 1, allows DHCP for any scope for this request. Read during scope selection and while checking for lease acceptability.
allow-dynamic-bootp
int
If set to a 1, allows dynamic BOOTP for any scope for this request. Read during scope selection and while checking for lease acceptability.
bootp-reply-options
blob
Overrides any bootp-reply-options in any policy. Read when gathering data for the output packet.
client-class-name
string
Name of the client-class used to complete the client information (if any).
client-class-policy
string
Name of the policy that is associated with the client-class. If set, it must be with the name of a policy that was already configured in the server.
client-domain-name
string
Domain name that the client wants to use. It may not exist, in which case the DHCP server uses the domain name specified in the scope. Read when queuing the request for DNS update just prior to the update of stable storage.
client-host-name
string
Host name for the client in DNS; read when queuing in the request for a DNS update just before updating stable storage. Places the actual name in DNS when that operation completes.
client-id
blob
Client identification that the server uses to track the client. May be the client-id sent with a request or internally generated from the MAC address. See client-id-created-from-mac-address.
client-id-created-from-mac-address
int
If set to 1, the client-id must be created for internal use from the client-supplied MAC address and should not be used in reporting.
client-ipaddress
IP address
IP address from which the client sent its packet. Note that it could be zero if the client does not yet have an IP address.
client-lookup-id
blob
Client lookup ID calculated by the client-lookup-id expression of the client-class.
client-mac-address
blob
MAC address stored in the client object associated with the request dictionary. Has the same format (and was created from) the mac-address described in Table C-3.
client-os-type
int
Change the client entry of the request packet by setting this at the pre-client-lookup or post-client-lookup extension points. Can also be read at check-lease-acceptable, but cannot be set there. To set the value, you must first set the os-type in the post-packet-decode request dictionary.
client-policy
string
Name of the policy that is associated with the client entry. If set, must be the name of a preconfigured policy in the DHCP server.
client-port
int
Port from which the client sent its request.
client-requested-host-name
string
Host name that the client requested be used for the DNS update. The DHCP server saves this information so that a change can be detected.
client-wants-nulls-in-strings
int
Determines whether the DHCP server returns strings to the client terminated with a null. If set to 1, the server terminates strings with a null. If set to 0, it does not terminate strings with a null. Set before post-packet-decode and read when encoding the response packet after pre-packet-encode.
dhcp-reply-options
blob
Overrides any DHCP reply options specified in any policy. Read when gathering data for the output packet.
import-packet
int
Determines whether the server treats the packet as if it came from an import client. If set to 1, the server treats the client as an import client and performs all DNS operations on it before sending an ACK. Read when checking the server import mode (right after post-packet-decode), getting ready for DNS processing, and when setting the reply address.
limitation-count
int
Number of simultaneous users allowed with the same limitation-id.
limitation-id
blob
Calculated by the limitation-id expression (if any) for the client-class in which this request falls.
limitation-id-null
int
Set to 1(true) if the limitation-id is null, 0 (false) if another value.
log-client-criteria-processing
int
If set to a 1, logs the criteria processing for the client for this request. Read when trying to acquire a new lease for a client that does not have one, and when checking for lease acceptability.
log-client-detail
int
If set to a 1, logs the client-class processing for this request. Read at the end of client-class processing, after post-client-lookup.
log-dns-update-detail
int
If set to a 1, logs DNS update details for this request.
log-failover-detail
int
If set to a 1, logs a more detailed level of failover activity, such as all failover state changes.
log-incoming-packet-detail
int
If set to a 1, checks whether detailed incoming packet tracing occurred for this request, so that you do not need to put a separate trace on it. Read before packet decoding and the first extension point.
log-incoming-packets
int
If set to a 1, logs the incoming packets for this request. Read after post-decode-packet.
log-ldap-create-detail
int
If set to a 1, logs messages whenever the DHCP server initiates a lease state entry creation to, receives a response from, or retrieves a result or error message from an LDAP server.
log-ldap-query-detail
int
If set to a 1, logs messages whenever the DHCP server initiates a query to, receives a response from, or retrieves a query result or an error message from an LDAP server.
log-ldap-update-detail
int
If set to a 1, logs messages whenever the DHCP server initiates an update lease state to, receives a response from, or a retrieves a result or error message from an LDAP server.
log-leasequery
int
If set to a 1, logs messages when leasequery packets are processed without internal errors and result in an ACK or a NAK.
log-incoming-packets
int
If set to a 1, logs incoming packets for this request. Read after post-decode-packet.
log-missing-options
int
If set to a 1, logs missing options (those a client requests but the DHCP server cannot return). Read while gathering data for the response.
log-outgoing-packet-detail
int
If set to a 1, logs a detailed dump of the outgoing packet for this request. Read after pre-packet-encode and just before sending the packet to the DHCP client.
log-unknown-criteria
int
If set to a 1, logs any unknown criteria specified in the client's inclusion or exclusion criteria for this request. Read when acquiring a new client lease or checking lease acceptability for an existing client.
namespace-description
string (read-only)
Description for the namespace. See namespace-name for details.
namespace-id
int (read-only)
Namespace identifier. See namespace-name for details.
namespace-name
string (read-only)
Name of the namespace. The request dictionary does not have valid values for these items at post-packet-decode, but does at all other extension points, because the namespace has not yet been determined. This is so that a script can change the vpn-id option or suboption at post-packet-decode and thereby affect the namespace used for a lease.
namespace-vrf-name
string (read-only)
Virtual routing and forwarding table identifier for the namespace. See namespace-name for details.
namespace-vpn-id
blob, typically 7 bytes (read-only)
Virtual private network identifier for the namespace. See namespace-name for details.
ping-clients
int
If set to a 1, performs a ping before offering a lease for this request. Read just before determining if a lease is acceptable for a client.
reply-to-client-address
int
If set to 1, the server sends the response packet to the client-ip-address and the client-port instead of using the RFC-mandated algorithm.
selection-criteria
string
Comma-separated string that contains the scope's selection criteria.
selection-criteria-excluded
string
Comma-separated string that contains the scope's exclusion criteria.
send-ack-first
int
If set to a 1, updates DNS after the ACK for DHCP requests. Read just before initiating the DNS operation.
transaction-time
int
Time, in seconds since 1970, that the input packet was decoded.
update-dns
string
Requests partial, full, or no dynamic DNS updates on a per-request packet basis. Input and output values are 1=update-all, 2=update-fwd-only, 3=update-rev-only, and 0=update-none.
update-dns-for-bootp
int
If set to a 1, updates DNS for BOOTP requests for this request. Read just before initializing the DNS operation for BOOTP.
verbose-logging
int
If set to a 1, logs verbose messages for this request. Read at various times during processing.
Response Dictionary
Table C-5 lists the data items you can set in the response dictionary at any time. The DHCP server reads them at various times. Unless indicated otherwise, the operation is read/write.
Table C-5 Response Dictionary Specific Data Items
Data Item
Value
auto-configure
int
Network Registrar can ask and be notified if autoconfiguration should be disabled on the local subnet. Writing an extension script to return yiaddr=0.0.0.0 and setting this option (0xFB) to 0 prevents a Windows 2000 RC3 DHCP client from autoconfiguring. Allows clients to choose a link-local IP address so that they can communicate with other hosts on the same link.
client-domain-name
string (read-only)
From the client information in the lease, the domain name that the client wants to use. It might not exist, in which case the DHCP server uses the domain name specified in the scope. Read when queuing the request for DNS update just prior to the update of stable storage.
client-expiration-time
int
Absolute time value of the lease expiration time last given to the client.
client-host-name
string
From the client information in the lease, the host name that the DHCP server puts into DNS. Read when queueing the request for a DNS update just before updating stable storage.
client-id
blob
From the client information in the lease, the client identification that the server used to keep track of the client. This might be the client-id sent with a request or a client-id internally generated from the MAC address.
client-id-created-from-mac-address
int (read-only)
From the client information in the lease. If set to 1, the client-id must be created from the MAC address and should not be used in reporting.
client-last-transaction-time
int (read-only)
Time, in seconds, since 1970, that the DHCP server last heard from this client.
client-mac-address
blob
From the client information in the lease, the MAC address stored in the client object associated with the request dictionary. Has the same format as (and was created from) the MAC address.
client-os-type
int
Change the client entry of the request packet by setting this at the pre-client-lookup or post-client-lookup extension points. Can also be read at check-lease-acceptable, but cannot be set there. To set the value, you must first set the os-type in the post-packet-decode request dictionary.
client-limitation-id
blob (read-only)
Limitation identifier of the client associated with the current lease.
client-requested-host-name
string
From the client information in the lease, the host name that the client requested for the DNS update.
domain-name-changed
int
If set to 1, the domain name in the current packet differs from the domain name used in the DNS update. Read after check-lease-acceptable and before pre-packet-encode.
host-name-changed
int
If set to 1, the host name in the current packet differs from that used in the DNS update. Read after check-lease-acceptable and before pre-packet-encode.
host-name-in-dns
int
If set to 1, the host name is in DNS. Read after check-lease-acceptable and before pre-packet-encode. Written after the host name goes into DNS.
lease-deactivated
int (read-only)
If set to 1, reports that the lease is de-activated.
lease-ipaddress
IP address (read-only)
IP address of the lease that the DHCP server uses in processing.
lease-namespace-description
string (read-only)
Description for the namespace stored with a response's lease.
lease-namespace-id
int (read-only)
Identifier for the namespace stored with a response's lease.
lease-namespace-name
string (read-only)
Name of the namespace stored with a response's lease.
lease-namespace-vrf-name
string (read-only)
Virtual routing and forwarding table identifier for the namespace stored with a response's lease.
lease-namespace-vpn-id
blob, typically 7 bytes (read-only)
Virtual private network (VPN) identifier for the namespace stored with a response's lease.
lease-relay-agent-circuit-id
blob
Accesses and manipulates the relay agent circuit id data as stored with a response's lease. Requires the suboption number 1 as the first byte. Deprecated in favor of the lease-relay-agent-circuit-id-data item.
lease-relay-agent-circuit-id-data
blob (use instead of deprecated lease-relay-agent-circuit-id)
Accesses and manipulates the relay-agent-circuit-id-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.
lease-relay-agent-remote-id
blob
Accesses and manipulates the relay-agent-remote-id data as stored with a response's lease. Requires suboption number 2 as the first byte. Deprecated in favor of the lease-relay-agent-remote-id-data item.
lease-relay-agent-remote-id-data
blob (use instead of lease-relay-agent-remote-id item)
Accesses and manipulates the relay-agent-remote-id-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.
lease-relay-agent-server-id- override-data
IP address
Accesses and manipulates the relay-agent-server-id-override-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.
lease-relay-agent-subnet- selection-data
IP address
Accesses and manipulates the relay-agent-subnet-selection-data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.
lease-relay-agent-vpn-id-data
blob
Accesses and manipulates the relay-agent-vpn-id data as stored with a response's lease. Relevant only if the save-relay-agent-data DHCP server attribute is enabled.
lease-reserved
int (read-only)
If set to 1, reports if the lease is reserved.
lease-start-time-of-state
int (read-only)
Time, in seconds since 1970, that this lease was first placed into its current state.
lease-state
string (read-only)
State of the lease, which can be available, offered, expired, leased, or unavailable.
mac-address
blob
If set to 1, the scope allows BOOTP. Written after a DNS operation completes.
namespace-description
string (read-only)
Description for the namespace.
namespace-id
int (read-only)
Namespace identifier.
namespace-name
string (read-only)
Name of the namespace.
namespace-vrf-name
string (read-only)
Virtual routing and forwarding table (VRF) identifier for the namespace.
namespace-vpn-id
blob, typically 7 bytes (read-only)
Virtual private network (VPN) identifier for the namespace.
ping-clients
int
If set to 1, performs a ping before offering a lease for this request. Read just before determining a client's lease acceptability.
reply-ipaddress
IP address
IP address to use when replying to the DHCP client. Read just after pre-packet-encode. If you change its value in a pre-packet-encode, the IP address you place in it should be for a system that can respond to ARP queries (unless it is a broadcast address). Even if unicast is enabled and the broadcast flag is not set in the DHCP request, the local ARP cache is not set with a mapping from a new reply-ipaddress in the pre-packet-encode to the MAC address in the DHCP request.
reply-port
int
Port to use when replying to the DHCP client. Read just after pre-packet encode.
reverse-name-in-dns
int
If equal to 1, the reverse name is in DNS. Read before initializing a DNS operation.
scope-allow-bootp
int
If set to 1, the scope allows BOOTP. Written after a DNS operation completes.
scope-allow-dhcp
int (read-only)
If set to 1, the scope allows DHCP.
scope-allow-dynamic-bootp
int (read-only)
If set to 1, the scope allows dynamic BOOTP.
scope-available-leases
int (read-only)
Number of available leases on the current scope.
scope-deactivated
int (read-only)
If set to 1, the scope is de-activated.
scope-dns-forward-server-address
IP address (read-only)
DNS server to use for the DNS forward address.
scope-dns-forward-zone-name
string (read-only)
Forward zone name configured in the scope.
scope-dns-number-of-host-bytes
int (read-only)
Number of host bytes used by the DHCP server code that handles DNS updates.
scope-dns-reverse-server-address
IP address (read-only)
DNS server to use for the DNS reverse address.
scope-dns-reverse-zone-name
string (read-only)
Reverse zone name configured in the scope.
scope-name
string (read-only)
Name of the scope that contains the lease that the DHCP server is processing.
scope-network-number
IP address (read-only)
Network number of the scope that contains the lease the DHCP server is processing.
scope-ping-clients
boolean (read-only)
If set to 1, the scope associated with the current lease was configured to support a ping operation prior to offering a lease.
scope-primary-network-number
IP address (read-only)
Network number of this scope's primary scope.
scope-primary-subnet-mask
IP address (read-only)
Subnet mask of this scope's primary scope.
scope-renew-only
int (read-only)
If set to 1, the scope is renew-only.
scope-renew-only-expire-time
int (read-only)
Absolute time, in seconds since January 1, 1970, at which a renew-only scope should cease to be renew-only.
scope-selection-tags
string (read-only)
Comma-separated string that contains the scope's selection criteria.
scope-send-ack-first
int (read-only)
If set to 1, the scope sends an ACK before performing the rest of the processing.
scope-subnet-mask
IP address (read-only)
Subnet mask of the scope that contains the lease the DHCP server is processing.
scope-update-dns
string (read-only)
DNS updates for forward or reverse zones. Output values are 1=update-all, 2=update-fwd-only, 3=update-rev-only, and 0=update-none. Introduced in Network Registrar 6.1.1.
scope-update-dns-enabled
boolean (read-only)
If set to 1, the scope has update DNS enabled for forward and reverse zones. Deprecated in favor of scope-update-dns.
scope-update-dns-for-bootp
int (read-only)
If set to 1, the scope has update DNS enabled for BOOTP.
transaction-time
int (read-only)
Time, in seconds since 1970, that the request was decoded.
Extension Dictionary API
This section contains the dictionary method calls to use when accessing dictionaries from Tcl extensions and shared libraries.
Tcl Attribute Dictionary API
In an attribute dictionary, the keys are constrained to be the names of attributes as defined in the Network Registrar DHCP server configuration. The values are the string representation of the legal values for that particular attribute. For example, IP addresses are specified by the dotted-decimal string representation of the address, and enumerated values are specified by the name of the enumeration. This means that numbers are specified by the string representation of the number.
Attribute dictionaries are unusual in that they can contain more than one instance of a key. These instances are ordered, with the first instance at index zero. Some of the attribute dictionary methods allow an index to indicate a particular instance or position in the list of instances to be referenced.
Attribute dictionaries use commands with which you can change and access the values in the dictionaries. Table C-6 lists the commands to use with the request and response dictionaries. In this case, you can define the dict variable as request or response.
See the install-path/examples/dhcp/tcl/tclextension.tcl file for examples.
Table C-6 Tcl Request and Response Dictionary Methods
Method
Syntax
get
$dictgetattribute [index [bMore]]
Returns the value of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute, the empty string is returned instead. If you include the index value, this returns the indexth instance of the attribute. Some attributes can appear more than once in the request or response packet. The index selects which instance to return.
If you include the bMore, the get method sets bMore to TRUE if there are more attributes after the one returned, otherwise to FALSE. Use this to determine whether to make another call to get to retrieve other instances of the attribute.
log
$dictloglevel message ...
Outputs a message into the DHCP server's logging system. The level should be LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated and sent to the logging system at the specified level.
remove
$dictremoveattribute [index]
Removes the attribute from the dictionary. If you omit the index or set it to the special value REMOVE_ALL, this removes any existing instances of the attribute. If you include the index as a number, this removes the instance of the attribute at the position indicated. This method always returns 1, even if the dictionary does not contain that attribute at that index.
put
$dictputattribute value [index]
Associates a value with the attribute in the dictionary. If you omit the index or set it to the special value REPLACE, this replaces any existing instances of the attribute with the single value. If you include the index value as the special value APPEND, this appends a new instance of the attribute to the end of the list of instances of the attribute. If you include the index value as a number, this inserts a new instance of the attribute at the position indicated. If you set the index value to the special value AUGMENT, this puts the attribute only if there is not one already.
trace
$dicttracelevel message ...
Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.
Tcl Environment Dictionary Methods
Table C-7 describes the commands to use with the environment dictionary. In this case, you can define the dict variable as environ, as in the following procedure example:
proc tclhelloworld2 { request response environ } {
$environ put trace-level 4
$environ log LOG_INFO "Environment hello world"
}
Table C-7 Tcl Environment Dictionary Methods
Method
Syntax
clear
$dictclear
Removes all entries from the dictionary.
containsKey
$dictcontainsKeykey
Returns 1 if the dictionary contains the key, otherwise 0.
firstKey
$dictfirstKey
Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name. If a key does not exist, returns the empty string.
get
$dictgetkey
Returns the value of the key from the dictionary. If a key does not exist, returns the empty string.
isEmpty
$dictisEmpty
Returns 1 if the dictionary has no entries, otherwise 0.
log
$dictloglevel message ...
Returns a message in the DHCP server's logging system. The level should be one of LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated and sent to the logging system at the specified level.
nextKey
$dictnextKey
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey. If a key does not exist, returns the empty string.
put
$dictputkey value
Associates a value with the key, replacing an existing instance of the key with the new value.
remove
$dictremovekey
Removes the key from the dictionary. Always returns 1, even if the dictionary did not contain the key.
size
$dictsize
Returns the number of entries in the dictionary.
trace
$dicttracelevel message ...
Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.
DEX Attribute Dictionary API
When writing DEX extensions for C/C++, you can specify keys as the attribute name's string representation or by type (a byte sequence defining the attribute). This mean that some of these access methods have four different variations that are the combinations of string or type for the key or value.
See the install-path/examples/dhcp/dex/dexextension.c file or other files in that directory for examples.
DEX Request and Response Dictionary Methods
DEX attribute dictionaries use active commands, called methods, with which you can change and access values. Table C-8 lists the methods to use with the request and response dictionaries. In this case, you can define the pDict variable as pRequest or pResponse, as in:
pRequest->get( pRequest, "host-name", 0, 0 );
Table C-8 DEX Request and Response Dictionary Methods
Returns the value of the iIndexed instance of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute (or that many instances of it), the empty string is returned instead. If pbMore is nonzero, the get method sets pbMore to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to get to retrieve other instances of the attribute.
Returns the value of the iIndexed instance of the attribute from the dictionary, as a sequence of bytes. If the dictionary does not contain the attribute (or that many instances of it), returns 0 instead. If pbMore is nonzero, the getBytes method sets it to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to getBytes to retrieve other instances of the attribute.
Returns the value of the iIndexed instance of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute (or that many instances of it), returns the empty string instead. If pbMore is nonzero, the getByType method sets pbMore to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to getByType to retrieve other instances.
Returns the value of the iIndexed instance of the attribute from the dictionary, as a sequence of bytes. If the dictionary does not contain the attribute (or that many instances of it), 0 is returned instead. If pbMore is nonzero, sets the variable pointed to TRUE if there are more instances of the attribute after the one returned, otherwise to FALSE. Use this to determine whether to make another call to get to retrieve other instances of the attribute.
Returns a message in the DHCP server's logging system. The eLevel should be one of DEX_LOG_ERROR, DEX_LOG_WARNING, or DEX_LOG_INFO. The pszFormat is treated as a printf style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.
Converts pszValue to a sequence of bytes, according to the definition of pszAttribute in the server configuration. Associates that sequence of bytes with the attribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with a single value. If the special value DEX_APPEND, it appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance at the position indicated. Returns TRUE unless the attribute name does not match any configured attributes or the value could not be converted to a legal value.
Converts pszValue to a sequence of bytes, according to the definition of pszAttribute in the server configuration. Associates that sequence of bytes with the attribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If the special value DEX_APPEND, appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance at the position indicated.
Associates pszValue with the pszAttribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If the special value DEX_APPEND, appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance at the position indicated. Returns TRUE unless the attribute name does not match a configured one.
Associates pszValue with the pszAttribute in the dictionary. If iIndex is the special value DEX_REPLACE, replaces any existing instances of the attribute with the new value. If the special value DEX_APPEND, appends a new instance of the attribute to its list. If the special value DEX_AUGMENT, puts the attribute only if there is not one already. Otherwise, inserts a new instance of the attribute at the position indicated.
Removes the attribute from the dictionary. If iIndex is the special value DEX_REMOVE_ALL, removes any existing instances of the attribute. Otherwise, removes the instance at the position indicated. Returns TRUE, even if the dictionary did not contain that attribute at that index, unless the attribute name does not match any configured one.
Removes the attribute from the dictionary. If iIndex is the value DEX_REMOVE_ALL, removes any existing instances of the attribute. Otherwise, removes the instance at the position indicated. Always returns TRUE, even if the dictionary does not contain that attribute at that index.
Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.
DEX Environment Dictionary Methods
The environment dictionary uses active commands, called methods, with which you can change and access the dictionary values. Table C-9 lists the methods to use with the environment dictionary. In this case, you can define the pDict variable as pEnviron, as in:
Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name. If a key does not exist, returns the empty string.
Returns a message in the DHCP server's logging system. The eLevel should be one of LOG_ERROR, LOG_WARNING, or LOG_INFO. The pszFormat is treated as a printf style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey. If a key does not exist, returns the empty string.
Returns a message in the DHCP server's packet tracing system. At level 0, no tracing occurs. At level 1, it traces only that the server received the packet and sent a reply. At level 4, it traces everything. The remaining arguments are concatenated and sent to the tracing system at the specified level. The default tracing is set using the DHCP server extension-trace-level attribute.
