Connection

Before you can communicate using a JMP connection, you first need to establish the connection. To do this, you need to define connection settings using the 'Connection Properties' object.

The 'Connection Properties' object allows you to define a connection's IP Address, Port number, Login Credentials, and if it should reconnect after the conection is lost. Settings you don't enter for the connection properties will use default values. You always need to provide an IP Address, but port 9220 is the default port, and 'jnior, jnior' (Admin Role) are the default login credentials. The connection is set to reconnect by default as well.

Connection Properties

@Snippet:versions:v26_0_0@

The Connection Properties structure is used to hold connection options. This structure is created by the user program and passed to the Create Connection method.

C++

/**
* @param       ip_address       ip address of the target jnior
* @param       port             jmp protocol port.  9220 by default
* @param       username         The username to use for the initial authentication.
                                The default "jnior" will be used if one is 
                                not provided.
* @param       password         The username to use for the initial authentication.
                                The default "jnior" will be used if one is 
                                not provided.
* @param       reconnect        this connection will try to reconnect if 
                                the connection is lost. This, by default, is true
* @param       timeout_sec      timeout in seconds.  5 seconds by default
*/

JMPLIB_EXPORT struct connection_properties {
    const std::string ip_address;
    const int port = 9220;
    const int timeout_sec = 5;
    bool reconnect = true;
    std::string username = "jnior";
    std::string password = "jnior";
};

Here is an example of how to define values for the Connection Properties object:

C++C#JavaPython

// define a connection that will be successful
// define the connection properties for the target jnior
const auto connection_props = new ipg::CONNECTION_PROPERTIES("10.0.0.96")
    .set_port(9222)
    .set_credentials("username_here", "password_here");

// instantiate a connection
ipg::create_connection(&connection_props, uuid);

// wait for the connection result.  we will expect this to be successful
const int connection_result = ipg::wait_for_connection(uuid);
auto status_description = new char[32];
ipg::get_connection_status_description(uuid, status_description);
std::cout << std::format("connection_result: ({}) {}",
                            connection_result, status_description) << std::endl;

// clean up
delete[] status_description;

if (ipg::CONNECTED != connection_result) {
    throw new std::runtime_error("Connection result was not SUCCESSFUL");
}

// get the connection state
int connection_status = ipg::get_connection_status(uuid);
if (ipg::CONNECTED == connection_status) success();
else failed();

// make sure to disconnect
ipg::disconnect(uuid);

using dotnetJmpLib;

// Define the connection properties and initialize the JmpConnection
var connectionProperties = new ConnectionProperties("10.0.0.96")
// Sets the connections port to 9220
.setPort(9200)
// Sets the connection's login to 'jnior' for username, and 'jnior' for 
// password.
.SetCredentials("jnior","jnior")
// Sets the connection to reconnect or not if the connection fails
.SetReconnect(True/False);

// use the connection properties that are defined to create a jmp connection
var _jmpConnection = new JmpConnection(connectionProperties);

import com.integ.jmplib;

// Defines a default connection properties object with IP
ConnectionProperties connectionproperties = new ConnectionProperties("10.0.0.96")
// Sets the connections port to 9220
.setPort(9220)
// Sets the connection's login to 'jnior' for username, and 'jnior' for 
// password.
.setCredentials("jnior", "jnior")
// Sets the connection to reconnect or not if the connection fails
.setReconnect(True/False);

// use the connection properties that are defined to create a jmp connection
JmpConnection jmpConnection = new JmpConnection(connectionproperties);

import jmplib_py

# Defines a default connection properties object with IP
connection_properties = jmplib_py.ConnectionProperties("10.0.0.96")
# Sets the connections port to 9220
    .set_port(9220)
# Sets the connection's login to 'jnior' for username, and 'jnior' for 
# password.
    .set_credentials("jnior", "jnior")
# Sets the connection to reconnect or not if the connection fails
    .set_reconnect(True/False)

# use the connection properties that are defined to create a jmp connection
jmp_connection = jmplib_py.JmpConnection(connection_properties)

Create Connection

@Snippet:versions:v26_0_0@

Uses the previously mentioned Connection Properties. The JMP Connection Connect method is not directly callable and therefore doesn't have any returned status codes.

Waiting for the Connection

@Snippet:versions:v26_0_0@

After creating the connection, you can wait for the connection to either connect, or timeout. The wait_for_connection() function call will return the status of the connection at the time of the return.

This call returns the moment the status is changed to CONNECTED or CONNECTION FAILED. This

Possible Status Returns:

• INVALID_UUID: If a JMP Connection is not found for the given UUID

sequenceDiagram
  autonumber
  Application->>connection_monitor_object: Wait for connection
  Note right of Application: Application thread blocks until the<br>connection is made/fails or the timeout expires
  loop
      connection_monitor_object->>connection_monitor_object: 2 second timeout
  end
  JmpConnection-->>connection_monitor_object: Connected / Connection Failed
  Note right of Application: returns the status of the connection
  connection_monitor_object->>Application: <Connection Status>
  Note right of Application: Application continues...

This is how you would call it in code...

C++C#JavaPython

// this call will block until the connection is either CONNECTED or has FAILED
const int connection_result = ipg::wait_for_connection(m_uuid);

// set up the connection
...

// this call will block until the connection is either CONNECTED or has FAILED
var connectionResult = _jmpConnection.WaitForConnection();

...

// This will wait to proceed further in the code until it resolves 
// the status of the JMP Connection.
jmpConnection.waitForConnection();

# This will wait to proceed further in the code until it resolves 
# the status of the JMP Connection.
jmp_connection.wait_for_connection()

Connection Status

@Snippet:versions:v26_0_0@

You can manually check the status of the connection by using the Get Connection Status function.

Possible Status Returns:

• INVALID_UUID: If a JMP Connection is not found for the given UUID

C++C#JavaPython

// gets the current status for the given connection
int connection_status = ipg::get_connection_status(uuid);

// gets the current status for the given connection
var connection_status = _jmpConnection.GetConnectionStatus()

// This will give us a STATUS Code that will represent the state of the connection.
connectionStatus = jmpConnection.getConnectionStatus()

# This will give us a STATUS Code that will represent the state of the connection.
connection_state = jmp_connection.get_connection_status()

Connection Status Description

@Snippet:versions:v26_0_0@

Alternatively, you can get a string description for state of the connection by using the Get Connection Status Description function.

Possible Status Returns:

• INVALID_UUID: If a JMP Connection is not found for the given UUID

C++C#JavaPython

// gets the current status description for the given connection
char connection_status_description[16];
ipg::get_connection_status_description(m_uuid, connection_status_description);
std::printf("\nConnection status description: %s\n", connection_status_description);

// gets the current status description for the given connection
var connectionStatusDescription = _jmpConnection.GetConnectionStatusDescription();

// This will give us a String value that represents the state of the connection.
String connectionStatusDescription = jmpConnection.getConnectionStatusDescription();

# This will give us a String value that represents the state of the connection.
connection_status_description = jmp_connection.get_connection_status_description()

Disconnect

@Snippet:versions:v26_0_0@

When you are done with a connection, you can us the Disconnect function to end it. To reestablish a connection to the unit, you will need to create a new connection.

Possible Status Returns:

• INVALID_UUID: If a JMP Connection is not found for the given UUID
• DISCONNECTED: Returned no matter what the current state of the socket is.

C++C#JavaPython

ipg::disconnect(uuid);

// Connection is stopped
_jmpConnection.Disconnect();

// Connection is stopped 
jmpConnection.disconnect();

# Connection is stopped
jmp_connection.disconnect()

Connection Callback

@Snippet:versions:v26_0_0@

Optionally, a callback can be assigned that will be alerted when ever there is a change to any of the connections. In order for the collback to be effective, it must be defined before any connections are defined. To define the call back we can do the following...

C++C#JavaPython

// Define callback method.  This function will get called when the status 
// of the connection changes.
int connection_callback(const char *sessionId, const char *status_description) {
    std::cout << std::string(sessionId) + ": " + status_description << std::endl;
    return 0;
}


// Add the callback to the library
ipg::add_connection_callback(connection_callback);

...

// When we are done with the callback, we must remove it from the library
ipg::remove_connection_callback(connection_callback);

// Defines the callback method that runs when the JMP connection's status 
// changes.
private static void ConnectionStatusChange(string uuid, int statusCode, string statusDescription) {
    Console.WriteLine($"{uuid}: Connection status is ({statusCode}) {statusDescription}");
}

// Once the ConnectionStatusChange function is defined, you can
// now add the connection listener to enable the callback.
// This will check for changes to the JMP connection, and run the 
// ConnectionStatusChange function when they occur.
JmpLib.add_connection_callback(ConnectionStatusChange);

// Defines the callback method that runs when the JMP connection's status 
// changes.
@Override
public void onConnectionStatusChange(jmpConnection, int statusCode, String statusDescription) {
    System.out.println("Connection Status Code = " + statusCode + ", Connection Status Description = " + statusDescription);
}

// Once the OnConnectionStatusChange function is defined, you can
// now add the connection listener to enable the callback.
// This will check for changes to the JMP connection, and run the 
// onConnectionStatusChange function when they occur.
JmpLib.addConnectionListener(this);

# Defines the callback method that runs when the JMP connection's status 
# changes.
def on_connection_status_change(jmp_connection, statusCode: int, statusDescription: str):
print(f"Authentication status code: {statusCode}. Authentication status description: {statusDescription}")

# Once the on_connection_status_change function is defined, you can
# now add the connection listener to enable the callback.
# This will check for changes to the JMP connection, and run the 
# on_connection_status_change function when they occur.
jmplib_py.add_connection_status_callback(on_connection_status_change)

The callback is alerted any time taht the connection status changes. The callbacks you should see are NOT_CONNECTED, CONNECTING, CONNECTED, DISCONNECTING, and DISCONNECTED. You might also see CONNECTION_FAILED if your connection fails.

Connection STATUS codes

Please go to the Connection Status Codes section.