src/script/api/script_cargomonitor.hpp

   1 /* $Id: script_cargomonitor.hpp 24986 2013-02-10 19:49:04Z zuu $ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /** @file script_cargomonitor.hpp Everything to monitor cargo pickup and deliveries by companies. */
  11
  12 #ifndef SCRIPT_CARGO_MONITOR_HPP
  13 #define SCRIPT_CARGO_MONITOR_HPP
  14
  15 #include "script_list.hpp"
  16 #include "script_object.hpp"
  17 #include "script_company.hpp"
  18 #include "../../cargomonitor.h"
  19
  20 /**
  21  * Class that handles all cargo movement monitoring related functions.
  22  *
  23  * To get an understanding of what users are transporting, this class provides cargo pick-up and delivery monitoring functions.
  24  * It works as follows:
  25  * - Select a company, a cargo-type, and an industry that gets the cargo triplet.
  26  * - Perform a call to #GetIndustryDeliveryAmount, setting 'keep_monitoring' to \c true.
  27  *   The return value is not important, but from this moment the program accumulates all deliveries by
  28  *   the given company to the given industry of the given cargo type.
  29  * - Some time later, perform another call to #GetIndustryDeliveryAmount. It returns the accumulated
  30  *   amount of cargo that the company has delivered.
  31  *   The call causes the collected amount to be reset. On the next call you will thus always get the
  32  *   delivered amount since the previous call.
  33  * - When monitoring the deliveries is not interesting any more, set 'keep_monitoring' to \c false.
  34  *   The collecting process that happens between calls is stopped.
  35  *
  36  * In the same way you can monitor town deliveries, and you can monitor pick-up from towns and industries.
  37  * The latter get added at the moment the cargo is delivered. This prevents users from getting credit for
  38  * picking up cargo without delivering it.
  39  *
  40  * The active monitors are saved and loaded. Upon bankruptcy or company takeover, the cargo monitors are
  41  * automatically stopped for that company. You can reset to the empty state with #StopAllMonitoring.
  42  *
  43  * @api game
  44  */
  45 class ScriptCargoMonitor : public ScriptObject {
  46 public:
  47         /**
  48          * Get the amount of cargo delivered to a town by a company since the last query, and update the monitoring state.
  49          * @param company %Company to query.
  50          * @param cargo Cargo type to query.
  51          * @param town_id %Town to query.
  52          * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends.
  53          * @return Amount of delivered cargo of the given cargo type to the given town by the given company since the last call, or
  54          * \c -1 if a parameter is out-of-bound.
  55          */
  56         static int32 GetTownDeliveryAmount(ScriptCompany::CompanyID company, CargoID cargo, TownID town_id, bool keep_monitoring);
  57
  58         /**
  59          * Get the amount of cargo delivered to an industry by a company since the last query, and update the monitoring state.
  60          * @param company %Company to query.
  61          * @param cargo Cargo type to query.
  62          * @param industry_id %Industry to query.
  63          * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends.
  64          * @return Amount of delivered cargo of the given cargo type to the given industry by the given company since the last call, or
  65          * \c -1 if a parameter is out-of-bound.
  66          */
  67         static int32 GetIndustryDeliveryAmount(ScriptCompany::CompanyID company, CargoID cargo, IndustryID industry_id, bool keep_monitoring);
  68
  69         /**
  70          * Get the amount of cargo picked up (and delivered) from a town by a company since the last query, and update the monitoring state.
  71          * @param company %Company to query.
  72          * @param cargo Cargo type to query.
  73          * @param town_id %Town to query.
  74          * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends.
  75          * @return Amount of picked up cargo of the given cargo type to the given town by the given company since the last call, or
  76          * \c -1 if a parameter is out-of-bound.
  77          * @note Amounts of picked-up cargo are added during final delivery of it, to prevent users from getting credit for picking up without delivering it.
  78          */
  79         static int32 GetTownPickupAmount(ScriptCompany::CompanyID company, CargoID cargo, TownID town_id, bool keep_monitoring);
  80
  81         /**
  82          * Get the amount of cargo picked up (and delivered) from an industry by a company since the last query, and update the monitoring state.
  83          * @param company %Company to query.
  84          * @param cargo Cargo type to query.
  85          * @param industry_id %Industry to query.
  86          * @param keep_monitoring If \c true, the given combination continues to be monitored for the next call. If \c false, monitoring ends.
  87          * @return Amount of picked up cargo of the given cargo type to the given industry by the given company since the last call, or
  88          * \c -1 if a parameter is out-of-bound.
  89          * @note Amounts of picked-up cargo are added during final delivery of it, to prevent users from getting credit for picking up without delivering it.
  90          */
  91         static int32 GetIndustryPickupAmount(ScriptCompany::CompanyID company, CargoID cargo, IndustryID industry_id, bool keep_monitoring);
  92
  93         /** Stop monitoring everything. */
  94         static void StopAllMonitoring();
  95 };
  96
  97 #endif /* SCRIPT_CARGO_MONITOR_HPP */