Editing SimTX API/Packets/Banner

{{SimTX API navigation}}
{{SimTX packet
| name = Banner
| frame = ServerFrame
| field = 4
| member = banner
| direction = s2c
| session = [[SimTX API/Control session|Control]]
| roles = Sent on control sessions. Clients of every role should accept it.
| permission = None
| group = connection
| file = control.proto
}}
'''Banner''' carries a server-wide notice for the client to display, such as planned maintenance, a performance warning or a ban notice. The server sends it when a control session starts, if a notice is active, and pushes it to every control session whenever a notice is set, replaced or cleared.

== Definition ==
<syntaxhighlight lang="protobuf">
message Banner {
  BannerLevel level = 1;
  string text = 2;
  int64 expires_at_ms = 3;     // 0 = no expiry
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>level</code> || [[SimTX API/Data types#BannerLevel|BannerLevel]] || <code>BANNER_LEVEL_INFO</code> (0) or <code>BANNER_LEVEL_BAN_NOTICE</code> (1). Show unknown levels as information.
|-
| 2 || <code>text</code> || <code>string</code> || Notice text, at most 512 characters. Empty clears the current notice.
|-
| 3 || <code>expires_at_ms</code> || <code>int64</code> || Hide the notice after this time, Unix ms. 0 = no expiry.
|}

== Usage ==
* Show the text prominently, replacing any earlier banner. Each Banner supersedes the previous one.
* Hide the banner when <code>text</code> is empty.
* Hide it at <code>expires_at_ms</code>. The server does not send a clearing banner when a notice expires.
* A <code>BANNER_LEVEL_BAN_NOTICE</code> banner is sent to the control sessions of an address that has just been banned. Those control sessions stay connected; new game connections from the address are refused with <code>HELLO_STATUS_IP_BANNED</code>.
* The server also posts short automatic notices when it is overloaded. They clear themselves after about a minute.
* Banners may arrive between any other frames. Current servers send them on control sessions only; a client of another role that receives one may show or ignore it.

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

'''<code>banner_ban_notice</code>''' (server to client, 36 bytes):

<syntaxhighlight lang="text">
23                                 frame length 35
22 21                              banner (Banner), 33 bytes
  08 01                            level = 1 (BANNER_LEVEL_BAN_NOTICE)
  12 16 54 68 69 73 20 61 64 64 …  text = "This address is banned"
  18 80 F1 DE BA 97 34             expires_at_ms = 1793003600000
</syntaxhighlight>

== See also ==
* [[SimTX API/Packets/BroadcastBanner|BroadcastBanner]]
* [[SimTX API/Control session]]

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