|
|
This appendix describes the Tcl and REX dictionaries that are used when writing Incoming or Outgoing scripts.
A dictionary is a data structure that contains key/value pairs. Two types of dictionaries exist: the Attribute dictionaries (used by the Request and Response dictionaries), and the Environment dictionary.
This section contains the dictionaries you reference when writing a Tcl script and the dictionaries you reference when you write a script using the shared libraries (REX---RADIUS EXtension).
An Attribute dictionary is a dictionary in which the keys are constrained to be the names of attributes as defined in the Cisco 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 numbers are specified by the string representation of the number.
Attribute dictionaries use active commands, called methods, that allow you to change and access the values in the dictionaries. Table A-1 lists of all of the methods you can use with the Request and Response dictionaries.
| Name | Syntax | Description |
|---|---|---|
$dict addProfile <profile> [<mode>] | Copies all of the attributes in the profile <profile> into the dictionary. Note, <profile> must be the name of one of the profiles listed in the server configuration. When <mode> is not provided or when <mode> equals the special value REPLACE, any duplicate instances of the attributes in the dictionary are replaced with the attribute from <profile>. When <mode> is provided and equals the special value APPEND, new instances of the attributes are appended to the attributes already in the dictionary. When <mode> is provided and equals the special value AUGMENT, only add the attribute when it does not already exist. | |
$dict clear | Removes all entries from the dictionary. | |
$dict containsKey <attribute> | Returns 1 when the dictionary contains the attribute <attribute>, otherwise returns 0. | |
$dict firstKey | Returns the name of the first attribute in the dictionary. Note, the attributes are not stored sorted by name. | |
$dict get <attribute> [<index> [bMore]] | Returns the value of the <attribute> attribute from the dictionary, represented as a string. When the dictionary does not contain the <attribute>, an empty string is returned. When <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. When bMore is provided, the get method sets bMore to 1 when more attributes exist 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. | |
$dict isEmpty | Returns 1 when the dictionary has no entries, otherwise returns 0. | |
$dict log <level> <message> | Outputs a message into the RADIUS 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. | |
$dict nextKey | Returns the name of the next attribute in the dictionary that follows the attribute returned in the last call to firstKey or nextKey. | |
$dict put <attribute> <value> [<index>] | Associates <value> with the attribute <attribute> in the dictionary. When <index> is not provided or when <index> equals the special value REPLACE, any existing instances of <attribute> are replaced with the single value. When <index> is provided and equals the special value APPEND, a new instance of <attribute> is appended to the end of the list of instances of the <attribute>. When <index> is provided and is a number, a new instance of <attribute> is inserted at the position indicated. When <index> is provided and equals the special value AUGMENT, only put the attribute when it does not already exist. | |
$dict remove <attribute> [<index>] | Removes the <attribute> attribute from the dictionary. When <index> is not provided or when <index> equals the special value REMOVE_ALL, remove any existing instances of <attribute>. When <index> is provided and is a number, remove the instance of <attribute> at the position indicated. Always returns 1, even when the dictionary did not contain the <attribute> at that <index>. | |
$dict size | Returns the number of entries in the dictionary. | |
$dict trace <level> <message> ... | Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication 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, where everything is traced as output. The remaining arguments are concatenated and sent to the tracing system at the specified level. |
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 Tcl 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, there can be only one instance of a key in the Environment dictionary.
Table A-2 lists of all the methods you can use with the Request and Response dictionaries.
| Name | Syntax | Description |
|---|---|---|
$dict clear | Removes all entries from the dictionary. | |
$dict containsKey <key> | Returns 1 when the dictionary contains the <key> key, otherwise returns 0. | |
$dict firstKey
| Returns the name of the first key in the dictionary. Note, the keys are not stored sorted by name. | |
$dict get <key> | Returns the value of <key> from the dictionary. When the dictionary does not contain the <key>, an empty string is returned. | |
$dict isEmpty | Returns 1 when the dictionary has no entries, otherwise returns 0. | |
$dict log <level> <message> | Outputs a message into the logging system used by the RADIUS server. <level> should be one of LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level. | |
$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. | |
$dict put <key> <value> | Associates <value> with the <key> key in the dictionary, replacing an existing instance of <key> with the new value. | |
$dict remove <key> | Removes the <key> key from the dictionary. Always returns 1, even when the dictionary did not contain the <key>. | |
$dict size | Returns the number of entries in the dictionary. | |
$dict trace <level> <message> | Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication 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, where everything the server traces is output. The remaining arguments are concatenated together and sent to the tracing system at the specified level. |
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 RADIUS 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 REX scripts, 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 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.
Table A-3 lists all of the methods you can use with the Request and Response dictionaries.
| Name | Syntax | Description |
|---|---|---|
abool_t pDict->addProfile(rex_AttributeDictionary_t* pDict, const char* <pszProfile>, int <iMode>) | Copies all of the attributes in the <pszProfile> profile into the dictionary. Note, <pszProfile> must be the name of one of the profiles listed in the server configuration. When <iMode> equals the special value REX_REPLACE, it replaces any duplicate instances of the attributes in the dictionary with the attribute from the profile. When <iMode> equals the special value REX_APPEND, it appends a new instance of the attributes to any attributes already in the dictionary. When <iMode> equals the special value REX_AUGMENT, it only puts the attribute when does not already exist. | |
void* pDict->allocateMemory(rex_AttributeDictionary_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. | |
void pDict->clear(rex_AttributeDictionary_t* pDict) | Removes all entries from the dictionary. | |
abool_t pDict->containsKey(rex_AttributeDictionary_t* pDict, const char* <pszAttribute>) | Returns TRUE when the dictionary contains <pszAttribute>, otherwise returns FALSE. | |
abool_t pDict->containsKeyByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>) | Returns TRUE when the dictionary contains <pAttribute>, otherwise returns FALSE. | |
const char* pDict->firstKey(rex_AttributeDictionary_t* pDict) | Returns the name of the first attribute in the dictionary. Note, the attributes are not stored sorted by name. | |
const abytes_t* pDict->firstKeyByType (rex_AttributeDictionary_t* pDict) | Returns a pointer to the byte sequence defining the first attribute in the dictionary. Note, attributes are not stored sorted by name. | |
const char* pDict->get(rex_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. When the dictionary does not contain the attribute (or that many instances of the attribute), an empty string is returned. When <pbMore> is non-zero, the get method sets <pbMore> to TRUE when more instances of the attribute exist 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. | |
const abytes_t* pDict->getBytes(rex_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. When the dictionary does not contain the attribute (or that many instances of the attribute), 0 is returned. When <pbMore> is non-zero, the getBytes method sets <pbMore> to TRUE when more instances of the attribute exist 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. | |
const abytes_t* pDict->getBytesByType (rex_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. When the dictionary does not contain the attribute (or that many instances of the attribute), 0 is returned instead. When <pbMore> is non-zero, sets the variable pointed to to TRUE when more instances of the attribute exist 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. | |
const char* pDict->get(rex_AttributeDictionary_t* pDict, const abytes_t* <pszAttribute>, int <iIndex>, abool_t* <pbMore>) | Returns the value of the <iIndex>'d instance of the attribute from the dictionary, as represented as a string. When the dictionary does not contain the attribute (or that many instances of the attribute), returns an empty string. When <pbMore> is non-zero, the getByType method sets <pbMore> to TRUE when more instances of the attribute exist 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. | |
const char* pDict->getByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>) | Returns a pointer to the byte sequence defining the attribute, when the attribute name matches a configured attribute, zero otherwise. | |
abool_t pDict->isEmpty(rex_AttributeDictionary_t* pDict) | Returns TRUE when the dictionary has 0 entries, FALSE otherwise. | |
abool_t pDict->log(rex_AttributeDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...) | Outputs a message into the logging system used by the RADIUS server. <iLevel> should be one of REX_LOG_ERROR, REX_LOG_WARNING, or REX_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. | |
const char* pDict->nextKey(rex_AttributeDictionary_t* pDict) | Returns the name of the next attribute in the dictionary that follows the attribute returned in the last call to firstKey or nextKey. | |
const abytes_t* pDict-> nextKeyByType(rex_AttributeDictionary_t* pDict) | Returns a pointer to the byte sequence defining the next attribute in the dictionary that follows the attribute returned in the last call to firstKeyByType or nextKeyByType. | |
abool_t pDict->put(rex_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 <pszAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of <pszAttribute> with a single value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. Otherwise, a new instance of <pszAttribute> is inserted at the position indicated. This method returns TRUE unless <pszAttribute> does not match any configured attributes or the value could not be converted to a legal value. When <iIndex> equals the special value REX_AUGMENT, only put <pszAttribute> when it does not already exist. | |
abool_t pDict->putBytes(rex_AttributeDictionary_t* pDict, const char* <pszAttribute>, const abytes_t* <pValue>, int <iIndex>) | Associates <pValue> with the attribute <pszAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of the <pszAttribute> with a single new value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. When <iIndex> equals the special value REX_AUGMENT, only put the <pszAttribute> when it does not already exist. Otherwise, a new instance of <pszAttribute> is inserted at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes. | |
abool_t pDict->putBytesByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>, const abytes_t* <pValue>, int <iIndex>) | Associates <pValue> with the attribute <pAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of <pAttribute> with the new value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pAttribute> to the end of the list of existing instances of <pAttribute>. When <iIndex> equals the special value REX_AUGMENT, only put <pAttribute> when it does not already exist. Otherwise, insert a new instance of <pAttribute> at the position indicated. This method returns TRUE unless the attribute name does not match any configured attributes. | |
abool_t pDict->putByType(rex_AttributeDictionary_t* pDict, const abytes_t* <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 <pszAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of <pszAttribute> with a single new value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. Otherwise, it inserts a new instance of <pszAttribute> at the position indicated. This method returns TRUE unless <pszAttribute> does not match any configured attributes, or the value could not be converted to a legal value. | |
abool_t pDict->remove(rex_AttributeDictionary_t* pDict, const char* <pszAttribute>, int <iIndex>) | Removes the <pszAttribute> from the dictionary. When <iIndex> equals the special value REX_REMOVE_ALL, removes any existing instances of <pszAttribute>. Otherwise, it removes the instance of <pszAttribute> at the position indicated. Returns TRUE, even when the dictionary did not contain <pszAttribute> at the <iIndex>, unless <pszAttribute> does not match any configured attribute. | |
abool_t pDict->removeByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>, int <iIndex>) | Removes the <pAttribute> from the dictionary. When <iIndex> equals the special value REX_REMOVE_ALL, it removes any existing instances of <pszAttribute>. Otherwise, the instance of <pAttribute> at the position indicated is removed. Always returns TRUE, even when the dictionary did not contain <pAttribute> at the <iIndex>. | |
abool_t pDict->reschedule(rex_AttributeDictionary_t* pDict) | Enables control over asynchronous activities. It enables you to collect similar activities and mark them as pending. You can then process them and reschedule them. You can only use this attribute with multithreaded services. Use caution when employing this method. | |
int pDict->size(rex_AttributeDictionary_t* pDict) | Returns the number of entries in the dictionary. | |
abool_t pDict->trace(rex_AttributeDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...) | Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication 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, where everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level. |
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 REX 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, there can be only one instance of a key in the Environment dictionary.
The Environment dictionary uses active commands, called methods, to allow you to change and access the values in the dictionary. Table A-4 lists all of the methods you can use with the REX Environment dictionary.
| Name | Syntax | Description |
|---|---|---|
void* pDict->allocateMemory(rex_EnvironmentDictionary_t* pDict, unsigned int <iSize>) | Allocate 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. | |
void pDict->clear(rex_EnvironmentDictionary_t* pDict) | Removes all entries from the dictionary. | |
abool_t pDict->containsKey(rex_EnvironmentDictionary_t* pDict, const char* <pszKey>) | Returns TRUE when the dictionary contains <pszKey>, otherwise returns FALSE. | |
const char* pDict->firstKey(rex_EnvironmentDictionary_t* pDict) | Returns the name of the first key in the dictionary. Note, the keys are not stored sorted by name. | |
const char* pDict->get(rex_EnvironmentDictionary_t* pDict, const char* <pszKey>) | Returns the value associated with <pszKey> from the dictionary. When the dictionary does not contain <pszKey>, an empty string is returned. | |
abool_t pDict->isEmpty(rex_EnvironmentDictionary_t* pDict) | Returns TRUE when the dictionary has 0 entries, FALSE otherwise. | |
abool_t pDict->log(rex_EnvironmentDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...) | Outputs a message into the logging system used by the RADIUS server. <iLevel> should be one of REX_LOG_ERROR, REX_LOG_WARNING, or REX_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. | |
const char* pDict->nextKey(rex_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. | |
abool_t pDict->put(rex_EnvironmentDictionary_t* pDict, const char* <pszValue>, const char* <pszKey>) | Associates the value with <pszKey> in the dictionary, replacing any existing instance of <pszKey> with the new <pszValue>. | |
abool_t pDict->remove(rex_EnvironmentDictionary_t* pDict, const char* <pszKey>) | Removes <pszKey> and the associated value from the dictionary. Always returns TRUE, even when the dictionary did not contain <pszKey> | |
abool_t pDict->reschedule(rex_AttributeDictionary_t* pDict) | Enables control over asynchronous activities. It enables you to collect similar activities and mark them as pending. You can then process them and reschedule them. You can only use this attribute with multithreaded services. Use caution when employing this method. | |
int pDict->size(rex_EnvironmentDictionary_t* pDict) | Returns the number of entries in the dictionary. | |
abool_t pDict->trace(rex_EnvironmentDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...) | Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication 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, where everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level. |
Posted: Thu Aug 19 08:14:43 PDT 1999
Copyright 1989-1999©Cisco Systems Inc.