//tabstop=4
//***********************************************************************
// ORBAsec SL3
// ----------------------------------------------------------------------
// Copyright (C) 2001 Adiron, LLC.
//                    All rights reserved.
// ----------------------------------------------------------------------
// $Id: SL3TCPIP.idl 59039 2004-07-19 08:00:00Z ossama $
//***********************************************************************
#ifndef _SL3TCPIP_IDL_
#define _SL3TCPIP_IDL_
#include <orb.idl>
#include <SL3/SecurityLevel3.idl>
#include <SL3/TransportSecurity.idl>
#include <SL3/SL3AQArgs.idl>

#pragma prefix "adiron.com"

module SL3TCPIP {

    const TransportSecurity::MechanismId       MID_TCPIP  = "TCPIP";

    /**
     * This is the only acquisition mechanism for acquiring TCPIP
     * Transport Credentials.
     */
    const TransportSecurity::AcquisitionMethod AQM_TCPIPArgs = "TCPIPArgs";

    /**
     * An object of this interface is created by the Argument Factory Object.
     * It aids in creating the Credentials Acquisition Argument for
     * TCPIP based Transport Credentials.
     */
    local interface TCPIPArgBuilder : SL3AQArgs::GenericArgBuilder {

        /**
         * This operation adds Transport Credentials CSIv1 protocol
         * version capability.
         * @param support If false, the associated transports will
         *                always be expected to  carry CSIv2 information.
         *                Default is true.
         *                For CSIv2 capability without the ability to
         *                use these credentials for CSIv1 transports, this
         *                argument must be explicitly stated with a value
         *                of false.
         */
        void addSupportCSIv1(
            in boolean support
        );

        /**
         * This operation adds Transport Credentials CSIv2 protocol
         * version capability.
         * @param support If false, the associated transports will
         *                not, or be expected to carry CSIv2 information.
         *                If true, they must, if CSIv1 support is false.
         *                It's default value is false.
         */
        void addSupportCSIv2(
            in boolean support
        );

        /**
         * This operation adds Transport Credentials Initiator Options to
         * the acquisition argument.  This argument is only relevant when
         * the Credentials Usage include Initiate.
         *
         * @param bind This argument contains the interface to which to bind.
         *             An empty string signifies to use the operating system
         *             default.
         * @param low_port  If this argument is 0, the system select the port.
         *                  If this argument is not 0, then connections
         *                  will attempt to bind to this port or higher.
         * @param high_port If low_port is not 0, and this argument is greater
         *                  than or equal to low_port, then the lowest
         *                  available port within the range will be selected.
         * @param timeout   Timeout (in milliseconds) for connection establishment.
         *                  The value 0 indicates an indefinite wait.
         */
        void addTCPIPInitiatorOptions(
            in string bind,      // Interface to bind the socket to.
                                 // If empty, then system selects
            in long   low_port,  // If 0 system selects
            in long   high_port, // Only if low_port != 0, high port >=low_port
                                 // If equal, it binds to that port.
                                 // If greater, it will try for ports within
                                 // the range.
            in long   timeout    // default timeout for connections.
        );

        /**
         * This operation adds Transport Credentials Acceptor Options to
         * the acquisition argument.  This argument is only relevant when
         * the Credentials Usage include Accept.
         *
         * @param hosts     This operation contains a list of "hosts", or
         *                  addresses that should be placed in the IOR of
         *                  objects associated with these credentials.
         * @param bind      This argument contains the interface to which to
         *                  bind. An empty string signifies to use the
         *                  operating system default.
         * @param low_port  If this argument is 0, the system select the port.
         *                  If this argument is not 0, then connections
         *                  will attempt to bind to this port or higher.
         * @param high_port If low_port is not 0, and this argument is greater
         *                  than or equal to low_port, then the lowest
         *                  available port within the range will be selected.
         * @param backlog   Socket Listening Backlog. 0 means use operating
         *                  system default.
         * @param numeric   If this argument is true, all addresses associated
         *                  with these credentials that are placed in IORs
         *                  will be in numeric form.
         */
        void addTCPIPAcceptorOptions(
            in CORBA::StringSeq   hosts,     // If empty, system select
            in string             bind,      // if not empty, must be one of hosts.
            in long               low_port,  // 0 means system select
            in long               high_port, // Only if low_port != 0;
            in long               backlog,   // socket parameter
            in boolean            numeric    // use numeric addresses inIORs?
        );
    };

    /**
     * This interface is used to create the TCPIP Argument Builder
     */
    local interface ArgumentFactory : SL3AQArgs::ArgumentFactory {

        /**
         * This operation creates a TCPIP Transport Security
         * Credentials Acquisition Argument Builder.
         */
        TCPIPArgBuilder createTCPIPArgBuilder(
            in TransportSecurity::CredentialsUsage usage
        );

        /**
         * This operation creates a TaggedArgument containing
         * the following information for acquiring transport
         * credentials with CSIv1 capability turned off or on.
         *
         * @param support. If false, call GIOP requests traveling
         *                 over these transports is expected to
         *                 carry CSIv2 information.
         */
        SL3AQArgs::Argument createSupportCSIv1(
            in boolean support
        );

        /**
         * This operation creates a TaggedArgument containing
         * the following information for acquiring transport
         * credentials with CSIv2 capability turned off or on.
         *
         * @param support. If false, call GIOP requests traveling
         *                 over these transports will not and is
         *                 not expected to carry CSIv2 information.
         */
        SL3AQArgs::Argument createSupportCSIv2(
            in boolean support
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring TCPIP credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the TCPIPArgBuilder.
         *
         * @see TCPIPArgBuilder
         */
        SL3AQArgs::Argument createTCPIPInitiatorOptions(
            in string bind,      // Interface to bind the socket to.
                                 // If empty, then system selects
            in long   low_port,  // If 0 system selects
            in long   high_port, // Only if low_port != 0, high port >=low_port
                                 // If equal, it binds to that port.
                                 // If greater, it will try for ports within
                                 // the range.
            in long   timeout    // default timeout for connections.
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring TCPIP credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the TCPIPArgBuilder.
         *
         * @see TCPIPArgBuilder
         */
        SL3AQArgs::Argument createTCPIPAcceptorOptions(
            in CORBA::StringSeq   hosts,     // If empty, system select
            in string             bind,      // if not empty, must be one of hosts.
            in long               low_port,  // 0 means system select
            in long               high_port, // Only if low_port != 0;
            in long               backlog,   // socket parameter
            in boolean            numeric    // use numeric addresses inIORs?
        );
    };
};

#endif
