From 42b689a7a09f44f0923c25030f6fc80094e115d5 Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Sun, 25 Aug 2019 15:22:22 -0700 Subject: [PATCH] ircd::m::room::power: Document with some usage details. --- include/ircd/m/room/power.h | 24 ++++++++++++++++++++++-- ircd/m_room.cc | 14 ++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) diff --git a/include/ircd/m/room/power.h b/include/ircd/m/room/power.h index c4c782ce1..7a30ac9e8 100644 --- a/include/ircd/m/room/power.h +++ b/include/ircd/m/room/power.h @@ -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; diff --git a/ircd/m_room.cc b/ircd/m_room.cc index 57b40164e..2a73497a6 100644 --- a/ircd/m_room.cc +++ b/ircd/m_room.cc @@ -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,