MirrorHub/construct
0
0
Fork 0
mirror of https://github.com/matrix-construct/construct synced 2024-06-11 06:28:55 +02:00
Code Issues Releases Wiki Activity

ircd:Ⓜ️:room::power: Document with some usage details.

Browse source
This commit is contained in:
Jason Volk 2019-08-25 15:22:22 -07:00
parent 4bf39ee1f2
commit 42b689a7a0
2 changed files with 36 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
include/ircd/m/room/power.h
View file

@ -16,10 +16,30 @@
/// This interface focuses specifically on making the power levels accessible
/// to developers for common query and manipulation operations. power_levels
/// is a single state event in the room containing integer thresholds for
/// privileges in the room in addition to a list of users mapping to an integer
/// for their level. This interface hides the details of that event by
/// privileges in the room. It also contains the list of users mapping to an
/// integer threshold. This interface hides the details of that event by
/// presenting single operations which can appear succinctly in IRCd code.
///
/// Users will typically query the operator() which will return true for allow
/// and false for deny. All other calls are slightly lower level and require
/// a bit more knowledge to safely use.
///
/// There are several modes of construction for this object, however they all
/// funnel into gathering the same information to implement the interface.
///
/// The content property of the power levels event is essential. If the user
/// does not provide this directly, or an event::idx of a power_levels event,
/// current state will be queried. If no power_levels event exists or if it
/// does not contain all of the default properties we will supplement the spec
/// defaults such that this interface always returns results (note that it is
/// still liable to throw exceptions for other reasons).
///
/// The mxid of the room creator should be supplemented for correct operation.
/// If this is not provided the interface still functions correctly but some
/// privileges reserved for room creators will not be available when querying
/// with the creator's room_id. This may be essential functionality when no
/// power_levels event exists.
///
struct ircd::m::room::power
{
using closure = std::function<void (const string_view &, const int64_t &)>;

14
ircd/m_room.cc
View file

@ -3953,6 +3953,20 @@ ircd::m::room::power::power(const json::object &power_event_content,
{
}
/// "all who attain great power and riches make use of either force or fraud"
///
/// Returns bool for "allow" or "deny"
///
/// Provide the user invoking the power. The return value indicates whether
/// they have the power.
///
/// Provide the property/event_type. There are two usages here: 1. This is a
/// string corresponding to one of the spec top-level properties like "ban"
/// and "redact". In this case, the type and state_key parameters to this
/// function are not used. 2. This string is empty or "events" in which case
/// the type parameter is used to fetch the power threshold for that type.
/// For state events of a type, the state_key must be provided for inspection
/// here as well.
bool
ircd::m::room::power::operator()(const m::user::id &user_id,
const string_view &prop,