Provides the interface to the KIM API Collections and is meant to be used by simulators. More...

#include <KIM_Collections.hpp>

Public Member Functions
int	GetItemType (std::string const &itemName, CollectionItemType *const itemType) const
	Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name. More...

int	GetItemLibraryFileNameAndCollection (CollectionItemType const itemType, std::string const &itemName, std::string const *const fileName, Collection const collection) const
	Get the item's library file name and its KIM::Collection. More...

int	CacheListOfItemMetadataFiles (CollectionItemType const itemType, std::string const &itemName, int *const extent)
	Cache a list of an item's metadata files. More...

int	GetItemMetadataFile (int const index, std::string const *const fileName, unsigned int const fileLength, unsigned char const *const fileRawData, int const availableAsString, std::string const **const fileString) const
	Get the name and content of one of an item's metadata files. More...

int	CacheListOfItemNamesByType (CollectionItemType const itemType, int *const extent)
	Cache a list of all item names of a specific type in the KIM API collections. More...

int	GetItemNameByType (int const index, std::string const **const itemName) const
	Get the name of an item from the cached list. More...

int	CacheListOfItemNamesByCollectionAndType (Collection const collection, CollectionItemType const itemType, int *const extent)
	Cache a list of all item names of a specific type in a specific collection. More...

int	GetItemNameByCollectionAndType (int const index, std::string const **const itemName) const
	Get the name of an item from the cached list. More...

int	GetItemLibraryFileNameByCollectionAndType (Collection const collection, CollectionItemType const itemType, std::string const &itemName, std::string const **const fileName) const
	Get the item's library file name. More...

int	CacheListOfItemMetadataFilesByCollectionAndType (Collection const collection, CollectionItemType const itemType, std::string const &itemName, int *const extent)
	Cache a list of an item's metadata files. More...

int	GetItemMetadataFileByCollectionAndType (int const index, std::string const *const fileName, unsigned int const fileLength, unsigned char const *const fileRawData, int const availableAsString, std::string const **const fileString) const
	Get the name and content of one of an item's metadata files. More...

void	GetProjectNameAndSemVer (std::string const const projectName, std::string const const semVer) const
	Get the KIM API project name and full Semantic Version string. More...

int	GetEnvironmentVariableName (CollectionItemType const itemType, std::string const **const name) const
	Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection. More...

void	GetConfigurationFileEnvironmentVariable (std::string const const name, std::string const const value) const
	Get the name and value of the environment variable that stores the name of the KIM API user configuration file. More...

void	GetConfigurationFileName (std::string const **const fileName) const
	Get the absolute file and path name of the KIM API user configuration file. More...

int	CacheListOfDirectoryNames (Collection const collection, CollectionItemType const itemType, int *const extent)
	Cache a list of directory names where a specific KIM API collection stores library files for a specific item type. More...

int	GetDirectoryName (int const index, std::string const **const directoryName) const
	Get the name of a directory from the cached list. More...

void	SetLogID (std::string const &logID)
	Set the identity of the Log object associated with the Collections object. More...

void	PushLogVerbosity (LogVerbosity const logVerbosity)
	Push a new LogVerbosity onto the Collections object's Log object verbosity stack. More...

void	PopLogVerbosity ()
	Pop a LogVerbosity from the Collections object's Log object verbosity stack. More...

Static Public Member Functions
static int	Create (Collections **const collections)
	Create a new KIM API Collections object. More...

static void	Destroy (Collections **const collections)
	Destroy a previously Collections::Create'd object. More...

Detailed Description

Provides the interface to the KIM API Collections and is meant to be used by simulators.

The KIM API defines interfaces to various types of "items" (KIM::CollectionItemType) and these items are organized and stored in various "collections" (KIM::Collection) on the user's system. Items are generally installed to or removed from the collections by using the kim-api-collections-management utility, and the KIM API/PMI and KIM API/SMI find items within the collections using the KIM::Collections interface. Typically, the collections are associated with different levels of user permissions on the system. The KIM::COLLECTION::system collection is available to all users on the system and is managed by the system administrator and cannot be changed by users without administrator privileges. The KIM::COLLECTION::user collection is specific to each user and the use has full privileges to manage the collection. The KIM::COLLECTION::environmentVariable and the KIM::COLLECTION::currentWorkingDirectory collections allow users more dynamic flexibility to manage and store items for special purposes.

Each collection consists of a set of items organized by their item type (KIM::CollectionItemType). There are currently three item types: KIM::COLLECTION_ITEM_TYPE::portableModel represents KIM Portable Models that can be used with any simulator that supports the KIM API/PMI; KIM::COLLECTION_ITEM_TYPE::simulatorModel represents the KIM Simulator Models that can be used with a specific simulator that supports the KIM API/SMI; and KIM::COLLECTION_ITEM_TYPE::modelDriver represents KIM Model Drivers that are libraries of code that can be used by multiple Portable Models to help reduce code duplication. The KIM::Collections interface provides programatic access to the contents and system settings for the KIM API collections and items stored within them. The contents and settings of the collections can change during the lifetime of a KIM::Collections object (due to installation or removal of items by other processes on the machine and/or changes to environment variables or the configuration file). Therefore, when lists of information about the collections are requested (via a "CacheListOf...()" routine), the KIM::Collections interface first creates a cache of the list and then provides access to the cached list via a getter ("Get...()") routine. The cached list is only updated when the simulator makes another request for the list (via a "CacheListOf...()" routine).

Items in the KIM API collections are generally referred to by name. An item name is required to be a valid C-identifier (no other restrictions are imposed by the KIM API). Items in different collections can have the same name and items of different type can have the same name. However, this should generally be avoided. Typically, an item is referred to by specifying its type and name. In such cases the KIM API will search through the KIM API collections in a specific order (first the KIM::COLLECTION::currentWorkingDirectory, then KIM::COLLECTION::environmentVariable, then KIM::COLLECTION::user, and finally KIM::COLLECTION::system) and return the first occurrence of an item with the requested type and name that is found. In some cases only the name of the desired item is known, and Collections::GetItemType must be used first to determine the item's type. The Collections::GetItemType routine will search through each collection (in the order described just above) and through each item type within each collection in a specific order (first the KIM::COLLECTION_ITEM_TYPE::portableModel type, then the KIM::COLLECTION_ITEM_TYPE::simulatorModel type, and finally the KIM::COLLECTION_ITEM_TYPE::modelDriver type) and return the first occurrence of an item with the requested name that is found.

See also: KIM_Collections, kim_collections_module::kim_collections_handle_type

Since: 2.1

Definition at line 110 of file KIM_Collections.hpp.

Member Function Documentation

◆ CacheListOfDirectoryNames()

int KIM::Collections::CacheListOfDirectoryNames	(	Collection const	collection,
		CollectionItemType const	itemType,
		int *const	extent
	)

Cache a list of directory names where a specific KIM API collection stores library files for a specific item type.

Parameters

[in]	collection	The KIM::Collection of the items.
[in]	itemType	The KIM::CollectionItemType of the items.
[out]	extent	The number of directory names in the list.

Returns: true if collection or itemType are unknown.; true if the list is not successfully cached for some reason.; false otherwise.

Postcondition: extent == 0 and the cached list is empty if an error occurs.

See also: KIM_Collections_CacheListOfDirectoryNames, kim_collections_module::kim_cache_list_of_directory_names

Since: 2.1

◆ CacheListOfItemMetadataFiles()

int KIM::Collections::CacheListOfItemMetadataFiles	(	CollectionItemType const	itemType,
		std::string const &	itemName,
		int *const	extent
	)

Cache a list of an item's metadata files.

Parameters

[in]	itemType	The KIM::CollectionItemType of the item.
[in]	itemName	The name of the item.
[out]	extent	The number of metadata files in the list.

Returns: true if itemType is unknown.; true if the list is not successfully cached for some reason.; false otherwise.

Postcondition: extent == 0 and the cached list is empty if an error occurs.

See also: KIM_Collections_CacheListOfItemMetadataFiles, kim_collections_module::kim_cache_list_of_item_metadata_files

Since: 2.1

◆ CacheListOfItemMetadataFilesByCollectionAndType()

int KIM::Collections::CacheListOfItemMetadataFilesByCollectionAndType	(	Collection const	collection,
		CollectionItemType const	itemType,
		std::string const &	itemName,
		int *const	extent
	)

Cache a list of an item's metadata files.

Parameters

[in]	collection	The KIM::Collection of the item.
[in]	itemType	The KIM::CollectionItemType of the item.
[in]	itemName	The name of the item.
[out]	extent	The number of metadata files in the list.

Returns: true if collection or itemType are unknown.; true if the list is not successfully cached for some reason.; false otherwise.

Postcondition: extent == 0 and the cached list is empty if an error occurs.

See also: KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType, kim_collections_module::kim_cache_list_of_item_metadata_files_by_collection_and_type

Since: 2.1

◆ CacheListOfItemNamesByCollectionAndType()

int KIM::Collections::CacheListOfItemNamesByCollectionAndType	(	Collection const	collection,
		CollectionItemType const	itemType,
		int *const	extent
	)

Cache a list of all item names of a specific type in a specific collection.

Parameters

[in]	collection	The KIM::Collection of the items.
[in]	itemType	The KIM::CollectionItemType of the items.
[out]	extent	The number of item names in the list.

Returns: true if collection or itemType are unknown.; false otherwise.

Postcondition: extent == 0 and the cached list is empty if an error occurs.

See also: KIM_Collections_CacheListOfItemNamesByCollectionAndType, kim_collections_module::kim_cache_list_of_item_names_by_collection_and_type

Since: 2.1

◆ CacheListOfItemNamesByType()

int KIM::Collections::CacheListOfItemNamesByType	(	CollectionItemType const	itemType,
		int *const	extent
	)

Cache a list of all item names of a specific type in the KIM API collections.

Parameters

[in]	itemType	The KIM::CollectionItemType of the items.
[out]	extent	The number of item names in the list.

Returns: true if itemType is unknown.; false otherwise.

Postcondition: extent == 0 and the cached list is empty if an error occurs.

See also: KIM_Collections_CacheListOfItemNamesByType, kim_collections_module::kim_cache_list_of_item_names_by_type

Since: 2.1

◆ Create()

static int KIM::Collections::Create ( Collections **const collections )

static

Create a new KIM API Collections object.

Parameters

[out] collections Pointer to the newly created Collections object.

Returns: true if the KIM API is unable to allocate a new log object.; false otherwise.

Postcondition: collections == NULL if an error occurs.

See also: KIM_Collections_Create, kim_collections_module::kim_collections_create

Since: 2.1

◆ Destroy()

static void KIM::Collections::Destroy ( Collections **const collections )

static

Destroy a previously Collections::Create'd object.

Parameters

[in,out] collections Pointer to the Collections object.

Precondition: *collections points to a previously created KIM API Collections object.

Postcondition: *collections == NULL.

See also: KIM_Collections_Destroy, kim_collections_module::kim_collections_destroy

Since: 2.1

◆ GetConfigurationFileEnvironmentVariable()

void KIM::Collections::GetConfigurationFileEnvironmentVariable	(	std::string const **const	name,
		std::string const **const	value
	)		const

Get the name and value of the environment variable that stores the name of the KIM API user configuration file.

The KIM API user configuration file contains configuration settings for the KIM::COLLECTION::user collection.

Note: String pointers obtained from this routine are valid until the next call to Collections::GetConfigurationFileEnvironmentVariable or the KIM::Collections object is Collections::Destroy'd.

Parameters

[out]	name	The name of the environment variable.
[out]	value	The current value of the environment variable.

Precondition: name and value may be NULL if the corresponding value is not needed.

See also: KIM_Collections_GetConfigurationFileEnvironmentVariable, kim_collections_module::kim_get_configuration_file_environment_variable

Since: 2.1

◆ GetConfigurationFileName()

void KIM::Collections::GetConfigurationFileName ( std::string const **const fileName ) const

Get the absolute file and path name of the KIM API user configuration file.

The KIM API user configuration file contains configuration settings for the KIM::COLLECTION::user collection.

Note: String pointer obtained from this routine are valid until the next call to Collections::GetConfigurationFileName or the KIM::Collections object is Collections::Destroy'd.

Parameters

[out] fileName The absolute file and path name of the configuration file.

See also: KIM_Collections_GetConfigurationFileName, kim_collections_module::kim_get_configuration_file_name

Since: 2.1

◆ GetDirectoryName()

int KIM::Collections::GetDirectoryName	(	int const	index,
		std::string const **const	directoryName
	)		const

Get the name of a directory from the cached list.

Parameters

[in]	index	Zero-based index for the directory name of interest.
[out]	directoryName	The directory's name.

Note: String pointers obtained from this routine are valid until the next call to Collections::CacheListOfDirectoryNames or the KIM::Collections object is Collections::Destroy'd.

Returns: true if index is invalid.; false otherwise.

Precondition: Collections::CacheListOfDirectoryNames must have been successfully executed before Collections::GetDirectoryName is called.

Postcondition: directoryName is unchanged if an error occurs.

See also: KIM_Collections_GetDirectoryName, kim_collections_module::kim_get_directory_name

Since: 2.1

◆ GetEnvironmentVariableName()

int KIM::Collections::GetEnvironmentVariableName	(	CollectionItemType const	itemType,
		std::string const **const	name
	)		const

Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection.

Parameters

[in]	itemType	The KIM::CollectionItemType of interest.
[out]	name	The environment variable name.

Returns: true if itemType is unknown.; false otherwise.

Postcondition: name is unchanged if an error occurs.

See also: KIM_Collections_GetEnvironmentVariableName, kim_collections_module::kim_get_environment_variable_name

Since: 2.1

◆ GetItemLibraryFileNameAndCollection()

int KIM::Collections::GetItemLibraryFileNameAndCollection	(	CollectionItemType const	itemType,
		std::string const &	itemName,
		std::string const **const	fileName,
		Collection *const	collection
	)		const

Get the item's library file name and its KIM::Collection.

Parameters

[in]	itemType	The KIM::CollectionItemType of the item.
[in]	itemName	The name of the item.
[out]	fileName	The absolute file and path name of the item's library.
[out]	collection	The KIM::Collection in which the item was found.

Returns: true if itemType is unknown.; true if a item with the specified type and name cannot be found.; false otherwise.

Precondition: fileName and collection may be NULL if the corresponding value is not needed.

Postcondition: fileName and collection are unchanged if an error occurs.

See also: KIM_Collections_GetItemLibraryFileNameAndCollection, kim_collections_module::kim_get_item_library_file_name_and_collection

Since: 2.1

◆ GetItemLibraryFileNameByCollectionAndType()

int KIM::Collections::GetItemLibraryFileNameByCollectionAndType	(	Collection const	collection,
		CollectionItemType const	itemType,
		std::string const &	itemName,
		std::string const **const	fileName
	)		const

Get the item's library file name.

Parameters

[in]	collection	The KIM::Collection of the item.
[in]	itemType	The KIM::CollectionItemType of the item.
[in]	itemName	The name of the item.
[out]	fileName	The absolute file and path name of the item's library.

Returns: true if collection or itemType are unknown.; true if a item with the specified type and name cannot be found in the specified collection.; false otherwise.

Postcondition: fileName is unchanged if an error occurs.

See also: KIM_Collections_GetItemLibraryFileNameByCollectionAndType, kim_collections_module::kim_get_item_library_file_name_by_collection_and_type

Since: 2.1

◆ GetItemMetadataFile()

int KIM::Collections::GetItemMetadataFile	(	int const	index,
		std::string const **const	fileName,
		unsigned int *const	fileLength,
		unsigned char const **const	fileRawData,
		int *const	availableAsString,
		std::string const **const	fileString
	)		const

Get the name and content of one of an item's metadata files.

Provide access to the specified metadata file's name and raw data. If there are no embedded NULL characters in the raw data, the file contents are also provided as a string, for convenience.

Parameters

[in]	index	Zero-based index for the metadata file of interest.
[out]	fileName	The basename (file name without path) of the metadata file.
[out]	fileLength	The length of the metadata file.
[out]	fileRawData	The raw metadata file content, as a contiguous block of memory of length `fileLength`.
[out]	availableAsString	An integer that is set to `true` if the metadata file has no embedded `NULL` characters, and set to `false` otherwise.
[out]	fileString	The contents of the metadata file as a string, if `availableAsString == true`, `NULL` otherwise.

Note: String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemMetadataFiles or the KIM::Collections object is Collections::Destroy'd.

Returns: true if index is invalid.; false otherwise.

Precondition: Collections::CacheListOfItemMetadataFiles must have been successfully executed before Collections::GetItemMetadataFile is called.; fileName, fileLength, fileRawData, availableAsString, and fileString may be NULL if the corresponding value is not needed.

Postcondition: fileName, fileLength, fileRawData, availableAsString, fileString are unchanged if an error occurs.

See also: KIM_Collections_GetItemMetadataFile, kim_collections_module::kim_get_item_metadata_file_length, kim_collections_module::kim_get_item_metadata_file_values

Since: 2.1

◆ GetItemMetadataFileByCollectionAndType()

int KIM::Collections::GetItemMetadataFileByCollectionAndType	(	int const	index,
		std::string const **const	fileName,
		unsigned int *const	fileLength,
		unsigned char const **const	fileRawData,
		int *const	availableAsString,
		std::string const **const	fileString
	)		const

Get the name and content of one of an item's metadata files.

Provide access to the specified metadata file's name and raw data. If there are no embedded NULL characters in the raw data, the file contents are also provided as a string, for convenience.

Parameters

[in]	index	Zero-based index for the metadata file of interest.
[out]	fileName	The basename (file name without path) of the metadata file.
[out]	fileLength	The length of the metadata file.
[out]	fileRawData	The raw metadata file content, as a contiguous block of memory of length `fileLength`.
[out]	availableAsString	An integer that is set to `true` if the metadata file has no embedded `NULL` characters, and set to `false` otherwise.
[out]	fileString	The contents of the metadata file as a string, if `availableAsString == true`, `NULL` otherwise.

Note: String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemMetadataFilesByCollectionAndType or the KIM::Collections object is Collections::Destroy'd.

Returns: true if index is invalid.; false otherwise.

Precondition: Collections::CacheListOfItemMetadataFilesByCollectionAndType must have been successfully executed before Collections::GetItemMetadataFileByCollectionAndType is called.; fileName, fileLength, fileRawData, availableAsString, and fileString may be NULL if the corresponding value is not needed.

Postcondition: fileName, fileLength, fileRawData, availableAsString, fileString are unchanged if an error occurs.

See also: KIM_Collections_GetItemMetadataFileByCollectionAndType, kim_collections_module::kim_get_item_metadata_file_length_by_collection_and_type, kim_collections_module::kim_get_item_metadata_file_values_by_collection_and_type

Since: 2.1

◆ GetItemNameByCollectionAndType()

int KIM::Collections::GetItemNameByCollectionAndType	(	int const	index,
		std::string const **const	itemName
	)		const

Get the name of an item from the cached list.

Parameters

[in]	index	Zero-based index for the item name of interest.
[out]	itemName	The item's name.

Note: String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemNamesByCollectionAndType or the KIM::Collections object is Collections::Destroy'd.

Returns: true if index is invalid.; false otherwise.

Precondition: Collections::CacheListOfItemNamesByCollectionAndType must have been successfully executed before Collections::GetItemNameByCollectionAndType is called.

Postcondition: itemName is unchanged if an error occurs.

See also: KIM_Collections_GetItemNameByCollectionAndType, kim_collections_module::kim_get_item_name_by_collection_and_type

Since: 2.1

◆ GetItemNameByType()

int KIM::Collections::GetItemNameByType	(	int const	index,
		std::string const **const	itemName
	)		const

Get the name of an item from the cached list.

Parameters

[in]	index	Zero-based index for the item name of interest.
[out]	itemName	The item's name.

Note: String pointers obtained from this routine are valid until the next call to Collections::CacheListOfItemNamesByType or the KIM::Collections object is Collections::Destroy'd.

Returns: true if index is invalid.; false otherwise.

Precondition: Collections::CacheListOfItemNamesByType must have been successfully executed before Collections::GetItemNameByType is called.

Postcondition: itemName is unchanged if an error occurs.

See also: KIM_Collections_GetItemNameByType, kim_collections_module::kim_get_item_name_by_type

Since: 2.1

◆ GetItemType()

int KIM::Collections::GetItemType	(	std::string const &	itemName,
		CollectionItemType *const	itemType
	)		const

Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name.

Searches for an item with the given name in the KIM API collections and item types (using the standard order for collections and item types).

Parameters

[in]	itemName	The item name to be found.
[out]	itemType	The KIM::CollectionItemType of the item.

Returns: true if an item with the specificed name cannot be found.; false otherwise.

Postcondition: itemType is unchanged if an error occurs.

See also: KIM_Collections_GetItemType, kim_collections_module::kim_get_item_type

Since: 2.1

◆ GetProjectNameAndSemVer()

void KIM::Collections::GetProjectNameAndSemVer	(	std::string const **const	projectName,
		std::string const **const	semVer
	)		const

Get the KIM API project name and full Semantic Version string.

The KIM API project name and version string are controlled by CMake settings during the configuration process.

Note: String pointers obtained from this routine are valid until the KIM::Collections object is Collections::Destroy'd.

Parameters

[out]	projectName	The project name.
[out]	semVer	The complete Semantic Version string.

Precondition: projectName and semVer may be NULL if the corresponding value is not needed.

See also: KIM_Collections_GetProjectNameAndSemVer, kim_collections_module::kim_get_project_name_and_sem_ver

Since: 2.1

◆ PopLogVerbosity()

void KIM::Collections::PopLogVerbosity ( )

Pop a LogVerbosity from the Collections object's Log object verbosity stack.

See also: KIM_Collections_PopLogVerbosity, kim_collections_module::kim_pop_log_verbosity

Since: 2.1

◆ PushLogVerbosity()

void KIM::Collections::PushLogVerbosity ( LogVerbosity const logVerbosity )

Push a new LogVerbosity onto the Collections object's Log object verbosity stack.

Parameters

[in] logVerbosity A LogVerbosity value.

See also: KIM_Collections_PushLogVerbosity, kim_collections_module::kim_push_log_verbosity

Since: 2.1

◆ SetLogID()

void KIM::Collections::SetLogID ( std::string const & logID )

Set the identity of the Log object associated with the Collections object.

Parameters

[in] logID String identifying the Collections object's Log object.

See also: KIM_Collections_SetLogID, kim_collections_module::kim_set_log_id

Since: 2.1

The documentation for this class was generated from the following file:

devel/cpp/include/KIM_Collections.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CacheListOfDirectoryNames()

◆ CacheListOfItemMetadataFiles()

◆ CacheListOfItemMetadataFilesByCollectionAndType()

◆ CacheListOfItemNamesByCollectionAndType()

◆ CacheListOfItemNamesByType()

◆ Create()

◆ Destroy()

◆ GetConfigurationFileEnvironmentVariable()

◆ GetConfigurationFileName()

◆ GetDirectoryName()

◆ GetEnvironmentVariableName()

◆ GetItemLibraryFileNameAndCollection()

◆ GetItemLibraryFileNameByCollectionAndType()

◆ GetItemMetadataFile()

◆ GetItemMetadataFileByCollectionAndType()

◆ GetItemNameByCollectionAndType()

◆ GetItemNameByType()

◆ GetItemType()

◆ GetProjectNameAndSemVer()

◆ PopLogVerbosity()

◆ PushLogVerbosity()

◆ SetLogID()