kim-api
2.3.1-git+v2.3.0-git-2-g378406f9.GNU.GNU.
An Application Programming Interface (API) for the Knowledgebase of Interatomic Models (KIM).
|
Go to the source code of this file.
Typedefs | |
typedef struct KIM_LogVerbosity | KIM_LogVerbosity |
Forward declaration. More... | |
typedef struct KIM_Collection | KIM_Collection |
typedef struct KIM_CollectionItemType | KIM_CollectionItemType |
typedef struct KIM_Collections | KIM_Collections |
Provides the interface to the KIM API Collections and is meant to be used by simulators. More... | |
Functions | |
int | KIM_Collections_Create (KIM_Collections **const collections) |
Create a new KIM API Collections object. More... | |
void | KIM_Collections_Destroy (KIM_Collections **const collections) |
Destroy a previously Collections::Create'd object. More... | |
int | KIM_Collections_GetItemType (KIM_Collections *const collections, char const *const itemName, KIM_CollectionItemType *const itemType) |
Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name. More... | |
int | KIM_Collections_GetItemLibraryFileNameAndCollection (KIM_Collections *const collections, KIM_CollectionItemType const itemType, char const *const itemName, char const **const fileName, KIM_Collection *const collection) |
Get the item's library file name and its KIM::Collection. More... | |
int | KIM_Collections_CacheListOfItemMetadataFiles (KIM_Collections *const collections, KIM_CollectionItemType const itemType, char const *const itemName, int *const extent) |
Cache a list of an item's metadata files. More... | |
int | KIM_Collections_GetItemMetadataFile (KIM_Collections *const collections, int const index, char const **const fileName, unsigned int *const fileLength, unsigned char const **const fileRawData, int *const availableAsString, char const **const fileString) |
Get the name and content of one of an item's metadata files. More... | |
int | KIM_Collections_CacheListOfItemNamesByType (KIM_Collections *const collections, KIM_CollectionItemType const itemType, int *const extent) |
Cache a list of all item names of a specific type in the KIM API collections. More... | |
int | KIM_Collections_GetItemNameByType (KIM_Collections *const collections, int const index, char const **const itemName) |
Get the name of an item from the cached list. More... | |
int | KIM_Collections_CacheListOfItemNamesByCollectionAndType (KIM_Collections *const collections, KIM_Collection const collection, KIM_CollectionItemType const itemType, int *const extent) |
Cache a list of all item names of a specific type in a specific collection. More... | |
int | KIM_Collections_GetItemNameByCollectionAndType (KIM_Collections *const collections, int const index, char const **const itemName) |
Get the name of an item from the cached list. More... | |
int | KIM_Collections_GetItemLibraryFileNameByCollectionAndType (KIM_Collections *const collections, KIM_Collection const collection, KIM_CollectionItemType const itemType, char const *const itemName, char const **const fileName) |
Get the item's library file name. More... | |
int | KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType (KIM_Collections *const collections, KIM_Collection const collection, KIM_CollectionItemType const itemType, char const *const itemName, int *const extent) |
Cache a list of an item's metadata files. More... | |
int | KIM_Collections_GetItemMetadataFileByCollectionAndType (KIM_Collections *const collections, int const index, char const **const fileName, unsigned int *const fileLength, unsigned char const **const fileRawData, int *const availableAsString, char const **const fileString) |
Get the name and content of one of an item's metadata files. More... | |
void | KIM_Collections_GetProjectNameAndSemVer (KIM_Collections *const collections, char const **const projectName, char const **const semVer) |
Get the KIM API project name and full Semantic Version string. More... | |
int | KIM_Collections_GetEnvironmentVariableName (KIM_Collections *const collections, KIM_CollectionItemType const itemType, char const **const name) |
Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection. More... | |
void | KIM_Collections_GetConfigurationFileEnvironmentVariable (KIM_Collections *const collections, char const **const name, char const **const value) |
Get the name and value of the environment variable that stores the name of the KIM API user configuration file. More... | |
void | KIM_Collections_GetConfigurationFileName (KIM_Collections *const collections, char const **const fileName) |
Get the absolute file and path name of the KIM API user configuration file. More... | |
int | KIM_Collections_CacheListOfDirectoryNames (KIM_Collections *const collections, KIM_Collection const collection, KIM_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 | KIM_Collections_GetDirectoryName (KIM_Collections *const collections, int const index, char const **const directoryName) |
Get the name of a directory from the cached list. More... | |
void | KIM_Collections_SetLogID (KIM_Collections *const collections, char const *const logID) |
Set the identity of the Log object associated with the Collections object. More... | |
void | KIM_Collections_PushLogVerbosity (KIM_Collections *const collections, KIM_LogVerbosity const logVerbosity) |
Push a new LogVerbosity onto the Collections object's Log object verbosity stack. More... | |
void | KIM_Collections_PopLogVerbosity (KIM_Collections *const collections) |
Pop a LogVerbosity from the Collections object's Log object verbosity stack. More... | |
typedef struct KIM_Collection KIM_Collection |
Definition at line 52 of file KIM_Collections.h.
typedef struct KIM_CollectionItemType KIM_CollectionItemType |
Definition at line 62 of file KIM_Collections.h.
typedef struct KIM_Collections KIM_Collections |
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 74 of file KIM_Collections.h.
typedef struct KIM_LogVerbosity KIM_LogVerbosity |
int KIM_Collections_CacheListOfDirectoryNames | ( | KIM_Collections *const | collections, |
KIM_Collection const | collection, | ||
KIM_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.
int KIM_Collections_CacheListOfItemMetadataFiles | ( | KIM_Collections *const | collections, |
KIM_CollectionItemType const | itemType, | ||
char const *const | itemName, | ||
int *const | extent | ||
) |
Cache a list of an item's metadata files.
int KIM_Collections_CacheListOfItemMetadataFilesByCollectionAndType | ( | KIM_Collections *const | collections, |
KIM_Collection const | collection, | ||
KIM_CollectionItemType const | itemType, | ||
char const *const | itemName, | ||
int *const | extent | ||
) |
Cache a list of an item's metadata files.
int KIM_Collections_CacheListOfItemNamesByCollectionAndType | ( | KIM_Collections *const | collections, |
KIM_Collection const | collection, | ||
KIM_CollectionItemType const | itemType, | ||
int *const | extent | ||
) |
Cache a list of all item names of a specific type in a specific collection.
int KIM_Collections_CacheListOfItemNamesByType | ( | KIM_Collections *const | collections, |
KIM_CollectionItemType const | itemType, | ||
int *const | extent | ||
) |
Cache a list of all item names of a specific type in the KIM API collections.
int KIM_Collections_Create | ( | KIM_Collections **const | collections | ) |
Create a new KIM API Collections object.
void KIM_Collections_Destroy | ( | KIM_Collections **const | collections | ) |
Destroy a previously Collections::Create'd object.
void KIM_Collections_GetConfigurationFileEnvironmentVariable | ( | KIM_Collections *const | collections, |
char const **const | name, | ||
char const **const | value | ||
) |
Get the name and value of the environment variable that stores the name of the KIM API user configuration file.
void KIM_Collections_GetConfigurationFileName | ( | KIM_Collections *const | collections, |
char const **const | fileName | ||
) |
Get the absolute file and path name of the KIM API user configuration file.
int KIM_Collections_GetDirectoryName | ( | KIM_Collections *const | collections, |
int const | index, | ||
char const **const | directoryName | ||
) |
Get the name of a directory from the cached list.
int KIM_Collections_GetEnvironmentVariableName | ( | KIM_Collections *const | collections, |
KIM_CollectionItemType const | itemType, | ||
char const **const | name | ||
) |
Get the names of environment variables that store configuration settings for the KIM::COLLECTION::environmentVariable collection.
int KIM_Collections_GetItemLibraryFileNameAndCollection | ( | KIM_Collections *const | collections, |
KIM_CollectionItemType const | itemType, | ||
char const *const | itemName, | ||
char const **const | fileName, | ||
KIM_Collection *const | collection | ||
) |
Get the item's library file name and its KIM::Collection.
int KIM_Collections_GetItemLibraryFileNameByCollectionAndType | ( | KIM_Collections *const | collections, |
KIM_Collection const | collection, | ||
KIM_CollectionItemType const | itemType, | ||
char const *const | itemName, | ||
char const **const | fileName | ||
) |
Get the item's library file name.
int KIM_Collections_GetItemMetadataFile | ( | KIM_Collections *const | collections, |
int const | index, | ||
char const **const | fileName, | ||
unsigned int *const | fileLength, | ||
unsigned char const **const | fileRawData, | ||
int *const | availableAsString, | ||
char const **const | fileString | ||
) |
Get the name and content of one of an item's metadata files.
int KIM_Collections_GetItemMetadataFileByCollectionAndType | ( | KIM_Collections *const | collections, |
int const | index, | ||
char const **const | fileName, | ||
unsigned int *const | fileLength, | ||
unsigned char const **const | fileRawData, | ||
int *const | availableAsString, | ||
char const **const | fileString | ||
) |
Get the name and content of one of an item's metadata files.
int KIM_Collections_GetItemNameByCollectionAndType | ( | KIM_Collections *const | collections, |
int const | index, | ||
char const **const | itemName | ||
) |
Get the name of an item from the cached list.
int KIM_Collections_GetItemNameByType | ( | KIM_Collections *const | collections, |
int const | index, | ||
char const **const | itemName | ||
) |
Get the name of an item from the cached list.
int KIM_Collections_GetItemType | ( | KIM_Collections *const | collections, |
char const *const | itemName, | ||
KIM_CollectionItemType *const | itemType | ||
) |
Get the KIM::CollectionItemType of the item in the KIM API collections with a specific name.
void KIM_Collections_GetProjectNameAndSemVer | ( | KIM_Collections *const | collections, |
char const **const | projectName, | ||
char const **const | semVer | ||
) |
Get the KIM API project name and full Semantic Version string.
void KIM_Collections_PopLogVerbosity | ( | KIM_Collections *const | collections | ) |
Pop a LogVerbosity from the Collections object's Log object verbosity stack.
void KIM_Collections_PushLogVerbosity | ( | KIM_Collections *const | collections, |
KIM_LogVerbosity const | logVerbosity | ||
) |
Push a new LogVerbosity onto the Collections object's Log object verbosity stack.
void KIM_Collections_SetLogID | ( | KIM_Collections *const | collections, |
char const *const | logID | ||
) |
Set the identity of the Log object associated with the Collections object.