NAME

ion_admin - Public API for ION (Interplanetary Overlay Network) Administration

SYNOPSIS

#include "ion_admin.h"

DESCRIPTION

The ion_admin.h header provides public interfaces for managing ION configuration parameters that are currently accessible only through the ionadmin CLI.

FUNCTIONS

Production Rate Management

• int ion_set_production_rate(int rate_bytes_per_sec)

  Sets the expected mean rate of continuous data origination by local Bundle Protocol applications.

  Parameters:

  • rate_bytes_per_sec

    The production rate in bytes per second. Special values:

    • -1 indicates the rate is unknown or not metered
    • 0 indicates router-only nodes with no local data production
    • Positive values specify the expected production rate

  Returns: 0 on success, -1 on error.

  Prerequisites: ION must be attached via ionAttach() before calling this function.

  Notes: Changes to production rate trigger an update to ION's congestion forecast by invoking the ionwarn utility.

• int ion_get_production_rate(int *rate_bytes_per_sec)

  Retrieves the current production rate setting.

  Parameters:

  • rate_bytes_per_sec

    Pointer to an integer where the current production rate will be stored.

  Returns: 0 on success, -1 on error.

  Prerequisites: ION must be attached via ionAttach() before calling this function.

Consumption Rate Management

• int ion_set_consumption_rate(int rate_bytes_per_sec)

  Sets the expected mean rate of data delivery to local Bundle Protocol applications.

  Parameters:

  • rate_bytes_per_sec

    The consumption rate in bytes per second. Special values:

    • -1 indicates the rate is unknown or not metered
    • 0 indicates no local data consumption
    • Positive values specify the expected consumption rate

  Returns: 0 on success, -1 on error.

  Prerequisites: ION must be attached via ionAttach() before calling this function.

  Notes: Changes to consumption rate trigger an update to ION's congestion forecast by invoking the ionwarn utility.

• int ion_get_consumption_rate(int *rate_bytes_per_sec)

  Retrieves the current consumption rate setting.

  Parameters:

  • rate_bytes_per_sec

    Pointer to an integer where the current consumption rate will be stored.

  Returns: 0 on success, -1 on error.

  Prerequisites: ION must be attached via ionAttach() before calling this function.

Congestion Forecast Horizon Management

• int ion_set_congestion_forecast_horizon(time_t horizon_time)

  Sets the end time for ION's congestion forecasting window.

  Parameters:

  • horizon_time

    End time for congestion forecasts as a Unix timestamp (seconds since epoch). Special values:

    • 0 disables congestion forecasting entirely
    • Positive values specify the forecast horizon as a UTC timestamp

  Returns: 0 on success, -1 on error.

  Prerequisites: ION must be attached via ionAttach() before calling this function.

  Notes: Changes to the horizon trigger an update to ION's congestion forecast by invoking the ionwarn utility.

• int ion_get_congestion_forecast_horizon(time_t *horizon_time)

  Retrieves the current congestion forecast horizon setting.

  Parameters:

  • horizon_time

    Pointer to a time_t variable where the current horizon timestamp will be stored.

  Returns: 0 on success, -1 on error.

  Prerequisites: ION must be attached via ionAttach() before calling this function.

RETURN VALUES

All functions return:

• 0

  Success

• -1

  Error (detailed error message available via ION's error reporting mechanisms)

ERROR HANDLING

Functions in this API return -1 on error and use ION's standard error reporting mechanism (putErrmsg). Common error conditions include:

• ION not attached (ionAttach() not called or failed)
• ION database not found or corrupted
• SDR transaction failures
• Invalid parameters (e.g., NULL pointer for output parameters)

Use ION's error reporting facilities to retrieve detailed error messages.

THREAD SAFETY

These functions are not inherently thread-safe. If multiple threads need to modify ION configuration parameters, the caller must provide appropriate synchronization.

PREREQUISITES

Before using these functions:

1. ION must be initialized using ionInitialize()
2. The calling process must be attached to ION using ionAttach()
3. The ION database must be accessible and properly configured

RELATIONSHIP TO IONADMIN

These functions provide programmatic access to configuration parameters that can also be set through the ionadmin command-line interface:

• ion_set_production_rate() is equivalent to: m production <rate>
• ion_set_consumption_rate() is equivalent to: m consumption <rate>
• ion_set_congestion_forecast_horizon() is equivalent to: m horizon <time>

Changes made through this API are immediately visible to ionadmin and vice versa, as both operate on the same underlying ION database.

• Involves spawning a separate process
• May perform computation-intensive forecast calculations
• Should not be called in high-frequency loops or time-critical code paths

For best performance, set configuration parameters during initialization or infrequently during runtime.

SEE ALSO

ionadmin(1), bp_admin(3), ion(3), ionattach(3), iondetach(3), ioninitialize(3)

COPYRIGHT

Copyright (c) 2025, California Institute of Technology. ALL RIGHTS RESERVED. U.S. Government Sponsorship acknowledged.

AUTHOR

NASA/JPL Interplanetary Overlay Network (ION) Project

BUGS

Report bugs to the ION development team or through the ION project's issue tracking system.