Editing SimTX API/Packets/ListStations

{{SimTX API navigation}}
{{SimTX packet
| name = ListStations
| frame = ClientFrame
| field = 30
| member = list_stations
| direction = c2s
| session = [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]]
| roles = <code>ROLE_CONTROL</code>, <code>ROLE_MODERATION</code>.
| permission = None on control sessions; <code>moderation.manage</code> on moderation sessions
| reply = [[SimTX API/Packets/StationList|StationList]] (moderation: then [[SimTX API/Packets/StationImpactList|StationImpactList]])
| group = control
| file = control.proto
}}
'''ListStations''' asks for the list of stations on the server. The server answers with [[SimTX API/Packets/StationList|StationList]]. On a [[SimTX API/Moderation session|moderation session]] the list includes client addresses and is followed by [[SimTX API/Packets/StationImpactList|StationImpactList]].

== Definition ==
<syntaxhighlight lang="protobuf">
message ListStations {
  int64 request_id = 1;
  bool include_sessions = 2;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Nonzero; echoed in the [[SimTX API/Packets/StationList|StationList]].
|-
| 2 || <code>include_sessions</code> || <code>bool</code> || Ignored by current servers, which always list live sessions. Send <code>true</code>.
|}

== Rate limiting ==
ListStations is a heavy request. Poll it every few seconds at most; the per-address heavy budget is 4 per second, shared by all control connections from the address.

== Example ==
Complete frames, including the varint length prefix.

'''<code>list_stations</code>''' (client to server, 8 bytes):

<syntaxhighlight lang="text">
07        frame length 7
F2 01 04  list_stations (ListStations), 4 bytes
  08 05   request_id = 5
  10 01   include_sessions = true
</syntaxhighlight>

== See also ==
* [[SimTX API/Packets/StationList|StationList]]
* [[SimTX API/Control session#Station list|Station list]]

{{SimTX API navbox}}
[[Category:SimTX API]]