src/EPTF_COAP_Transport_Definitions.ttcn

///////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000-2021 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
///////////////////////////////////////////////////////////////////////////////
//  File:               EPTF_COAP_Transport_Definitions.ttcn
//  Description:
//  Rev:                R1B
//  Prodnr:             CNL 113 858
//  Updated:            2020-02-03
//  Contact:            http://ttcn.ericsson.se
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////
//  Module: EPTF_COAP_Transport_Definitions
// 
//  Purpose:
//    This module contains the generic transport definitions of the COAP load generator
//
//  Component Diagram:
//    (see EPTF_COAP_Transport_Definitions.components.jpg)
//
//  See also:
//    - <EPTF_COAP_LGen_Definitions>
//    - <EPTF_COAP_Transport_User_CT>
//    - <EPTF_COAP_Transport_Provider_CT>
///////////////////////////////////////////////////////////////
/*****************************************************************
 @startuml EPTF_COAP_Transport_Definitions.components.jpg
   package "EPTF_COAP_Transport_Definitions" {
     class EPTF_COAP_Transport_User_CT {
       fcb_EPTF_COAP_Transport_sendMessage vf_EPTF_COAP_Transport_send
       fcb_EPTF_COAP_Transport_apiRequest vf_EPTF_COAP_Transport_apiRequest
     }
     class EPTF_COAP_Transport_Provider_CT {
       fcb_EPTF_COAP_Transport_receiveMessage vf_EPTF_COAP_Transport_receiveMessage
       fcb_EPTF_COAP_Transport_receiveEvent fcb_EPTF_COAP_Transport_receiveEvent
       fcb_EPTF_COAP_Transport_apiResponse vf_EPTF_COAP_Transport_apiResponse
     }
     EPTF_COAP_Transport_Provider_CT <-> EPTF_COAP_Transport_User_CT
  }
 @enduml
******************************************************************/
module EPTF_COAP_Transport_Definitions
{
  import from CoAP_Types all;
  import from IPL4asp_Types all;

  ///////////////////////////////////////////////////////////
  //  Type: fcb_EPTF_COAP_Transport_receiveMessage
  //
  //  Purpose:
  //    Call-back function type for reporting received <EPTF_COAP_PDU> COAP message
  //
  //  Elements:
  //    pl_message  - *in* <EPTF_COAP_PDU> - received COAP message
  ///////////////////////////////////////////////////////////
  type function fcb_EPTF_COAP_Transport_receiveMessage(in EPTF_COAP_PDU pl_message) runs on self;

  ///////////////////////////////////////////////////////////
  //  Type: fcb_EPTF_COAP_Transport_receiveEvent
  //
  //  Purpose:
  //    Call-back function type for reporting received <ASP_Event> COAP event
  //
  //  Elements:
  //    p_event  - *in* <ASP_Event> - received COAP event
  ///////////////////////////////////////////////////////////
  type function fcb_EPTF_COAP_Transport_receiveEvent(in ASP_Event p_event) runs on self;

  ///////////////////////////////////////////////////////////
  //  Type: fcb_EPTF_COAP_Transport_sendMessage
  //
  //  Purpose:
  //    Call-back function type for sending a <EPTF_COAP_PDU> COAP message
  //
  //  Elements:
  //    pl_msg  - *in* <EPTF_COAP_PDU> - COAP message to be sent
  ///////////////////////////////////////////////////////////
  type function fcb_EPTF_COAP_Transport_sendMessage(in EPTF_COAP_PDU pl_msg) runs on self;

  ///////////////////////////////////////////////////////////
  //  Type: fcb_EPTF_COAP_Transport_apiRequest
  //
  //  Purpose:
  //    Call-back function type for sending a <EPTF_COAP_Transport_Request> COAP transport request
  //
  //  Elements:
  //    pl_req  - *in* <EPTF_COAP_Transport_Request> - COAP transport request to be sent
  ///////////////////////////////////////////////////////////
  type function fcb_EPTF_COAP_Transport_apiRequest(in EPTF_COAP_Transport_Request pl_req) runs on self;

  ///////////////////////////////////////////////////////////
  //  Type: fcb_EPTF_COAP_Transport_apiResponse
  //
  //  Purpose:
  //    Call-back function type for reporting a <EPTF_COAP_Transport_Response> COAP transport response
  //
  //  Elements:
  //    pl_rsp  - *in* <EPTF_COAP_Transport_Response> - COAP transport response to be reported
  ///////////////////////////////////////////////////////////
  type function fcb_EPTF_COAP_Transport_apiResponse(in EPTF_COAP_Transport_Response pl_rsp) runs on self;

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_PDU
  //
  //  Purpose:
  //    Encapsulates a COAP PDU with the corresponding entity (and FSM) indices and transport information
  //
  //  Elements:
  //    pdu - <CoAP_ReqResp> - COAP PDU
  //    transportParams - <EPTF_COAP_TransportParameters> - transport protocol information
  //    eIdx - *integer* - entity index
  //    fsmIdx - *integer* - fsm index
  ///////////////////////////////////////////////////////////
  type record EPTF_COAP_PDU
  {
    CoAP_ReqResp                  pdu,
    EPTF_COAP_TransportParameters transportParams,
    integer                       eIdx,
    integer			  fsmIdx
  }
  
  
  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport
  //
  //  Purpose:
  //    Defines the COAP transport layer (union)
  //
  //  Elements:
  //    nidd - *boolean* - Non-IP Data Delivery selected (NIDD)
  //    ip - <ProtoTuple> - IP transport selected
  ///////////////////////////////////////////////////////////
  type union EPTF_COAP_Transport
  {
    boolean    nidd,
    ProtoTuple ip
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_TransportParameters
  //
  //  Purpose:
  //    Encapsulates COAP transport protocol information
  //
  //  Elements:
  //    localAddress - <Socket> - local address and local port
  //    remoteAddress - <Socket> - remote address and remote port
  //    transport - <EPTF_COAP_Transport> - transport protocol description
  ///////////////////////////////////////////////////////////
  type record EPTF_COAP_TransportParameters
  {
    Socket      localAddress,
    Socket      remoteAddress,
    EPTF_COAP_Transport  transport
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_Request
  //
  //  Purpose:
  //    API exposed for requesting transport operation from the <EPTF_COAP_Transport_Provider_CT>
  //
  //  Elements:
  //    eIdx - *integer* - entity index
  //    fsmIdx - *integer* - fsm index
  //    params - <EPTF_COAP_Transport_RequestParams> - details of the transport request
  //
  //  Related Types:
  //    <fcb_EPTF_COAP_Transport_apiRequest>
  ///////////////////////////////////////////////////////////
  type record EPTF_COAP_Transport_Request
  {
    integer eIdx,
    integer fsmIdx,
    EPTF_COAP_Transport_RequestParams params optional
  }

  const EPTF_COAP_Transport_Request c_EPTF_COAP_Transport_Request_init :=
  {
    eIdx := -1,
    fsmIdx := -1,
    params := omit
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_RequestParams
  //
  //  Purpose:
  //    A union encapsulating various transport requests
  //
  //  Elements:
  //    startListening - <EPTF_COAP_Transport_startListening> - request for initializing a listening socket
  //    startDTLS - <EPTF_COAP_Transport_dtlsConnect> - request for starting DTLS
  ///////////////////////////////////////////////////////////
  type union EPTF_COAP_Transport_RequestParams
  {
    EPTF_COAP_Transport_startListening startListening,
    EPTF_COAP_Transport_dtlsConnect    startDTLS
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_startListening
  //
  //  Purpose:
  //    Transport request for initializing a listening socket
  //
  //  Elements:
  //    localAddress - <Socket> - local address and local port
  //    protocol - <ProtoTuple> - transport protocol description
  ///////////////////////////////////////////////////////////
  type record EPTF_COAP_Transport_startListening
  {
    Socket localAddress,
    ProtoTuple protocol
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_dtlsConnect
  //
  //  Purpose:
  //    Transport request for starting DTLS
  //
  //  Elements:
  //    localAddress - <Socket> - local address and local port
  //    remoteAddress - <Socket> - remote address and remote port
  //    pskIdentity - *charstring* *optional* - identity for PSK authentication
  //    pskKey - *charstring* *optional* - key for PSK authentication
  ///////////////////////////////////////////////////////////
  type record EPTF_COAP_Transport_dtlsConnect
  {
    Socket localAddress,
    Socket remoteAddress,
    charstring pskIdentity optional,
    charstring pskKey optional
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_Response
  //
  //  Purpose:
  //    API for responding to transport operations to the <EPTF_COAP_Transport_User_CT>
  //
  //  Elements:
  //    succ - *boolean* - indicates if the requested operation was performed succesfully
  //    eIdx - *integer* - entity index
  //    fsmIdx - *integer* - fsm index
  //    params - <EPTF_COAP_Transport_Response> - details of the transport response
  //
  //  Related Types:
  //    <fcb_EPTF_COAP_Transport_apiResponse>
  ///////////////////////////////////////////////////////////
  type record EPTF_COAP_Transport_Response
  {
    boolean succ,
    integer eIdx,
    integer fsmIdx,
    EPTF_COAP_Transport_ResponseParams params optional
  }

  const EPTF_COAP_Transport_Response c_EPTF_COAP_Transport_Response_init :=
  {
    succ := false,
    eIdx := -1,
    fsmIdx := -1,
    params := omit
  }

  ///////////////////////////////////////////////////////////
  //  Type: EPTF_COAP_Transport_ResponseParams
  //
  //  Purpose:
  //    A union encapsulating various transport responses
  //
  //  Elements:
  //    listening - *boolean* - indicates if the request operation was creating a listning socket
  //    transportError - *charstring* - indicates that some transport error occured, the string contains the description
  //    dtlsConnectionClosed - *boolean* - indicates that a DTLS connection was closed or interrupted
  ///////////////////////////////////////////////////////////
  type union EPTF_COAP_Transport_ResponseParams
  {
    boolean listening,
    charstring transportError,
    boolean dtlsConnectionClosed
  }

  /*****************************************************************
   @startuml EPTF_COAP_Transport_Definitions.EPTF_COAP_Transport_Provider_CT.jpg
     class EPTF_COAP_Transport_Provider_CT {
       fcb_EPTF_COAP_Transport_receiveMessage vf_EPTF_COAP_Transport_receiveMessage
       fcb_EPTF_COAP_Transport_receiveEvent fcb_EPTF_COAP_Transport_receiveEvent
       fcb_EPTF_COAP_Transport_apiResponse vf_EPTF_COAP_Transport_apiResponse
     }
   @enduml
  *****************************************************************/
  ///////////////////////////////////////////////////////////
  // Type: EPTF_COAP_Transport_Provider_CT
  //
  // Purpose:
  //   Base component type for a COAP transport realization
  //
  // Class:
  //   (see EPTF_COAP_Transport_Definitions.EPTF_COAP_Transport_Provider_CT.jpg)
  //
  // Variables:
  //   vf_EPTF_COAP_Transport_receiveMessage - <fcb_EPTF_COAP_Transport_receiveMessage> - Function hook for reporting received messages
  //   vf_EPTF_COAP_Transport_receiveEvent - <fcb_EPTF_COAP_Transport_receiveEvent> - Function hook for reporting received events
  //   vf_EPTF_COAP_Transport_apiResponse - <fcb_EPTF_COAP_Transport_apiResponse> - Function hook for reporting transport API responses
  ///////////////////////////////////////////////////////////
  type component EPTF_COAP_Transport_Provider_CT
  {
    var fcb_EPTF_COAP_Transport_receiveMessage  vf_EPTF_COAP_Transport_receiveMessage := null;
    var fcb_EPTF_COAP_Transport_receiveEvent    vf_EPTF_COAP_Transport_receiveEvent := null;
    var fcb_EPTF_COAP_Transport_apiResponse     vf_EPTF_COAP_Transport_apiResponse := null;
  }

  /*****************************************************************
   @startuml EPTF_COAP_Transport_Definitions.EPTF_COAP_Transport_User_CT.jpg
     class EPTF_COAP_Transport_User_CT {
       fcb_EPTF_COAP_Transport_sendMessage vf_EPTF_COAP_Transport_send
       fcb_EPTF_COAP_Transport_apiRequest vf_EPTF_COAP_Transport_apiRequest
     }
   @enduml
  *****************************************************************/
  ///////////////////////////////////////////////////////////
  // Type: EPTF_COAP_Transport_User_CT
  //
  // Purpose:
  //   Base component type for a COAP transport user realization
  //
  // Class:
  //   (see EPTF_COAP_Transport_Definitions.EPTF_COAP_Transport_User_CT.jpg)
  //
  // Variables:
  //   vf_EPTF_COAP_Transport_send - <fcb_EPTF_COAP_Transport_sendMessage> - Function hook for reporting received messages
  //   vf_EPTF_COAP_Transport_apiRequest - <fcb_EPTF_COAP_Transport_apiRequest> - Function hook for reporting received events
  ///////////////////////////////////////////////////////////
  type component EPTF_COAP_Transport_User_CT
  {
    var fcb_EPTF_COAP_Transport_sendMessage     vf_EPTF_COAP_Transport_send := null;
    var fcb_EPTF_COAP_Transport_apiRequest      vf_EPTF_COAP_Transport_apiRequest := null;
  }
}