/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2011 Raritan Inc. All rights reserved.
 */

#ifndef __EVENT_SERVICE_IDL__
#define __EVENT_SERVICE_IDL__

#include<Event.idl>

/** Event interface */
module event {

    /// @cond
    /**
     * Consumer interface is for event consumers that want to be
     * called back in case new events have occured. Subscription
     * with this interface happens in Channel interface.
     * Note that this interface cannot be used over transports that 
     * do not support callbacks.
     *
     * Not available via JSON-RPC.
     */
    interface Consumer {

	/**
	 * This method is called by EventService to notify Consumer
	 * about new events. Consumer is not supposed to block this
	 * function but return immidiately. Policy of how often and
	 * with how many events this method is called is up to the
	 * EventService Implementation.
	 */
	void pushEvents(in vector<idl.Event> events);
	
    };
    /// @endcond

    /** Event Channel */
    interface Channel_1_0_1 {

	/* --- filter interface --- */

        /**
         * Subscribe for events of a given type.
         *
         * @param evttype typecode of valueobject of demanded event
         */
        void demandEventType(in typecode type);

	/**
         * Cancel the subscription for events of a given type.
         *
         * @param evttype typecode of valueobject of demanded event
         */
        void cancelEventType(in typecode type);

        /**
         * Subscribe for multiple event types at once.
         *
         * @param evttypes  List of event typecodes
         */
        void demandEventTypes(in vector<typecode> types);

        /**
         * Cancel subscription for events that are of any of given types.
         *
         * @param evttypes  List of event typecodes
         */
        void cancelEventTypes(in vector<typecode> types);

        /**
         * Subscribe for events that are of given type and emitted by a
         * specific object instance.
         *
         * @param evttype  %Event typecode
         * @param src      %Event source instance
         */
        void demandEvent(in typecode type, in Object src);

        /**
         * Cancel the subscription for events that are of given type and
         * emitted by a specific object instance.
         *
         * @param evttype  %Event typecode
         * @param src      %Event source instance
         */
        void cancelEvent(in typecode type, in Object src);

	/**
	 * Structure to select an Event *
	 */
	structure EventSelect {
	    typecode type;
	    Object src;
	};
	
        /**
         * Subscribe for multiple specific events at once.
         *
         * @param events  List of typecodes to subscribe for
         */
        void demandEvents(in vector<EventSelect> events);

        /**
         * Cancel the subscription for multiple specific events.
         *
         * @param events  List of typecodes to unsubscribe from 
         */
        void cancelEvents(in vector<EventSelect> events);
	

	/// @cond
	/* --- push interface --- */

	/**
	 * Subsribe for push notifications from EventService.
	 *
	 * Not available via JSON-RPC.
	 *
	 * @param consumer interface on which subscriber is called back.
	 */
	void subscribe(in Consumer consumer);

	/**
	 * Unsubscribe from  push notifications from EventService.
	 *
	 * Not available via JSON-RPC.
	 *
	 * @param consumer interface which was used for the subscription.
	 * @return 0 if OK
	 *         1 if consumer is unknown to channel
	 */
	int unsubscribe(in Consumer consumer);
	/// @endcond

	
	/* --- poll interface --- */

	/**
	 * Poll for new events blockingly.
	 *
	 * This method will block in case the queue is empty. It will return
	 * as soon as at least one event is available, or after a maximum
	 * wait time of 30 seconds.
	 *
	 * The method will not return more than an implementation-defined
	 * maximum number of events. The boolean return value indicates
	 * whether there are more events in the queue.
	 *
	 * @param events List of new events
	 * @return \c true if there are more events in the queue
	 *         \c false if the queue is empty
	 */
	boolean pollEvents(out vector<idl.Event> events);

	/**
	 * Poll for new events non-blockingly.
	 *
	 * The method will not return more than an implementation-defined
	 * maximum number of events. The boolean return value indicates
	 * whether there are more events in the queue.
	 *
	 * @param events List of new events
	 * @return \c true if there are more events in the queue
	 *         \c false if the queue is empty
	 */
	boolean pollEventsNb(out vector<idl.Event> events);

    };

    /** Event Service */
    interface Service_1_0_1 {

	constant int INVALID_CHANNEL = 1;
	
	/**
	 * Create a new event channel.
	 *
	 * @return New event channel reference
	 *         or nil if all channels have been used
	 */
	Channel_1_0_1 createChannel();

	/**
	 * Destroy an event channel.
	 *
	 * @param channel  %Event channel reference
	 * @return 0 if OK
	 * @return INVALID_CHANNEL if channel is not implemented by this Service
	 */
	int destroyChannel(in Channel_1_0_1 channel);

	/**
	 * Push an Event into the service and to all existing
	 * receiver channels
	 */
	void pushEvent(in idl.Event event);

	/**
	 * Push a vector of Events into the service and to all existing
	 * receiver channels
	 */
	void pushEvents(in vector<idl.Event> events);

    };

}

#endif
