DHCP Extension Dictionary API

A dictionary is a data structure that contains key-value pairs. There are two types of dictionaries: the attribute dictionaries that are used by the request and response dictionaries, and the environment dictionary.

This appendix contains the dictionary method calls you can use when accessing dictionaries from Tcl extensions and from shared libraries.

Tcl Attribute Dictionary API

An attribute dictionary is a dictionary in which the keys are constrained to be the names of attributes as defined in the Access Registrar server configuration, and 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 have the unusual feature that there can be more than one instance of a particular key in the dictionary. These instances are ordered, with the first instance at index zero. Some of the methods of an attribute dictionary allow an index to be specified to indicate a particular instance or position in the list of instances to be referenced.

Attribute Dictionary Methods

Attribute dictionaries use commands that allow you to change and access the values in the dictionaries. Table C-1 lists the commands that you can use with the request and response dictionaries.

Table C-1: Tcl Attribute Dictionary Methods

Name	Syntax

remove	$dict remove attribute [index]
Removes the attribute attribute from the dictionary. If index is not provided or if index equals the special value REMOVE_ALL, remove any existing instances of attribute. If index is provided and is a number, remove the instance of attribute at the position indicated. Always returns 1, even if the dictionary did not contain that attribute at that index.
get	$dict get attribute [index [ <bMore> ] ]
Returns the value of the attribute attribute from the dictionary, as represented as a string. If the dictionary does not contain the attribute, the empty string is returned instead. If index is provided, return the index'th instance of the attribute. Some attributes can appear more than once in the request (or response) packet. The index argument is used to select which instance to return. If bMore is provided, the get method will set bMore to 1 if there are more attributes after the one returned, and to 0 otherwise. You can use this to determine whether another call to get should be made to retrieve other instances of the attribute.
put	$dict put attribute value [index]
Associates value with the attribute attribute in the dictionary. If index is not provided or if index equals the special value REPLACE, replace any existing instances of attribute with the single value. If index is provided and equals the special value APPEND, append a new instance of attribute to the end of the list of instances of the attribute. If index is provided and is a number, insert a new instance of attribute at the position indicated. If index is provided and equals the special value AUGMENT, only put the attribute if there is not one already.
log	$dict log level message
Outputs a message into the DHCP server's logging system. The level should be either LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level.
trace	$dict trace level message
Outputs a message into the packet tracing system used by the DHCP server. At level 0, no tracing occurs. At level 1, only an indication that the server received the packet and sent a reply is output. As the number gets higher the amount of information output increases, until at level 4 everything is traced as output. The remaining arguments are concatenated and sent to the tracing system at the specified level.

Tcl Environment Dictionary Methods

A dictionary is a data structure that contains key/value pairs. An environment dictionary is a dictionary in which the keys and values are constrained to be strings. The environment dictionary is used to communicate information from the extension to the server and from extension to extension within the processing of a particular request. Note that there can be only one instance of a key in the environment dictionary.

Table C-2 describes the commands that you can use with the environment dictionary.

Table C-2: Tcl Environment Dictionary Methods

Name	Syntax

size	$dict size
Returns the number of entries in the dictionary.
isEmpty	$dict isEmpty
Returns 1 if the dictionary has no entries, otherwise returns 0.
clear	$dict clear
Removes all entries from the dictionary.
containsKey	$dict containsKey key
Returns 1 if the dictionary contains the key key, otherwise returns 0.
remove	$dict remove key
Removes the key key from the dictionary. Always returns 1, even if the dictionary did not contain the key.
get	$dict get key
Returns the value of the key key from the dictionary. If the dictionary does not contain the key, the empty string is returned instead.
put	$dict put key value
Associates value with the key key in the dictionary, replacing an existing instance of key with the new value.
firstKey	$dict firstKey
Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name.
nextKey	$dict nextKey
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey.
log	$dict log level message
Outputs a message into the logging system used by the DHCP server, level should be one of the LOG_ERROR, LOG_WARNING or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level.
trace	$dict trace level message
Outputs a message into the packet tracing system used by the DHCP server. At level 0, no tracing occurs. At level 1, only an indication that the server received the packet and sent a reply is output. As the number gets higher, the amount of information output is greater, until at level 4 everything the server traces is output. The remaining arguments are concatenated together and sent to the tracing system at the specified level.

DEX Attribute Dictionary API

A dictionary is a data structure that contains key-value pairs. An attribute dictionary is a dictionary in which the keys are constrained to be the attributes as defined in the DHCP server configuration, and the values are constrained to be legal values for that particular attribute. Attribute dictionaries have the unusual feature that there can be more than one instance of a particular key in the dictionary. These instances are ordered, with the first instance at index 0. Some of the methods of an attribute dictionary allow an index to be specified to indicate a particular instance or position in the list of instances to be referenced.

When writing DEX extensions (DHCP Extensions), you can specify keys as the string representation of the name of the attribute or by type, which is a byte sequence defining the attribute. The values can also be specified as the string representation of the value or as the byte sequence, which is the attribute. These options mean that some of these access methods have four different variations that are the combinations of string or type for the key, and string or bytes for the value.

Attribute Dictionary Methods

Attribute dictionaries use active commands, called methods, that allow you to change and access the values in the dictionaries. Table C-3 lists the methods that you can use with the request and response dictionaries.

Table C-3: DEX Attribute Dictionary Methods

Name	Syntax

get	const char* pDict->get ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex,abool_t* pbMore )
Returns the value of the iIndex'd instance of the attribute from the dictionary, represented as a string. If the dictionary does not contain the attribute (or that many instances of the attribute), the empty string is returned instead. If pbMore is non-zero, the get method will set pbMore to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to 'get' should be made to retrieve other instances of the attribute.
put	abool_t pDict->put ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, const char* pszValue, int iIndex )
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 equals the special value DEX_REPLACE, replaces any existing instances of the attribute with a single value. If iIndex equals the special value DEX_APPEND, it appends a new instance of attribute to the end of the list of existing instances of the attribute. Otherwise, a new instance of the attribute is inserted at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes or the value could not be converted to a legal value. If iIndex equals the special value DEX_AUGMENT, only put the attribute if there is not one already.
getBytes	const abytes_t* pDict->getBytes ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex, abool_t* pbMore )
Returns the value of the iIndex'd 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 the attribute), returns 0 instead. If pbMore is non-zero, the getBytes method will set pbMore to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to getBytes should be made to retrieve other instances of the attribute.
putBytes	abool_t pDict->putBytes ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, const abytes_t* pValue, int iIndex )
Associates pValue with the attribute pszAttribute in the dictionary. If iIndex equals the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If iIndex equals the special value DEX_APPEND, appends a new instance of attribute to the end of the list of existing instances of the attribute. If iIndex equals the special value DEX_AUGMENT, only put the attribute if there is not one already. Otherwise, a new instance of the attribute is inserted at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes.
getType	const char* pDict->getByType ( dex_AttributeDictionary_t* pDict, const abytes_t* pAttribute )
Returns a pointer to the byte sequence defining the attribute, if the attribute name matches a configured attribute, 0 otherwise.
removeByType	abool_t pDict->removeByType ( dex_AttributeDictionary_t* pDict, const abytes_t* pAttribute, int iIndex )
Removes the attribute from the dictionary. If iIndex equals the special value DEX_REMOVE_ALL, remove any existing instances of the attribute. Otherwise, the instance of the attribute at the position indicated is removed. Always returns TRUE, even if the dictionary did not contain that attribute at that index.
getByType	constabytes_t* pDict->getByType ( dex_AttributeDictionary_t* pDict, const char* pszKey)
Returns the value of the iIndex'd instance of the attribute from the dictionary, as represented as a string. If the dictionary does not contain the attribute (or that many instances of the attribute), returns the empty string instead. If pbMore is non-zero, the getByType method sets pbMore to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to getByType should be made to retrieve other instances of the attribute.
putByType	abool_t pDict->putByType ( dex_AttributeDictionary_t* pDict, const abytes_t* pAttribute, const char* pszValue, int iIndex )
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 equals the special value DEX_REPLACE, replaces any existing instances of the attribute with a single new value. If iIndex equals the special value DEX_APPEND, appends a new instance of attribute to the end of the list of existing instances of the attribute. Otherwise, inserts a new instance of the attribute at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes or the value could not be converted to a legal value.
getBytesByType	const abytes_t* pDict-> getBytesByType ( dex_AttributeDictionary_t* pDict,const abytes_t* pAttribute, int iIndex,abool_t* pbMore )
Returns the value of the iIndex'd 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 the attribute), 0 is returned instead. If pbMore is non-zero, sets the variable pointed to TRUE if there are more instances of the attribute after the one returned and to FALSE otherwise. This can be used to determine whether another call to 'get' should be made to retrieve other instances of the attribute.
putBytesByType	abool_t pDict->putBytesByType ( dex_AttributeDictionary_t* pDict,const abytes_t* pAttribute,const abytes_t* pValue, int iIndex )
Associates pValue with the attribute pszAttribute in the dictionary. If iIndex equals the special value DEX_REPLACE, replaces any existing instances of the attribute with the new value. If iIndex equals the special value DEX_APPEND, appends a new instance of attribute to the end of the list of existing instances of the attribute. If iIndex equals the special value DEX_AUGMENT, only put the attribute if there is not one already. Otherwise, inserts a new instance of the attribute at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes.
alloc Memory	void* pDict->allocateMemory(dex_AttributeDictionary_t* pDict, unsigned int iSize)
Allocates memory for use in scripts that persists only for the lifetime of this request. This memory is released when processing for this request is complete.
log	abool_t pDict->log( dex_AttributeDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the logging system used by the DHCP server. iLevel should be one of DEX_LOG_ERROR, DEX_LOG_WARNING or DEX_LOG_INFO. The pszFormat argument 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.
trace	abool_t pDict->trace ( dex_AttributeDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the packet tracing system used by the DHCP server. At level 0 no tracing occurs. At level 1 only an indication that the packet was received and a reply was sent is output. As the number gets higher, the amount of information output is greater, until at level 4 everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level.
remove	abool_t pDict->remove ( dex_AttributeDictionary_t* pDict, const char* pszAttribute, int iIndex )
Removes the attribute from the dictionary. If iIndex equals the special value DEX_REMOVE_ALL, remove any existing instances of the attribute. Otherwise, remove the instance of the attribute 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 attribute.

DEX Environment Dictionary API

A dictionary is a data structure that contains key/value pairs. An environment dictionary is a dictionary in which the keys and values are constrained to be strings. The environment dictionary is used to communicate information from the script to the server and from script to script within the processing of a particular request. Note that there can be only one instance of a key in the environment dictionary.

DEX Environment Dictionary Methods

The environment dictionary uses active commands, called methods, that allow you to change and access the values in the dictionary. Table C-4 lists the methods that you can use with the environment dictionary.

Table C-4: DEX Environment Dictionary Methods

Name	Syntax

size	int pDict->size (dex_EnvironmentDictionary_t* pDict )
Returns the number of entries in the dictionary.
isEmpty	abool_t pDict->isEmpty (dex_EnvironmentDictionary_t* pDict )
Returns TRUE if the dictionary has 0 entries, FALSE otherwise.
clear	void pDict->clear (dex_EnvironmentDictionary_t* pDict )
Removes all entries from the dictionary.
containsKey	abool_t pDict->containsKey(dex_EnvironmentDictionary_t* pDict,const char* pszKey )
Returns TRUE if the dictionary contains the key, otherwise returns FALSE.
remove	abool_t pDict->remove (dex_EnvironmentDictionary_t* pDict, const char* pszKey )
Removes the key and the associated value from the dictionary. Always returns TRUE, even if the dictionary did not contain the key.
get	const char* pDict->get (dex_EnvironmentDictionary_t* pDict, const char* pszKey )
Returns the value associated with the key from the dictionary. If the dictionary does not contain the key, the empty string is returned.
put	abool_t pDict->put (dex_EnvironmentDictionary_t* pDict, const char* pszKey, const char* pszValue )
Associates the value with the key in the dictionary, replacing any existing instance of the key with the new value.
firstKey	const char* pDict->firstKey (dex_EnvironmentDictionary_t* pDict )
Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name.
nextKey	const char* pDict->nextKey (dex_EnvironmentDictionary_t* pDict )
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey.
allocateMemory	void* pDict->allocateMemory (dex_EnvironmentDictionary_t* pDict, unsigned int iSize)
Allocates memory for use in scripts that persist only for the lifetime of this request. This memory is released when processing for this request is complete.
log	abool_t pDict->log (dex_EnvironmentDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the logging system used by the DHCP server. iLevel should be one of DEX_LOG_ERROR, DEX_LOG_WARNING or DEX_LOG_INFO. The pszFormat argument 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.
trace	abool_t pDict->trace (dex_EnvironmentDictionary_t* pDict, int iLevel, const char* pszFormat, ... )
Outputs a message into the packet tracing system used by the DHCP server. At level 0 no tracing occurs. At level 1 only an indication that the packet was received and a reply was sent is output. As the number gets higher, the amount of information output is greater, until at level 4 everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level.

Table of Contents

DHCP Extension Dictionary API