AMPS Utility API

AMPS provides a set of functions for use by external modules. These functions can be called AMPS modules to interact with the AMPS server. 60East only supports calling functions in the AMPS server through the functions exposed in the header files. Calling any other functions in the AMPS binary is undefined behavior.

Header File

The definitions for the utility API are included in the following header file:

sdk/include/amps_api.h

There are three categories of functions in the AMPS utility API.

• Utility functions. These functions are designed to help you implement AMPS modules. For example, the external API contains a function to validate that AMPS can successfully parse a given entitlement filter

• AMPS actions. These functions call directly into the AMPS server process to perform an action. If you are developing a custom implementation of an AMPS action module, use these functions to implement the action.

• Embedded client. The external API offers an embedded client, discussed in .

The header file contains API documentation for each of the functions. A short description of the most commonly used functions appears below.

Utility Functions

This section describes the utility functions in the AMPS external API.

Notice that functions that require AMPS to have processed the configuration file will produce undefined results when called from amps_module_init() or one of the context creation functions. AMPS modules are loaded and initialized before topics, message types, and so forth are configured. At the time modules are loading and contexts are being created, AMPS has not yet created the set of transports, message types, and so forth.

If your module needs to perform validation or otherwise refer to configuration state outside of the module's own initialization or context creation, register a startup function to do that validation after the configuration file has been fully processed and AMPS is started.

Function	Description
amps_get_last_error	Returns the description of the last error from AMPS, if any. Otherwise returns NULL.
amps_free_last_error	Frees the last error.
amps_validate_filter	Checks that AMPS can properly parse and compile the filter. Returns AMPS_SUCCESS when the filter is valid, otherwise returns AMPS_FAILURE. This function only checks to see that AMPS can process the filter. It does not predict whether the filter will return results for any particular document.
amps_get_message_type_names	Returns the set of message type registered in the instance.
amps_free_message_type_names	Frees the list of message types returned by get_message_type_names
amps_hash_topic	Returns a hash of the provided topic name.
amps_hash_message_type	Returns a hash of the provided message type name.
amps_validate_message_type	Check to see whether the specified message type is registered with AMPS. returns AMPS_SUCCESS if so, AMPS_FAILURE otherwise.
amps_topic_get_list	Returns a list of topics for the specified message type that match the specified regular expression.
amps_get_topic_metadata	Returns the topic metadata handle for the topic with the provided topic hash.
amps_topic_metadata_destroy	Frees a topic metadata handle.
amps_topic_metadata_*	A set of functions to test properties of a given topic, referenced by the topic metadata handle for the topic.
amps_version	Returns the version information for the AMPS instance.
amps_compare_version	Compares the version string provided to the currently running version of AMPS. Returns 0 if the versions are the same, 1 if the running AMPS version is greater than the version provided, and -1 if the running AMPS version is less than the version provided.
amps_parse_datetime	Parses an ISO-8601 datetime into an equivalent number of microseconds. Returns AMPS_SUCCESS on success, AMPS_FAILURE on failure.
amps_parse_interval	Parses an AMPS interval into a number of nanoseconds. Returns AMPS_SUCCESS on success, AMPS_FAILURE on failure.
amps_parse_bytes	Parses a number of bytes into a numeric equivalent. Returns AMPS_SUCCESS on success, AMPS_FAILURE on failure.
amps_get_transport_name	Returns the name of the current transport when called during amps_authentication_create_context or amps_entitlement_create_context. Returns NULL outside of context initialization. The pointer returned is not guaranteed to be valid outside of the scope of the create_context call.
amps_extract_config_value	Returns the value of the specified entry in the configuration file when provided an XPath expression for that entry.
amps_get_module_name	Returns the name of the current module when called during amps_module_init. This function will return NULL outside of calls to amps_module_init. The pointer returned is not guaranteed to be valid outside of the scope of the amps_module_init call.
amps_startup_progress	Returns the state of AMPS startup progress as an integer from 0-100, where 100 indicates fully started.
amps_shutdown_progress	Returns the state of AMPS shutdown progress as an integer from 0-100, where 0 indicates that no shutdown is occurring and 100 indicates fully shutdown.
amps_is_running	Returns 1 when AMPS is fully started, 0 otherwise.
amps_is_stopped	Returns 1 when AMPS is in the process of shutting down, 0 otherwise.
amps_get_authids	Returns a list of authorization ids for a specified transport.
amps_free_authids	Frees a list of authorization ids returned by amps_get_authids.
amps_ping_thread_monitor	Indicates to the thread monitor that the current thread is running as expected. AMPS uses a thread monitor to detect threads that have stopped making progress, or become "stuck". When a module calls this function, the thread monitor resets the timeout for considering the thread to be "stuck". For modules that provide long-running operations, periodically pinging the thread monitor can prevent AMPS from marking the thread as potentially stuck. This function should only be called from threads created by AMPS. Calling this function from a thread created by the module has undefined results.

Action Functions

This section describes the action functions in the AMPS external API.

Function	Description
amps_compress_journals	Compresses journals older than the specified age.
amps_archive_journals	Archives journals older than the specified age.
amps_remove_journals	Removes journals older than the specified age.
amps_disable_authentication	Disable AMPS authentication.
amps_enable_authentication	Enable AMPS authentication.
amps_reset_authentication	Reset authentication on the transport with the name specified.
amps_disable_entitlement	Disable entitlements.
amps_enable_entitlement	Enable entitlements.
amps_reset_entitlement	Reset entitlements on the provided transport. Must not be called from a call to amps_entitlement_check.
amps_reset_entitlement_for_authid	Reset entitlements for the provided authentication ID on the provided transport. Must not be called from a call to amps_entitlement_check.
amps_disable_transport	Disable the specified transport.
amps_enable_transport	Enable the specified transport.
amps_minidump	Create a minidump.
amps_rotate_logs	Rotate logs for logging targets that support rotation.
amps_downgrade_replication_age	Downgrade replication destinations that have fallen behind more than the specified age.
amps_upgrade_replication_age	Upgrade replication destinations that were previously downgraded but are now behind by less than the specified age.
amps_delete_sow	Delete SOW messages, using the specified parameters.
amps_truncate_statistics	Truncate statistics that are older than the provided age.
amps_vacuum_statistics	Free any unused space in the AMPS statistics store.
amps_shutdown	Gracefully shut down AMPS.

Registering a Startup Function

Some modules may need to register actions that are only run after the AMPS startup sequence is complete. For example, a module that subscribes to a topic should not submit a subscription before AMPS has initialized the subscription infrastructure.

For some modules, particularly modules that may want to start several tasks with different parameters, adding an action interface and registering the module to be run on startup (that is, adding an Action that is run on startup and calls the module's startup function with different parameters) is the best option.

For other modules, though, AMPS allows you to register a callback which AMPS will invoke when startup is complete. A callback must have the following signature:

int run_after_startup(void *user_data);

The function to register the callback has the following signature:

typedef int (*amps_startup_callback)(void*);

int amps_add_startup_function(amps_startup_callback callback, void* user_data);

AMPS calls each registered function once, in the order in which the startup callbacks were registered. However, AMPS does not guarantee that the startup functions will be called from a single thread: therefore, if functions require strict ordering, it is best to provide a wrapper function that calls the functions you need in the desired order. (As an example, if you use an external interface that requires a handle to be constructed, initialized, and then started, you would provide a function to do this rather than registering the API functions directly.)

Registering a Shutdown Function

Some modules may need to register actions that are run when AMPS is shutting down. AMPS provides the ability to register a callback that will run when AMPS intentionally shuts down.

A callback must have the following signature:

int run_on_shutdown(void *user_data);

The function to register the callback has the following signature:

typedef int (*amps_shutdown_callback)(void*);

int amps_add_shutdown_function(amps_shutdown_callback callback, void* user_data);

AMPS calls each registered function once, in the reverse of the order in which the shutdown callbacks were registered.

AMPS does not guarantee that the shutdown functions will be called from a single thread: therefore, if functions require strict ordering, it is best to provide a wrapper function that calls the functions you need in the desired order.

A shutdown function should not be used to invalidate contexts. AMPS will run the destroy context functions as a part of shutdown. As a part of the shutdown sequence, AMPS will destroy contexts in an order that minimizes dependencies between module types. Cleanup for global module state should be done in your module's amps_module_terminate() function.

Working with Expression Values

AMPS uses expression values as the internal representation of values in the expression engine. Your module treats these values as opaque pointers, and uses a set of convenience functions to manipulate the contents of the expression value. These values are, in particular, used for both input and output for User-Defined functions (as described in ) and when using the message parser in the embedded client (as described in ).

When working with sets of values, AMPS uses C arrays. When retrieving values from a parser, you provide an array of the appropriate size, and AMPS fills in the array with the expression values that correspond to the operation. When AMPS passes arguments to a UDF, amps provides the incoming arguments as an array of expression values, typed as an amps_expression_value_array.

The AMPS external API provides the amps_expression_value_get function to retrieve a specific value from an amps_expression_value_array. The function takes the array to extract the value from, and the position of the value to extract. For example, the following code returns the first argument from an amps_expression_value_array named args.

amps_expression_value myVal = amps_expression_value_get(args,0);

Once the value is extracted, the AMPS external API offers a set of functions for retrieving a C type representation of the amps_expression_value.

AMPS provides a set of functions to determine whether a given expression value can be represented as a specific type. For example, to determine if a given value can be represented as a double, your module can call amps_expression_value_as_double. A non-zero return value indicates that the value can be represented as a double.

Once you know that the value can be represented as a specific C type, you can then retrieve a C type value from the amps_expression_value. For example, to retrieve a string value, you provide a pointer and variable to hold the length, then call amps_expression_value_as_string to retrieve the string:

char* value = NULL;
size_t valueLen = 0;
// value will point to the beginning of the string,
// size_t will specify the length of the string.
amps_expression_value_as_string(myVal, &value, &valueLen);

The AMPS utility API provides similar functions for all of the types recognized by the AMPS expression engine.

Notice that the results of the amps_expression_value_is_<type> family of functions only provide information on whether the value can be represented as a given type. No information is available on they type originally assigned by a parser, or whether the value is the result of parsing an incoming message, was produced as the output of another function, or is the result of field construction in a view, enrichment, or an aggregated subscription.

Expression values returned from a parser, or provided to a UDF as incoming arguments, should be treated as read-only values. When returning a value from a UDF, you need to set the value to return. The AMPS utility API includes a set of functions for setting the type and contents of an expression value.

// result is an amps_expression_value provided by AMPS
// to hold the return value of a UDF, and args are
// the amps_expression_value_array provided to the UDF.

if (processMyUDF(args) == 1)
{
    amps_expression_value_set_bool(result, 1L);
}
else
{
    amps_expression_value_set_bool(result, 0L);
}