Editing SimTX API/Packets/IpModerationRequest

{{SimTX API navigation}}
{{SimTX packet
| name = IpModerationRequest
| frame = ClientFrame
| field = 61
| member = ip_moderation
| direction = c2s
| session = [[SimTX API/Moderation session|Moderation]]
| roles = <code>ROLE_MODERATION</code>.
| permission = <code>moderation.manage</code>
| reply = [[SimTX API/Packets/IpModerationResult|IpModerationResult]] or [[SimTX API/Packets/Error|Error]]
| group = moderation
| file = control.proto
}}
'''IpModerationRequest''' bans or unbans a client address.

== Definition ==
<syntaxhighlight lang="protobuf">
message IpModerationRequest {
  int64 request_id = 1;
  IpModerationAction action = 2;
  string target = 3;
  string reason = 4;
  int64 duration_seconds = 5;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Nonzero; echoed in the [[SimTX API/Packets/IpModerationResult|IpModerationResult]] or [[SimTX API/Packets/Error|Error]].
|-
| 2 || <code>action</code> || [[SimTX API/Data types#IpModerationAction|IpModerationAction]] || <code>IP_MODERATION_ACTION_BAN</code> or <code>IP_MODERATION_ACTION_UNBAN</code>. Required.
|-
| 3 || <code>target</code> || <code>string</code> || An IP address, or the callsign of a connected session whose address should be used.
|-
| 4 || <code>reason</code> || <code>string</code> || Reason, shown to the banned user.
|-
| 5 || <code>duration_seconds</code> || <code>int64</code> || Ban duration. 0 = permanent. At most 3,650 days; not negative.
|}

== Effects ==
A ban disconnects the address's receiver and transmitter sessions, sends a <code>BANNER_LEVEL_BAN_NOTICE</code> [[SimTX API/Packets/Banner|Banner]] to its control sessions, and refuses new game connections from it with <code>HELLO_STATUS_IP_BANNED</code>. Unbanning an address that is not banned is answered with [[SimTX API/Packets/Error|Error]] <code>NOT_FOUND</code>; an invalid target or duration with <code>INVALID_REQUEST</code>.

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

'''<code>ip_moderation_ban</code>''' (client to server, 30 bytes):

<syntaxhighlight lang="text">
1D                                        frame length 29
EA 03 1A                                  ip_moderation (IpModerationRequest), 26 bytes
  08 2E                                   request_id = 46
  10 02                                   action = 2 (IP_MODERATION_ACTION_BAN)
  1A 0B 32 30 33 2E 30 2E 31 31 33 2E 39  target = "203.0.113.9"
  22 04 73 70 61 6D                       reason = "spam"
  28 90 1C                                duration_seconds = 3600
</syntaxhighlight>

== See also ==
* [[SimTX API/Moderation session]]

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