"Fossies" - the Fresh Open Source Software Archive

Member "navit-0.5.6/navit/traffic.h" (6 Mar 2021, 52324 Bytes) of package /linux/privat/navit-0.5.6.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "traffic.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 0.5.5_vs_0.5.6.

    1 /**
    2  * Navit, a modular navigation system.
    3  * Copyright (C) 2005-2017 Navit Team
    4  *
    5  * This program is free software; you can redistribute it and/or
    6  * modify it under the terms of the GNU Library General Public License
    7  * version 2 as published by the Free Software Foundation.
    8  *
    9  * This program is distributed in the hope that it will be useful,
   10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   12  * GNU Library General Public License for more details.
   13  *
   14  * You should have received a copy of the GNU Library General Public
   15  * License along with this program; if not, write to the
   16  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   17  * Boston, MA  02110-1301, USA.
   18  */
   19 
   20 /** @file
   21  *
   22  * @brief Contains exported code for traffic.c, the traffic module
   23  *
   24  * This file contains types and function prototypes exported from the traffic module, which enables
   25  * Navit to route around traffic problems.
   26  *
   27  * The traffic module consists of two parts:
   28  *
   29  * The traffic core interacts with the Navit core and converts traffic messages into traffic
   30  * distortions (future versions may add support for other traffic information).
   31  *
   32  * The traffic backends obtain traffic information from a source of their choice (e.g. from a TMC
   33  * receiver or a network service), translate them into Navit data structures and report them to the
   34  * traffic plugin.
   35  *
   36  * Traffic messages and related structures are considered immutable once created (when information
   37  * changes, the old message is replaced with a new one). For this reason, there are very few data
   38  * manipulation methods. Those that exist are intended for the creation of new messages rather than
   39  * for extensive manipulation.
   40  *
   41  * As a rule, responsibility for freeing up any `traffic_*` instances normally lies with the
   42  * traffic plugin, which frees messages as they expire or are replaced. Since this also frees all child
   43  * data structures, traffic backends will seldom need to call any of the destructors. The only case in
   44  * which this would be necessary is if a backend has instantiated an object which is not going to be
   45  * used (i.e. attached to a parent object or, in the case of `traffic_message`, reported to the
   46  * traffic plugin: these need to be freed up manually by calling the destructor of the topmost object in
   47  * the hierarchy.
   48  *
   49  * Any other references passed in functions (including pointer arrays and `quantifier` instances)
   50  * must be freed up by the caller. This is safe to do as soon as the function returns.
   51  */
   52 
   53 #ifndef NAVIT_TRAFFIC_H
   54 #define NAVIT_TRAFFIC_H
   55 
   56 #ifdef __cplusplus
   57 extern "C" {
   58 #endif
   59 
   60 /**
   61  * @brief Translates a Navit tile order to a minimum road class as used in TraFF.
   62  *
   63  * This can be used to translate a map selection into a TraFF filter.
   64  *
   65  * The tile order is the lowest tile level in which an object of a certain type can be placed (higher numbers
   66  * correspond to lower levels). Currently, 8 is the maximum order for `highway_city`, `highway_land` and
   67  * `street_n_lanes`, equivalent to `MOTORWAY` and `TRUNK`. 10 is the maximum order for `street_4_city` and
   68  * `street_4_land` (`SECONDARY`), 12 for `street_3_city` and `street_3_land` (`TERTIARY`). All others can
   69  * be placed in any tile level.
   70  *
   71  * This macro returns `PRIMARY`, `SECONDARY` and `TERTIARY` for the three bins above these cut-off orders,
   72  * corresponding to one level below the lowest road class we expect to find there. (Not considering that
   73  * low-level roads can be placed into higher-level tiles if they cross a tile boundary of the next lower
   74  * level.) Below the lowest cut-off order, the macro returns NULL.
   75  */
   76 #define order_to_min_road_class(x) (x <= 8 ? "PRIMARY" : x <= 10 ? "SECONDARY" : x <= 12 ? "TERTIARY" : NULL)
   77 
   78 /**
   79  * @brief Classes for events.
   80  */
   81 /* If additional event classes are introduced, traffic_event_is_valid() must be adapted to recognize them. */
   82 enum event_class {
   83     event_class_invalid = 0, /*!< Invalid event which should be ignored */
   84     event_class_congestion,  /*!< Traffic congestion, typically indicating the approximate speed */
   85     event_class_delay,       /*!< Delays, typically indicating the amount of extra waiting time */
   86     event_class_restriction, /*!< Temporary traffic restrictions, such as road or lane closures or size,
   87                               *   weight or access restrictions */
   88 };
   89 
   90 /**
   91  * @brief Event types.
   92  */
   93 /* If additional events are introduced, remember to do the following:
   94  * - If the events belong to an existing class, insert them right after the last existing event for that class.
   95  * - If the events belong to a new class, insert them at the end of the list.
   96  * - Always keep events of the same class together.
   97  * - After adding events (of any class) at the end of the list, adapt traffic_event_is_valid() to recognize them. */
   98 enum event_type {
   99     event_invalid = 0,                                 /*!< Invalid event which should be ignored */
  100     event_congestion_cleared,                          /*!< Traffic congestion cleared */
  101     event_congestion_forecast_withdrawn,               /*!< Traffic congestion forecast withdrawn */
  102     event_congestion_heavy_traffic,                    /*!< Heavy traffic with average speeds of `speed` */
  103     event_congestion_long_queue,                       /*!< Long queues with average speeds of `speed` */
  104     event_congestion_none,                             /*!< No problems to report */
  105     event_congestion_normal_traffic,                   /*!< Traffic has returned to normal */
  106     event_congestion_queue,                            /*!< Queuing traffic with average speeds of `speed` */
  107     event_congestion_queue_likely,                     /*!< Danger of queuing traffic with average speeds
  108                                                         *   of `speed` */
  109     event_congestion_slow_traffic,                     /*!< Slow traffic with average speeds of `speed` */
  110     event_congestion_stationary_traffic,               /*!< Stationary traffic (frequent standstills) */
  111     event_congestion_stationary_traffic_likely,        /*!< Danger of stationary traffic */
  112     event_congestion_traffic_building_up,              /*!< Traffic building up with average speeds of
  113                                                         *   `speed` */
  114     event_congestion_traffic_congestion,               /*!< Traffic congestion with average speeds of
  115                                                         *   `speed` */
  116     event_congestion_traffic_easing,                   /*!< Traffic easing */
  117     event_congestion_traffic_flowing_freely,           /*!< Traffic flowing freely with average speeds
  118                                                         *   of `speed` */
  119     event_congestion_traffic_heavier_than_normal,      /*!< Traffic heavier than normal with average
  120                                                         *   speeds of `speed` */
  121     event_congestion_traffic_lighter_than_normal,      /*!< Traffic lighter than normal with average
  122                                                         *   speeds of `speed` */
  123     event_congestion_traffic_much_heavier_than_normal, /*!< Traffic very much heavier than normal with
  124                                                         *   average speeds of `speed` (increased density
  125                                                         *   but no significant decrease in speed) */
  126     event_congestion_traffic_problem,                  /*!< Traffic problem */
  127     event_delay_clearance,                             /*!< Delays cleared */
  128     event_delay_delay,                                 /*!< Delays up to `q_timespan` */
  129     event_delay_delay_possible,                        /*!< Delays up to `q_timespan` possible */
  130     event_delay_forecast_withdrawn,                    /*!< Delay forecast withdrawn */
  131     event_delay_long_delay,                            /*!< Long delays up to `q_timespan` */
  132     event_delay_several_hours,                         /*!< Delays of several hours */
  133     event_delay_uncertain_duration,                    /*!< Delays of uncertain duration */
  134     event_delay_very_long_delay,                       /*!< Very long delays up to `q_timespan` */
  135     event_restriction_access_restrictions_lifted,      /*!< Traffic restrictions lifted: reopened for all
  136                                                         *   traffic, other restrictions (overtaking etc.)
  137                                                         *   remain in place */
  138     event_restriction_all_carriageways_cleared,        /*!< All carriageways cleared */
  139     event_restriction_all_carriageways_reopened,       /*!< All carriageways reopened */
  140     event_restriction_batch_service,                   /*!< Batch service (to limit the amount of traffic
  141                                                         *   passing through a section, unlike single
  142                                                         *   alternate line traffic) */
  143     event_restriction_blocked,                         /*!< Blocked (refers to the entire road; separate
  144                                                         *   codes exist for blockages of individual lanes
  145                                                         *   or carriageways) */
  146     event_restriction_blocked_ahead,                   /*!< Blocked ahead (at a point beyond the
  147                                                         *   indicated location) */
  148     event_restriction_carriageway_blocked,             /*!< Carriageway blocked (main carriageway, unless
  149                                                         *   otherwise indicated in supplementary information) */
  150     event_restriction_carriageway_closed,              /*!< Carriageway closed (main carriageway, unless
  151                                                         *   otherwise indicated in supplementary information) */
  152     event_restriction_contraflow,                      /*!< Contraflow */
  153     event_restriction_closed,                          /*!< Closed until `q_time` (refers to the entire
  154                                                         *   road; separate codes exist for closures of
  155                                                         *   individual lanes or carriageways) */
  156     event_restriction_closed_ahead,                    /*!< Closed ahead (at a point beyond the indicated
  157                                                         *   location) */
  158     event_restriction_entry_blocked,                   /*!< `q_int` th entry slip road blocked */
  159     event_restriction_entry_reopened,                  /*!< Entry reopened */
  160     event_restriction_exit_blocked,                    /*!< `q_int` th exit slip road blocked */
  161     event_restriction_exit_reopened,                   /*!< Exit reopened */
  162     event_restriction_intermittent_closures,           /*!< Intermittent short term closures */
  163     event_restriction_lane_blocked,                    /*!< `q_int` lanes blocked */
  164     event_restriction_lane_closed,                     /*!< `q_int` lanes closed */
  165     event_restriction_open,                            /*!< Open */
  166     event_restriction_ramp_blocked,                    /*!< Ramps blocked */
  167     event_restriction_ramp_closed,                     /*!< Ramps closed */
  168     event_restriction_ramp_reopened,                   /*!< Ramps reopened */
  169     event_restriction_reduced_lanes,                   /*!< Carriageway reduced from `q_ints[1]` lanes to `q_int[0]`
  170                                                         *   lanes (quantifiers are currently not implemented for this
  171                                                         *   event type) */
  172     event_restriction_reopened,                        /*!< Reopened */
  173     event_restriction_road_cleared,                    /*!< Road cleared */
  174     event_restriction_single_alternate_line_traffic,   /*!< Single alternate line traffic (because the
  175                                                         *   affected stretch of road can only be used in
  176                                                         *   one direction at a time, different from batch
  177                                                         *   service) */
  178     event_restriction_speed_limit,                     /*!< Speed limit `speed` in force */
  179     event_restriction_speed_limit_lifted,              /*!< Speed limit lifted */
  180 };
  181 
  182 /**
  183  * @brief The directionality of a location.
  184  */
  185 enum location_dir {
  186     location_dir_one = 1,  /*!< Indicates a unidirectional location. */
  187     location_dir_both = 2, /*!< Indicates a bidirectional location. */
  188 };
  189 
  190 /**
  191  * @brief The fuzziness of a location.
  192  */
  193 enum location_fuzziness {
  194     location_fuzziness_none = 0,       /*!< No fuzziness information is given. */
  195     location_fuzziness_low_res,        /*!< Locations are constrained to a predefined table; the actual
  196                                         *   extent of the condition may be shorter than indicated. */
  197     location_fuzziness_end_unknown,    /*!< The end is unknown, e.g. a traffic jam reported by a driver
  198                                         *   who has just entered it. */
  199     location_fuzziness_start_unknown,  /*!< The start is unknown, e.g. a traffic jam reported by a driver
  200                                             who has just passed the obstruction which caused it. */
  201     location_fuzziness_extent_unknown, /*!< Start and end are unknown, e.g. a traffic jam reported by a
  202                                             driver who is in the middle of it. */
  203 };
  204 
  205 /**
  206  * @brief Whether a location refers to the main carriageway or the ramps.
  207  */
  208 enum location_ramps {
  209     location_ramps_none = 0, /*!< The location refers to the carriageways of the main road. */
  210     location_ramps_all,      /*!< The location refers to the entry and exit ramps, not the main carriageway. */
  211     location_ramps_entry,    /*!< The location refers to the entry ramps only, not the main carriageway. */
  212     location_ramps_exit,     /*!< The location refers to the exit ramps only, not the main carriageway. */
  213 };
  214 
  215 /**
  216  * @brief Classes for supplementary information items.
  217  */
  218 enum si_class {
  219     si_class_invalid = 0, /*!< Invalid supplementary information item which should be ignored */
  220     si_class_place,       /*!< Qualifiers specifying the place(s) to which the event refers */
  221     si_class_tendency,    /*!< Traffic density development */
  222     si_class_vehicle,     /*!< Specifies categories of vehicles to which the event applies */
  223 };
  224 
  225 /**
  226  * @brief Supplementary information types.
  227  */
  228 enum si_type {
  229     si_invalid = 0,               /*!< Invalid supplementary information item which should be ignored */
  230     si_place_bridge,              /*!< On bridges */
  231     si_place_ramp,                /*!< On ramps (entry/exit) */
  232     si_place_roadworks,           /*!< In the roadworks area */
  233     si_place_tunnel,              /*!< In tunnels */
  234     si_tendency_queue_decreasing, /*!< Traffic queue length decreasing (average rate in optional `q_speed`) */
  235     si_tendency_queue_increasing, /*!< Traffic queue length increasing (average rate in optional `q_speed`) */
  236     si_vehicle_all,               /*!< For all vehicles */
  237     si_vehicle_bus,               /*!< For buses only (TODO currently supported for public buses only) */
  238     si_vehicle_car,               /*!< For cars only */
  239     si_vehicle_car_with_caravan,  /*!< For cars with caravans only (TODO currently not supported) */
  240     si_vehicle_car_with_trailer,  /*!< For cars with trailers only (TODO currently not supported) */
  241     si_vehicle_hazmat,            /*!< For hazardous loads only */
  242     si_vehicle_hgv,               /*!< For heavy trucks only */
  243     si_vehicle_motor,             /*!< For all motor vehicles */
  244     si_vehicle_with_trailer,      /*!< For vehicles with trailers only (TODO currently not supported) */
  245 };
  246 
  247 struct traffic;
  248 struct traffic_priv;
  249 struct traffic_location_priv;
  250 struct traffic_message_priv;
  251 
  252 /**
  253  * @brief Holds all functions a traffic plugin has to implement to be usable
  254  *
  255  * This structure holds pointers to a traffic plugin's functions which navit's core will call
  256  * to communicate with the plugin.
  257  */
  258 struct traffic_methods {
  259     struct traffic_message **(* get_messages)(struct traffic_priv * this_); /**< Retrieves new messages from the traffic plugin */
  260     void (*destroy)(struct traffic_priv * this_);                   /**< Destructor for the traffic plugin */
  261 };
  262 
  263 /**
  264  * @brief A point on the road.
  265  *
  266  * This can either be a point location or an endpoint of a linear location. It specifies a coordinate
  267  * pair and can optionally be supplemented with a junction name and/or number where applicable.
  268  */
  269 struct traffic_point {
  270     struct coord_geo coord; /*!< The coordinates of this point, as supplied by the source. These may
  271                              *   deviate somewhat from the coordinates on the map. */
  272     char * junction_name;   /*!< The name of the motorway junction this point refers to. */
  273     char * junction_ref;    /*!< The reference number of the motorway junction this point refers to. */
  274     char * tmc_id;          /*!< The TMC identifier of the point, if the location was obtained via TMC.
  275                              *   This can be an LCID (12345) or a combination of an LCID and an offset
  276                              *   (12345+2, i.e. an offset of 2 points in positive direction from 12345).
  277                              *   The offset is typically used with the secondary location in TMC. */
  278 };
  279 
  280 /**
  281  * @brief Location data for a traffic message.
  282  *
  283  * Locations can be either point or linear locations.
  284  *
  285  * Linear locations are indicated by a pair of points and refer to a stretch of road. The entire
  286  * location must be part of the same road, i.e. either the road name or the road reference must be the
  287  * same for all affected segments, or all segments must be of the same type and be of a higher order
  288  * than any road connecting to them directly.
  289  *
  290  * Point locations are indicated by a single point, as well as one or two auxiliary points to indicate
  291  * direction. Auxiliary points can be omitted if `tmc_table`, `tmc_direction` and
  292  * `at->tmc_id` are supplied. However, this will only work if the map has accurate TMC data for
  293  * the location, thus it is recommended to supply an auxiliary point nonetheless.
  294  *
  295  * The order of points is as a driver would encounter them, i.e. first `from`, then `at`,
  296  * finally `to`.
  297  */
  298 struct traffic_location {
  299     struct traffic_point * at;         /*!< The point for a point location, NULL for linear locations. */
  300     struct traffic_point * from;       /*!< The start of a linear location, or a point before `at`. */
  301     struct traffic_point * to;         /*!< The end of a linear location, or a point after `at`. */
  302     struct traffic_point * via;        /*!< A point between `from` and `to`. Required on ring roads
  303                                         *   unless `not_via` is used; cannot be used together with `at`. */
  304     struct traffic_point * not_via;    /*!< A point NOT between `from` and `to`. Required on ring roads
  305                                         *   unless `via` is used; cannot be used together with `at`. */
  306     char * destination;                /*!< A destination, preferably the one given on road signs,
  307                                         *   indicating that the message applies only to traffic going in
  308                                         *   that direction. Do not use for bidirectional locations. */
  309     char * direction;                  /*!< A compass direction indicating the direction of travel which
  310                                         *   this location refers to. Do not use where ambiguous. */
  311     enum location_dir directionality;  /*!< Indicates whether the message refers to one or both directions
  312                                         *   of travel. */
  313     enum location_fuzziness fuzziness; /*!< Indicates how precisely the end points are known. */
  314     enum location_ramps ramps;         /*!< Any value other than `location_ramps_none` implies
  315                                         *   that only the specified ramps are affected while the main
  316                                         *   road is not. In that case, the `road*` fields refer to
  317                                         *   the main road served by the ramp, not the ramp itself. This
  318                                         *   is mainly intended for compatibility with TMC, where
  319                                         *   junctions with all their ramps are represented by a single
  320                                         *   point. Other sources should use coordinate pairs instead. */
  321     enum item_type road_type;          /*!< The importance of the road within the road network, must be a
  322                                         *   road item type. Use `line_unspecified` if not known or
  323                                         *   not consistent. */
  324     char * road_name;                  /*!< A road name, if consistent throughout the location. */
  325     char * road_ref;                   /*!< A road number, if consistent throughout the location. */
  326     char * tmc_table;                  /*!< For messages received via TMC, the country identifier (CID)
  327                                         *   and location table number (LTN or TABCD) for the location
  328                                         *   table to be used for location lookup. The CID is the decimal
  329                                         *   number stored in the COUNTRIES and LOCATIONDATASETS tables,
  330                                         *   not the hexadecimal code from the PI (known as CCD in TMC). */
  331     int tmc_direction;                 /*!< For messages received via TMC, the direction of the road to
  332                                         *   which this message applies (positive or negative). Ignored
  333                                         *   for bidirectional messages. */
  334     struct traffic_location_priv * priv; /*!< Internal data, not exposed via the API */
  335 };
  336 
  337 /**
  338  * @brief A quantifier, which can be used with events and supplementary information.
  339  */
  340 /*
  341  * For now, these are various integer types, but other types may be added in the future.
  342  */
  343 struct quantifier {
  344     union {
  345         int q_duration;      /*!< A duration in 1/10 of a second. */
  346         int q_int;           /*!< An integer. */
  347         int q_speed;         /*!< A speed in km/h. */
  348         unsigned int q_time; /*!< A timestamp in epoch time (seconds elapsed since Jan 1, 1970, 00:00 UTC). */
  349     } u;
  350 };
  351 
  352 /**
  353  * @brief Extra information supplied with a traffic event.
  354  */
  355 struct traffic_suppl_info {
  356     enum si_class si_class;       /*!< The supplementary information class (generic category). */
  357     enum si_type type;            /*!< The supplementary information type, which can be mapped to a
  358                                    *   string to be displayed to the user. */
  359     struct quantifier * quantifier; /*!< Additional quantifier for supplementary information types
  360                                    *   allowing this. Data type and meaning depends on the event type. */
  361 };
  362 
  363 /**
  364  * @brief A traffic event.
  365  *
  366  * An event refers to a condition, its cause or its effect.
  367  */
  368 struct traffic_event {
  369     enum event_class event_class;    /*!< The event class (generic category). */
  370     enum event_type type;            /*!< The event type, which can be mapped to a string to be displayed
  371                                       *   to the user. */
  372     int length;                      /*!< The length of the affected route in meters. */
  373     int speed;                       /*!< The speed in km/h at which vehicles can expect to pass through the
  374                                       *   affected stretch of road (either a temporary speed limit or
  375                                       *   average speed in practice, whichever is less), `INT_MAX` if
  376                                       *   not set or unknown. */
  377     struct quantifier * quantifier;  /*!< Additional quantifier for events allowing this. Data type and
  378                                       *   meaning depends on the event type. */
  379     int si_count;                    /*!< Number of supplementary information items in `si_count`. */
  380     struct traffic_suppl_info ** si; /*!< Points to an array of pointers to supplementary information items. */
  381 };
  382 
  383 /**
  384  * @brief A traffic message.
  385  *
  386  * A message is the atomic element of traffic information, referring to a particular condition at a
  387  * given location.
  388  *
  389  * If no updates are received for a message, it should be discarded after both `expiration_time`
  390  * and `end_time` (if specified) have elapsed.
  391  */
  392 struct traffic_message {
  393     char * id;                  /*!< An identifier, which remains stable over the entire lifecycle of the
  394                                  *   message. The colon (:) is a reserved character to separate different
  395                                  *   levels of source identifiers from each other and from the local
  396                                  *   message identifier. */
  397     time_t receive_time;        /*!< When the message was first received by the source, should be kept
  398                                  *   stable across all updates. */
  399     time_t update_time;         /*!< When the last update to this message was received by the source. */
  400     time_t expiration_time;     /*!< How long the message should be considered valid.*/
  401     time_t start_time;          /*!< When the condition is expected to begin (optional, 0 if not set). */
  402     time_t end_time;            /*!< How long the condition is expected to last (optional, 0 if not set). */
  403     int is_cancellation;        /*!< If true, this message is a cancellation message, indicating that
  404                                  *   existing messages with the same ID should be deleted or no longer
  405                                  *   considered current. All other attributes of a cancellation message
  406                                  *   should be ignored. */
  407     int is_forecast;            /*!< If false, the message describes a current situation. If true, it
  408                                  *   describes an expected situation in the future. */
  409     int replaced_count;         /*!< The number of entries in `replaces`. */
  410     char ** replaces;           /*!< Points to an array of identifiers of messages which the current
  411                                  *   message replaces. */
  412     struct traffic_location * location; /*!< The location to which this message refers. */
  413     int event_count;            /*!< The number of events in `events`. */
  414     struct traffic_event ** events; /*!< Points to an array of pointers to the events for this message. */
  415     struct traffic_message_priv * priv; /*!< Internal data, not exposed via the API */
  416 };
  417 
  418 struct map;
  419 struct mapset;
  420 struct traffic;
  421 
  422 /**
  423  * @brief Creates an event class from its string representation.
  424  *
  425  * @param string The string representation (case is ignored)
  426  *
  427  * @return The corresponding `enum event_class`, or `event_class_invalid` if `string` does not match a
  428  * known identifier
  429  */
  430 enum event_class event_class_new(char * string);
  431 
  432 /**
  433  * @brief Translates an event class to its string representation.
  434  *
  435  * @return The string representation of the event class
  436  */
  437 const char * event_class_to_string(enum event_class this_);
  438 
  439 /**
  440  * @brief Creates an event type from its string representation.
  441  *
  442  * @param string The string representation (case is ignored)
  443  *
  444  * @return The corresponding `enum event_type`, or `event_invalid` if `string` does not match a known
  445  * identifier
  446  */
  447 enum event_type event_type_new(char * string);
  448 
  449 /**
  450  * @brief Translates an event type to its string representation.
  451  *
  452  * @return The string representation of the event type
  453  */
  454 const char * event_type_to_string(enum event_type this_);
  455 
  456 /**
  457  * @brief Creates an item type from a road type.
  458  *
  459  * This is guaranteed to return either a routable type (i.e. `route_item_first <= type <= route_item_last`)
  460  * or `type_line_unspecified`. The latter is also returned if `string` refers to a Navit item type which
  461  * is not routable.
  462  *
  463  * @param string A TraFF road type or the string representation of a Navit item type
  464  * @param is_urban Whether the road is in a built-up area (ignored if `string` is a Navit item type)
  465  *
  466  * @return The corresponding `enum item_type`, or `type_line_unspecified` if `string` does not match a
  467  * known and routable identifier
  468  */
  469 enum item_type item_type_from_road_type(char * string, int is_urban);
  470 
  471 /**
  472  * @brief Creates a location directionality from its string representation.
  473  *
  474  * @param string The string representation (case is ignored)
  475  *
  476  * @return The corresponding `enum location_dir`, or `location_dir_both` if `string` does
  477  * not match a known identifier
  478  */
  479 enum location_dir location_dir_new(char * string);
  480 
  481 /**
  482  * @brief Creates a location fuzziness from its string representation.
  483  *
  484  * @param string The string representation (case is ignored)
  485  *
  486  * @return The corresponding `enum location_fuzziness`, or `location_fuzziness_none` if `string` does
  487  * not match a known identifier
  488  */
  489 enum location_fuzziness location_fuzziness_new(char * string);
  490 
  491 /**
  492  * @brief Translates location fuzziness to its string representation.
  493  *
  494  * @return The string representation of the location fuzziness, or NULL for `location_fuzziness_none`
  495  */
  496 const char * location_fuzziness_to_string(enum location_fuzziness this_);
  497 
  498 /**
  499  * @brief Creates an `enum location_ramps` from its string representation.
  500  *
  501  * @param string The string representation (case is ignored)
  502  *
  503  * @return The corresponding `enum location_ramps`, or `location_ramps_none` if `string` does
  504  * not match a known identifier
  505  */
  506 enum location_ramps location_ramps_new(char * string);
  507 
  508 /**
  509  * @brief Translates an `enum location_ramps` to its string representation.
  510  *
  511  * @return The string representation
  512  */
  513 const char * location_ramps_to_string(enum location_ramps this_);
  514 
  515 /**
  516  * @brief Creates a supplementary information class from its string representation.
  517  *
  518  * @param string The string representation (case is ignored)
  519  *
  520  * @return The corresponding `enum si_class`, or `si_class_invalid` if `string` does not match a
  521  * known identifier
  522  */
  523 enum si_class si_class_new(char * string);
  524 
  525 /**
  526  * @brief Translates a supplementary information class to its string representation.
  527  *
  528  * @return The string representation of the supplementary information class
  529  */
  530 const char * si_class_to_string(enum si_class this_);
  531 
  532 /**
  533  * @brief Creates a supplementary information type from its string representation.
  534  *
  535  * @param string The string representation (case is ignored)
  536  *
  537  * @return The corresponding `enum si_type`, or `si_invalid` if `string` does not match a known
  538  * identifier
  539  */
  540 enum si_type si_type_new(char * string);
  541 
  542 /**
  543  * @brief Translates a supplementary information type to its string representation.
  544  *
  545  * @return The string representation of the supplementary information type
  546  */
  547 const char * si_type_to_string(enum si_type this_);
  548 
  549 /**
  550  * @brief Creates a new `traffic_point`.
  551  *
  552  * It is the responsibility of the caller to destroy all references passed to this function. This can be
  553  * done immediately after the function returns.
  554  *
  555  * @param lon The longitude, as reported by the source, in GPS coordinates
  556  * @param lat The latitude, as reported by the source, in GPS coordinates
  557  * @param junction_name The name of the motorway junction this point refers to, NULL if not applicable
  558  * @param junction_ref The reference number of the motorway junction this point refers to, NULL if not applicable
  559  * @param tmc_id The TMC identifier of the point, if the location was obtained via TMC, or NULL if not applicable
  560  */
  561 struct traffic_point * traffic_point_new(float lon, float lat, char * junction_name, char * junction_ref,
  562         char * tmc_id);
  563 
  564 /**
  565  * @brief Creates a new `traffic_point`.
  566  *
  567  * This is the short version of the constructor, which sets only mandatory members. Other members can be
  568  * set after the instance is created.
  569  *
  570  * @param lon The longitude, as reported by the source, in GPS coordinates
  571  * @param lat The latitude, as reported by the source, in GPS coordinates
  572  */
  573 struct traffic_point * traffic_point_new_short(float lon, float lat);
  574 
  575 /**
  576  * @brief Destroys a `traffic_point`.
  577  *
  578  * This will release the memory used by the `traffic_point` and all related data.
  579  *
  580  * A `traffic_point` is usually destroyed together with its parent `traffic_location`, thus
  581  * it is usually not necessary to call this destructor directly.
  582  *
  583  * @param this_ The point
  584  */
  585 void traffic_point_destroy(struct traffic_point * this_);
  586 
  587 /**
  588  * @brief Creates a new `traffic_location`.
  589  *
  590  * The `traffic_point` instances are destroyed when the `traffic_location` is destroyed, and
  591  * therefore cannot be shared between multiple `traffic_location` instances.
  592  *
  593  * It is the responsibility of the caller to destroy all other references passed to this function. This
  594  * can be done immediately after the function returns.
  595  *
  596  * If `at` is non-NULL, the location is a point location, and `from` and `to` are
  597  * interpreted as auxiliary locations.
  598  *
  599  * Of `from` and `to`, one is mandatory for a unidirectional point location; both are
  600  * mandatory for a linear location.
  601  *
  602  * `ramps` is mainly intended for compatibility with TMC, where junctions with all their ramps are
  603  * represented by a single point. Other sources should use coordinate pairs instead.
  604  *
  605  * @param at The coordinates for a point location, NULL for a linear location
  606  * @param from The start of a linear location, or a point before `at`
  607  * @param to The end of a linear location, or a point after `at`
  608  * @param via A point between `from` and `to`, needed only on ring roads
  609  * @param not_via A point not between `from` and `to`, needed only on ring roads
  610  * @param destination A destination, preferably the one given on road signs, indicating that the message
  611  * applies only to traffic going in that direction; can be NULL, do not use for bidirectional locations
  612  * @param direction A compass direction indicating the direction of travel which this location refers to;
  613  * can be NULL, do not use where ambiguous
  614  * @param directionality Whether the location is unidirectional or bidirectional
  615  * @param fuzziness A precision indicator for `from` and `to`
  616  * @param ramps Whether the main carriageway or the ramps are affected
  617  * @param road_type The importance of the road within the road network, must be a road item type,
  618  * `type_line_unspecified` if not known or not consistent
  619  * @param road_name A road name, if consistent throughout the location; NULL if not known or inconsistent
  620  * @param road_ref A road number, if consistent throughout the location; NULL if not known or inconsistent
  621  * @param tmc_table For messages received via TMC, the CID and LTN; NULL otherwise
  622  * @param tmc_direction For messages received via TMC, the direction of the road; ignored for
  623  * bidirectional or non-TMC messages
  624  */
  625 // TODO split CID/LTN?
  626 struct traffic_location * traffic_location_new(struct traffic_point * at, struct traffic_point * from,
  627         struct traffic_point * to, struct traffic_point * via, struct traffic_point * not_via,
  628         char * destination, char * direction, enum location_dir directionality,
  629         enum location_fuzziness fuzziness, enum location_ramps ramps, enum item_type road_type,
  630         char * road_name, char * road_ref, char * tmc_table, int tmc_direction);
  631 
  632 /**
  633  * @brief Creates a new `traffic_location`.
  634  *
  635  * This is the short version of the constructor, which sets only mandatory members. Other members can be
  636  * set after the instance is created.
  637  *
  638  * The `traffic_point` instances are destroyed when the `traffic_location` is destroyed, and
  639  * therefore cannot be shared between multiple `traffic_location` instances.
  640  *
  641  * If `at` is non-NULL, the location is a point location, and `from` and `to` are
  642  * interpreted as auxiliary locations.
  643  *
  644  * Of `from` and `to`, one is mandatory for a unidirectional point location; both are
  645  * mandatory for a linear location.
  646  *
  647  * @param at The coordinates for a point location, NULL for a linear location
  648  * @param from The start of a linear location, or a point before `at`
  649  * @param to The end of a linear location, or a point after `at`
  650  * @param via A point between `from` and `to`, needed only on ring roads
  651  * @param not_via A point not between `from` and `to`, needed only on ring roads
  652  * @param directionality Whether the location is unidirectional or bidirectional
  653  * @param fuzziness A precision indicator for `from` and `to`
  654  */
  655 struct traffic_location * traffic_location_new_short(struct traffic_point * at, struct traffic_point * from,
  656         struct traffic_point * to, struct traffic_point * via, struct traffic_point * not_via,
  657         enum location_dir directionality, enum location_fuzziness fuzziness);
  658 
  659 /**
  660  * @brief Destroys a `traffic_location`.
  661  *
  662  * This will release the memory used by the `traffic_location` and all related data.
  663  *
  664  * A `traffic_location` is usually destroyed together with its parent `traffic_message`, thus
  665  * it is usually not necessary to call this destructor directly.
  666  *
  667  * @param this_ The location
  668  */
  669 void traffic_location_destroy(struct traffic_location * this_);
  670 
  671 /**
  672  * @brief Creates a new `traffic_suppl_info`.
  673  *
  674  * It is the responsibility of the caller to destroy all references passed to this function. This can be
  675  * done immediately after the function returns.
  676  *
  677  * @param si_class The supplementary information class (generic category)
  678  * @param type The supplementary information type, which can be mapped to a string to be displayed to
  679  * the user
  680  * @param quantifier Additional quantifier for supplementary information types allowing this, or NULL
  681  */
  682 struct traffic_suppl_info * traffic_suppl_info_new(enum si_class si_class, enum si_type type,
  683         struct quantifier * quantifier);
  684 
  685 /**
  686  * @brief Destroys a `traffic_suppl_info`.
  687  *
  688  * This will release the memory used by the `traffic_suppl_info` and all related data.
  689  *
  690  * A `traffic_suppl_info` is usually destroyed together with its parent `traffic_event`, thus
  691  * it is usually not necessary to call this destructor directly.
  692  *
  693  * @param this_ The supplementary information item
  694  */
  695 void traffic_suppl_info_destroy(struct traffic_suppl_info * this_);
  696 
  697 /**
  698  * @brief Creates a new `traffic_event`.
  699  *
  700  * The `traffic_suppl_info` instances are destroyed when the `traffic_event` is destroyed, and
  701  * therefore cannot be shared between multiple `traffic_event` instances.
  702  *
  703  * It is the responsibility of the caller to destroy all other references passed to this function
  704  * (including the `si` buffer but not the `traffic_suppl_info` instances). This can be done
  705  * immediately after the function returns.
  706  *
  707  * @param event_class The event class (generic category)
  708  * @param type The event type, which can be mapped to a string to be displayed to the user
  709  * @param length The length of the affected route in meters, -1 if not known
  710  * @param speed The speed in km/h at which vehicles can expect to pass through the affected stretch of
  711  * road (either a temporary speed limit or average speed in practice, whichever is less); INT_MAX if unknown
  712  * @param quantifier Additional quantifier for supplementary information types allowing this, or NULL
  713  * @param si_count Number of supplementary information items in `si_count`
  714  * @param si Points to an array of pointers to supplementary information items
  715  */
  716 struct traffic_event * traffic_event_new(enum event_class event_class, enum event_type type,
  717         int length, int speed, struct quantifier * quantifier, int si_count, struct traffic_suppl_info ** si);
  718 
  719 /**
  720  * @brief Creates a new `traffic_event`.
  721  *
  722  * This is the short version of the constructor, which sets only mandatory members. Other members can be
  723  * set after the instance is created.
  724  *
  725  * @param event_class The event class (generic category)
  726  * @param type The event type, which can be mapped to a string to be displayed to the user
  727  */
  728 struct traffic_event * traffic_event_new_short(enum event_class event_class, enum event_type type);
  729 
  730 /**
  731  * @brief Destroys a `traffic_event`.
  732  *
  733  * This will release the memory used by the `traffic_event` and all related data.
  734  *
  735  * A `traffic_event` is usually destroyed together with its parent `traffic_message`, thus
  736  * it is usually not necessary to call this destructor directly.
  737  *
  738  * @param this_ The event
  739  */
  740 void traffic_event_destroy(struct traffic_event * this_);
  741 
  742 /**
  743  * @brief Adds a supplementary information item to an event.
  744  *
  745  * The `traffic_suppl_info` instance is destroyed when the `traffic_event` is destroyed, and
  746  * therefore cannot be shared between multiple `traffic_event` instances.
  747  *
  748  * @param this_ The event
  749  * @param si The supplementary information item
  750  */
  751 void traffic_event_add_suppl_info(struct traffic_event * this_, struct traffic_suppl_info * si);
  752 
  753 /**
  754  * @brief Retrieves a supplementary information item associated with an event.
  755  *
  756  * @param this_ The event
  757  * @param index The index of the supplementary information item, zero-based
  758  * @return The supplementary information item at the specified position, or NULL if out of bounds
  759  */
  760 struct traffic_suppl_info * traffic_event_get_suppl_info(struct traffic_event * this_, int index);
  761 
  762 /**
  763  * @brief Creates a new `traffic_message`.
  764  *
  765  * The `traffic_event` and `traffic_location` instances are destroyed when the
  766  * `traffic_message` is destroyed, and therefore cannot be shared between multiple
  767  * `traffic_message` instances.
  768  *
  769  * It is the responsibility of the caller to destroy all other references passed to this function
  770  * (including the `events` buffer but not the `traffic_event` instances). This can be done
  771  * immediately after the function returns.
  772  *
  773  * @param id The message identifier; existing messages with the same identifier will be replaced by the
  774  * new message
  775  * @param receive_time When the message was first received by the source, should be kept stable across
  776  * all updates
  777  * @param update_time When the last update to this message was received by the source
  778  * @param expiration_time How long the message should be considered valid
  779  * @param start_time When the condition is expected to begin (optional, 0 if not set)
  780  * @param end_time How long the condition is expected to last (optional, 0 if not set)
  781  * @param isCancellation If true, create a cancellation message (existing messages with the same ID
  782  * should be deleted or no longer considered current, and all other attributes ignored)
  783  * @param isForecast If false, the message describes a current situation; if true, it describes an
  784  * expected situation in the future
  785  * @param replaced_count The number of entries in `replaces`
  786  * @param replaces Points to an array of identifiers of messages which the current message replaces
  787  * @param location The location to which this message refers
  788  * @param event_count The number of events in `events`
  789  * @param events Points to an array of pointers to the events for this message
  790  */
  791 struct traffic_message * traffic_message_new(char * id, time_t receive_time, time_t update_time,
  792         time_t expiration_time, time_t start_time, time_t end_time, int is_cancellation, int is_Forecast,
  793         int replaced_count, char ** replaces, struct traffic_location * location, int event_count,
  794         struct traffic_event ** events);
  795 
  796 /**
  797  * @brief Creates a new `traffic_message`.
  798  *
  799  * This is the short version of the constructor, which sets only mandatory members. Other members can be
  800  * set after the instance is created.
  801  *
  802  * The `traffic_event` and `traffic_location` instances are destroyed when the
  803  * `traffic_message` is destroyed, and therefore cannot be shared between multiple
  804  * `traffic_message` instances.
  805  *
  806  * It is the responsibility of the caller to destroy all other references passed to this function
  807  * (including the `events` buffer but not the `traffic_event` instances). This can be done
  808  * immediately after the function returns.
  809  *
  810  * @param id The message identifier; existing messages with the same identifier will be replaced by the
  811  * new message
  812  * @param receive_time When the message was first received by the source, should be kept stable across
  813  * all updates
  814  * @param update_time When the last update to this message was received by the source
  815  * @param expiration_time How long the message should be considered valid
  816  * @param is_forecast If false, the message describes a current situation; if true, it describes an
  817  * expected situation in the future
  818  * @param location The location to which this message refers
  819  * @param event_count The number of events in `events`
  820  * @param events Points to an array of pointers to the events for this message
  821  */
  822 struct traffic_message * traffic_message_new_short(char * id, time_t receive_time, time_t update_time,
  823         time_t expiration_time, int is_forecast, struct traffic_location * location,
  824         int event_count, struct traffic_event ** events);
  825 
  826 /**
  827  * @brief Creates a new single-event `traffic_message`.
  828  *
  829  * This is a convenience constructor, which sets only mandatory members. Other members can be
  830  * set after the instance is created.
  831  *
  832  * The `traffic_location` instances are destroyed when the `traffic_message` is destroyed,
  833  * and therefore cannot be shared between multiple `traffic_message` instances.
  834  *
  835  * It is the responsibility of the caller to destroy all other references passed to this function. This
  836  * can be done immediately after the function returns.
  837  *
  838  * @param id The message identifier; existing messages with the same identifier will be replaced by the
  839  * new message
  840  * @param receive_time When the message was first received by the source, should be kept stable across
  841  * all updates
  842  * @param update_time When the last update to this message was received by the source
  843  * @param expiration_time How long the message should be considered valid
  844  * @param is_forecast If false, the message describes a current situation; if true, it describes an
  845  * expected situation in the future
  846  * @param location The location to which this message refers
  847  * @param event_class The event class (generic category)
  848  * @param type The event type, which can be mapped to a string to be displayed to the user
  849  */
  850 struct traffic_message * traffic_message_new_single_event(char * id, time_t receive_time, time_t update_time,
  851         time_t expiration_time, int is_forecast, struct traffic_location * location,
  852         enum event_class event_class, enum event_type type);
  853 
  854 /**
  855  * @brief Creates a new cancellation `traffic_message`.
  856  *
  857  * This is a convenience constructor, which creates a cancellation message, without the need to supply
  858  * members which are not required for cancellation messages. Upon receiving a cancellation message,
  859  * existing messages with the same ID should be deleted or no longer considered current, and all other
  860  * attributes ignored.
  861  *
  862  * The `traffic_location` instances are destroyed when the `traffic_message` is destroyed,
  863  * and therefore cannot be shared between multiple `traffic_message` instances.
  864  *
  865  * It is the responsibility of the caller to destroy all other references passed to this function. This
  866  * can be done immediately after the function returns.
  867  *
  868  * @param id The message identifier; existing messages with the same identifier will be replaced by the
  869  * new message
  870  * @param receive_time When the message was first received by the source, should be kept stable across
  871  * all updates
  872  * @param update_time When the last update to this message was received by the source
  873  * @param expiration_time How long the message should be considered valid
  874  * @param location The location to which this message refers
  875  */
  876 struct traffic_message * traffic_message_new_cancellation(char * id, time_t receive_time, time_t update_time,
  877         time_t expiration_time, struct traffic_location * location);
  878 
  879 /**
  880  * @brief Destroys a `traffic_message`.
  881  *
  882  * This will release the memory used by the `traffic_message` and all related data.
  883  *
  884  * A `traffic_message` is usually destroyed by the traffic plugin, thus it is usually not
  885  * necessary to call this destructor directly.
  886  *
  887  * @param this_ The message
  888  */
  889 void traffic_message_destroy(struct traffic_message * this_);
  890 
  891 /**
  892  * @brief Adds an event to a message.
  893  *
  894  * The `traffic_event` instance is destroyed when the `traffic_message` is destroyed, and
  895  * therefore cannot be shared between multiple `traffic_message` instances.
  896  *
  897  * @param this_ The message
  898  * @param event The event to add to this message
  899  */
  900 void traffic_message_add_event(struct traffic_message * this_, struct traffic_event * event);
  901 
  902 /**
  903  * @brief Retrieves an event associated with a message.
  904  *
  905  * @param this_ The message
  906  * @param index The index of the event, zero-based
  907  * @return The event at the specified position, or NULL if out of bounds
  908  */
  909 struct traffic_event * traffic_message_get_event(struct traffic_message * this_, int index);
  910 
  911 /**
  912  * @brief Returns the items associated with a message.
  913  *
  914  * Note that no map rectangle is required to obtain traffic items. This behavior is particular to traffic items, which
  915  * do not rely on a map rectangle. Items obtained from other maps may behave differently.
  916  *
  917  * @param this_ The message
  918  *
  919  * @return Items as a NULL-terminated array. The caller is responsible for freeing the array (not its elements) when it
  920  * is no longer needed. This method will always return a valid pointer—if no items are associated with the message, an
  921  * empty array (with just one single NULL element) will be returned. No particular order is guaranteed for the items.
  922  */
  923 struct item ** traffic_message_get_items(struct traffic_message * this_);
  924 
  925 /**
  926  * @brief Initializes the traffic plugin.
  927  *
  928  * This function is called once on startup.
  929  */
  930 void traffic_init(void);
  931 
  932 /**
  933  * @brief Reads previously stored traffic messages from an XML file.
  934  *
  935  * @param this_ The traffic instance
  936  * @param filename The full path to the XML file to parse
  937  *
  938  * @return A `NULL`-terminated pointer array. Each element points to one `struct traffic_message`.
  939  * `NULL` is returned (rather than an empty pointer array) if there are no messages to report.
  940  */
  941 struct traffic_message ** traffic_get_messages_from_xml_file(struct traffic * this_, char * filename);
  942 
  943 /**
  944  * @brief Reads traffic messages from an XML string.
  945  *
  946  * @param this_ The traffic instance
  947  * @param filename The XML document to parse, as a string
  948  *
  949  * @return A `NULL`-terminated pointer array. Each element points to one `struct traffic_message`.
  950  * `NULL` is returned (rather than an empty pointer array) if there are no messages to report.
  951  */
  952 struct traffic_message ** traffic_get_messages_from_xml_string(struct traffic * this_, char * xml);
  953 
  954 /**
  955  * @brief Returns the map for the traffic plugin.
  956  *
  957  * The map is created by the first traffic plugin loaded. If multiple traffic plugin instances are
  958  * active at the same time, they share the map created by the first instance.
  959  *
  960  * @param this_ The traffic plugin instance
  961  *
  962  * @return The traffic map
  963  */
  964 struct map * traffic_get_map(struct traffic *this_);
  965 
  966 /**
  967  * @brief Returns currently active traffic messages.
  968  *
  969  * If multiple plugin instances are active, this will give the same result for any plugin, as traffic messages are
  970  * shared between instances.
  971  *
  972  * @param this_ The traffic plugin instance
  973  *
  974  * @return A null-terminated array of traffic messages. The caller is responsible for freeing the array (not its
  975  * elements) when it is no longer needed. This method will always return a valid pointer—if the message store is empty,
  976  * an empty array (with just one single NULL element) will be returned.
  977  */
  978 struct traffic_message ** traffic_get_stored_messages(struct traffic *this_);
  979 
  980 /**
  981  * @brief Processes new traffic messages.
  982  *
  983  * Calling this method delivers new messages in a “push” manner (as opposed to the “pull” fashion of
  984  * calling a plugin method).
  985  *
  986  * Messages which are past their expiration timestamp are skipped, and the flags in the return value
  987  * are set only if at least one valid message is found.
  988  *
  989  * @param this_ The traffic instance
  990  * @param messages The new messages
  991  */
  992 void traffic_process_messages(struct traffic * this_, struct traffic_message ** messages);
  993 
  994 /**
  995  * @brief Sets the mapset for the traffic plugin.
  996  *
  997  * This sets the mapset from which the segments affected by a traffic report will be retrieved.
  998  *
  999  * @param this_ The traffic plugin instance
 1000  * @param ms The mapset
 1001  */
 1002 void traffic_set_mapset(struct traffic *this_, struct mapset *ms);
 1003 
 1004 /**
 1005  * @brief Sets the route for the traffic plugin.
 1006  *
 1007  * This sets the route which may get notified by the traffic plugin if traffic distortions change.
 1008  */
 1009 void traffic_set_route(struct traffic *this_, struct route *rt);
 1010 
 1011 /**
 1012  * @brief Destructor.
 1013  */
 1014 void traffic_destroy(struct traffic *this_);
 1015 
 1016 /* end of prototypes */
 1017 #ifdef __cplusplus
 1018 }
 1019 #endif
 1020 
 1021 #endif