# Copyright (C) 2006-2012 Mortal Coil Games
# See LICENSE for details.
"""
Interfaces for various server related items.
"""

from mv3d.util.iservice import IDirectoryClient, IRealmClient, IService
from mv3d.util.iservice import ISimulationClient, IAssetClient


class IDirectoryService(IDirectoryClient):
    """
    Maintains directories of various types of items and points to
    the servers on which they are hosted
    """
    def getDirectories(): #@NoSelf
        """
        Return our directories 
        """


    def getDirectory(name): #@NoSelf
        """
        return the directory filed under name (str)
        """



class IRealmService(IRealmClient):
    """
    Provides full access to realms
    """
    def hasRealm(rid): #@NoSelf
        """
        Returns true if we have realm with id rid locallly
        """


    def getRealms(): #@NoSelf
        """
        Returns all the realms hosted by this service
        """


    def addMasterRealm(cg, rid): #@NoSelf
        """
        Create a new realm that we will be
        the master for.
        """



class ISimulationService(ISimulationClient):
    """
    Runs the simulation of objects
    """
    def joinRealms(r): #@NoSelf
        """
        Join a list of realms
        """


    def joinRealm(rid): #@NoSelf
        """
        Join a realm by informing the realm server
        """


    def partRealm(rid): #@NoSelf
        """
        Leave a realm by informing the realm server
        """


    def getLoad(): #@NoSelf
        """
        Give an estimate of the load of this server
        """


    def listContents(con): #@NoSelf
        """
        List all object ids on this server
        """


    def addMasterItem(cg, i): #@NoSelf
        """
        Add a master item to the server
        """


    def addSlaveItem(i): #@NoSelf
        """
        Add i as a slave item.
        """


    def remSlaveItem(iid): #@NoSelf
        """
        Change a slave item to only be a cached item
        Returns a deferred.
        """


    def promoteSlaveItem(i): #@NoSelf
        """
        Promote a slave item to master
        """


    def demoteMasterItem(iid, ns): #@NoSelf
        """
        Demote a master item to a slave
        """


    def getAllInRealm(rid, pris): #@NoSelf
        """
        Return all of our items in the given realm
        """


    def haveItem(i): #@NoSelf
        """
        Check if this server has an item locally.
        """


    def getArea(aid): #@NoSelf
        """
        Get an area (locally)
        """


    def getObject(oid): #@NoSelf
        """
        Get an object (locally)
        """


    def getAreas(priority=None): #@NoSelf
        """
        Get all local areas
        """


    def getObjects(priority=None): #@NoSelf
        """
        Returns all objects based on priority if specified.
        """


    def cacheItem(iid, recursive=False): #@NoSelf
        """
        Locate item by id and cache it from the server it exists on.
        If recursive is True, then also cache the contents of the item if
        they are on a different server.
        """


    def enableItem(i): #@NoSelf
        """
        Enable a single item 
        """


    def disableItem(i): #@NoSelf
        """
        Disable a single item 
        """


    def getRealmInfo(realmid): #@NoSelf
        """
        Returns the name of the realm currently, but could return 
        a dict with a desc and other things (current time/weather/etc).
        """



class IAssetService(IAssetClient):
    """
    Defines the interface for a full featured asset service
    """
    def hasAssetGroup(agid): #@NoSelf
        """
        Check if we have this asset group
        Returns True or False
        """


    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 getAssetGroup(agid): #@NoSelf
        """
        If the asset group is local, then return it
        """


    def remAssetGroup(a): #@NoSelf
        """
        Remove this asset group if it exists and return 1
        else return 0 and do nothing
        """


    def getAssetGroupServers(grpid): #@NoSelf
        """
        Query our directory servers to get
        a bunch of servers that are responsible for
        this group...
        """


    def addMasterAssetGroup(cg, i): #@NoSelf
        """
        Create a new realm that we will be
        the master for.
        """


    def removeMasterAssetGroup(agid): #@NoSelf
        """
        Remove an asset group from this server
        """


    def promoteSlaveAssetGroup(i, om=0): #@NoSelf
        """
        Promote a slave asset group to a master and notify om server
        if defined
        """


    def demoteMasterAssetGroup(i, ns): #@NoSelf
        """
        Demote an asset group from a master to a slave with the
        master being on ns
        """


    def addSlaveAssetGroup(i): #@NoSelf
        """
        Add an asset group as a slave on this service
        """


    def remSlaveAssetGroup(i): #@NoSelf
        """
        Remove an asset group that is marked as a slave
        """


    def listAssetGroups(): #@NoSelf
        """
        Return a list of [id, name] of all asset groups 
        """


    def listAssets(grp, types=[]): #@NoSelf
        """
        Return a list of [id, name, type] of all
        assets in grp. If types is specified,
        the assets returned will be an instance of
        one of the classes in the classgenerators
        specified by types.
        """


    def remAsset(aid): #@NoSelf
        """
        Remove an asset
        """


    def newAsset(con, grpid, cg): #@NoSelf
        """
        Convenience function to create a new asset in a given asset
        group        
        """



class IPersistService(IService):
    """
    Defines the interface for a service which is in charge of persisting data
    to disk.
    """
    def registerSchema(typeName, version, attributeList, force=False): #@NoSelf
        """
        Install new schema into the store. This must be run once on the store
        for each type you expect to store there. typeName must be unique.
        Version is an integer specifying the version number of the type.
        attributeList includes all the schema data to register, and force
        will force registration of that schema.
        """


    def startTransaction(self): #@NoSelf
        """
        Begin a transaction on the store. This will return a transaction ID
        which can be passed to other methods in order to execute operations
        within the same transaction.
        """

    def commitTransaction(self, transactionID): #@NoSelf
        """
        Successfully complete a transaction. Call with the transaction ID that
        was given out in startTransaction.
        """


    def rollbackTransaction(self, transactionID): #@NoSelf
        """
        Revert any changes made during the specified transaction. The
        transaction is closed and the ID is no longer valid after this point.
        """


    def new(typeName, data, transactionID=None): #@NoSelf
        """
        Store a new item. typeName must match a type which has had its
        schema registered with this store.
        """


    def update(typeName, parameters, data, transactionID=None): #@NoSelf
        """
        Update an existing item in the store. Parameters specifies a query
        that will match one or more records to be updated. data includes what
        fields to update and does not necessarily have to include all fields
        in the item. See query for more information on parameters.
        """


    def delete(typeName, parameters, specificVersion=None, transactionID=None): #@NoSelf
        """
        Remove an item or items from the store. As with update, parameters
        specifies a query that will match one or more records which will be
        deleted. If this is not done in a transaction, it can not be undone.
        See query for more information on parameters.
        """


    def query(typeName, parameters, fields=None, transactionID=None): #@NoSelf
        """
        Executes a query to return 0 or more results. If fields is not
        specified, all fields are returned including a version number for
        the schema from which the result came from. When fields is specified,
        results are only returned from the most recent schema version. This is
        because fields in previous schema versions may not be the same.

        parameters is a possibly nested set of 3 length tuples. Each one
        contains (left, operator, right). For boolean operators like and/or,
        left and right should be another 3 length tuple. Example:

        (("name", "=", "'mike'"), " and ", ("age", ">", "20"))


        All items are expected to be in store format already.
        """


class IAccountService(IService):
    """
    Interface for an Account type Service
    """
    def getAccount(account): #@NoSelf
        """
        Add account to this service
        """


    def remAccount(account): #@NoSelf
        """
        Remove account from this service
        """


    def createAccount(username, password, email, groups=None): #@NoSelf
        """
        Create an account on this service with the given
        details
        """


    def buildAccountInfo(acct): #@NoSelf
        """
        Take non confidential stuff from the account and
        spit it back out as a dict
        """


    def getAccountInfo(username): #@NoSelf
        """
        Returns the account info for the given username
        """


    def authenticate(creds): #@NoSelf
        """
        Try to authenticate this account. Raises UnauthorizedLogin
        on failure, returns accountInfo on success.
        """


    def authenticateResponse(session, user, challenge, encData): #@NoSelf
        """
        Validate user's login by decrypting the data
        """


    def createPasswords(user, session): #@NoSelf
        """
        Create random one use passwords for a user
        """


    def getLoginInfo(serverUser, session, authUser, uid): #@NoSelf
        """
        Get the previously generated random passwords for the given
        authUser and uid
        """


    def addPCToAccount(userName, pcid): #@NoSelf
        """
        Add a PC to an account on this service
        """


    def logoutUser(session, userName): #@NoSelf
        """
        Log a user out
        """



class IOverseerService(IService):
    """
    Interface for an overseer service which controls processes on this machine
    """
    def newServer(name, config): #@NoSelf
        """
        Start up a new server process
        """


    def killServer(name): #@NoSelf
        """
        Shuts down the server process with the specified name
        """


class ISubordinateService(IService):
    """
    Slave service to the overseer service. A server will run one or the other.
    """
    def startUpService(name, config): #@NoSelf
        """
        Start a new service on this server.
        """


    def shutDownService(name): #@NoSelf
        """
        Shut down an existing service on this server.
        """


class ILoginService(IService):
    """
    A login service for authenticating accounts.
    """


class ILogService(IService):
    """
    A log service that handles collecting log messages from multiple servers.
    """
    def query(parameters=None, offset=0, limit=None, order=None): #@NoSelf
        """
        Query the log for messages that match the parameters and return up to
        limit starting at offset and sorted by the specified order.
        """


    def log(logMessage): #@NoSelf
        """
        Enter a new log message.
        """