src/NameService/EPTF_CLL_NameServiceClient_Functions.ttcn

///////////////////////////////////////////////////////////////////////////////
//                                                                           //
// Copyright (c) 2000-2019 Ericsson Telecom AB                               //
//                                                                           //
// All rights reserved. This program and the accompanying materials          //
// are made available under the terms of the Eclipse Public License v2.0     //
// which accompanies this distribution, and is available at                  //
// https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html                                 //
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
//  Module: EPTF_CLL_NameServiceClient_Functions
// 
//  Purpose:
//    This module contains the implementation of the EPTF_NameService_Client functions.
// 
//  Module depends on:
//    <EPTF_CLL_Base_Functions>
//    <EPTF_CLL_NameService_Definitions>
//    <EPTF_CLL_NameService_Functions>
//    <EPTF_CLL_Logging_Definitions>
//    <EPTF_CLL_Logging_Functions>
// 
//  Current Owner:
//    Jozsef Gyurusi (ETHJGI)
// 
//  Last Review Date:
//    2007-12-06
//
//  Detailed Comments:
//    This module contains the interface functions for the EPTF_NameService_Client. 
//
///////////////////////////////////////////////////////////////

module EPTF_CLL_NameServiceClient_Functions {

import from EPTF_CLL_NameService_Definitions all;
import from EPTF_CLL_NameService_Functions all;
import from EPTF_CLL_Base_Functions all;
import from EPTF_CLL_Logging_Definitions all;
import from EPTF_CLL_Logging_Functions all;

// INIT & CLEANUP

///////////////////////////////////////////////////////////
//  Function: f_EPTF_NS_Client_init_CT
// 
//  Purpose:
//    Initializes the EPTF_NS_Client_CT component
//
//  Parameters:
//    pl_selfName - *in* *charstring*  - name of the component
//    pl_NS_ServerCompRef - *in* <EPTF_NS_CT> - reference to the NS server component
//
//  Return Value:
//    -
//
//  Errors:
//    -
//
//  Detailed Comments:
//    This function should be called before using the EPTF NS Client
//    component.
//
///////////////////////////////////////////////////////////
public function f_EPTF_NS_Client_init_CT(in charstring pl_selfName, in EPTF_NS_CT pl_NS_ServerCompRef) runs on EPTF_NS_Client_CT {
  if (v_NS_Client_initialized) {
    return;
  }
  f_EPTF_Logging_init_CT(pl_selfName);
  v_NameServiceClient_loggingMaskId := f_EPTF_Logging_registerComponentMasks(
    tsp_EPTF_NameServiceClient_loggingComponentMask,
    c_EPTF_NameService_loggingEventClasses,
    EPTF_Logging_CLL);
  if(tsp_debug_EPTF_NameService_Functions) {
    f_EPTF_Logging_enableLocalMask(v_NameServiceClient_loggingMaskId, c_EPTF_NameService_loggingClassIdx_Debug);
  } else {
    f_EPTF_Logging_disableLocalMask(v_NameServiceClient_loggingMaskId, c_EPTF_NameService_loggingClassIdx_Debug);
  }

  v_NS_Server := pl_NS_ServerCompRef;
  connect(self:EPTF_NS_Client_MgmtIf,v_NS_Server:EPTF_NS_MgmtIf);
  v_EPTF_NS_Client_def := activate(as_handle_main_EPTF_NS_Client_MgmtIf());
  v_NS_Client_initialized := true;

  f_EPTF_Base_registerCleanup(refers(f_EPTF_NS_Client_cleanup_CT));

  //log("----NS_Client INIT DONE----");
  f_EPTF_NameServiceClient_debug("---- EPTF_NS_Client INIT "&pl_selfName&" DONE----");
}

///////////////////////////////////////////////////////////
//  Function: f_EPTF_NS_Client_cleanup_CT
// 
//  Purpose:
//    This function should be called before the EPTF_NS_Client_CT component shuts down.
//
//  Parameters:
//    -
//
//  Return Value:
//    -
//
//  Errors:
//    -
//
//  Detailed Comments:
//    The function is registered by <f_EPTF_Base_registerCleanup> as a cleanup function in the init function for the ETPF_NS_Client_CT component.
//    This function makes it possible to be able to shut down the
//    EPTF_NS_Client_CT component gracefully.
//    The function blocks execution until the response for bye message
//    has received, or until 0.5secs.
//    
///////////////////////////////////////////////////////////
/*private*/ function f_EPTF_NS_Client_cleanup_CT() runs on EPTF_NS_Client_CT {
// FIXME: this function is called from test case EPTF_NameService_Test_Testcases
  if (v_NS_Client_initialized == false) {
    return;
  }
  f_EPTF_NS_Bye();
  timer t_bye := 0.5;
  t_bye.start;
  alt {
    [] t_bye.timeout {
       //log("WARNING:","--CLEANUP TIMEOUT-- Not all responses received for bye messages.");
       f_EPTF_NameServiceClient_warning("--CLEANUP TIMEOUT-- Not all responses received for bye messages.");
    }
  }
  v_NS_Client_initialized := false;
  //log("----NS_Client CLEANUP DONE----");
  f_EPTF_NameServiceClient_debug("----NS_Client CLEANUP DONE----");
}

// REGISTER & DEREGISTER NAME

///////////////////////////////////////////////////////////
//  Function: f_EPTF_NS_RegisterName
// 
//  Purpose:
//    This function should be called to register a name into the NS server.
//
//  Parameters:
//    pl_name - *in* *charstring* - name to register
//    pl_id - *in* *integer* *optional* - a positive id to store for the registered name
//
//  Return Value:
//    -
//
//  Errors:
//    -
//
//  Detailed Comments:
//    The function registers the name in the NS. When this name is queried, the component reference
//    to the component which registered the name is returned (together with the optional id)
//    
///////////////////////////////////////////////////////////
public function f_EPTF_NS_RegisterName(in charstring pl_name, in integer pl_id := -1) runs on EPTF_NS_Client_CT {
  var EPTF_NS_RegisterName vl_registerName := {pl_name,pl_id};
  // if not given
  if (pl_id == -1) {
    vl_registerName.id := omit;
  }
  f_EPTF_NS_send({registerName := vl_registerName});
}

///////////////////////////////////////////////////////////
//  Function: f_EPTF_NS_DeregisterName
// 
//  Purpose:
//    This function deregisters a name from the NS server.
//
//  Parameters:
//    pl_name - *in* *charstring* - name to register
//
//  Return Value:
//    -
//
//  Errors:
//    -
//
//  Detailed Comments:
//    Clears the name from the NS server if it was registered
//    
///////////////////////////////////////////////////////////
public function f_EPTF_NS_DeregisterName(in charstring pl_name) runs on EPTF_NS_Client_CT {
  var EPTF_NS_DeregisterName vl_deregisterName := {pl_name};
  f_EPTF_NS_send({deregisterName := vl_deregisterName});
}

// QUERY

///////////////////////////////////////////////////////////
//  Function: f_EPTF_NS_DeregisterName
// 
//  Purpose:
//    This function queries a name from the NS server.
//
//  Parameters:
//    pl_name - *in* *charstring* - name to register
//    pl_queryResp - *out* <EPTF_NS_QueryResp> - response to the query
//
//  Return Value:
//    -
//
//  Errors:
//    -
//
//  Detailed Comments:
//    The reference to the component and the optional id is returned in the pl_queryResp argument
//    
///////////////////////////////////////////////////////////
public function f_EPTF_NS_Query(in charstring pl_name, out EPTF_NS_QueryResp pl_queryResp) runs on EPTF_NS_Client_CT {
  f_EPTF_NS_send({query := {pl_name}});
  as_handle_EPTF_NS_Client_QueryResp(pl_queryResp);
}

//*************************************************************
//  private
//*************************************************************

// SEND FUNCTION

private function f_EPTF_NS_send(in EPTF_NS_MgmtMsg pl_EPTF_NS_MgmtMsg) runs on EPTF_NS_Client_CT {
  EPTF_NS_Client_MgmtIf.send(pl_EPTF_NS_MgmtMsg) to v_NS_Server;
}

// BYE

private function f_EPTF_NS_Bye() runs on EPTF_NS_Client_CT {
  f_EPTF_NS_send({bye := {}});
}

// HANDLER FUNCTIONS

private function f_EPTF_NS_handle_RegisterNAck(in EPTF_NS_RegisterName pl_registerNAck) runs on EPTF_NS_Client_CT {
  //log("WARNING:", "Registration failed for ", pl_registerNAck);
  f_EPTF_NameServiceClient_warning(log2str("Registration failed for ",pl_registerNAck));
}

private function f_EPTF_NS_handle_QueryResp(in EPTF_NS_QueryResp pl_queryResp) runs on EPTF_NS_Client_CT {
  if (pl_queryResp.ownerComp==omit) {
    //log("WARNING:","EPTF_NS_Query failed for name ", pl_queryResp.name);
    f_EPTF_NameServiceClient_warning(log2str("EPTF_NS_Query failed for name ", pl_queryResp.name));
    return;
  }
}

private function f_EPTF_NS_Client_handle_ByeAck() runs on EPTF_NS_Client_CT {
  disconnect(self:EPTF_NS_Client_MgmtIf,v_NS_Server:EPTF_NS_MgmtIf);
}

// the main handler function of the EPTF_NS_MgmtIf.
// returns true if the repeat, false to exit from the main altsep
private function f_handle_main_EPTF_NS_Client_MgmtIf(
  in EPTF_NS_MgmtMsg vl_EPTF_NS_MgmtIf_msg,
  in EPTF_NS_CT vl_EPTF_NS_MgmtIf_msg_sender) runs on EPTF_NS_Client_CT return boolean {
  if (ischosen(vl_EPTF_NS_MgmtIf_msg.registerNAck)) {
    f_EPTF_NS_handle_RegisterNAck(vl_EPTF_NS_MgmtIf_msg.registerNAck);
    return true;
  }
  if (ischosen(vl_EPTF_NS_MgmtIf_msg.queryResp)) {
    f_EPTF_NS_handle_QueryResp(vl_EPTF_NS_MgmtIf_msg.queryResp);
    return true;
  }
  if (ischosen(vl_EPTF_NS_MgmtIf_msg.byeAck)) {
    f_EPTF_NS_Client_handle_ByeAck();
    return false; // exit
  }
  //log("ERROR:","Unexpected message received from ",vl_EPTF_NS_MgmtIf_msg_sender,": ",vl_EPTF_NS_MgmtIf_msg);
  f_EPTF_NameServiceClient_warning(log2str("Unexpected message received from ",vl_EPTF_NS_MgmtIf_msg_sender,": ",vl_EPTF_NS_MgmtIf_msg));
  return false;
}

private altstep as_handle_EPTF_NS_Client_QueryResp(out EPTF_NS_QueryResp pl_queryResp) runs on EPTF_NS_Client_CT {
  var EPTF_NS_MgmtMsg vl_EPTF_NS_MgmtIf_msg;
  var EPTF_NS_CT vl_EPTF_NS_MgmtIf_msg_sender;
  [] EPTF_NS_Client_MgmtIf.receive(EPTF_NS_MgmtMsg:{queryResp:={?,*,*}}) -> value vl_EPTF_NS_MgmtIf_msg sender vl_EPTF_NS_MgmtIf_msg_sender {
    f_EPTF_NS_handle_QueryResp(vl_EPTF_NS_MgmtIf_msg.queryResp);
    pl_queryResp := vl_EPTF_NS_MgmtIf_msg.queryResp;
  }
}


// MAIN ALTSTEP
private altstep as_handle_main_EPTF_NS_Client_MgmtIf() runs on EPTF_NS_Client_CT {
  var EPTF_NS_MgmtMsg vl_EPTF_NS_MgmtIf_msg;
  var EPTF_NS_CT vl_EPTF_NS_MgmtIf_msg_sender;
  [] EPTF_NS_Client_MgmtIf.receive(?) -> value vl_EPTF_NS_MgmtIf_msg sender vl_EPTF_NS_MgmtIf_msg_sender {
    if (f_handle_main_EPTF_NS_Client_MgmtIf(vl_EPTF_NS_MgmtIf_msg,vl_EPTF_NS_MgmtIf_msg_sender)) {repeat;}
  }
}

///////////////////////////////////////////////////////////
// Group: Private
//
// Purpose:
//   Private functions. These functions must not be called by the user of <EPTF_NameService_CT>
//
// Elements:
///////////////////////////////////////////////////////////

group Private {
group Logging {

  ///////////////////////////////////////////////////////////
  //  Function: f_EPTF_NameServiceClient_error
  // 
  //  Purpose:
  //    Function to log an error from NameServiceClient feature.
  //
  //  Parameters:
  //    - pl_message - *in* *charstring* - the message to log
  //
  //  Return Value:
  //    -
  //
  //  Errors & assertions:
  //    - 
  //
  //  Detailed Comments:
  //    -
  //
  ///////////////////////////////////////////////////////////
  private function f_EPTF_NameServiceClient_error(in charstring pl_message)
  runs on EPTF_NS_Client_CT
  {
    f_EPTF_Logging_error(true, tsp_EPTF_NameServiceClient_loggingComponentMask&": "&pl_message);
    f_EPTF_Base_stopAll();
  }
  
  ///////////////////////////////////////////////////////////
  //  Function: f_EPTF_NameServiceClient_warning
  // 
  //  Purpose:
  //    Function to log a warning from NameServiceClient feature.
  //
  //  Parameters:
  //    - pl_message - *in* *charstring* - the message to log
  //
  //  Return Value:
  //    -
  //
  //  Errors & assertions:
  //    - 
  //
  //  Detailed Comments:
  //    -
  //
  ///////////////////////////////////////////////////////////
  private function f_EPTF_NameServiceClient_warning(in @lazy charstring pl_message)
  runs on EPTF_NS_Client_CT
  {
    f_EPTF_Logging_warningV2(pl_message, v_NameServiceClient_loggingMaskId, {c_EPTF_NameService_loggingClassIdx_Warning});
  }
  
  ///////////////////////////////////////////////////////////
  //  Function: f_EPTF_NameServiceClient_debug
  // 
  //  Purpose:
  //    Function to log a debug message from NameServiceClient feature.
  //
  //  Parameters:
  //    - pl_message - *in* *charstring* - the message to log
  //
  //  Return Value:
  //    -
  //
  //  Errors & assertions:
  //    - 
  //
  //  Detailed Comments:
  //    -
  //
  ///////////////////////////////////////////////////////////
  private function f_EPTF_NameServiceClient_debug(in @lazy charstring pl_message)
  runs on EPTF_NS_Client_CT
  {
    f_EPTF_Logging_debugV2(pl_message, v_NameServiceClient_loggingMaskId, {c_EPTF_NameService_loggingClassIdx_Debug});
  }
  
  ///////////////////////////////////////////////////////////
  //  Function: f_EPTF_NameService_debugEnabled
  // 
  //  Purpose:
  //    Function to check if debug is enabled for NameService
  //
  //  Parameters:
  //    -
  //
  //  Return Value:
  //    *boolean* - true if debug enalbed
  //
  //  Errors & assertions:
  //    - 
  //
  //  Detailed Comments:
  //    -
  //
  ///////////////////////////////////////////////////////////
  private function f_EPTF_NameServiceClient_debugEnabled()
  runs on EPTF_NS_Client_CT
  return boolean
  {
    return f_EPTF_Logging_isEnabled(v_NameServiceClient_loggingMaskId, c_EPTF_NameService_loggingClassIdx_Debug);
  }
} // group Logging

} // group Private


} // end of module