muc

package
v0.21.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 11, 2023 License: BSD-2-Clause Imports: 15 Imported by: 5

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

View Source 
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

View Source 
var (
	Feature = info.Feature{Var: NS}
)

A list of service discovery features that are supported by this package.

Functions

func GetConfig 

func GetConfig(ctx context.Context, room jid.JID, s *xmpp.Session) (*form.Data, error)

GetConfig requests a room config form.

func GetConfigIQ 

func GetConfigIQ(ctx context.Context, iq stanza.IQ, s *xmpp.Session) (*form.Data, error)

GetConfigIQ is like GetConfig except that it lets you customize the IQ. Changing the type of the IQ has no effect.

func HandleClient 

func HandleClient(h *Client) mux.Option

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 

func Invite(ctx context.Context, to jid.JID, invite Invitation, s *xmpp.Session) error

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.

func SetConfig 

func SetConfig(ctx context.Context, room jid.JID, form *form.Data, s *xmpp.Session) error

SetConfig sets the room config. The form should be the one provided by a call to GetConfig with various values set.

func SetConfigIQ 

func SetConfigIQ(ctx context.Context, iq stanza.IQ, form *form.Data, s *xmpp.Session) error

SetConfigIQ is like SetConfig except that it lets you customize the IQ. Changing the type of the IQ 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 

func (a *Affiliation) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

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) Addr 

func (c *Channel) Addr() jid.JID

Addr returns the address of the channel.

func (*Channel) Invite 

func (c *Channel) Invite(ctx context.Context, reason string, to jid.JID) error

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 

func (c *Channel) Join(ctx context.Context, opt ...Option) error

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 

func (c *Channel) JoinPresence(ctx context.Context, p stanza.Presence, opt ...Option) error

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) Joined 

func (c *Channel) Joined() bool

Joined returns true if this room is still being managed by the service.

func (*Channel) Leave 

func (c *Channel) Leave(ctx context.Context, status string) error

Leave exits the MUC, causing Joined to begin to return false.

func (*Channel) LeavePresence 

func (c *Channel) LeavePresence(ctx context.Context, status string, p stanza.Presence) error

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) Me 

func (c *Channel) Me() jid.JID

Me returns the users last-known address in the channel.

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).

func (*Channel) Subject 

func (c *Channel) Subject(ctx context.Context, subject string) error

Subject attempts to change the room subject. It returns immediately after the request has been sent and does not wait to see if the request was successful or not.

func (*Channel) SubjectMessage 

func (c *Channel) SubjectMessage(ctx context.Context, subject string, m stanza.Message) error

SubjectMessage is like Subject except that it allows you to customize the message stanza. Changing the receipient or type has no effect.

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 

func (*Client) ForFeatures(node string, f func(info.Feature) error) error

ForFeatures implements info.FeatureIter.

func (*Client) HandleMessage 

func (c *Client) HandleMessage(p stanza.Message, r xmlstream.TokenReadEncoder) error

HandleMessage satisfies mux.MessageHandler. it is used by the multiplexer and normally does not need to be called by the user.

func (*Client) HandlePresence 

func (c *Client) HandlePresence(p stanza.Presence, r xmlstream.TokenReadEncoder) error

HandlePresence satisfies mux.PresenceHandler. it is used by the multiplexer and normally does not need to be called by the user.

func (*Client) Join 

func (c *Client) Join(ctx context.Context, room jid.JID, s *xmpp.Session, opt ...Option) (*Channel, error)

Join a MUC on the provided session. Room should be a full JID in which the desired nickname is the resourcepart.

Join blocks until the full room roster has been received.

func (*Client) JoinPresence 

func (c *Client) JoinPresence(ctx context.Context, p stanza.Presence, s *xmpp.Session, opt ...Option) (*Channel, error)

JoinPresence is like Join except that it gives you more control over the presence. Changing the presence type has no effect.

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 Duration 

func Duration(d time.Duration) Option

Duration configures the room to send history received within a window of time.

func MaxBytes 

func MaxBytes(b uint64) Option

MaxBytes configures the maximum number of bytes of XML that will be sent to the client when joining the room.

func MaxHistory 

func MaxHistory(messages uint64) Option

MaxHistory configures the maximum number of messages that will be sent to the client when joining the room.

func Nick 

func Nick(n string) Option

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.

func Password 

func Password(p string) Option

Password is used to join password protected rooms.

func Since 

func Since(t time.Time) Option

Since configures the room to send history received since the provided time.

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 

func (r *Role) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr satisfies xml.MarshalerAttr.

func (Role) String 

func (i Role) String() string

func (*Role) UnmarshalXMLAttr 

func (r *Role) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr satisfies xml.UnmarshalerAttr.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.