/*
 *  Copyright (C) 2018 Eduardo Zarate Lasurtegui
 *  Copyright (C) 2018, University of the Basque Country (UPV/EHU)
 *
 * Contact for licensing options: <licensing-mcpttclient(at)mcopenplatform(dot)com>
 *
 * This file is part of MCOP MCPTT Client
 *
 * This is free software: you can redistribute it and/or modify it under the terms of
 * the GNU General Public License as published by the Free Software Foundation, either version 3
 * of the License, or (at your option) any later version.
 *
 * This is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
package org.mcopenplatform.muoapi;

import org.mcopenplatform.muoapi.IMCOPCallback;

/**
 * AIDL definition {@link https://developer.android.com/guide/components/aidl.html}
 * Used as a callback for MCOP SDK server-client communication, and for MCPTT (Mission Critical Push to Talk) Services.
 * @author Eduardo Zarate Lasurtegui
 * @version 0.1
 */
interface IMCOPsdk {
    /**
     * Allows to synchronously get the capabilities from the different MCPTT SDK plugins.
     * @return Returns an structure with all the capabilities.
     * @throws android.os.RemoteException
     */
    String getMCOPCapabilities();


    boolean loginMCOP();

    /**
     * This method starts the MCPTT System unLogin procedure.
     * No input parameters.
     * In case of re-execution it restarts the unlogin procedure.
     *
     * @return  Indicates if the unLogin procedure can be started.
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.AuthorizationRequestExtras org.mcopenplatform.muoapi.ConstantsMCOP.AuthorizationRequestExtras (Definition of all the asynchronous response values of this method)
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.AuthorizationRequestExtras org.mcopenplatform.muoapi.ConstantsMCOP.LoginEventExtras (Definition of all the asynchronous response values of this method and the errors)
     *
     */
     boolean unLoginMCOP();

     /**
     * Once the authentication procedure has been carried out against a third party,
     * this method must be called to continue with the Login process started
     * with loginMCOP() method, defined in this AIDL.
     *
     * Before making the call to this method, the client must use the "request uri", obtained in the callback "org.mcopenplatform.muoapi.ConstantsMCOP.ActionsCallBack.authorizationRequestEvent",
     * to authenticate against a third party, so that the SDK can verify the authentication with the "url" input parameter.
     *
     * @return  Indicates if the Login procedure can be started.
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.AuthorizationRequestExtras org.mcopenplatform.muoapi.ConstantsMCOP.AuthorizationRequestExtras (Definition of all the asynchronous response values of this method and the errors)
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.AuthorizationRequestExtras org.mcopenplatform.muoapi.ConstantsMCOP.LoginEventExtras (Definition of all the asynchronous response values of this method and the errors)
     * @param url. String with URL format where the parameters are indicated so that the SDK can authenticate the user.
     */
    boolean authorizeUser(String url);

    /**
     *
     * Method to make MCPTT type calls. Allowed call types are limited.
     * MCPTT services that a call can contain are listed in {@link org.mcopenplatform.muoapi.ConstantsMCOP.CallTypeEnum}
     *
     * @return Indicates whether the make call procedure could be started. In case of invalid MCPTT session, FALSE is returned.
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.CallTypeEnum org.mcopenplatform.muoapi.ConstantsMCOP.CallTypeEnum (Definition of the MCPTT Services a call may contain)
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.CallEventExtras org.mcopenplatform.muoapi.ConstantsMCOP.CallEventExtras (Definition of the different asynchronous responses this method can have through the callback)
     * @param userID. String to identify the MCOP system user or group to call. If no identity is indicated, the selected contact will be called.
     * @param callType. Integer that contains a series of FLAGs indicating the services for the new MCPTT session.
     */
    boolean makeCall(String userID, int callType);

    /**
     * Hang up an incoming, established or initiated MCPTT session.
     * @param sessionID. Identifier of the specific MCPTT session where the specific action is carried out.
     * @return Indicates whether the desired operation can be started.
     * @throws android.os.RemoteException
     */
    boolean hangUpCall(String sessionID);

    /**
     * Accept an incoming MCPTT sesion.
     * @param sessionID. Identifier of the specific MCPTT session where the specific action is carried out.
     * @return Indicates whether the desired operation can be started.
     * @throws android.os.RemoteException
     */
    boolean acceptCall(String sessionID);

    /**
     * Update the emergency state of a particular session.
     * @param sessionID. Identifier of the specific MCPTT session to be updated.
     * @param emergencyType. New emergency state of the session. It must be type {@link org.mcopenplatform.muoapi.ConstantsMCOP.EmergencyTypeEnum}
     * @return Indicates whether the desired operation can be started.
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.EmergencyTypeEnum
     * @throws android.os.RemoteException
     */
    boolean updateEmergencyState(String sessionID, int emergencyType);

    /**
     * Perform floor control operations over MCPTT sessions.
     * @param sessionID Identifier of the specific MCPTT session where the specific action is carried out.
     * @param requestType Type of action to be performed. It must be type {@link org.mcopenplatform.muoapi.ConstantsMCOP.FloorControlEventExtras.FloorControlOperationTypeEnum}
     * @param UserID To be used in Video sessions, indicating the specific user to receive video from.
     * @return Indicates whether the desired operation can be started.
     * @throws android.os.RemoteException
     */
    boolean floorControlOperation(String sessionID, int requestType, String UserID);

    /**
     * Requests group information to the SDK,
     * generating a type {@link org.mcopenplatform.muoapi.ConstantsMCOP.ActionsCallBack#groupInfoEvent} event callback.
     * @return Indicates whether the desired operation can be started.
     * @throws android.os.RemoteException
     */
    boolean updateGroupsInfo();

    /**
     * Requests group affiliation information to the SDK,
     * generating a type {@link org.mcopenplatform.muoapi.ConstantsMCOP.ActionsCallBack#groupAffiliationEvent} event callback.
     * @return Indicates whether the desired operation can be started.
     * @throws android.os.RemoteException
     */
    boolean updateGroupsAffiliation();

    /**
     * Perform a group affiliation operation.
     * @param groupMcpttId. Unequivocally identifies the group on which the operation is carried out. The group list will be received in the event {@link ConstantsMCOP.ActionsCallBack#groupAffiliationEvent}
     * @param affiliationOperation. Operation to perform on the indicated group. Allowed actions: {@link org.mcopenplatform.muoapi.ConstantsMCOP.GroupAffiliationEventExtras.AffiliationOperationTypeEnum}.
     * @return Indicates whether the desired operation can be started.
     * @See org.mcopenplatform.muoapi.ConstantsMCOP.GroupAffiliationEventExtras
     * @throws android.os.RemoteException
     */
    boolean groupAffiliationOperation(String groupMcpttId, int affiliationOperation);

    /**
     * Select default contact (user or group).
     * @param groupID. Unequivocal identifier of the MCPTT group defined for default MCPTT sessions.
     * @return Indicates whether the desired operation can be started.
     * @See org.mcopenplatform.muoapi.ConstantsMCOP.SelectedContactChangeEventExtras
     * @throws android.os.RemoteException
     */
    boolean changeSelectedContact(String groupID);

     /**
     * Register the callback defined by AIDL so that the SDK can send asynchronous events to the user.
     * @param mcopCallBack. Callback where the different events are sent.
     * @return Indicates whether the desired operation can be started.
     * @see org.mcopenplatform.muoapi.ConstantsMCOP.ActionsCallBack
     * @throws android.os.RemoteException
     */
    boolean registerCallback(IMCOPCallback mcopCallBack);
}