Documentation ¶
Overview ¶
Package muc implements Multi-User Chat.
Unlike many Multi-User Chat (MUC) implementations, the muc package tries to be as stateless as possible. It allows you to receive chat messages and invites sent through a channel, for example, but does not keep track of what users are joined to the channel at any given time. This is best left up to the user who may want to use a distributed datastore to keep track of users in a large system for searching many public channels, or may want a simple in-memory map for a small client.
The main entrypoint into the muc package (for clients) is the Client type. It can be used to join MUCs and has callbacks for receiving MUC events such as presence or mediated invites to a new channel. It is normally registered with a multiplexer such as the one found in the mux package:
mucClient := muc.Client{} m := mux.New( muc.HandleClient(mucClient), ) channel, err := mucClient.Join(…)
Once the Join method has been called the resulting channel type can be used to perform actions on the channel such as setting the subject, rejoining (to force syncronize state), or leaving the channel.
channel, err := mucClient.Join(…) channel.Subject(context.Background(), "Bridge operation and tactical readiness")
Index ¶
- Constants
- Variables
- func GetConfig(ctx context.Context, room jid.JID, s *xmpp.Session) (*form.Data, error)
- func GetConfigIQ(ctx context.Context, iq stanza.IQ, s *xmpp.Session) (*form.Data, error)
- func HandleClient(h *Client) mux.Option
- func HandleInvite(f func(Invitation)) mux.Option
- func Invite(ctx context.Context, to jid.JID, invite Invitation, s *xmpp.Session) error
- func SetConfig(ctx context.Context, room jid.JID, form *form.Data, s *xmpp.Session) error
- func SetConfigIQ(ctx context.Context, iq stanza.IQ, form *form.Data, s *xmpp.Session) error
- type Affiliation
- type Channel
- func (c *Channel) Addr() jid.JID
- func (c *Channel) Invite(ctx context.Context, reason string, to jid.JID) error
- func (c *Channel) Join(ctx context.Context, opt ...Option) error
- func (c *Channel) JoinPresence(ctx context.Context, p stanza.Presence, opt ...Option) error
- func (c *Channel) Joined() bool
- func (c *Channel) Leave(ctx context.Context, status string) error
- func (c *Channel) LeavePresence(ctx context.Context, status string, p stanza.Presence) error
- func (c *Channel) Me() jid.JID
- func (c *Channel) SetAffiliation(ctx context.Context, a Affiliation, j jid.JID, nick, reason string) error
- func (c *Channel) Subject(ctx context.Context, subject string) error
- func (c *Channel) SubjectMessage(ctx context.Context, subject string, m stanza.Message) error
- type Client
- func (*Client) ForFeatures(node string, f func(info.Feature) error) error
- func (c *Client) HandleMessage(p stanza.Message, r xmlstream.TokenReadEncoder) error
- func (c *Client) HandlePresence(p stanza.Presence, r xmlstream.TokenReadEncoder) error
- func (c *Client) Join(ctx context.Context, room jid.JID, s *xmpp.Session, opt ...Option) (*Channel, error)
- func (c *Client) JoinPresence(ctx context.Context, p stanza.Presence, s *xmpp.Session, opt ...Option) (*Channel, error)
- type Invitation
- func (i Invitation) MarshalDirect() xml.TokenReader
- func (i Invitation) MarshalMediated() xml.TokenReader
- func (i Invitation) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
- func (i Invitation) TokenReader() xml.TokenReader
- func (i *Invitation) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
- func (i Invitation) WriteXML(w xmlstream.TokenWriter) (n int, err error)
- type Item
- type Option
- type Privileges
- type Role
Constants ¶
const ( NS = `http://jabber.org/protocol/muc` NSUser = `http://jabber.org/protocol/muc#user` NSOwner = `http://jabber.org/protocol/muc#owner` NSAdmin = `http://jabber.org/protocol/muc#admin` // NSConf is the legacy conference namespace, now only used for direct MUC // invitations and backwards compatibility. NSConf = `jabber:x:conference` )
Various namespaces used by this package, provided as a convenience.
Variables ¶
var (
Feature = info.Feature{Var: NS}
)
A list of service discovery features that are supported by this package.
Functions ¶
func GetConfigIQ ¶
GetConfigIQ is like GetConfig except that it lets you customize the IQ. Changing the type of the IQ has no effect.
func HandleClient ¶
HandleClient returns an option that registers the handler for use with a multiplexer.
func HandleInvite ¶
func HandleInvite(f func(Invitation)) mux.Option
HandleInvite returns an option that registers a handler for direct MUC invitations. To handle mediated invitations register a client handler using HandleClient.
func Invite ¶
Invite sends a direct MUC invitation using the provided session. This is useful when a mediated invitation (one sent through the channel using the Invite method) is being blocked by a user that does not allow contact from unrecognized JIDs. Changing the XMLName field of the invite has no effect.
Types ¶
type Affiliation ¶
type Affiliation uint8
Affiliation indicates a users affiliation to the room.
const ( AffiliationNone Affiliation = iota // none // Support for the owner affiliation is required. AffiliationOwner // owner // Support for these affiliations is recommended, but optional. AffiliationAdmin // admin AffiliationMember // member AffiliationOutcast // outcast )
A list of room affiliations.
func (*Affiliation) MarshalXMLAttr ¶
MarshalXMLAttr satisfies xml.MarshalerAttr.
func (Affiliation) String ¶
func (i Affiliation) String() string
func (*Affiliation) UnmarshalXMLAttr ¶
func (a *Affiliation) UnmarshalXMLAttr(attr xml.Attr) error
UnmarshalXMLAttr satisfies xml.UnmarshalerAttr.
type Channel ¶
type Channel struct {
// contains filtered or unexported fields
}
Channel represents a group chat, conference, or chatroom.
Channel aims to be as stateless as possible, so details such as the channel subject and participant list are not stored. Instead, it is up to the user to store this information and associate it with the channel (probably by mapping details to the channel address).
func (*Channel) Invite ¶
Invite sends a mediated invitation (an invitation sent from the channel itself) to the user.
For direct invitations sent from your own account (ie. to avoid users who block all unrecognized JIDs) see the Invite function.
func (*Channel) Join ¶
Join is like the Join function except that it joins or re-synchronizes the current room. It is useful if somehow the room has become unsyncronized with the server or when you want to leave the room and join again later.
func (*Channel) JoinPresence ¶
JoinPresence is like Join except that it gives you more control over the presence. Changing the presence type or to address has no effect.
func (*Channel) LeavePresence ¶
LeavePresence is like Leave except that it gives you more control over the presence. Changing the presence type or to attributes have no effect.
func (*Channel) SetAffiliation ¶
func (c *Channel) SetAffiliation(ctx context.Context, a Affiliation, j jid.JID, nick, reason string) error
SetAffiliation changes the affiliation of the provided JID which should be the users real bare-JID (not their room JID).
type Client ¶
type Client struct { // HandleInvite will be called if we receive a mediated MUC invitation. HandleInvite func(Invitation) HandleUserPresence func(stanza.Presence, Item) // contains filtered or unexported fields }
Client is an xmpp.Handler that handles MUC payloads from a client perspective.
func (*Client) ForFeatures ¶
ForFeatures implements info.FeatureIter.
func (*Client) HandleMessage ¶
HandleMessage satisfies mux.MessageHandler. it is used by the multiplexer and normally does not need to be called by the user.
func (*Client) HandlePresence ¶
HandlePresence satisfies mux.PresenceHandler. it is used by the multiplexer and normally does not need to be called by the user.
type Invitation ¶
type Invitation struct { XMLName xml.Name Continue bool JID jid.JID Password string Reason string Thread string }
Invitation is a mediated or direct MUC invitation. When the XML is marshaled or unmarshaled the namespace determines whether the invitation was direct or mediated. The default is mediated.
func (Invitation) MarshalDirect ¶
func (i Invitation) MarshalDirect() xml.TokenReader
MarshalDirect returns the invitation as a direct MUC invitation (sent directly to the invitee).
func (Invitation) MarshalMediated ¶
func (i Invitation) MarshalMediated() xml.TokenReader
MarshalMediated returns the invitation as a mediated MUC invitation (sent to the room and then forwarded to the invitee).
func (Invitation) MarshalXML ¶
func (i Invitation) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
MarshalXML implements xml.Marshaler.
func (Invitation) TokenReader ¶
func (i Invitation) TokenReader() xml.TokenReader
TokenReader satisfies the xmlstream.Marshaler interface.
It calls either MarshalDirect or MarshalMediated depending on the invitations XMLName field.
func (*Invitation) UnmarshalXML ¶
func (i *Invitation) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
UnmarshalXML implements xml.Unmarshaler.
func (Invitation) WriteXML ¶
func (i Invitation) WriteXML(w xmlstream.TokenWriter) (n int, err error)
WriteXML satisfies the xmlstream.WriterTo interface. It is like MarshalXML except it writes tokens to w.
type Item ¶
type Item struct { JID jid.JID `xml:"jid,attr,omitempty"` Affiliation Affiliation `xml:"affiliation,attr,omitempty"` Nick string `xml:"nick,attr,omitempty"` Role Role `xml:"role,attr,omitempty"` Reason string `xml:"reason"` }
Item represents a user in the channel. Various fields will be set when a user joins the channel or when the channel informs us of upates to the users information.
type Option ¶
type Option func(*config)
Option is used to configure joining a channel.
func MaxBytes ¶
MaxBytes configures the maximum number of bytes of XML that will be sent to the client when joining the room.
func MaxHistory ¶
MaxHistory configures the maximum number of messages that will be sent to the client when joining the room.
func Nick ¶
Nick overrides the resourcepart of the JID and sets a different nickname in the room.
This is mostly useful if you want to change the nickname when re-joining a room (when the JID is already known and is not provided to the method) or when the room JID is known and you want to let this package handle any errors encountered when appending the nickname and reduce boilerplate in your own code.
type Privileges ¶
type Privileges uint16
Privileges is a bit mask indicating the various privileges assigned to a room user.
const ( PrivilegePresent Privileges = 1 << iota // present PrivilegeReceiveMessages // receive-messages PrivilegeReceivePresence // receive-presence PrivilegeBroadcastPresence // broadcast-presence PrivilegeChangeAvailability // change-availability PrivilegeChangeNick // change-nick PrivilegePrivateMessage // send-private-message PrivilegeSendInvites // send-invites PrivilegeSendMessages // send-messages PrivilegeModifySubject // modify-subject PrivilegeKick // kick PrivilegeGrantVoice // grant-voice PrivilegeRevokeVoice // revoke-voice // Common default privilages for each role. // These are just common defaults provided as a convenience, it is not // guaranteed that a user of a given role has this set of privileges. PrivilegesVisitor = PrivilegePresent | PrivilegeReceiveMessages | PrivilegeReceivePresence | PrivilegeBroadcastPresence | PrivilegeChangeAvailability | PrivilegeChangeNick | PrivilegePrivateMessage | PrivilegeSendInvites PrivilegesParticipant = PrivilegesVisitor | PrivilegeSendMessages | PrivilegeModifySubject PrivilegesModerator = PrivilegesParticipant | PrivilegeKick | PrivilegeGrantVoice | PrivilegeRevokeVoice )
A list of possible privileges.
func (Privileges) String ¶
func (i Privileges) String() string
type Role ¶
type Role uint8
Role indicates a users role in the room.
const ( RoleNone Role = iota // none // Support for these roles is required. RoleModerator // moderator RoleParticipant // participant // Support for these roles is recommended, but optional. RoleVisitor // visitor )
A list of user roles.
func (*Role) MarshalXMLAttr ¶
MarshalXMLAttr satisfies xml.MarshalerAttr.