SimTX API/Packets/Banner

Banner

Frame	ServerFrame, field 4
Member	banner
Direction	Server → client
Session	Control
Roles	Sent on control sessions. Clients of every role should accept it.
Permission	None
Answered by
Answers
Defined in	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

message Banner {
  BannerLevel level = 1;
  string text = 2;
  int64 expires_at_ms = 3;     // 0 = no expiry
}

Fields

#	Field	Type	Description
1	level	BannerLevel	BANNER_LEVEL_INFO (0) or BANNER_LEVEL_BAN_NOTICE (1). Show unknown levels as information.
2	text	string	Notice text, at most 512 characters. Empty clears the current notice.
3	expires_at_ms	int64	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 text is empty.
• Hide it at expires_at_ms. The server does not send a clearing banner when a notice expires.
• A BANNER_LEVEL_BAN_NOTICE banner is sent to the control sessions of an address that has just been banned. Those control sessions stay connected so that the user can read it; new game connections from the address are refused with HELLO_STATUS_IP_BANNED.
• 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, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).

banner_ban_notice (server to client, 36 bytes):

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

See also

• BroadcastBanner
• SimTX API/Control session