# Copyright (C) 2009-2012 Mortal Coil Games
# See LICENSE for details.
"""
Interfaces for services
"""

from zope.interface import Interface


class IService(Interface):
    """
    The basic interface for a MV3D Service
    """
    def configure(cf): #@NoSelf
        """
        Configure this service using the config object cf
        """


    def getInterface(client, protocol): #@NoSelf
        """
        Returns a valid interface for the given protocol assuming
        the client specified is allowed to get one
        """


    def getName(): #@NoSelf
        """
        Just return the name of the service (from Service)
        """


    def isLocal(): #@NoSelf
        """
        Returns true since this is a local service (feel free to override)
        """



class IIterableService(IService):
    """
    This service needs to be iterated every server tick.
    """
    def iterate(tm): #@NoSelf
        """
        Process one server tick. tm specifies the time that has passed
        in seconds.
        """



class IAssetClient(IService):
    """
    Provides asset retrieval services
    """
    def getAsset(aid, local=False): #@NoSelf
        """
        Get an asset. If the group is local and the asset
        exists, return it. If the group isn't local, connect
        to a server that has it and get it from there before
        returning it.
        """


    def acquireAsset(aid, **kw): #@NoSelf
        """
        Download this asset.
        """



class IDirectoryClient(IService):
    """
    Provides a means of getting information on directory entries
    """
    def getMasterServersFor(nm, i): #@NoSelf
        """
        Looks up i (id) in the directory for nm (str)
        return 0 if not found or other error
        return i's master servers otherwise
        it is possible for this to return a Deferred
        """


    def getSlaveServersFor(nm, i): #@NoSelf
        """
        Looks up i (id) in the directory for nm (str)
        return 0 if not found or other error
        return i's slave servers otherwise
        it is possible for this to return a Deferred
        """


    def getServersFor(nm, i): #@NoSelf
        """
        Looks up i (id) in the directory for nm (str)
        return 0 if not found or other error
        return i's servers otherwise
        it is possible for this to return a Deferred
        """


    def getDirectoryItem(nm, i, lo=False): #@NoSelf
        """
        Get a directory item i from directory nm.
        if lo is True, only look at directories we have. Otherwise,
        Query our directory servers for i in directory nm 
        """



class IRealmClient(IService):
    """
    Provides a means to get information about realms
    """
    def getDirectoryServers(): #@NoSelf
        """
        return all of our directory servers 
        """


    def addDirectoryServer(s): #@NoSelf
        """
        Add a directory server (s = ServiceLoc) 
        """


    def remDirectoryServer(s): #@NoSelf
        """
        Remove a directory server (s=ServiceLoc) 
            if we don't have it, return 0, else 1
        """



    def getRealmServer(realmid): #@NoSelf
        """
        Find the realm server for a given realm
        """


    def getServiceLocsFor(realmid): #@NoSelf
        """
        Get service locations for the given realm
        """


    def getServiceLocFor(realmid): #@NoSelf
        """
        Get master service location for the given realm
        """


    def locateObject(obj, realmid): #@NoSelf
        """
        Find which server an object is on
        """


    def getRealm(realmid, local=False): #@NoSelf
        """
        Try to get a realm locally if we don't have it, cache
        it from the appropriate server and then return that.
        """




class ISimulationClient(IIterableService):
    """
    Provides client access to the simulated objects
    """
    def getItem(iid, local=False, recursive=False): #@NoSelf
        """
        Get an item.
        First try to get the item locally. If it doesn't
        exist on our server, then locate it through the 
        realm server of the realm that it belongs to.
        Once located, cache the object from the server
        and return the local copy.
        
        Always returns a deferred
        """


    def getLocalRealm(realmID): #@NoSelf
        """
        Returns a realm if we have it locally.
        """



class IPlayerClient(IService):
    """
    Handles player interaction from the client side
    """
    def getPCs(): #@NoSelf
        """
        This function will return a deferred, that will
        eventually give you a list of oids that your account
        can use as Players.
        """


    def connectPC(oid): #@NoSelf
        """
        This function will return a deferred that will
        return 0 if the client doesn't have access to use
        oid as a PC. Otherwise, it'll return a PlayerManipulator
        object for that PC which we will store as self.pc
        """


    def do(what, *a, **kw): #@NoSelf
        """
        Execute an action
        """


    def createCharacter(): #@NoSelf
        """
        Tell the server that we would like to create a new player
        character
        """


    def addAction(b): #@NoSelf
        """
        Add an action
        """


    def remAction(nm): #@NoSelf
        """
        Removes an action
        """


    def getActions(): #@NoSelf
        """
        Returns all registered actions
        """


    def getAction(nm): #@NoSelf
        """
        Returns an action with the given name
        """


    def addBinding(n, b): #@NoSelf
        """
        Add an action binding for n
        """


    def getBindingsFor(n): #@NoSelf
        """
        Gets all the bindings for n
        """


    def remBindingsFor(n): #@NoSelf
        """
        Remove all bindings called n
        """


    def remBinding(n, b): #@NoSelf
        """
        Remove an action binding
        """


    def updateLoginServers(): #@NoSelf
        """ 
        This will get a server connection
        and ask it for suggestions of other login
        servers that we can use.. Update the list
        kept by the client with this new info.
        """


    def connectAndSelectPC(): #@NoSelf
        """
        Connect to a server and select and log in as a PC
        """


class IPBServer(IService):
    """
    A twisted perspective broker service provider.
    """


class IConductor(Interface):
    """
    Interface for a conductor
    """