ESF Manager provides an API of service routines to the ESM Modules. Simple modules may not need any of these routines, but many will use some or all of them.
The API is not exported directly to the modules. Instead, a pointer to a structure that includes a function table is passed to the module's Init procedure when the module is loaded and initialized. Modules that need any of the service routines should implement an Init procedure that saves this pointer, or a copy of the structure it points to.
It's likely that additional functions will be added to the API over time, so ESM Modules should check the version and count information in the structure they receive to ensure that all of the functions they use are included. See SafEsmApi for more information.
Currently, the defined functions are:
- Log
- Log a message to the calling environment's log facility. See EsmLog().
- GetAcee
- Locate an existing ACEE or create a new one. ESMs that need to alter the ACEE on a VERIFY operation will use this service. See EsmGetAcee().
- GetSharedMem
- Locate an existing named shared memory region or create a new one. ESMs that want to share information with other instances of themselves (eg to cache data across SEPs) can use this service. See EsmGetSharedMem().
- LockEnq
- Acquire a named lock (enqueue). ESMs can use this to coordinate access to shared resources. See EsmLockEnq().
- LockDeq
- Release a named lock (dequeue). See EsmLockDeq().
- GetSafInit
- Get a copy of the ESF Manager initialization data. Some ESM Modules may need this information for their own processing. See EsmGetSafInit().
- ExtractVerifyStrings
- Extract the string information for a ESF Verify request from the ESF parameter block as C strings. This is useful in the Verify Procedure in an ESM Module written in C. See EsmExtractVerifyStrings().
- ExtractAuthStrings
- Extract the string information for a ESF Auth request from the ESF parameter block as C strings. This is useful in the Auth Procedure in an ESM Module written in C. See EsmExtractAuthStrings().
- ExtractXAuthStrings
- Extract the string information for a ESF XAuth request from the ESF parameter block as C strings. This is useful in the XAuth Procedure in an ESM Module written in C. See EsmExtractXAuthStrings().
- SafQuery
- Query ESF Manager for various pieces of configuration and state information, such as whether the operating environment is multithreaded (so the ESM Module knows whether it needs to synchronize access to private resources). See EsmSafQuery().
- ParseConfig
- Parse structured text, usually taken from the ESM Module's custom configuration area in MFDS (and passed in the module configuration block during initialization). Currently the text must be in "ini" format, as described in SafStoreLoad(). After parsing, QueryConfig can be used to extract particular values. See EsmParseConfig().
- QueryConfig
- Query parsed ESM Module configuration text for the value associated with a given name, within a given "class" (aka section header or tag). See EsmQueryConfig().
- FreeConfig
- Free a parsed configuration if the module no longer needs it. (Note that many modules will keep their parsed configurations for the lifetime of the process; in that case it's not necessary to free it.) See EsmFreeConfig().
- AceeIterate
- Iterate over all ACEEs, invoking a callback supplied by the ESM Module for each one. See EsmAceeIterate().
For more information see the documentation for the ESF ESM Interface component.