7. 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 8. AMPS Embedded Client.

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.

Table 7.1: Utility Functions

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.

Table 7.2: Action Functions

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.)

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 User-Defined Functions) and when using the message parser in the embedded client (as described in User-Defined Functions.)

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);
}

Table Of Contents

Related Topics