trek_ionizer_api.h File Reference

The commonly shared macros, structures and functions. More...

#include "trek_ionizer_defines.h"

Data Structures
struct	ion_stats
	Holds count/byte information for single comm statistics line. More...
struct	ion_comm_statistics
	All communication statistics for the local ION node. More...

Typedefs
typedef void(*	InfoCallback) (const struct tm *occur_time, const char *msg)
	Callback function for information messages in the ion.log file. More...
typedef void(*	WarningCallback) (const struct tm *occur_time, const char *msg)
	Callback function for warning messages in the ion.log file. More...
typedef void(*	DiagnosticCallback) (const struct tm *occur_time, const char *msg)
	Callback function for diagnostic messages in the ion.log file. More...
typedef void(*	BundleStatusReportCallback) (const struct tm *occur_time, const char *msg)
	Callback function for bundle status report messages in the ion.log file. More...
typedef void(*	CommunicationStatisticsCallback) (const struct tm *occur_time, const struct ion_comm_statistics *ion_stats)
	Callback function for communication statistics in the ion.log file. More...
typedef void(*	FreeFormCallback) (const struct tm *occur_time, const char *msg)
	Callback function for unclassified messages in the ion.log file. More...
typedef void(*	ReadErrorCallback) (const struct tm *occur_time, const char *msg)
	Callback function for read errors in the ion.log file. More...
typedef void(*	MissingProcessCallback) (const struct tm *occur_time, const char *process, unsigned int expected, unsigned int found)
	Callback function for detection of missing processes. More...
typedef void(*	IonNodeConnectionCallback) (unsigned int local_node_number, unsigned int remote_node_number, const char *ip_addr, unsigned short port, unsigned short connected)
	Callback function for change of state of an ION connection. More...

Functions
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterInfoCallback (InfoCallback function_ptr)
	Registers a function that will be called whenever an information message is generated in the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterWarningCallback (WarningCallback function_ptr)
	Registers a function that will be called whenever a warning message is generated in the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterDiagnosticCallback (DiagnosticCallback function_ptr)
	Registers a function that will be called whenever a diagnostic message is generated in the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterBundleStatusReportCallback (BundleStatusReportCallback function_ptr)
	Registers a function that will be called whenever a bundle status report is generated in the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterCommunicationStatisticsCallback (CommunicationStatisticsCallback function_ptr)
	Registers a function that will be called whenever communication statistics are generated in the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterFreeFormCallback (FreeFormCallback function_ptr)
	Registers a function that will be called whenever a free form message is generated in the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterReadErrorCallback (ReadErrorCallback function_ptr)
	Registers a function that will be called whenever an error occurs while attempting to read the ion.log file. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterMissingProcessCallback (MissingProcessCallback function_ptr)
	Registers a function that will be called whenever a process is detected as missing. More...
void EXPORT_THIS_IONIZER_C_FUNCTION	RegisterIonNodeConnectionCallback (IonNodeConnectionCallback function_ptr)
	Registers a function that will be called whenever a process is detected as missing. More...
int EXPORT_THIS_IONIZER_C_FUNCTION	WatchIonLog (const char *ion_working_dir)
	Starts monitoring the ion.log file for messages. More...
int EXPORT_THIS_IONIZER_C_FUNCTION	StopIonLogWatch ()
	Stops monitoring the ion.log file. More...
int EXPORT_THIS_IONIZER_C_FUNCTION	WatchIonProcesses (const char *ion_working_dir)
	Starts monitoring expected processes for ION. More...
int EXPORT_THIS_IONIZER_C_FUNCTION	StopIonProcessWatch ()
	Stops monitoring expected processes for ION. More...
int EXPORT_THIS_IONIZER_C_FUNCTION	WatchIonConnection (const char *ion_working_dir)
	Starts monitoring connections for ION. More...
int EXPORT_THIS_IONIZER_C_FUNCTION	StopIonConnectionWatch ()
	Stops monitoring for ION TCP connections. More...

Detailed Description

The commonly shared macros, structures and functions.

Typedef Documentation

BundleStatusReportCallback

typedef void(* BundleStatusReportCallback) (const struct tm *occur_time, const char *msg)

Callback function for bundle status report messages in the ion.log file.

Parameters

[in]	occur_time	The time stamp from the log file.
[in]	msg	Message from the log file.

CommunicationStatisticsCallback

typedef void(* CommunicationStatisticsCallback) (const struct tm *occur_time, const struct ion_comm_statistics *ion_stats)

Callback function for communication statistics in the ion.log file.

The statistics span multiple lines in the log file and are collected into the structure

Parameters

[in]	occur_time	The time stamp from the log file.
[in]	ion_stats	The communcation statistics.

DiagnosticCallback

typedef void(* DiagnosticCallback) (const struct tm *occur_time, const char *msg)

Callback function for diagnostic messages in the ion.log file.

Parameters

[in]	occur_time	The time stamp from the log file.
[in]	msg	Message from the log file.

FreeFormCallback

typedef void(* FreeFormCallback) (const struct tm *occur_time, const char *msg)

Callback function for unclassified messages in the ion.log file.

Parameters

[in]	occur_time	The time stamp from the log file.
[in]	msg	Message from the log file.

InfoCallback

typedef void(* InfoCallback) (const struct tm *occur_time, const char *msg)

Callback function for information messages in the ion.log file.

Parameters

[in]	occur_time	The time stamp from the log file.
[in]	msg	Message from the log file.

IonNodeConnectionCallback

typedef void(* IonNodeConnectionCallback) (unsigned int local_node_number, unsigned int remote_node_number, const char *ip_addr, unsigned short port, unsigned short connected)

Callback function for change of state of an ION connection.

TCP and STCP connections from ION to other nodes are monitored and change of states are reported through this callback. You can optionally register for an initial state callback for each connection.

Parameters

[in]	local_node_number	The node number of the local computer.
[in]	remote_node_number	The node number for the HOSC DTN gateway.
[in]	ip_addr	The IP address of the remote node
[in]	port	The port number of the remote node
[in]	connected	Set to 1 if connected, otherwise will be zero

MissingProcessCallback

typedef void(* MissingProcessCallback) (const struct tm *occur_time, const char *process, unsigned int expected, unsigned int found)

Callback function for detection of missing processes.

This callback is generated for each missing process when the expected number of processes does not equal the amount found. It is possible for more processes to be found than is expected. This is most likely to occur if you run multiple instances of ION on the same computer.

Parameters

[in]	occur_time	The time stamp from the operation system when the message occured.
[in]	process	The name of the process that is missing.
[in]	expected	The number of expected instances of the process.
[in]	found	The number of instances of the process found.

ReadErrorCallback

typedef void(* ReadErrorCallback) (const struct tm *occur_time, const char *msg)

Callback function for read errors in the ion.log file.

Read errors occur when the format of the ion.log file is unreadable. This is most likely caused by two ION processes' messages being written to the file.

Parameters

[in]	occur_time	The time stamp when the read error occurred obtained from the operation system.
[in]	msg	Message from the log file.

WarningCallback

typedef void(* WarningCallback) (const struct tm *occur_time, const char *msg)

Callback function for warning messages in the ion.log file.

Parameters

[in]	occur_time	The time stamp from the log file.
[in]	msg	Message from the log file.

Function Documentation

RegisterBundleStatusReportCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterBundleStatusReportCallback

(

BundleStatusReportCallback

function_ptr

)

Registers a function that will be called whenever a bundle status report is generated in the ion.log file.

Registers the specified function which will be called whenever ION writes a bundle status report to the ion.log file. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each bundle status report until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.
From the ION documentation:
A bundle status report (BSR) message informs the user of the arrival of a BSR.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyBundleStatusReportCallbackFunction( const struct tm *occur_time, const char *msg )
{
    // format time as desired
    printf( "Bundle Status Report Message: %s\n", msg );
}
 
main()
{
    // register the function
    RegisterBundleStatusReportCallback( MyBundleStatusReportCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterBundleStatusReportCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterCommunicationStatisticsCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterCommunicationStatisticsCallback

(

CommunicationStatisticsCallback

function_ptr

)

Registers a function that will be called whenever communication statistics are generated in the ion.log file.

Registers the specified function which will be called whenever ION writes communication statistics to the ion.log file. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each information message until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.
From the ION documentation:
Communication statistics messages are reports of network performance for each of eight different types of network activity.

Note

The eight communication messages are combined into a single structure.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyCommStatsCallbackFunction( const struct tm *occur_time, const struct ion_comm_statistics *ion_stats )
{
    // format time as desired
    // print the total bundles recevied by this node.
    printf( "Bundles received = %u\n", ion_stats->rcv.totalCount );
}
 
main()
{
    // register the function
    RegisterCommunicationStatisticsCallback( MyCommStatsCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterCommunicationStatisticsCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterDiagnosticCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterDiagnosticCallback

(

DiagnosticCallback

function_ptr

)

Registers a function that will be called whenever a diagnostic message is generated in the ion.log file.

Registers the specified function which will be called whenever ION writes a diagnostic message to the ion.log file. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each diagnostic message until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.
From the ION documentation:
Diagnostic messages are generated to inform the user of the occurrence of events that are off-nominal and might be due to errors in the software. The generated message will contain the source file and line number where the error was generated. If reporting this error, please include this information.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyDiagnosticCallbackFunction( const struct tm *occur_time, const char *msg )
{
    // format time as desired
    printf( "Diagnostic Message: %s\n", msg );
}
 
main()
{
    // register the function
    RegisterDiagnosticCallback( MyDiagnosticCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterDiagnosticCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterFreeFormCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterFreeFormCallback

(

FreeFormCallback

function_ptr

)

Registers a function that will be called whenever a free form message is generated in the ion.log file.

Registers the specified function which will be called whenever ION writes a free form message to the ion.log file. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each free form message until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyFreeFormCallbackFunction( const struct tm *occur_time, const char *msg )
{
    // format time as desired
    printf( "Free Form Message: %s\n", msg );
}
 
main()
{
    // register the function
    RegisterFreeFormCallback( MyFreeFormCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterFreeFormCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterInfoCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterInfoCallback

(

InfoCallback

function_ptr

)

Registers a function that will be called whenever an information message is generated in the ion.log file.

Registers the specified function which will be called whenever ION writes an information message to the ion.log file. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each information message until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.
From the ION documentation:
Information messages are generated for events that are nominal, but significant. The include the termination of a daemon or the production of a congestion forecast.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyInfoCallbackFunction( const struct tm *occur_time, const char *msg )
{
    // format time as desired
    printf( "Info Message: %s\n", msg );
}
 
main()
{
    // register the function
    RegisterInfoCallback( MyInfoCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterInfoCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterIonNodeConnectionCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterIonNodeConnectionCallback

(

IonNodeConnectionCallback

function_ptr

)

Registers a function that will be called whenever a process is detected as missing.

Registers the specified function which will be called whenever an ION process is not running as expected. For details on which processes are monitored see WatchIonProcesses(). The callback will include a process name as well as the number of expected processes and the number of processes with that name currently executing. The callback will continue to be triggered until the probem is solved or you unregister for the callback.
You can unregister for this callback by passing a NULL pointer to the function.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyIonNodeConnectionCallbackFunction( const char *ip_addr, unsigned short port, unsigned short connected )
{
    if( connected )
        printf( "%s:%u is connected.\n", ip_addr, port );
    else
        printf( "%s:%u is disconnected.\n", ip_addr, port );
}
 
main()
{
    // register the function
    RegisterIonNodeConnectionCallback( MyIonNodeConnectionCallbackFunction );
 
    // you should really check the return code on this call.
    RegisterIonNodeConnectionCallback( "/home/me/iondir" );
 
    // unregister the function
    RegisterIonNodeConnectionCallback( 0 );
}

RegisterMissingProcessCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterMissingProcessCallback

(

MissingProcessCallback

function_ptr

)

Registers a function that will be called whenever a process is detected as missing.

Registers the specified function which will be called whenever an ION process is not running as expected. For details on which processes are monitored see WatchIonProcesses(). The callback will include a process name as well as the number of expected processes and the number of processes with that name currently executing. The callback will continue to be triggered until the probem is solved or you unregister for the callback.
You can unregister for this callback by passing a NULL pointer to the function.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyMissingCallbackFunction( const struct tm *occur_time, const char *process, unsigned int expected, unsigned int found )
{
    // format time as desired
    printf( "Missing process: %s (expected %u instances, found %u)\n", process, expected, found );
}
 
main()
{
    // register the function
    RegisterMissingProcessCallback( MyMissingCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonProcesses( "/home/me/iondir" );
 
    // unregister the function
    RegisterMissingProcessCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterReadErrorCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterReadErrorCallback

(

ReadErrorCallback

function_ptr

)

Registers a function that will be called whenever an error occurs while attempting to read the ion.log file.

Registers the specified function which will be called whenever ION writes message to the ion.log file and the message is not properly formatted. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each read error message until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyReadErrorCallbackFunction( const struct tm *occur_time, const char *msg )
{
    // format time as desired
    printf( "Read Error Message: %s\n", msg );
}
 
main()
{
    // register the function
    RegisterReadErrorCallback( MyReadErrorCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterReadErrorCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

RegisterWarningCallback()

void EXPORT_THIS_IONIZER_C_FUNCTION RegisterWarningCallback

(

WarningCallback

function_ptr

)

Registers a function that will be called whenever a warning message is generated in the ion.log file.

Registers the specified function which will be called whenever ION writes a warning message to the ion.log file. This callback will only be generated if WatchIonLog() has been called. The callback will continue to be triggered for each warning message until you call StopIonLogWatch() or unregister for the callback. You can unregister for this callback by passing a NULL pointer to the function.
From the ION documentation:
Warning messages inform the user of the occurrence of events that are off-nominal but are likely caused by configuration or operational errors rather than software failure.

Parameters

[in]

function_ptr

The function to handle the callback.

Example:

void MyWarningCallbackFunction( const struct tm *occur_time, const char *msg )
{
    // format time as desired
    printf( "Warning Message: %s\n", msg );
}
 
main()
{
    // register the function
    RegisterWarningCallback( MyWarningCallbackFunction );
 
    // you should really check the return code on this call.
    WatchIonLog( "/home/me/iondir" );
 
    // unregister the function
    RegisterWarningCallback( 0 );
}

Examples

user_ionizer_app/user_ionizer_app.cpp.

StopIonConnectionWatch()

int EXPORT_THIS_IONIZER_C_FUNCTION StopIonConnectionWatch

(

)

Stops monitoring for ION TCP connections.

Deletes the thread associated with monitoring the connections created by WatchIonConnection(). The functions registered for each log message type will no longer be called.

Returns

SUCCESS

other return codes from lower level functions.

Example:

int ret_value;
ret_value = WatchIonConnection();
 
if( ret_value )
{
    printf( "Error %d returned from WatchIonConnection\n", ret_value )
}
 
// When you no longer wish to monitor the ION connections...
StopIonConnectionWatch();

StopIonLogWatch()

int EXPORT_THIS_IONIZER_C_FUNCTION StopIonLogWatch

(

)

Stops monitoring the ion.log file.

Deletes the thread associated with monitoring the ion.log file created by WatchIonLog(). The functions registered for each log message type will no longer be called.

Returns

SUCCESS

other return codes from lower level functions.

Example:

int ret_value;
ret_value = WatchIonLog( "/home/user/iondir" );
 
if( ret_value )
{
    printf( "Error %d returned from WatchIonLog\n", ret_value )
}
 
// When you no longer wish to monitor the ion.log file...
StopIonLogWatch();

Examples

user_ionizer_app/user_ionizer_app.cpp.

StopIonProcessWatch()

int EXPORT_THIS_IONIZER_C_FUNCTION StopIonProcessWatch

(

)

Stops monitoring expected processes for ION.

Deletes the thread associated with monitoring ION processes created by WatchIonProcesses(). The function registered with RegisterMissingProcessCallback() will no longer be called.

Returns

SUCCESS

other return codes from lower level functions.

Example:

int ret_value;
ret_value = WatchIonProcesses( "d:/iondir" );
 
if( ret_value )
{
    printf( "Error %d returned from WatchIonProcesses\n", ret_value )
}
 
// When you no longer wish to monitor the ION processes...
StopIonProcessWatch();

Examples

user_ionizer_app/user_ionizer_app.cpp.

WatchIonConnection()

int EXPORT_THIS_IONIZER_C_FUNCTION WatchIonConnection

(

const char *

ion_working_dir

)

Starts monitoring connections for ION.

Starts a thread to monitor the connections that are part of the ION configuration. Only outgoing connections are monitored.
You can stop monitoring the exptected processes using StopIonConnectionWatch().

Parameters

[in]

ion_working_dir

The directory contains ION files.

Returns

SUCCESS

IONIZER_ALREADY_WATCHING

IONIZER_NULL_POINTER

other return codes from lower level functions.

Example:

int ret_value;
ret_value = WatchIonConnection( "/home/user/iondir" );
 
if( ret_value )
{
    printf( "Error %d returned from WatchIonConnection\n", ret_value )
}
 
// When you no longer wish to monitor the ION processes...
StopIonConnectionWatch();

WatchIonLog()

int EXPORT_THIS_IONIZER_C_FUNCTION WatchIonLog

(

const char *

ion_working_dir

)

Starts monitoring the ion.log file for messages.

Starts a thread to monitor the ion.log file. This function expects that the ion.log file is in the specified directory.
You can stop monitoring the ion.log using StopIonLogWatch().

Parameters

[in]

ion_working_dir

The directory contains ION files including ion.log.

Returns

SUCCESS

IONIZER_ION_LOG_FILE_NOT_FOUND

IONIZER_NULL_POINTER

other return codes from lower level functions.

Example:

int ret_value;
ret_value = WatchIonLog( "/home/user/iondir" );
 
if( ret_value )
{
    printf( "Error %d returned from WatchIonLog\n", ret_value )
}
 
// When you no longer wish to monitor the ion.log file...
StopIonLogWatch();

Examples

user_ionizer_app/user_ionizer_app.cpp.

WatchIonProcesses()

int EXPORT_THIS_IONIZER_C_FUNCTION WatchIonProcesses

(

const char *

ion_working_dir

)

Starts monitoring expected processes for ION.

Starts a thread to monitor the operating system for the expected processes related to ION. This function expects that a file named process.txt to be defined in the ION working directory. This file is automatically generated for you if you use IONconfig that is part of the install.
You can stop monitoring the exptected processes using StopIonProcessWatch().

Parameters

[in]

ion_working_dir

The directory contains ION files including process.txt.

Returns

SUCCESS

IONIZER_PROCESS_FILE_NOT_FOUND

IONIZER_NULL_POINTER

other return codes from lower level functions.

Example:

int ret_value;
ret_value = WatchIonProcesses( "/home/user/iondir" );
 
if( ret_value )
{
    printf( "Error %d returned from WatchIonProcesses\n", ret_value )
}
 
// When you no longer wish to monitor the ION processes...
StopIonProcessWatch();

Examples

user_ionizer_app/user_ionizer_app.cpp.