Struct PntosMediator

Struct Documentation

struct PntosMediator

A set of callbacks which are handed to a pntOS plugin upon initialization.

When a plugin is first initialized into pntOS, it is guaranteed that the plugin will be passed an instance of this struct via an invocation of PntosCommonPlugin.init_plugin (see PntosCommonPlugin for more information). The plugin may then use the set of function calls in this struct to make requests of the controller.

All of the functions on this struct (and any returned values from those functions) are guaranteed to be thread-safe for use by all plugins. Thus, after a pntOS plugin has received a copy of a PntosMediator it can freely call the functions contained therein without doing any explicit locking. This thread safety is implemented by the controller when it creates the mediator before passing them to other plugins.

Callers must still take care to only call functions in PntosMediator which they are not themselves responsible for implementing. The details of which plugins are used in the implementation of any particular function on this struct is decided by the PntosControllerPlugin, and thus is implementation specific to the controller used.

Public Members

PntosManagedMemory *memory
PntosStringArray *(*get_filter_description_list)(struct PntosMediator *self)

Request a list of strings describing the solutions available. One of these description strings may be used when calling request_solutions. For consistency, these strings should adhere to the following conventions:

  • Strings should be upper case and have words and acronyms separated by underscores (UPPER_SNAKE_CASE).

  • Strings should contain the substring BEST when they represent the primary solution.

  • Strings should contain the substring DEAD_RECKONING when they represent a solution suitable for estimating relative motion or rotation over a period of time. This solution may drift more than BEST solutions, as the goal is to allow a user to get an estimate of the relative motion between different times. In the calculation of this solution, some sensor measurement might be excluded. For example, a system with an IMU might provide a DEAD_RECKONING solution which is the solution from its free-running inertial mechanization, with resets disabled during the time intervals between solution_times (but resets applied before all of the solution_times).

  • Strings should include a substring indicating the type of solution returned. This substring should contain the string-equivalent to the AspnMessageType enum value, followed by the string _ESTIMATE. This allows the user to perform substring matching without a risk of getting a false positive match from a type whose string would be a subset of another type.

For example, if the primary solution is an ASPN PVA then the string MY_BEST_ASPN_MEASUREMENT_POSITION_VELOCITY_ATTITUDE_ESTIMATE would fulfill the convention.

These conventions allow the user to identify their desired type of solution using substring matching.

PntosMessageArray *(*request_solutions)(struct PntosMediator *self, AspnTypeTimestamp *solution_times, size_t num_solution_times, char *filter_description)

Request filtering solutions at the times specified in the array solution_times. The number of time entries in solution_times is specified by num_solution_times.

To select which filter(s) to request solutions from, enter a valid filter description string in filter_description. Valid filter description strings can be obtained by calling get_filter_description_list(). Passing in NULL will provide a result specific to a particular implementation. When filter_description is NULL, the implementation should endeavor to return its best solution.

Returned will be an array of messages containing the filter solutions for the requested solution_times. The number of solutions should equal num_solution_times, although some entries may be NULL if they are unavailable at the corresponding time in solution_times. The returned PntosMessageArray may be NULL if filter_description is invalid.

void (*process_pntos_message)(struct PntosMediator *self, PntosMessage *message)

Send a new message to the system for arbitrary processing. For example, this function is useful for plugins who have just received new sensor data that they wish to relay to the system to be used in a sensor fusion solution.

void (*broadcast_aspn_message)(struct PntosMediator *self, PntosMessage *message, char *transport, char *destination_identifier)

Request that pntOS broadcast the provided message out to the network. The destination_identifier parameter is a transport-specific identifier that allows transports to determine how to route the message. If the destination transport has the concept of a channel or topic, destination_identifier should be populated by the channel or topic. Otherwise, the identifier is populated in a plugin-specific manner defined by the destination transport. If destination_identifier is NULL, then the transport should output the message in the “default” output channel/topic and route being used by pntOS.

The transport parameter is the C string identifier of a transport plugin that the message should be routed to. The transport parameter should match the PntosCommonPlugin.identifier string of a PntosTransportPlugin active in the system. If the transport parameter is NULL, this indicates that the message should be broadcast to all available transports.

void (*log_message)(struct PntosMediator *self, PntosLoggingLevel level, char *message)

Send a loggable message to the system, to be logged through the current logging infrastructure enabled (e.g. the console, a logfile, etc.).

void (*log_message_fmt)(struct PntosMediator *self, PntosLoggingLevel level, char *fmt, ...)

Send a loggable message to the system, to be logged through the current logging infrastructure enabled (e.g. the console, logfile, etc.). The fmt parameter and message parameters are interpreted as printf(fmt, message) arguments.

PntosRegistry *registry

A pointer to a PntosRegistry object that can be used to update keys/values in the pntOS global registry.