RustPlusBot/src/RustPlusBot.Abstractions/Connections/IRustServerQuery.cs at bde1edc17c2baf12b49a039f647891ce9d9d554a · HandyS11/RustPlusBot · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
namespace RustPlusBot.Abstractions.Connections;

/// <summary>Reads live data from a connected server's socket (implemented by the connection supervisor).</summary>
public interface IRustServerQuery
{
    /// <summary>Gets server info, or null when (guildId, serverId) has no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A server-info snapshot, or null when there is no live socket.</returns>
    Task<ServerInfoSnapshot?> GetServerInfoAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);

    /// <summary>Gets in-game time, or null when there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>An in-game time snapshot, or null when there is no live socket.</returns>
    Task<ServerTimeSnapshot?> GetTimeAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);

    /// <summary>Gets a team snapshot, or null when there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A team snapshot, or null when there is no live socket.</returns>
    Task<TeamInfoSnapshot?> GetTeamInfoAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);

    /// <summary>Promotes a team member to team leader; returns false when there is no live socket or the API fails.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="steamId">Steam64 id of the member to promote.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>True if promoted; false when no live socket or the API fails.</returns>
    Task<bool> PromoteToLeaderAsync(ulong guildId, Guid serverId, ulong steamId, CancellationToken cancellationToken);

    /// <summary>Gets the base map image (JPEG bytes), or null when there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>The base-map JPEG bytes, or null when there is no live socket.</returns>
    Task<byte[]?> GetMapImageAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);

    /// <summary>Gets the static map dimensions (for grid rendering), or null when there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>The map dimensions, or null when there is no live socket.</returns>
    Task<MapDimensions?> GetMapDimensionsAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);

    /// <summary>Gets the server's monuments, or an empty list when there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>The monuments, or an empty list when there is no live socket.</returns>
    Task<IReadOnlyList<MonumentSnapshot>> GetMonumentsAsync(
        ulong guildId,
        Guid serverId,
        CancellationToken cancellationToken);

    /// <summary>Reads a smart switch's on/off state, or null when there is no live socket or the call fails.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="entityId">The in-game smart-switch entity id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>True/false for on/off, or null when unavailable.</returns>
    Task<bool?> GetSmartSwitchStateAsync(ulong guildId,
        Guid serverId,
        ulong entityId,
        CancellationToken cancellationToken);

    /// <summary>Reads a smart alarm's live state and reachability (kind-aware Rust+ read).</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="entityId">The in-game smart-alarm entity id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>The reading; <see cref="DeviceReachability.NoResponse"/> with a null state when there is no live socket.</returns>
    Task<DeviceReading> GetSmartAlarmReadingAsync(ulong guildId,
        Guid serverId,
        ulong entityId,
        CancellationToken cancellationToken);

    /// <summary>Reads a storage monitor's contents for a (guild, server), or null when there is no live socket.</summary>
    /// <param name="guildId">The guild snowflake.</param>
    /// <param name="serverId">The server id.</param>
    /// <param name="entityId">The storage-monitor entity id.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>The contents snapshot, or null when unreachable.</returns>
    Task<StorageContentsSnapshot?> GetStorageContentsAsync(
        ulong guildId,
        Guid serverId,
        ulong entityId,
        CancellationToken cancellationToken);

    /// <summary>Sets a smart switch on/off; returns the reachability reason when the call fails or there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="entityId">The in-game smart-switch entity id.</param>
    /// <param name="value">True to turn on, false to turn off.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns><see cref="DeviceReachability.Reachable"/> on success; the failure reason otherwise.</returns>
    Task<DeviceReachability> SetSmartSwitchAsync(ulong guildId,
        Guid serverId,
        ulong entityId,
        bool value,
        CancellationToken cancellationToken);

    /// <summary>Strobes a smart switch; returns the reachability reason when the call fails or there is no live socket.</summary>
    /// <param name="guildId">The owning guild snowflake.</param>
    /// <param name="serverId">The target server id.</param>
    /// <param name="entityId">The in-game smart-switch entity id.</param>
    /// <param name="timeoutMs">The in-game strobe duration in milliseconds.</param>
    /// <param name="value">The terminal value after strobing.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns><see cref="DeviceReachability.Reachable"/> on success; the failure reason otherwise.</returns>
    Task<DeviceReachability> StrobeSmartSwitchAsync(ulong guildId,
        Guid serverId,
        ulong entityId,
        int timeoutMs,
        bool value,
        CancellationToken cancellationToken);
}