Core API use

Please find an example of how the API is expected to be used

Brief explanation

The API works on a few levels but for developers it should be fairly simple.

The discovery service and peerstore to give you a list of peer type data structures.

To create a conversation between peers you link them with session

Both session and peer are controlled by session_service and discovery_service respectively.

Overall the session_service links two peers together and then starts the auth_comms service to establish a secure link.

| Discovery Service | ----------Remote peers-----> | Session Service | <------------
|  Peer store       |                                      |                        | 
                                                   | Auth comms service| ->  |Secure comms|

The callback setup

When creating a session service you'll need to pass two function pointers for what should occur during linking and unlinking.

This paradigm was chosen as there might be additional operations in UI programs that need to occur before either operation.

In the example below I've passed some variables through with optargs but ultimately the only thing we need to ensure is we call auth_comms_initiator_start on a client that's initiating a connection.

Note that the E_AM_INITIATOR and E_AM_RECEIVER can be used to selectively choose functionality on the linking e.g. On the linking of the receiver you do not need to initiate the auth comms connection.

int linking_test_procedure(session *s,linked_session_type session_type,
    void *optargs) {
  if(session_type == E_AM_INITIATOR){
    discovery_service *ds = (discovery_service*)optargs;

    int init_port = rand() % 1000;

    //port control could also be passed in with opt args in a DTO, but it's here for example
    port_control_service *ps = port_control_service_create(8000 + 
        init_port,
        12341,1);

    //For the sake of this example auth comms is global, but regardless of where you set it,
    //you have to initialise the listener.
    ac = auth_comms_create();
    ac->listener = jnx_socket_tcp_listener_create("9991",AF_INET,15);
    
    auth_comms_initiator_start(ac,ds,ps,s);
  }
  return 0;
}
int unlinking_test_procedure(session *s,linked_session_type session_type,
    void *optargs) {
  auth_comms_stop(ac,s);
  return 0;
}

The initialisation

In the main program this would be the procedure to setup the session_service and create a linked session.

//Function pointers to the linking procedures
session_service *service = session_service_create(linking_test_procedure,
      unlinking_test_procedure);

session *os;
//Creating a new blank session
session_state e = session_service_create_session(service,&os);

//Assert there is nothing going on with this session
JNXCHECK(session_service_session_is_linked(service,&os->session_guid) == 0);
JNXCHECK(session_is_active(os) == 0);

//Link the session between two peers (Local and remote)
session_service_link_sessions(service,E_AM_INITIATOR,
      ds,&(*os).session_guid,local,remote_peer);


JNXCHECK(session_is_active(os) == 1);

//Write messages into this live session (or read)
session_write_message(os,"Hello with encryption!");

And to unlink...

session_service_unlink_sessions(service,E_AM_INITIATOR,
      ds,&(*os).session_guid);

JNXCHECK(session_is_active(os) == 0);
  
JNXCHECK(session_service_session_is_linked(service,&os->session_guid) == 0);