# MTEnumConfig

Top level object that contains methods for:

- Reading existing enumerated types' collection; and

- Reading new and updating existing enum space objects (enum type collections).

Internal collections are created from a number of XML files, located under the directory passed to the Initialize() method.

## Program ID

Metratech.MTEnumConfig.1

## MtEnumConfig Methods

EnumerateFQN | Sets internal iterator to collection begin.
FQNCollectionEnd | Did internal iterator hit collections end?
FQNCount | Number of elements in the collection.
GetEnumeratorByID | Looks up an FQN using the NameId object and then gets the enumerator part from it.
GetEnumerators | Returns MTEnumeratorCollection given enum space name and enum type name.
GetEnumFileList | Internal Use Only
GetEnumSpace | Looks up an enumspace in internal EnumSpaceCollection object by name and returns it.
GetEnumSpaces | Returns an internal EnumSpaceCollection object - all enum space objects defined in enumtype XML files.
GetEnumType | Returns MTEnumType object given enum space name and enum type name.
GetEnumeratorValueByID | Returns a first value for enumerator by given id.
GetEnumWithValue | Looks up an enumerator for a given enum space, enum type and value metered in.
GetFileName | Internal use only.
GetFQN | Looks up an enumerator for given enum space, enum type and value metered in.
GetID | Returns a description id.
Initialize | If config_root is empty, create an internal map and COM collections running system config tree (pointed to in MTConfigDir registry value); if Read Only mode, all writing functionality will be disabled. Otherwise, set config directory to config_root\EnumType. Deprecated.
InitializeFromHost | Initializes internal collections remotely.
InitializeWithFileName | Initializes internal collections and gives master file name and/or host name. Deprecated.
LoadEnumeration | Adds an enumeration read from file to internal collection.
NextFQN | Returns next FQN in the collection.
Read | Internal use only.
ReadConfiguration | Internal use only.
ReadWithSet | Internal use only.
UpdateEnumSpace | Finds and updates an existing enum space.
UpdateMasterFile | Internal use only.
ValidEnumSpace | Returns 1 if enum space exists in the internal collection, 0 if it doesn't. Replace interger with Boolean VARIANT.
ValidEnumType | Returns 1 if enum type exists in given enum space, 0 if it doesn't. Replace interger with Boolean VARIANT.
WriteConfiguration | Internal use only.
WriteNewEnumSpace | Create file name as MT_CONFIG_DIR\\enum_space_name\enum_space_name.xml and calls WriteNewEnumSpaceWithFileName(relativeFilePath, pEnumSpace). Note: Check if this enumspace already exists in this file, right now it writes a duplicate one.
WriteNewEnumSpaceWithFileName | Writes an MTEnumSpace object to the given file. Note: Check if this enumspace already exists in this file, right now it writes a duplicate one.

## Example

An example will be available in future versions of this online help system.

# Method Detail

## GetEnumeratorValueByID

Returns a first value for enumerator by given id.

### Visual Basic Syntax

Function GetEnumeratorValueByID(aID As Long) As String

### C++ Syntax

HRESULT GetEnumeratorValueByID([in] long aID, [out, retval] BSTR* aEnum);

### Arguments

aID

ID of enumerator to retrieve.

### Return Value

Value (string) of the enumerator.

## GetID

Returns a description id.

### Visual Basic Syntax

Function GetID(enum_space As String, enum_name As String, enum_value As String) As Long

### C++ Syntax

HRESULT GetID([in] BSTR enum_space, [in] BSTR enum_name, [in]BSTR enum_value, [out,retval]long* name);

### Arguments

enum_space

Enum space for the enumerator, for example acme.com

enum_name

Enum name for the enumerator, for example ServiceLevel

enum_value

Enum value for the enumerator, for example Platinum

### Return Value

Enumerator's ID.

## Initialize

Replaces integer with Boolean VARIANT.

### Visual Basic Syntax

Sub Initialize([config_path])

### C++ Syntax

HRESULT Initialize([in, optional] VARIANT config_path);

### Arguments

VARIANT config_path

Directory under which EnumType/EnumFileList.xml master file will be found

### Return Value

S_OK for success or appropriate error code.

## GetEnumWithValue

Look up an enumerator for given enum space, enum type and value metered in. For example, country name enum type in Global enum space defined in Global.xml:

<mt_config>
<enum_spaces>
<enum_space name="Global">
<description>Global namespace</description>&#9;&#9;&#9;

<enums>
<enum name="CountryName">
<description>Country list enumeration</description>

<entries>
<entry name="Afghanistan">
<value>2</value>
</entry>
<entry name="Albania">
<value>3</value>
</entry>

For given Global as enum space. CountryName as enum type and 3 as value "Albania" will be returned.

### Visual Basic Syntax

Function GetEnumWithValue(enum_space As String, enum_name As String, enum_value As String) As String

### C++ Syntax

HRESULT GetEnumWithValue([in] BSTR enum_space, [in] BSTR enum_name, [in]BSTR enum_value, [out,retval]BSTR* name);

### Arguments

enum_space

Name for enum space.

enum_name

Name for enum type.

enum_value

Value metered in.

### Return Value

Enumerator name or empty string if not found.

## GetFQN

Looks up an enumerator for given enum space, enum type and value metered in. For example, country name enum type in Global enum space is defined in Global.xml as:

<mt_config>
<enum_spaces>
<enum_space name="Global">
<description>Global namespace</description>&#9;&#9;&#9;

<enums>
<enum name="CountryName">
<description>Country list enumeration</description>

<entries>
<entry name="Afghanistan">
<value>2</value>
</entry>
<entry name="Albania">
<value>3</value>
</entry>

For given Global as enum space. CountryName as enum type and 3 as value "Global/CountryName/Albania" will be returned.

### Visual Basic Syntax

Function GetFQN(enum_space As String, enum_name As String, enum_value As String) As String

### C++ Syntax

HRESULT GetFQN([in] BSTR enum_space, [in] BSTR enum_name, [in]BSTR enum_value, [out,retval]BSTR* name);

### Arguments

enum_space

Name for enum space.

enum_name

Name for enum type.

enum_value

Value metered in.

### Return Value

Enumerator fully qualified name or empty string if not found.

## Read

Internal use only.

## ReadWithSet

Internal use only.

## GetEnumFileList

Internal use only.

## GetEnumSpaces

Returns an internal EnumSpaceCollection object; all enum space objects are defined in enumtype XML files.

### Visual Basic Syntax

Function GetEnumSpaces() As MTEnumSpaceCollection

### C++ Syntax

HRESULT GetEnumSpaces([out, retval] IMTEnumSpaceCollection**);

### Return Value

Enum space collection.

## GetEnumSpace

Looks up an enumspace in the internal EnumSpaceCollection object by name and returns it.

### Visual Basic Syntax

Function GetEnumSpace(__MIDL_0015 As String) As MTEnumSpace

### C++ Syntax

HRESULT GetEnumSpace([in] BSTR, [out, retval] IMTEnumSpace** enum_space);

### Arguments

BSTR name

Enum space name to be looked up.

### Return Value

MTEnumSpace object

## WriteNewEnumSpaceWithFileName

Writes an MTEnumSpace object to the given file. Note: Check if this enum space already exists in this file, right now it writes a duplicate one.

### Visual Basic Syntax

Sub WriteNewEnumSpaceWithFileName(file As String, enum_space As MTEnumSpace)

### C++ Syntax

HRESULT WriteNewEnumSpaceWithFileName(BSTR file, IMTEnumSpace* enum_space);

### Arguments

file

File name for the enum space to be written to.

enum_space

Enum space object to be written to the file.

## UpdateEnumSpace

Finds and updates an existing enum space.

### Visual Basic Syntax

Sub UpdateEnumSpace(enum_space As MTEnumSpace)

### C++ Syntax

HRESULT UpdateEnumSpace(IMTEnumSpace* enum_space);

### Arguments

Enum_space

Enum space object to be written to the file.

## WriteNewEnumSpace

Creates file name as MT_CONFIG_DIR\\enum_space_name\enum_space_name.xml and calls WriteNewEnumSpaceWithFileName(relativeFilePath, pEnumSpace). Note: Check to see if this enum space already exists in this file, right now it writes a duplicate one.

### Visual Basic Syntax

Sub WriteNewEnumSpace(enum_space As MTEnumSpace)

### C++ Syntax

HRESULT WriteNewEnumSpace([in] IMTEnumSpace* enum_space);

### Arguments

enum_space

MTEnumSpace object to be written to the file.

## GetFileName

Internal use only.

### Arguments

BSTR name_space

Name for enumspace based on which the file name will be constructed

### Return Value

Constucted file name

## UpdateMasterFile

Internal use only.

### Arguments

BSTR name_space

New entry to be added to master file.

## ValidEnumSpace

Returns 1 if enum space exists in the internal collection, 0 if it doesn't. Replace interger with Boolean VARIANT.

### Visual Basic Syntax

Function ValidEnumSpace(name As String) As Long

### C++ Syntax

HRESULT ValidEnumSpace([in] BSTR name, [out, retval] int* ret);

### Arguments

name

Name for enum space.

### Return Value

Return code.

## ValidEnumType

Returns 1 if enum type exists in given enum space, 0 if it doesn't. Replace interger with Boolean VARIANT.

### Visual Basic Syntax

Function ValidEnumType(__MIDL_0017 As String, __MIDL_0018 As String) As Long

### C++ Syntax

HRESULT ValidEnumType([in] BSTR enumspace_name, [in] BSTR enumtype_name, [out, retval] int* ret);

### Arguments

enum_space

Name for enum space.

enum_type

Name for enum type.

### Return Value

Return code.

## GetEnumType

Returns MTEnumType object given enum space name and enum type name.

### Visual Basic Syntax

Function GetEnumType(enum_space As String, enum_type As String) As MTEnumType

### C++ Syntax

HRESULT GetEnumType([in] BSTR enum_space, [in] BSTR enum_type, [out, retval] IMTEnumType** pEnumType);

### Arguments

enum_space

Name for enum space.

enum_type

Name for enum type.

### Return Value

Return code.

## GetEnumerators

Returns MTEnumeratorCollection given enum space name and enum type name.

### Visual Basic Syntax

Function GetEnumerators(enum_space As String, enum_type As String) As MTEnumeratorCollection

### C++ Syntax

HRESULT GetEnumerators([in] BSTR enum_space, [in] BSTR enum_type, [out, retval] IMTEnumeratorCollection** coll);

### Arguments

enum_space

Name for enum space.

enum_type

Name for enum type.

### Return Value

MTEnumeratorCollection

Enumerator collection object.

## InitializeFromHost

Initializes internal collections remotely.

### Visual Basic Syntax

Sub InitializeFromHost(host As String, relative_path As String)

### C++ Syntax

HRESULT InitializeFromHost(BSTR host, BSTR relative_path);

### Arguments

host

Host name.

relative_path

Host's virtual directory.

## ReadConfiguration

Internal use only.

### Arguments

IMTConfigPropSet**

Propset to be filled from file.

BSTR file

File path to fill propset from.

## WriteConfiguration

Internal use only.

### Arguments

IMTConfigPropSet**

Propset to be filled from file.

BSTR file

File path to fill propset from.

## LoadEnumeration

Adds an enumeration read from file to internal collection.

### Visual Basic Syntax

Sub LoadEnumeration(from_file_path As String)

### C++ Syntax

HRESULT LoadEnumeration([in] BSTR from_file_path);

### Arguments

from_file_path

File where enumeration is defined.

## InitializeWithFileName

Initializes internal collections to give master file name and/or host name.

### Visual Basic Syntax

Sub InitializeWithFileName(master_file_full_path As String, [host_name])

### C++ Syntax

HRESULT InitializeWithFileName([in]BSTR master_file_full_path, [in, optional]VARIANT host_name);

### Arguments

master_file_full_path

Full path to master file.

host_name

Optional host name.

## EnumerateFQN

Sets internal iterator to collection begin.

### Visual Basic Syntax

Sub EnumerateFQN()

### C++ Syntax

HRESULT EnumerateFQN();

## NextFQN

Returns next FQN in the collection.

### Visual Basic Syntax

Function NextFQN() As String

### C++ Syntax

HRESULT NextFQN([out, retval] BSTR* fqn);

### Return Value

Returns next FQN in the collection as a string.

## FQNCollectionEnd

Did internal iterator hit collections end?

### Visual Basic Syntax

Function FQNCollectionEnd() As Long

### C++ Syntax

HRESULT FQNCollectionEnd([out, retval] int* ret);

### Return Value

Return code.

## FQNCount

Number of elements in the collection.

### Visual Basic Syntax

Function FQNCount() As Long

### C++ Syntax

HRESULT FQNCount([out, retval] int* pVal);

### Return Value

pVal

Number of elements in the collection.

## GetEnumeratorByID

This helper method takes in an ID that is being stored in a session and returns an enumerator name for this id. For example:

If "Global/CountryName/Estonia" fully qualified name has ID 56 in t_enum_data_table, then GetEnumeratorByID(56) will return "Estonia"

This method could be useful for plugins that want to do something based on the enum type value that is being metered in. Right now there is no easy way to do it, because when session is generated, all enum types are stored in a session as an ID from t_enum_data table.

### Visual Basic Syntax

Function GetEnumeratorByID(aID As Long) As String

### C++ Syntax

HRESULT GetEnumeratorByID([in] long aID, [out, retval] BSTR* aEnum);

### Arguments

aID

Value from t_enum_data table

### Return Value

Enumerator string