//Editor-Info: -*- C++ -*-
//
//Subject: TOVE project / TRS
//
//File: trs.idl
//
//Version: $Revision: 1.1 $
//
//State: $State: Exp $
//
//Date: $Date: 1998/10/06 14:45:14 $
//
//Organisation:
//      Helsinki University of Technology
//      Laboratory of Telecommunications Software and Multimedia
//
//Author: Harri Sunila
//
//Description:
//      Define IDL interface between TOVE Route Service (TRS) client (C++)
//	and TOVE Route Service server/client (Java).
//
//Copyright:
//      Copyright 1999 Helsinki University of Technology
//      ALL RIGHTS RESERVED BETWEEN JANUARY 1996 AND JUNE 1999.
//
//Licence:
//
//
//History: 

#ifndef __TRS_TRS_IDL__
#define __TRS_TRS_IDL__

#include "cause.idl"

module trs
{
    // NSAP / E.164 address is represented as a string
    typedef string Address;

    // Physical link number is an unsigned long integer
    typedef unsigned long LinkNumber;

    typedef sequence<LinkNumber> LinkNumberList;
    
    // The value of a (QoS) parameter
    typedef unsigned long ParameterValue;

    // The (QoS) parameter
    struct Parameter
    {
        string name;                        // name of the parameter
        ParameterValue value;               // value of the parameter    
    };

    // DTL stack (Designated Transit Link) is a sequence of Addresses
    typedef sequence<Address> DTLstack;

    typedef sequence<DTLstack> DTLstackList;
    
    typedef sequence<Parameter> ParameterList;
    
    exception NoRoute // No route to the destination
    {
        unsigned long cause;
    };

    exception InvalidAddress {};    // Address format is invalid

    // Information of a link between two adjacent nodes
    struct Link
    {
        Address destination;     // Address or network to reach via this link
        LinkNumber linkNumber;   // Physical link number 
        ParameterList qosParameters; // Assigned QoS parameters of the link
    };

    typedef sequence<Link> LinkList;
    
    // Information of a node in the network
    struct Node
    {
        Address prefix;  // Prefix of the node
        LinkList links;    // Links to adjacent nodes or hosts
    };

    interface RouteServerCallback
    {
        void routeSelection(in LinkNumberList nextLinks,
                            in DTLstackList dtlStacks,
                            in unsigned long failure);
    };
    
    interface RouteServer
    {
        // Register a node to the route service
        void registerNode(in Node node)
            raises (InvalidAddress);

        // Remove a node from the service
        void unregisterNode(in Node node)
            raises (InvalidAddress);

        // Add new links to an existing node
        void addLinks(in Node node,
                      in LinkList additionalLinks)
            raises (InvalidAddress);
        
        // Remove existing links  from an existing node
        void removeLinks(in Node node,
                         in LinkList removableLinks)
            raises (InvalidAddress);
        
        // Update parameters of existing links in an existing node
        void updateLinks(in Node node,
                         in LinkList updatedlinks)
            raises (InvalidAddress);
        
        // Query for the next link to reach the called party
        oneway void selectRoute(in Address caller,
                                in Address calledParty,
                                in DTLstack dtlStack,
                                in ParameterList qosParameters,
                                in RouteServerCallback callback,
                                in unsigned long numberOfRoutes);
    };
};    

#endif // __TRS_TRS_IDL__