The interaction protocol
[Interaction and awareness]

Collaboration diagram for The interaction protocol:

The interaction protocol is defined to allow object called interactor to interact with parameters of an interactive simulated object. More...

Modules
	Interactive object
	The module for simulated object defined as interactive object.
	Interactor
	TO DO .
	Interaction objects and ids
	The types and ids used for interaction.

---

Detailed Description

The interaction protocol is defined to allow object called interactor to interact with parameters of an interactive simulated object.

The interaction protocol between interactor and interactive objects

The protocol is based on events that define a communication protocol. Both object knows this protocol and is able to answer to the requests emitted by the other object. The protocol events are the following:

"parameters ?"

This event is the first in the protocol, it initializes the dialog between the interactor and an interactive object. This event is sent by the interactor to an object to know which are its available interactive parameters. If the object does not answer, it means that it is not an interactive object or of a too high access level. To answer the interactive object sends a valued event available connectors'.

The format of the event is AccessLevelEvent which is valued with an integer value which is the access level of the interactor.

sendValuedEvent( <interactive object id>, EventId::getParameters, OMK::Type::IntType( (int)<access level of the interactor> ) ) ;

Examples see also selfGetParameters for emitter and processGetParameters for receiver.

"available connectors"

This event is sent by the interactive object as an answer to the interactor which sends event "parameters ?". In it, each connector is defined by its id and its category (the category depends of the type of the parameter).

The format of the event is ConnectorsCategoryListEvent which is valued with an list of pairs of ids, the first is the connector id, the second the connector category.

OM::Type::TwoIdsListPrm connectorsList ;
connectorsList.push_back( OM::Iii::TwoIdsPrm( <connector id>, <connector category> ) );
...
sendValuedEvent( <interactor id>, EventId::availableConnectors, OM::Type::TwoIdsListType( connectorsList ) ) ;

Examples see also processGetParameters for emitter and processAvailableConnectors for receiver.

"current values ?"

This event is sent by the interactor to an interactive object to know which are the values of its available interactive parameters, these previously get by "parameters ?" event. See "getCurrentValues".

The format of the event is AccessCurrentValueEvent which is valued with an integer value which is the access level of the interactor associated to a list of pairs of ids, the first is the connector id, the second the output id which will receive the value.

OM::Type::AccessCurrentValuePrm connectorsToGet( <access level of the interactor> ) ;
connectorsToGet.addItem( OM::Iii::TwoIdsPrm( <connector id>, <id of the output which will receive the value> ) ) ;
...
sendValuedEvent( <interactive object id>, EventId::currentValue, OM::Type::AccessCurrentValueType( connectorsToGet ) ) ;

Examples see also selfGetCurrentValues for emitter and processGetParameters for receiver.

"current value"

This event is sent by the interactive object as an answer to the interactor which sends event 'current values ?'. In fact, each connector sends this message. It is processing by the interactor attribut associated with the output.

The format of the event is valued event with a PsPair defined by an id associated to data of the parameter type, the first is the connector id, the second the value of the parameter.

sendValuedEvent< PsPair< PsName, Type > >( <interactor id>, EventId::currentValue, PsPair< PsName, <Type> >( <id of the output which will receive the value>, <the current value of the parameter> ) ) ;

Examples see also sendValue for emitter and processSetValue for receiver.

"current values sent"

This event is sent by the interactive object as an answer to the interactor which sends event 'current values ?'. In fact, each connector sends its own value, but the interactor is informed by this message that all the values are sent. It is processing by the interactor extension associated to the interactor.

"control take over"

This event is sent by the interactor to an interactive object to take control of its interactive parameters, these previously get by 'parameters ?' event.

The format of the event is AccessTakeOverEvent which is valued with an integer value which is the access level of the interactor associated to a list of pairs of ids associated to a flag, the first id is the connector id, the second the output id which will be connected, the flag is the freeze flag.

OM::Iii::AccessTakeOverPrm connectorsToControl( <access level of the interactor> ) ;
connectorsToControl.addItem( OM::Iii::ControlTakeOverPrm( <connector id>, <id of the output which will receive the value>, <freeze flag> ) ) ;
...
sendValuedEvent( <interactive object id>, EventId::controlTakeOver, OM::Iii::AccessTakeOverType( connectorsToControl ) ) ;

Examples see also selfControlTakeOver for emitter and processControlTakeOver for receiver.

"control taken"

This event is sent by the interactive object as an answer to the interactor which sends event 'control take over'.

The format of the event is ConnectorsListEvent which is valued with a list of connector ids which are in fact controlled by the interactor.

"control release"

This event is sent by the interactor to an interactive object to release the control of its interactive parameters, these previously controlled by "control take over" event.

There is two formats for this event the first format is ConnectorsListEvent which is valued with a list of connector ids.

OM::Iii::ConnectorsList connectorsList ;
connectorsList.push_back( <connector id> ) ;
...
sendValuedEvent( <interactive object id>, EventId::controlRelease, connectorsList ) ;

The second format is just a no-valued event, in this case all the controls are removed.

sendEvent( <interactive object id>, EventId::controlRelease ) ;

Examples see also selfControlRelease for emitter and processControlRelease for receiver.

"control ended"

This event is sent by the interactive object when the interactor loses the control of a parameter against its will.

The format of the event is ConnectorsListEvent which is valued with a list of connector ids which are no more controlled by the interactor.

"control freeze"

This event is sent by the interactor to an interactive object to freeze the access to its interactive parameters, these must be controlled by the interactor.

The format of the event is ConnectorsListEvent which is valued with a list of connector ids.

OM::Iii::ConnectorsList connectorsList ;
connectorsList.push_back( <connector id> ) ;
...
sendValuedEvent( <interactive object id>, EventId::controlFreeze, connectorsList ) ;

Examples see also selfControlFreeze and processControlFreeze for receiver.

"control unfreeze"

This event is sent by the interactor to an interactive object to release the control of its interactive parameters, these previously controlled by "control take over" event.

There is two formats for this event the first format is ConnectorsListEvent which is valued with a list of connector ids.

OM::Iii::ConnectorsList connectorsList ;
connectorsList.push_back( <connector id> ) ;
...
sendValuedEvent( <interactive object id>, EventId::controlRelease, connectorsList ) ;

The second format is just a no-valued event, in this case all the controls are removed.

sendEvent( <interactive object id>, EventId::controlUnfreeze ) ;

Examples see also selfControlUnfreeze and processControlUnfreeze for receiver.

---