/**
 *	@author 	ETSI / STF405
 *  @version 	$URL$
 *				$Id$
 *	@desc		Module containing functions for DENM
 *
 */
module LibItsDenm_Functions {
    
    // LibIts
    import from LibIts_TestSystem all;
    import from LibIts_Interface all; 
    import from LibItsDenm_TypesAndValues all; 
    import from LibItsDenm_Templates all; 
    import from CAM_PDU_Descriptions language "ASN.1:1997" all;
    import from DENM_PDU_Descriptions language "ASN.1:1997" all;
    
    // LibCommon
    import from LibCommon_VerdictControl all;

    /**
     * @desc 	Create Facility component and connects DENM port
     * @remark	Only used when ItsFa is a PTC
     * @param	p_ptcDenm returned Facility component variable
     */    
    function f_ptcDenmUp(out ItsFa p_ptcDenm) {
        
        // Create Facility component
        p_ptcDenm := ItsFa.create("DENM Tester");
        
        // map ports
        map(p_ptcDenm:denmPort, system:denmPort);
        
    } // end f_ptcDenmUp       
    
    /**
     * @desc 	Wait for component to finish and unmap DENM ports
     * @remark	Only used when ItsFa is a PTC
     * @param	p_camPtc Facility component variable
     */    
    function f_ptcDenmDown(in ItsFa p_ptcDenm) runs on ItsMtc {    
    	tc_guard.start;
        alt {
        	[] p_ptcDenm.done {
            	tc_guard.stop;
            }
            
            [] tc_guard.timeout {
             	log("*** f_ptcDenmDown: ERROR: Timeout while waiting for component ***");
             	setverdict(inconc);   
            }
        }
        unmap(p_ptcDenm:denmPort);
        
    } // end f_ptcDenmDown
    
    group altsteps {
        
        /**
         * @desc The base default.
         */
        altstep a_default() runs on ItsFa {
            [] denmPort.receive {
                setverdict (inconc, "Received an unexpected message");
                //TODO shall stop be called here?
                stop;
            }
            [] tc_wait.timeout {
                setverdict (inconc, "Timeout while awaiting reaction of the IUT prior to Upper Tester action");
                //TODO shall stop be called here?
                stop;
            }
            [] tc_ac.timeout {
                setverdict (inconc, "Timeout while awaiting the reception of a message");
                //TODO shall stop be called here?
                stop;
            }
        }
        
    } // end group altsteps
    
    group preambles {
        
        /**
         * @desc The default preamble.
         */
        function f_prDefault() runs on ItsFa {
            vc_default := activate(a_default());
        }
        
        /**
         * @desc Brings the IUT into an initial state.
         * @return 
         */
        function f_prInitialState() runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            f_prDefault();
            
            //TODO raise action or send message via port
            
            f_setVerdictPreOrPostamble(v_ret);
            
            return v_ret;
        }
        
    } // end group preambles
    
    group postambles {
        
        /**
         * @desc The default postamble.
         */
        function f_poDefault() runs on ItsFa {
            var FncRetCode v_ret := e_success;
            //empty
            f_setVerdictPreOrPostamble(v_ret);
            
        }
        
        /**
         * @desc Postamble including cancellation of an event.
         * @param p_trigger Indicates if the cancellation have to be raised by the test system(e_ets) or at the application layer of the IUT(e_iut).
         * @param p_event The event to cancel.
         * @verdict 
         */
        function f_poCancelEvent(template (value) Trigger p_trigger, template (value) Situation p_event) runs on ItsFa {
            var FncRetCode v_ret := e_success;
            
            if (p_trigger == e_ets) {
                f_sendDenMessage(
                    m_denmReq(
                    	m_denmPdu(
                        	m_denmWithCause(c_dataVersionCancellation, p_event, f_getCurrentPosition(), f_getStationId())
                        )
                    )
                );
            }
            else {
                v_ret := f_triggerEventCancellation(p_event);
            }
            f_setVerdictPreOrPostamble(v_ret);
            
            f_poDefault();
        }
        
    } // end group postambles
    
    group eventFunctions {
        
        //TODO check if type Situation is suitable
        /**
         * @desc Triggers event from the application layer
         * @param p_event The event cause and subcause.
         * @return 
         */
        function f_triggerEvent(template (value) Situation p_event) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        /**
         * @desc Triggers cancellation event from the application layer
         * @param p_event The event cause and subcause.
         * @return 
         */
        function f_triggerEventCancellation(template (value) Situation p_event) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            var DataVersion v_dataVersion := c_dataVersionCancellation;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        /**
         * @desc Triggers event negation from the application layer
         * @param p_event The event cause and subcause.
         * @return 
         */
        function f_triggerEventNegation(template (value) Situation p_event) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            var DecentralizedEnvironmentalNotificationMessage.management.isNegation v_isNegation := true;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        /**
         * @desc Triggers event with additional TrafficFlowEffect information field included from the application layer
         * @param p_event The event cause and subcause.
         * @param p_tfe The Traffic Flow Effect.
         * @return 
         */
        function f_triggerEventTrafficFlowEffect(
            template (value) Situation p_event, 
            template (value) TrafficFlowEffect p_tfe
            ) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        /**
         * @desc Triggers event with additional LinkedCause information field included from the application layer
         * @param p_event The event cause and subcause.
         * @param p_linkedCause The linked event.
         * @return 
         */
        function f_triggerEventLinkedCause(
            template (value) Situation p_event, 
            template (value) Situation p_linkedCause
            ) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }

		/**
         * @desc Triggers event with expiration time information field and frequency information field 
         * 		  included from the application layer
         * @param p_event The event cause and subcause.
         * @param p_expirationTime The expiration time.
         * @param p_frequency The frequency.
         * @return 
         */        
        function f_triggerEventExpirationTimeFrequency(
            template (value) Situation p_event, 
            template (value) TimeStamp p_expirationTime,
            template (value) DecentralizedSituationManagement.frequency p_frequency
            ) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }

        /**
         * @desc Triggers event with expiration time information field included from the application layer
         * @param p_event The event cause and subcause.
         * @param p_expirationTime The expiration time.
         * @return 
         */        
        function f_triggerEventExpirationTime(
            template (value) Situation p_event, 
            template (value) TimeStamp p_expirationTime
            ) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }

        /**
         * @desc Triggers update of event's expiration time
         * @param p_event The event cause and subcause.
         * @param p_expirationTime The new expiration time.
         * @return 
         */        
        function f_triggerEventExpirationTimeUpdate(
            template (value) Situation p_event, 
            template (value) TimeStamp p_expirationTime
            ) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }        
               
        /**
         * @desc Triggers event with additional Event Characteristics information field included from the application layer
         * @param p_event The event cause and subcause.
         * @param p_eventCharact The event characteristics.
         * @return 
         */
        function f_triggerEventEventCharact(
            template (value) Situation p_event, 
            template (value) DecentralizedSituation.eventCharact p_eventCharact
            ) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        //TODO check if type Situation is suitable
        /**
         * @desc Checks that the event was indicated the application layer
         * @param p_event The event cause and subcause.
         * @return 
         */
        function f_checkEvent(template (value) Situation p_event) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        /**
         * @desc Checks that the event cancellation was indicated to the application layer
         * @param p_event The event cause and subcause.
         * @return 
         */
        function f_checkEventCancellation(template (value) Situation p_event) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
        /**
         * @desc Checks that the event negation was indicated to the application layer
         * @param p_event The event cause and subcause.
         * @return 
         */
        function f_checkEventNegation(template (present) Situation p_event) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            //TODO raise action or send message via port
            
            return v_ret;
        }
        
    } // end group eventFunctions
    
    group sendFunctions {
        
        /**
         * @desc Sends a DEN message
         * @param p_sendMsg The DEN message to send.
         * @return 
         */
        function f_sendDenMessage(template (value) DenmReq p_sendMsg) runs on ItsFa {
            p_sendMsg.msgOut.denm.management.actionID.sequenceNo := vc_sequenceNo;
            
            denmPort.send(p_sendMsg);
        }
        
    } // end sendFunctions
    
    group receiveFunctions {
        
        /**
         * @desc Awaits a DEN message
         * @param p_rcvMsg The expected message to be received.
         * @return 
         */
        function f_awaitDenMessage(template (present) DenmInd p_rcvMsg) runs on ItsFa return FncRetCode {
            var DenmInd v_denmInd;
            return f_awaitDenMessageOut(p_rcvMsg, v_denmInd);
        }
        
        /**
         * @desc Awaits a DEN message
         * @param p_rcvMsg The expected message to be received.
         * @param p_rcvdMsg The received message - OUT.
         * @return 
         */
        function f_awaitDenMessageOut(in template (present) DenmInd p_rcvMsg, out template (value) DenmInd p_rcvdMsg) runs on ItsFa return FncRetCode {
            var FncRetCode v_ret := e_timeout;
            
            tc_ac.start;
            alt {
                [] denmPort.receive(p_rcvMsg) -> value p_rcvdMsg {
                    tc_ac.stop;
                    v_ret := e_success;
                }
                [] tc_ac.timeout {
                	log("Timeout while awaiting the reception of a message");
                	v_ret := e_timeout;
           		}
            }
            
            return v_ret;
        }
        
    } // end receiveFunctions
    
    group getFunctions {
        
        group iutGetFunctions {
            
            
            
        } // end iutGetFunctions
        
        group testerGetFunctions {
            
            /**
             * @desc Gets the station identifier of IUT.
             * @return 
             */
            function f_getIutDefaultEventDuration() return TimeStamp {
                var TimeStamp v_iutDefaultEventDuration;
                
                //TODO get the value from PIXIT or MIB
                
                return v_iutDefaultEventDuration;
            }            
            
        } // end testerGetFunctions
        
        // TODO: Clean up 
        
        /**
         * @desc Gets the station identifier of IUT.
         * @return 
         */
        function f_getStationId() return StationID {
            var StationID v_stationId;
            
            //TODO get the value from PIXIT or MIB
            
            return v_stationId;
        }
        
        /**
         * @desc Gets the position of the test system.
         * @return 
         */
        function f_getCurrentPosition() return DecentralizedSituationLocation.eventPosition {
            var DecentralizedSituationLocation.eventPosition v_eventPos;
            
            //TODO get the value from PIXIT or ...
            
            return v_eventPos;
        }
        
        /**
         * @desc Gets the current time
         * @return 
         */
        function f_getCurrentTime() return TimeStamp {
            var TimeStamp v_timeStamp;
            
            //TODO get the value from xf ...
            
            return v_timeStamp;
        }
        
    } // end group getFunctions
    
} // end LibItsDenm_Functions