ampCommands.py

# coding=utf-8
from twisted.protocols import amp
from twisted.cred.error import UnauthorizedLogin

from errors import SlotErrorNotification
from errors import BadCredentials

"""
   Copyright 2014, 2015 Xabier Crespo Álvarez

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

:Author:
    Xabier Crespo Álvarez (xabicrespog@gmail.com)
"""
__author__ = 'xabicrespog@gmail.com'


class StartRemote(amp.Command):
    # arguments = [('iSlotId', amp.Integer())]
    response = [('iResult', amp.Integer())]
    errors = {
        SlotErrorNotification: 'SLOT_ERROR_NOTIFICATION'}
    """
    Invoked when a client wants to connect to an N-server. This shall be
    called right after invoking login method.

    :param iSlotId:
        ID number of the slot which should have been previously reserved
        through the web interface.
    :type iSlotId:
        L{int}

    :returns iResult:
        Raises an error if the slot is not available yet or if it isn't
        assigned to the calling client. Otherwise, it may return one of
        the following codes:

        (0) REMOTE_READY: the remote client is already connected to the server
        (-1) CLIENTS_COINCIDE: the remote client is the same as the calling
        client
        (-2) REMOTE_NOT_CONNECTED: indicates if the the remote client is not
        connected

        In case that any of the previous cases are detected, the slotId is
        returned.
    :rtype:
        int or L{SlotNotAvailable}
    """
    # Remote client ready
    REMOTE_READY = 0
    # Both MCC and GSS belong to the same client
    CLIENTS_COINCIDE = -1
    # Remote user not connected yet
    REMOTE_NOT_CONNECTED = -2


class EndRemote(amp.Command):
    arguments = []
    response = [('bResult', amp.Boolean())]
    """
    Invoked by a client whenever this one wants to finalize the
    remote operation.
    """


class SendMsg(amp.Command):
    arguments = [('sMsg', amp.String()),
                 ('iTimestamp', amp.Integer())]
    response = [('bResult', amp.Boolean())]
    errors = {
        SlotErrorNotification: 'SLOT_ERROR_NOTIFICATION'}

    """
    Invoked when a client wants to send a message to a remote entity.
    To use it, the command StartRemote shall be invoked first.

    :param sMsg:
        String containing the message
    :type sMsg:
        L{String}
    :param iDopplerShift:
        Integer indicating the Doppler shift in kHz
    :type iDopplerShift:
        L{int}
    :param iTimestamp:
        Integer indicating the UTC timestamp at reception.
        If the command is called before StartRemote raises SlotNotAvailable.
    :type iTimestamp:
        L{Integer} or L{SlotNotAvailable}

    :returns bResult:
        True if the command is successfully run
    :rtype:
        Boolean
    """

# Commandes implemented by G- or M- clients which will be invoked
# by a N-server.


class NotifyEvent(amp.Command):

    arguments = [('iEvent', amp.Integer()),
                 ('sDetails', amp.String(optional=True))]
    requiresAnswer = False

    """
    Used to inform a client about an event in the network.

    :param iEvent:
        Code indicating the event.There are three cases:

        (-1) REMOTE_DISCONNECTED: notifies when the remote client has
        been disconnected and it is not receiving the messages.
        (-2) SLOT_END: notifies both clients about the slot end
        (-3) END_REMOTE: notifies a client that the remote has finished
        the connection
        (-4) REMOTE_CONNECTED: notifies a client when the remote has just
        connected
    :type iEvent:
        int
    :param sDetails:
        Details of the event. If it is REMOTE_CONNECTED this parameter
        is equal to the username of the remote client. Otherwise the
        parameter is None
    :type sDetails:
        L{String} or None
    """

    # Remote user not connected
    REMOTE_DISCONNECTED = -1
    # Both MCC and GSS belong to the same client
    SLOT_END = -2
    # Remote client finished connection
    END_REMOTE = -3
    # Remote client finished connection
    REMOTE_CONNECTED = -4


class NotifyMsg(amp.Command):

    arguments = [('sMsg', amp.String())]
    response = [('bResult', amp.Boolean())]
    errors = {
        SlotErrorNotification: 'SLOT_ERROR_NOTIFICATION'}

    """
    Used to send a message to a remote client.

    :param sMsg:
        Remote client identification number
    :type sMsg:
        L{String}
    """


class Login(amp.Command):

    arguments = [('sUsername', amp.String()),
                 ('sPassword', amp.String())]
    response = [('bAuthenticated', amp.Boolean())]
    errors = {
        UnauthorizedLogin: 'UNAUTHORIZED_LOGIN',
        BadCredentials: 'BAD_CREDENTIALS',
        NotImplementedError: 'NOT_IMPLEMENTED_ERROR'}

    """
    Command to authenticate an user.  The server response is a boolean
    granting or not the access to the client.

    :param sUsername:
        Client username for the SATNET network
    :type sUsername:
        String
    :param sPassword:
        Plain-text client password for the SATNET network
    :type sPassword:
        String

    :returns bAuthenticated:
        True if the user has been granted access and L{UnauthorizedLogin}
        otherwise.
    :rtype:
        boolean or L{UnauthorizedLogin}
    """