/* $Id$ */
/** @file ai_order.hpp Everything to query and build orders. */
#ifndef AI_ORDER_HPP
#define AI_ORDER_HPP
#include "ai_object.hpp"
#include "ai_error.hpp"
/**
* Class that handles all order related functions.
*/
class AIOrder : public AIObject {
public:
static const char *GetClassName() { return "AIOrder"; }
/**
* All order related error messages.
*/
enum ErrorMessages {
/** Base for all order related errors */
ERR_ORDER_BASE = AIError::ERR_CAT_ORDER << AIError::ERR_CAT_BIT_SIZE,
/** No more space for orders */
ERR_ORDER_TOO_MANY, // [STR_8831_NO_MORE_SPACE_FOR_ORDERS]
/** Destination of new order is to far away from the previous order */
ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION, // [STR_0210_TOO_FAR_FROM_PREVIOUS_DESTINATIO]
};
/**
* Flags that can be used to modify the behaviour of orders.
*/
enum AIOrderFlags {
/** Just go to the station/depot, stop unload if possible and load if needed. */
AIOF_NONE = 0,
/** Transfer instead of deliver the goods; only for stations. */
AIOF_TRANSFER = 1 << 0,
/** Always unload the vehicle; only for stations. Cannot be set when AIOF_FULL_LOAD is set. */
AIOF_UNLOAD = 1 << 1,
/** Wait till the the vehicle is fully loaded; only for stations. Cannot be set when AIOF_UNLOAD is set. */
AIOF_FULL_LOAD = 1 << 2,
/** Service the vehicle when needed, otherwise skip this order; only for depots. */
AIOF_SERVICE_IF_NEEDED = 1 << 2,
/** Do not stop at the stations that are passed when going to the destination. */
AIOF_NON_STOP = 1 << 3,
/** For marking invalid order flags */
AIOF_INVALID = 0xFFFF,
};
/**
* Checks whether the given order id is valid for the given vehicle.
* @param vehicle_id The vehicle to check the order index for.
* @param order_id The order index to check.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @return True if and only if the order_id is valid for the given vehicle.
*/
static bool IsValidVehicleOrder(VehicleID vehicle_id, uint32 order_id);
/**
* Checks whether the given order flags are valid for the given destination.
* @param destination The destination of the order.
* @param order_flags The flags given to the order.
* @return True if and only if the order_flags are valid for the given location.
*/
static bool AreOrderFlagsValid(TileIndex destination, AIOrderFlags order_flags);
/**
* Returns the number of orders for the given vehicle.
* @param vehicle_id The vehicle to get the order count of.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @return The number of orders for the given vehicle or a negative
* value when the vehicle does not exist.
*/
static int32 GetNumberOfOrders(VehicleID vehicle_id);
/**
* Gets the destination of the given order for the given vehicle.
* @param vehicle_id The vehicle to get the destination for.
* @param order_id The order to get the destination for.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
* @return The destination tile of the order.
*/
static TileIndex GetOrderDestination(VehicleID vehicle_id, uint32 order_id);
/**
* Gets the AIOrderFlags of the given order for the given vehicle.
* @param vehicle_id The vehicle to get the destination for.
* @param order_id The order to get the destination for.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
* @return The AIOrderFlags of the order.
*/
static AIOrderFlags GetOrderFlags(VehicleID vehicle_id, uint32 order_id);
/**
* Appends an order to the end of the vehicle's order list.
* @param vehicle_id The vehicle to append the order to.
* @param destination The destination of the order.
* @param order_flags The flags given to the order.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @pre AreOrderFlagsValid(destination, order_flags).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
* @exception AIOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
* @return True if and only if the order was appended.
*/
static bool AppendOrder(VehicleID vehicle_id, TileIndex destination, AIOrderFlags order_flags);
/**
* Inserts an order before the given order_id into the vehicle's order list.
* @param vehicle_id The vehicle to add the order to.
* @param order_id The order to place the new order before.
* @param destination The destination of the order.
* @param order_flags The flags given to the order.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
* @pre AreOrderFlagsValid(destination, order_flags).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
* @exception AIOrder::ERR_ORDER_TOO_FAR_AWAY_FROM_PREVIOUS_DESTINATION
* @return True if and only if the order was inserted.
*/
static bool InsertOrder(VehicleID vehicle_id, uint32 order_id, TileIndex destination, AIOrderFlags order_flags);
/**
* Removes an order from the vehicle's order list.
* @param vehicle_id The vehicle to remove the order from.
* @param order_id The order to remove from the order list.
* @pre AIVehicle::IsValidVehicleOrder(vehicle_id, order_id).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @return True if and only if the order was removed.
*/
static bool RemoveOrder(VehicleID vehicle_id, uint32 order_id);
/**
* Changes the order flags of the given order.
* @param vehicle_id The vehicle to change the order of.
* @param order_id The order to change.
* @param order_flags The new flags given to the order.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
* @pre AreOrderFlagsValid(GetOrderDestination(vehicle_id, order_id), order_flags).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @return True if and only if the order was changed.
*/
static bool ChangeOrder(VehicleID vehicle_id, uint32 order_id, AIOrderFlags order_flags);
/**
* Move an order inside the orderlist
* @param vehicle_id The vehicle to move the orders.
* @param order_id_move The order to move.
* @param order_id_target The target order
* @pre IsValidVehicleOrder(vehicle_id, order_id_move).
* @pre IsValidVehicleOrder(vehicle_id, order_id_target).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @return True if and only if the order was moved.
* @note If the order is moved to a lower place (e.g. from 7 to 2)
* the target order is moved upwards (e.g. 3). If the order is moved
* to a higher place (e.g. from 7 to 9) the target will be moved
* downwards (e.g. 8).
*/
static bool MoveOrder(VehicleID vehicle_id, uint32 order_id_move, uint32 order_id_target);
/**
* Copies the orders from another vehicle. The orders of the main vehicle
* are going to be the orders of the changed vehicle.
* @param vehicle_id The vehicle to copy the orders to.
* @param main_vehicle_id The vehicle to copy the orders from.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @pre AIVehicle::IsValidVehicle(main_vehicle_id).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @exception AIOrder::ERR_ORDER_NO_MORE_SPACE
* @return True if and only if the copying succeeded.
*/
static bool CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
/**
* Shares the orders between two vehicles. The orders of the main
* vehicle are going to be the orders of the changed vehicle.
* @param vehicle_id The vehicle to add to the shared order list.
* @param main_vehicle_id The vehicle to share the orders with.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @pre AIVehicle::IsValidVehicle(main_vehicle_id).
* @exception AIError::ERR_OWNED_BY_ANOTHER_COMPANY
* @return True if and only if the sharing succeeded.
*/
static bool ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
/**
* Removes the given vehicle from a shared orders list.
* @param vehicle_id The vehicle to remove from the shared order list.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @return True if and only if the unsharing succeeded.
*/
static bool UnshareOrders(VehicleID vehicle_id);
};
DECLARE_ENUM_AS_BIT_SET(AIOrder::AIOrderFlags);
#endif /* AI_ORDER_HPP */