-
Notifications
You must be signed in to change notification settings - Fork 3
Test page
Some of the terms in this document are borrowed from the XMPP protocol or an extension.
There are several ways to think of what a channel is.
A channel is a "groupware" entity that allows a set of users to interact and share content with each other.
A channel is a stream of content, activities and notifications (generated by the members of the channel).
A channel is a set of users, a set of beacons, and a set of notes. A channel provides a context for the interactions between, and within, these sets.
Users have great flexibility in how they use channels. The functionality of a channel is intentionally generic so users can adapt them to their own habits and usage patterns.
Beacons are geographical locations or points of interest which can be associated with a channel. Used to associate location with activities or content. Can be none, one or many.
Users are able to post content to a channel which will be available to all members of a channel. Content is divided into two levels as posts and comments.
A post is a stand-alone piece of content. It may also be thought of as "top-level" content. A post may be text and one of an image, audio or video.
A comment is a piece of text and represents commentary on a "parent" post. Comments are text only and does not include image, audio or video.
Notifications can be generated. For example: a new post is made, a user joins or leaves a channel, a user enters/lingers/exits a beacon of the channel, a beacon is associated/de-associated with the channel.
A channel's visibility can be public or private.
A public channel is discoverable by anyone and anyone can join.
A private channel is not discoverable. It is visible only to existing members. Becoming a member is invite-only or requires approval.
(ToDo: Consider allowing private channels to be discoverable in some scenarios. Less compute-intensive.)
"Local" is the concept that channel participation is restricted to users in a vicinity or vicinities.
(ToDo: Consider a more meaningful and intuitive term than "local")
If a channel is local, only users who are in the proximity of a specially configured beacon (or beacons) are allowed to participate. "Participate" in this context means posting content but could be expanded to include other actions in the future.
This property does not affect visibility or view access. It only affects participation.
At some time in the future, channels will require optional moderation ability.
The owner of a channel will have the ability to designate arbitrary users as channel moderators.
There are two moderation models under consideration.
In this model, moderators moderate content.
- Moderators have the ability to delete any posts.
- The channel may be configured such that all posts by unprivileged members require approval before being published. Privileged users (ie. moderators and the owner) are under no such restriction.
(Suggested terms: "Curated" channel, "Curation moderation")
In this model, moderators moderate users.
- Moderators have the ability to delete any posts.
- The channel may be configured such that unprivileged members are not permitted to post. Privileged users (ie. moderators and the owner) are under no such restriction.
- Moderators (and the owner) may give "voice" to arbitrary members. Members "with voice" are permitted to post.
(Suggested terms: "Whitelist" channel, "Whitelist moderation")
In both moderation models, channel owners and moderators can ban arbitrary users from a channel.
This is a table of the possible channel affiliations and the actions permitted for each affiliation.
| Permission | Owner | Moderator | Member | None | Outcast |
|---|---|---|---|---|---|
| Public channel | |||||
| Discover channel | ✓ | ✓ | ✓ | ✓ | ✓ |
| Subscribe | ✓ | ✓ | ✓ | ✓ | |
| Private channel | |||||
| Discover channel | ✓ | ✓ | ✓ | ||
| Apply for subscription | ✓ | ✓ | ✓ | ||
| Common | |||||
| View content | ✓ | ✓ | ✓ | ||
| Post content | ✓ | ✓ | ? | ||
| Delete own content | ✓ | ✓ | ✓ | ||
| Delete any content | ✓ | ✓ | |||
| Moderate | ✓ | ✓ | |||
| Configure channel | ✓ | ||||
| Delete channel | ✓ | ||||
| Transfer ownership | ✓ |
Note: This has incomplete support for moderation as moderation is deferred.
Discover channel means that the channel name appears in browsable lists or search results. Only a limited set of information is exposed during discovery.
Moderate is an umbrella term for the privileged actions that moderators can take. This set of actions is not finalised but could include things like: approve subscriptions, assign affiliations, ban users etc.
(ToDo: Insert a "Follower" column)
This is a list of user settings for per channel.
The relationship between a user and a channel is termed a subscription. A subscription may have the following states:
- None: There is no relationship between the user and the channel. This is the default.
- Pending: The user has applied for a subscription and the request has not yet been approved by the channel owner or moderator.
- Subscribed: The user is subscribed to the channel and is allowed to view content ie. affiliation "Member" (or above).
This is a boolean setting which the user can enable to indicate they have an active interest in the channel.
mute is a boolean setting which lets the user temporarily suspend their subscription to the channel. (Needs more thought)
disable is a boolean setting which allows the channel owner to temporarily disable the channel. (Needs more thought)
These settings are related to member-to-member proximity sharing ie. detecting when two members of the same channel are in proximity to each other. For this to happen, both members must opt into proximity sharing with the same channel.
(Needs more thought)
If enabled, the channel is allowed to use the user's location in order to calculate proximity to other members.
If enabled, when a co-proximity event is detected, the user is notified. (This could be a device-level setting)
TBD
hippware.com/hxep/channel
hippware.com/hxep/errors
To retrieve simple information about a channel, send an <iq type='get'><get> element specifying the channel as a node.
<iq type='get'
from='[email protected]/device'
to='server2.xmpp.domain.com'
id='123'>
<get xmlns='hippware.com/hxep/channel'
node='channel/123e4567-e89b-12d3-a456-426655440000'>
</get>
</iq>If successful, this will return single-valued scalar fields and meta-fields of the channel.
<iq type='result'
from='server2.xmpp.domain.com'
to='[email protected]/device'
id='123'>
<channel xmlns='hippware.com/hxep/channel'
node='channel/123e4567-e89b-12d3-a456-426655440000'>
<field id='jid' type='jid'
value='server2.xmpp.domain.com/channel/123e4567-e89b-12d3-a456-426655440000'/>
<field id='title' type='string' value='My channel'/>
<field id='shortname' type='string' value='mychan'/>
<field id='owner' type='jid' value='[email protected]'/>
<field id='description' type='string' value='This is my channel'/>
<field id='visibility' type='int' value='0'/>
<field id='local' type='int' value='0'/>
<field id='created' type='int' value='143000000'/>
<field id='image+version' type='string' value='...'/>
<field id='subscribers+version' type='string' value='...'/>
<field id='subscribers+size' type='int' value='...'/>
<field id='followers+version' type='string' value='...'/>
<field id='followers+size' type='int' value='...'/>
<field id='moderators+version' type='string' value='...'/>
<field id='moderators+size' type='int' value='...'/>
<field id='outcasts+version' type='string' value='...'/>
<field id='outcasts+size' type='int' value='...'/>
<field id='beacons+version' type='string' value='...'/>
<field id='beacons+size' type='int' value='...'/>
</channel>
</iq>If any fields are restricted and should be withheld from the requesting entity or user, they do not appear in the <channel> element.
The requesting entity does not have sufficient privileges to retreive information about a channel.
<iq type='error'
from='server2.xmpp.domain.com'
to='[email protected]/device'
id='123'>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>The channel does not exist.
This error may also occur if the channel is a private channel and the requesting entity is not a subscriber.
<iq type='error'
from='server2.xmpp.domain.com'
to='[email protected]/device'
id='123'>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>To retrieve a single field of a channel, specify the field with a <field> element.
<iq type='get'
from='[email protected]/device'
to='server2.xmpp.domain.com'
id='123'>
<get xmlns='hippware.com/hxep/channel'
node='channel/123e4567-e89b-12d3-a456-426655440000'>
<field id='title'/>
</get>
</iq>This will return a single field.
<iq type='result'
from='server2.xmpp.domain.com'
to='[email protected]/device'
id='123'>
<channel xmlns='hippware.com/hxep/channel'
node='channel/123e4567-e89b-12d3-a456-426655440000'>
<field id='title' type='string' value='My channel'/>
</channel>
</iq>See the corresponding section in Get simple information.
This error may also occur if the requesting entity has sufficient privileges to retrieve simple information about the channel, but has insufficient privileges to retrieve the requested field.
See the corresponding section in "Get simple information".