ipc-quartztime
Inter Process Communication based on shared memory, mutexes and signals
 All Pages
ipc-quartztime User Documentation
ipc-quartztime_user_doc_intro.jpeg

Overview

To use the ipc-quartztime communication, the interface between two processes needs to be defined by the Franca IDL. From this interface description, the client stubs and service stubs are generated.

The service and clients can then be implemented in C or C++.

Define Interface

Interface Definition using the Franca IDL

Using the Franca IDL, attributes and methods of services can be defined.

package localhost
import localhost.common_types.* from "common_types_v2_6.fidl"
interface navigation {
version {
major 0
minor 6
}
<** @description : indicates if a route guidance is active. Only the status for sessionId 0 is provided. **>
attribute Boolean is_guidance_active
<** @description : indicates if the rerouting option is active. Only the status for sessionId 0 is provided. **>
attribute Boolean is_traffic_rerouting_active
<** @description : lists the last destionations for sessionId 0. **>
attribute last_destinations_list last_destinations
<** @description : This method starts a route guidance,
given a start and a destination coordiante. **>
method start_route_guidance {
in {
Double start_coordinate_lat
Double start_coordinate_lon
Double destination_coordinate_lat
Double destination_coordinate_lon
coordinate_system system
Int32 sessionId
}
out {
Double distance_value
length_unit distance_unit
}
error general_guidance_errors
}
<** @description : This method stops a route guidance,
given a client-instance id(session id). **>
method stop_route_guidance {
in {
Int32 sessionId
}
out {
}
error general_guidance_errors
}
<** @description : error constants **>
enumeration general_guidance_errors {
ILLEGAL_COORDINATES
ILLEGAL_SESSION_ID
}
<** @description : systems of coordinates **>
enumeration coordinate_system {
COORD_WGS84
COORD_MERCATOR
}
<** @description : length unit **>
enumeration length_unit {
LENGTH_KM
LENGTH_MILES
}
<** @description : a location on the planet. **>
struct location {
Double latitude
Double longitude
coordinate_system system
}
<** @description : list of last destionations. **>
array last_destinations_list of location
}

To define maximum sizes of arrays, strings and bytebuffers, additional deployment model files (.fdepl) have to be added to the idl files.

import "classpath:/ipcq.fdepl"
import "classpath:/navigation_v0_6.fidl"
define localhost.fidl2ipcq.deploymentspec for interface localhost.navigation
{
array last_destinations_list {
MaxArraySize = 32
}
}

ipc-quartztime version compatibility

When changing the interface while compiling only some target-processes anew, the version needs to be changed.
No version change is necessary when

The minor version number shall be increased when

The major version number shall be changed in all other cases.

Franca Compliance

ipc-quartztime translates the following Franca IDL declarations with listed limitations.

The list above is derived from FrancaUserGuide-0.9.2.0.pdf.

Note that there is a deviation in semantics between message-based ipc and ipc-quartztime, which is last-status based:
A client gets the last status of an attribute - but may miss some intermediate values:
If a service writes the numbers 1, 2, 3, 4, 5 to an integer attribute, a client may read 1, 2, 5 - and miss the 3, 4 in between. The same applies to broadcasts.

Generate Stubs

ipc-quartztime_user_doc_gen.png

Service implementation

All functions necessary to provide a service are declared in the generated header include/ipcq/srv_if_<service_name>_<version>.h

#include "ipcq/ipcq.h"
#include "ipcq/srv_if_addressbook_v1_3.h"
static void provide_service()
{
ipcq_error_t err;
ipcq_service_if_t srv_if;
ipcq_notification_t srv_notification;
err = ipcq_notification_init( IPCQ_NOTIFY_PROCESS_SIGNAL, &srv_notification );
err = ipc_addressbook_register_service( "MainDisplayInstance", &srv_notification, &srv_if );
int32_t value = 32004;
err = ipc_addressbook_set_count( &srv_if, &value );
sleep(2);
err = ipc_addressbook_unregister_service( &srv_if );
err = ipcq_notification_destroy( &srv_notification );
}

Client implementation

All functions necessary to use a service are declared in the generated header include/ipcq/if_<service_name>_<version>.h

#include "ipcq/ipcq.h"
#include "ipcq/if_addressbook_v1_3.h"
static void connect_to_service()
{
ipcq_error_t err;
ipcq_service_if_t srv_if;
ipcq_notification_t cli_notification;
err = ipcq_notification_init( IPCQ_NOTIFY_PROCESS_SIGNAL, &cli_notification );
err = ipc_addressbook_connect_to_service( "MainDisplayInstance", &cli_notification, &srv_if );
int32_t value;
err = ipc_addressbook_get_count( &srv_if, &value );
err = ipc_addressbook_disconnect_from_service( &srv_if );
err = ipcq_notification_destroy( &cli_notification );
}

Integration

Compile and link the C or C++ code.
Set the compiler flags to -std=c99 -D_XOPEN_SOURCE=700
Less restrictive and newer standards should also work.

Appendix

Author
(c) 2013-2015 A.Warnke; Email-contact: ipc-quartztime-at-andreaswarnke-dot-de