kim-api
2.1.2+v2.1.2.GNU
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
|
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... | |
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.
Definition at line 113 of file KIM_Collections.hpp.
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.
[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. |
true
if collection
or itemType
are unknown. true
if the list is not successfully cached for some reason. false
otherwise.extent == 0
and the cached list is empty if an error occurs.int KIM::Collections::CacheListOfItemMetadataFiles | ( | CollectionItemType const | itemType, |
std::string const & | itemName, | ||
int *const | extent | ||
) |
Cache a list of an item's metadata files.
[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. |
true
if itemType
is unknown. true
if the list is not successfully cached for some reason. false
otherwise.extent == 0
and the cached list is empty if an error occurs.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.
[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. |
true
if collection
or itemType
are unknown. true
if the list is not successfully cached for some reason. false
otherwise.extent == 0
and the cached list is empty if an error occurs.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.
[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. |
true
if collection
or itemType
are unknown. false
otherwise.extent == 0
and the cached list is empty if an error occurs.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.
[in] | itemType | The KIM::CollectionItemType of the items. |
[out] | extent | The number of item names in the list. |
true
if itemType
is unknown. false
otherwise.extent == 0
and the cached list is empty if an error occurs.
|
static |
Create a new KIM API Collections object.
[out] | collections | Pointer to the newly created Collections object. |
true
if the KIM API is unable to allocate a new log object. false
otherwise.collections
== NULL
if an error occurs.
|
static |
Destroy a previously Collections::Create'd object.
[in,out] | collections | Pointer to the Collections object. |
collections
points to a previously created KIM API Collections object.collections == NULL
.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.
[out] | name | The name of the environment variable. |
[out] | value | The current value of the environment variable. |
name
and value
may be NULL
if the corresponding value is not needed.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.
[out] | fileName | The absolute file and path name of the configuration file. |
int KIM::Collections::GetDirectoryName | ( | int const | index, |
std::string const **const | directoryName | ||
) | const |
Get the name of a directory from the cached list.
[in] | index | Zero-based index for the directory name of interest. |
[out] | directoryName | The directory's name. |
true
if index
is invalid. false
otherwise.directoryName
is unchanged if an error occurs.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.
[in] | itemType | The KIM::CollectionItemType of interest. |
[out] | name | The environment variable name. |
true
if itemType
is unknown. false
otherwise.name
is unchanged if an error occurs.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.
[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. |
true
if itemType
is unknown. true
if a item with the specified type and name cannot be found. false
otherwise.fileName
and collection
may be NULL
if the corresponding value is not needed.fileName
and collection
are unchanged if an error occurs.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.
[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. |
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.fileName
is unchanged if an error occurs.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.
[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 fales otherwise. |
[out] | fileString | The contents of the metadata file as a string, if availableAsString == true , NULL otherwise. |
true
if index
is invalid. false
otherwise.fileName
, fileLength
, fileRawData
, availableAsString
, and fileString
may be NULL
if the corresponding value is not needed.fileName
, fileLength
, fileRawData
, availableAsString
, fileString
are unchanged if an error occurs.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.
[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 fales otherwise. |
[out] | fileString | The contents of the metadata file as a string, if availableAsString == true , NULL otherwise. |
true
if index
is invalid. false
otherwise.fileName
, fileLength
, fileRawData
, availableAsString
, and fileString
may be NULL
if the corresponding value is not needed.fileName
, fileLength
, fileRawData
, availableAsString
, fileString
are unchanged if an error occurs.int KIM::Collections::GetItemNameByCollectionAndType | ( | int const | index, |
std::string const **const | itemName | ||
) | const |
Get the name of an item from the cached list.
[in] | index | Zero-based index for the item name of interest. |
[out] | itemName | The item's name. |
true
if index
is invalid. false
otherwise.itemName
is unchanged if an error occurs.int KIM::Collections::GetItemNameByType | ( | int const | index, |
std::string const **const | itemName | ||
) | const |
Get the name of an item from the cached list.
[in] | index | Zero-based index for the item name of interest. |
[out] | itemName | The item's name. |
true
if index
is invalid. false
otherwise.itemName
is unchanged if an error occurs.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).
[in] | itemName | The item name to be found. |
[out] | itemType | The KIM::CollectionItemType of the item. |
true
if an item with the specificed name cannot be found. false
otherwise.itemType
is unchanged if an error occurs.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.
[out] | projectName | The project name. |
[out] | semVer | The complete Semantic Version string. |
projectName
and semVer
may be NULL
if the corresponding value is not needed.void KIM::Collections::PopLogVerbosity | ( | ) |
Pop a LogVerbosity from the Collections object's Log object verbosity stack.
void KIM::Collections::PushLogVerbosity | ( | LogVerbosity const | logVerbosity | ) |
Push a new LogVerbosity onto the Collections object's Log object verbosity stack.
[in] | logVerbosity | A LogVerbosity value. |
void KIM::Collections::SetLogID | ( | std::string const & | logID | ) |
Set the identity of the Log object associated with the Collections object.
[in] | logID | String identifying the Collections object's Log object. |