roster

Documentation

Overview

Package roster implements contact list functionality.

Index

• Constants
• func Delete(ctx context.Context, s *xmpp.Session, j jid.JID) error
• func DeleteIQ(ctx context.Context, iq IQ, s *xmpp.Session) error
• func Handle(h Handler) mux.Option
• func Set(ctx context.Context, s *xmpp.Session, item Item) error
• func SetIQ(ctx context.Context, iq IQ, s *xmpp.Session) error
• func Versioning() xmpp.StreamFeature
• type Handler
  • func (h Handler) HandleIQ(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error
• type IQ
  • func (iq IQ) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (iq IQ) TokenReader() xml.TokenReader
  • func (iq IQ) WriteXML(w xmlstream.TokenWriter) (n int, err error)
• type Item
  • func (item Item) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (item Item) TokenReader() xml.TokenReader
  • func (item Item) WriteXML(w xmlstream.TokenWriter) (n int, err error)
• type Iter
  • func Fetch(ctx context.Context, s *xmpp.Session) *Iter
  • func FetchIQ(ctx context.Context, iq IQ, s *xmpp.Session) *Iter
  • func (i *Iter) Close() error
  • func (i *Iter) Err() error
  • func (i *Iter) Item() Item
  • func (i *Iter) Next() bool
  • func (i *Iter) Version() string

Constants

const (
	NS         = "jabber:iq:roster"
	NSFeatures = "urn:xmpp:features:rosterver"
)

Namespaces used by this package provided as a convenience.

Functions

func Delete

func Delete(ctx context.Context, s *xmpp.Session, j jid.JID) error

Delete removes a roster item from the users roster.

func DeleteIQ

func DeleteIQ(ctx context.Context, iq IQ, s *xmpp.Session) error

DeleteIQ is like Delete but it allows you to customize the IQ. Changing the type of the provided IQ has no effect.

func Handle

func Handle(h Handler) mux.Option

Handle returns an option that registers a Handler for roster pushes.

func Set

func Set(ctx context.Context, s *xmpp.Session, item Item) error

Set creates a new roster item or updates an existing item.

func SetIQ

func SetIQ(ctx context.Context, iq IQ, s *xmpp.Session) error

SetIQ is like Set but it allows you to customize the IQ. Changing the type of the provided IQ has no effect.

func Versioning

func Versioning() xmpp.StreamFeature

Versioning returns a stream feature that advertises roster versioning support.

Actually attempting to negotiate the feature does nothing as it is meant to be informational only.

Types

type Handler

type Handler struct {
	Push func(ver string, item Item) error
}

Handler responds to roster pushes. If Push returns a stanza.Error it is sent as an error response to the IQ push, otherwise it is passed through and returned from HandleIQ.

func (Handler) HandleIQ

func (h Handler) HandleIQ(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error

HandleIQ responds to roster push IQs.

type IQ

type IQ struct {
	stanza.IQ

	Query struct {
		Ver  string `xml:"ver,attr"`
		Item []Item `xml:"item"`
	} `xml:"jabber:iq:roster query"`
}

IQ represents a user roster request or response. The zero value is a valid query for the roster.

func (IQ) MarshalXML

func (iq IQ) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML satisfies the xml.Marshaler interface.

func (IQ) TokenReader

func (iq IQ) TokenReader() xml.TokenReader

TokenReader returns a stream of XML tokens that match the IQ.

func (IQ) WriteXML

func (iq IQ) 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"`
	Name         string   `xml:"name,attr,omitempty"`
	Subscription string   `xml:"subscription,attr,omitempty"`
	Group        []string `xml:"group,omitempty"`
}

Item represents a contact in the roster.

func (Item) MarshalXML

func (item Item) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML satisfies the xml.Marshaler interface.

func (Item) TokenReader

func (item Item) TokenReader() xml.TokenReader

TokenReader satisfies the xmlstream.Marshaler interface.

func (Item) WriteXML

func (item Item) 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 Iter

type Iter struct {
	// contains filtered or unexported fields
}

Iter is an iterator over roster items.

func Fetch

func Fetch(ctx context.Context, s *xmpp.Session) *Iter

Fetch requests the roster and returns an iterator over all roster items (blocking until a response is received).

The iterator must be closed before anything else is done on the session or it will become invalid. Any errors encountered while creating the iter are deferred until the iter is used.

func FetchIQ

func FetchIQ(ctx context.Context, iq IQ, s *xmpp.Session) *Iter

FetchIQ is like Fetch but it allows you to customize the IQ. Changing the type of the provided IQ or adding items has no effect.

func (*Iter) Close

func (i *Iter) Close() error

Close indicates that we are finished with the given iterator and processing the stream may continue. Calling it multiple times has no effect.

func (*Iter) Err

func (i *Iter) Err() error

Err returns the last error encountered by the iterator (if any).

func (*Iter) Item

func (i *Iter) Item() Item

Item returns the last roster item parsed by the iterator.

func (*Iter) Next

func (i *Iter) Next() bool

Next returns true if there are more items to decode.

func (*Iter) Version

func (i *Iter) Version() string

Version returns the roster version being iterated over or the empty string if roster versioning is not enabled.