/*
   Project: AdunCore

   Copyright (C) 2007 Michael Johnston & Jordi Villa-Freixa

   Author: Michael Johnston

   This application 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 2 of the License, or (at your option) any later version.

   This application 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
   Library General Public License for more details.

   You should have received a copy of the GNU General Public
   License along with this library; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
*/
#ifndef _ADSERVERINTERFACE_
#define _ADSERVERINTERFACE_

/**
\ingroup coreProtocols
Contains methods that AdunCore sends to the AdServer instance it is connected to.
**/

@protocol AdServerInterface <NSObject>
/**
AdunCore processes establish two way communciation with the server using this method.
\param object An interface object which conforms to the AdCommandInterface protocol
\param pid The process identifier of the kernel instance sending the message
*/
- (void) useInterface: (id) object forProcess: (int) pid;
/**
Returns a dictionary containing the
external objects be used in the simulation identified by \e pid
*/
- (bycopy NSDictionary*) externalObjectsForProcess: (int) pid;
/**
Returns the template for the simulation identified by \e pid
*/
- (bycopy NSDictionary*) templateForProcess: (int) pid;
/**
AdunCore processes use this method to send any datasets generated by controllers back
to the interface when they have finished.
\todo Allow return of multiple controller data objects.
*/
- (void) controllerData: (bycopy id) results forProcess: (int) pid;
/**
AdunCore processes use this method to give the interface access to the 
AdSimulationData object representing the simulation output.
\todo Allow return of multiple simulation data objects.
*/
- (void) simulationData: (bycopy id) data forProcess: (int) pid;
/**
AdunCore processes send this messages when they are ready to accept command requests from the server.
This message is only sent when AdunCore is running in interactive mode.
\param pid The process identifier of the simulation that is ready to accept requests.
*/
- (void) acceptingRequests: (int) pid;
/**
Tells the server to close the connection to the process identified by the \e pid arguement. 
This method should be sent to the server by kernel processes when they are about to exit. 
\param pid The process identifier of the process requesting that its connection be closed
\param error An NSError object describing why the process is exiting if it is doing so due to some
internal problem. If not i.e. if it is exiting normally, then this parameter should be nil.
*/
- (void) closeConnectionForProcess: (int) pid error: (bycopy NSError*) error;
@end

#endif
