Cisco CNS Network Registrar CLI Reference Guide, 5.5
Appendix: DHCP Extension Dictionary API
Downloads: This chapterpdf (PDF - 175.0KB) | Feedback

DHCP Extension Dictionary API

Table Of Contents

DHCP Extension Dictionary API

Tcl Attribute Dictionary API

Attribute Dictionary Methods

Tcl Environment Dictionary Methods

DEX Attribute Dictionary API

Attribute Dictionary Methods

DEX Environment Dictionary API

DEX Environment Dictionary Methods


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 B-1 lists the commands that you can use with the request and response dictionaries.

Table B-1 Tcl Attribute Dictionary Methods 

Name
Syntax

get

$dict get attribute [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, and to FALSE otherwise. You can use this to determine whether to make another call to get to retrieve other instances of the attribute.

log

$dict log level 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 together and sent to the logging system at the specified level.

remove

$dict remove attribute [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

$dict put attribute 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 and 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 only puts the attribute if there is not one already.

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 data 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 B-2 describes the commands that you can use with the environment dictionary.

Table B-2 Tcl Environment Dictionary Methods 

Name
Syntax

clear

$dict clear

Removes all entries from the dictionary.

containsKey

$dict containsKey key

Returns 1 if the dictionary contains the key, otherwise returns 0.

firstKey

$dict firstKey

Returns the name of the first key in the dictionary. Note that the keys are not stored sorted by name.

   
   

get

$dict get key

Returns the value of the key from the dictionary. If the dictionary does not contain the key, the empty string is returned instead.

isEmpty

$dict isEmpty

Returns 1 if the dictionary has no entries, otherwise returns 0.

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.

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.

put

$dict put key value

Associates value with the key in the dictionary, replacing an existing instance of key with the new value.

remove

$dict remove key

Removes the key from the dictionary. Always returns 1, even if the dictionary did not contain the key.

size

$dict size

Returns the number of entries in the dictionary.

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 B-3 lists the methods that you can use with the request and response dictionaries.

Table B-3 DEX Attribute Dictionary Methods 

Name
Syntax

allocateMemory

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.

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.

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 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 getBytes should be made to retrieve other instances of the attribute.

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.

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.

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.

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.

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 the 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 puts the attribute if there is not one already.

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.

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 puts 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.

   

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 puts 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.

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, removes 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.

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, removes 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 does not contain that attribute at that index.

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.


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 B-4 lists the methods that you can use with the environment dictionary.

Table B-4 DEX Environment Dictionary Methods 

Name
Syntax

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.

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.

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.

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.

isEmpty

abool_t pDict->isEmpty ( dex_EnvironmentDictionary_t* pDict )

Returns TRUE if the dictionary has 0 entries, FALSE otherwise.

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.

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.

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.

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.

size

int pDict->size ( dex_EnvironmentDictionary_t* pDict )

Returns the number of entries in the dictionary.

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.