source: xplra/src/plugin/src/xplra/Protocol.h@ 99:bb320ead601d

// Copyright (c) 2013 by István Váradi

// This file is part of XPLRA, a remote-access plugin for X-Plane

// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:

// 1. Redistributions of source code must retain the above copyright notice, this
//    list of conditions and the following disclaimer.
// 2. Redistributions in binary form must reproduce the above copyright notice,
//    this list of conditions and the following disclaimer in the documentation
//    and/or other materials provided with the distribution.

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
// ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// The views and conclusions contained in the software and documentation are those
// of the authors and should not be interpreted as representing official policies,
// either expressed or implied, of the FreeBSD Project.

#ifndef XPLRA_PROTOCOL_H
#define XPLRA_PROTOCOL_H
//------------------------------------------------------------------------------

#include <inttypes.h>

//------------------------------------------------------------------------------

namespace xplra {

//------------------------------------------------------------------------------

/**
 * Constants and helpers for the protocol.
 */
class Protocol
{
public:
    /**
     * Command: get the value of a single dataref.
     */
    static const uint8_t COMMAND_GET_SINGLE = 0x01;

    /**
     * Command: set the value of a single dataref.
     */
    static const uint8_t COMMAND_SET_SINGLE = 0x02;

    /**
     * Command: get the value of a multiple datarefs.
     */
    static const uint8_t COMMAND_GET_MULTI = 0x03;

    /**
     * Command: set the value of a multiple datarefs.
     */
    static const uint8_t COMMAND_SET_MULTI = 0x04;

    /**
     * Command: register a multiple-data query request
     */
    static const uint8_t COMMAND_REGISTER_GET_MULTI = 0x11;

    /**
     * Command: unregister a multiple-data query request
     */
    static const uint8_t COMMAND_UNREGISTER_GET_MULTI = 0x12;

    /**
     * Command: execute a registered multiple-data query request
     */
    static const uint8_t COMMAND_EXECUTE_GET_MULTI = 0x13;

    /**
     * Command: register a multiple-data update request
     */
    static const uint8_t COMMAND_REGISTER_SET_MULTI = 0x21;

    /**
     * Command: unregister a multiple-data update request
     */
    static const uint8_t COMMAND_UNREGISTER_SET_MULTI = 0x22;

    /**
     * Command: execute a registered multiple-data update request
     */
    static const uint8_t COMMAND_EXECUTE_SET_MULTI = 0x23;

    /**
     * Command: get the versions of the simulator
     */
    static const uint8_t COMMAND_GET_VERSIONS = 0x31;

    /**
     * Command: reload the plugins
     */
    static const uint8_t COMMAND_RELOAD_PLUGINS = 0x32;

    /**
     * Command: save the current situation.
     *
     * Followed by a string containing the path of the file to save
     * relative to the X-System directory.
     */
    static const uint8_t COMMAND_SAVE_SITUATION = 0x33;

    /**
     * Command: show a message in the message window.
     */
    static const uint8_t COMMAND_SHOW_MESSAGE = 0x41;

    /**
     * Command: register a set of hotkeys for the client. Old hotkeys,
     * if any, are forgotten.
     *
     * The command is followed by the following data:
     * - The number of the hotkeys defined (U32).
     * - The code of the hotkeys (U16*number of the hotkeys).
     *   The lower byte is the same as the X-Plane virtual key code
     *   (the same as the ASCII code for numbers and upper-case letters),
     *   the upper one is a logical OR of the HOTKEY_MODIFIER_XXX
     *   codes.
     *
     * The reply consists of a result code only. It may fail with an
     * invalid length code if the number of hotkeys is too large.
     */
    static const uint8_t COMMAND_REGISTER_HOTKEYS = 0x51;

    /**
     * Command: query the hotkeys.
     *
     * The reply consists of a result code, followed by the following
     * data, if the result code is RESULT_OK:
     * - The number of hotkeys defined (U32).
     * - An array of U8 values each being 0 or 1 depending on whether
     *   the corresponding hotkey has been pressed since the last
     *   query (or the registration, whichever is later). The value at
     *   index i corresponds to the hotkey code at index i in the
     *   array passed with COMMAND_REGISTER_HOTKEYS.
     *
     * If not hotkey has been registered, the number of hotkeys is
     * returned as 0.
     */
    static const uint8_t COMMAND_QUERY_HOTKEYS = 0x52;

    /**
     * Command: unregister the previously registered hotkeys.
     *
     * The reply is a result code.
     */
    static const uint8_t COMMAND_UNREGISTER_HOTKEYS = 0x53;

    /**
     * Data type: int
     */
    static const uint8_t TYPE_INT = 0x01;

    /**
     * Data type: float
     */
    static const uint8_t TYPE_FLOAT = 0x02;

    /**
     * Data type: double
     */
    static const uint8_t TYPE_DOUBLE = 0x03;

    /**
     * Data type: float array
     */
    static const uint8_t TYPE_FLOAT_ARRAY = 0x11;

    /**
     * Data type: int array
     */
    static const uint8_t TYPE_INT_ARRAY = 0x12;

    /**
     * Data type: byte array
     */
    static const uint8_t TYPE_BYTE_ARRAY = 0x13;

    /**
     * Result code: no error, everything is OK.
     */
    static const uint8_t RESULT_OK = 0x00;

    /**
     * Result code: invalid command
     */
    static const uint8_t RESULT_INVALID_COMMAND = 0x01;

    /**
     * Result code: unknown dataref
     */
    static const uint8_t RESULT_UNKNOWN_DATAREF = 0x02;

    /**
     * Result code: invalid type
     */
    static const uint8_t RESULT_INVALID_TYPE = 0x03;

    /**
     * Result code: invalid length
     */
    static const uint8_t RESULT_INVALID_LENGTH = 0x04;

    /**
     * Result code: invalid offset
     */
    static const uint8_t RESULT_INVALID_OFFSET = 0x05;

    /**
     * Result code: invalid count
     */
    static const uint8_t RESULT_INVALID_COUNT = 0x06;

    /**
     * Result code: invalid ID
     */
    static const uint8_t RESULT_INVALID_ID = 0x07;

    /**
     * Result code: invalid duration
     */
    static const uint8_t RESULT_INVALID_DURATION = 0x08;

    /**
     * Result code: other error
     */
    static const uint8_t RESULT_OTHER_ERROR = 0xff;

    /**
     * Hotkey modifier: shift
     */
    static const uint16_t HOTKEY_MODIFIER_SHIFT = 0x0100;

    /**
     * Hotkey modifier: control
     */
    static const uint16_t HOTKEY_MODIFIER_CONTROL = 0x0200;

    /**
     * The maximal length we accept (in order to protect ourselves).
     */
    static const int MAX_LENGTH = 2048;

    /**
     * The maximal count of requests in a multiple-data query or
     * update.
     */
    static const size_t MAX_MULTI_COUNT = 1024;

    /**
     * The maximal message duration
     */
    static constexpr float MAX_MESSAGE_DURATION = 5*60;

    /**
     * The maximal number of hotkeys that can be registered for a
     * client.
     */
    static const size_t MAX_HOTKEY_COUNT = 128;

    /**
     * The version of the plugin.
     */
    static const int version = 10;
};

//------------------------------------------------------------------------------

} /* namespace xplra */

//------------------------------------------------------------------------------
#endif // XPLRA_PROTOCOL_H

// Local Variables:
// mode: C++
// c-basic-offset: 4
// indent-tabs-mode: nil
// End: