xmpp

Documentation

Overview

This package implements a simple XMPP client according to RFCs 3920 and 3921, plus the various XEPs at http://xmpp.org/protocols/. The implementation is structured as a stack of layers, with TCP at the bottom and the application at the top. The application receives and sends structures representing XMPP stanzas. Additional stanza parsers can be inserted into the stack of layers as extensions.

Index

• Constants
• Variables
• func NextId() string
• type Client
  • func NewClient(jid *JID, password string, tlsconf tls.Config, exts []Extension, pr Presence, ...) (*Client, error)
  • func NewClientFromHost(jid *JID, password string, tlsconf tls.Config, exts []Extension, pr Presence, ...) (*Client, error)
  • func (cl *Client) AddRecvFilter(filt Filter)
  • func (cl *Client) AddSendFilter(filt Filter)
  • func (cl *Client) Close()
  • func (cl *Client) SetCallback(id string, f func(Stanza))
• type Data
• type Error
  • func (er *Error) Error() string
• type Extension
• type Features
• type Filter
• type Generic
  • func (u *Generic) String() string
• type Header
• type Iq
  • func (iq *Iq) GetHeader() *Header
• type JID
  • func (j JID) Bare() JID
  • func (j JID) Domain() string
  • func (j JID) Node() string
  • func (j JID) Resource() string
• type Message
  • func (m *Message) GetHeader() *Header
• type Presence
  • func (p *Presence) GetHeader() *Header
• type Roster
  • func (r *Roster) Get() []RosterItem
• type RosterItem
• type RosterQuery
• type Stanza
• type Status
  • func (s Status) Fatal() bool
• type Text
• Bugs

Constants

const (
	// Version of RFC 3920 that we implement.
	XMPPVersion = "1.0"

	// Various XML namespaces.
	NsClient  = "jabber:client"
	NsStreams = "urn:ietf:params:xml:ns:xmpp-streams"
	NsStream  = "http://etherx.jabber.org/streams"
	NsTLS     = "urn:ietf:params:xml:ns:xmpp-tls"
	NsSASL    = "urn:ietf:params:xml:ns:xmpp-sasl"
	NsBind    = "urn:ietf:params:xml:ns:xmpp-bind"
	NsSession = "urn:ietf:params:xml:ns:xmpp-session"
	NsRoster  = "jabber:iq:roster"
)

Variables

var Debug = false

If enabled, print all sent and received XML.

Functions

func NextId

func NextId() string

This function may be used as a convenient way to generate a unique id for an outgoing iq, message, or presence stanza.

Types

type Client

type Client struct {
	// This client's full JID, including resource
	Jid JID

	// Incoming XMPP stanzas from the remote will be published on
	// this channel. Information which is used by this library to
	// set up the XMPP stream will not appear here.
	Recv <-chan Stanza
	// Outgoing XMPP stanzas to the server should be sent to this
	// channel. The application should not close this channel;
	// rather, call Close().
	Send chan<- Stanza

	// The client's roster is also known as the buddy list. It's
	// the set of contacts which are known to this JID, or which
	// this JID is known to.
	Roster Roster
	// Features advertised by the remote.
	Features *Features
	// contains filtered or unexported fields
}

The client in a client-server XMPP connection.

func NewClient

func NewClient(jid *JID, password string, tlsconf tls.Config, exts []Extension,
	pr Presence, status chan<- Status) (*Client, error)

Creates an XMPP client identified by the given JID, authenticating with the provided password and TLS config. Zero or more extensions may be specified. The initial presence will be broadcast. If status is non-nil, connection progress information will be sent on it.

func NewClientFromHost

func NewClientFromHost(jid *JID, password string, tlsconf tls.Config,
	exts []Extension, pr Presence, status chan<- Status, host string,
	port int) (*Client, error)

Connect to the specified host and port. This is otherwise identical to NewClient.

func (*Client) AddRecvFilter

func (cl *Client) AddRecvFilter(filt Filter)

AddRecvFilter adds a new filter to the top of the stack through which incoming stanzas travel on their way up to the client.

func (*Client) AddSendFilter

func (cl *Client) AddSendFilter(filt Filter)

AddSendFilter adds a new filter to the top of the stack through which outgoing stanzas travel on their way down from the client to the network.

func (*Client) Close

func (cl *Client) Close()

func (*Client) SetCallback

func (cl *Client) SetCallback(id string, f func(Stanza))

Register a callback to handle the next XMPP stanza (iq, message, or presence) with a given id. The provided function will not be called more than once. If it returns false, the stanza will not be made available on the normal Client.Recv channel. The callback must not read from that channel, as deliveries on it cannot proceed until the handler returns true or false.

type Data

type Data struct {
	XMLName  xml.Name
	Chardata string `xml:",chardata"`
}

Non-human-readable content of some sort, used by the protocol.

type Error

type Error struct {
	XMLName xml.Name `xml:"error"`
	// The error type attribute.
	Type string `xml:"type,attr"`
	// Any nested element, if present.
	Any *Generic
}

Describes an XMPP stanza error. See RFC 3920, Section 9.3.

func (*Error) Error

func (er *Error) Error() string

type Extension

type Extension struct {
	// Maps from an XML name to a structure which holds stanza
	// contents with that name.
	StanzaTypes map[xml.Name]reflect.Type
	// If non-nil, will be called once to start the filter
	// running. RecvFilter intercepts incoming messages on their
	// way from the remote server to the application; SendFilter
	// intercepts messages going the other direction.
	RecvFilter Filter
	SendFilter Filter
}

Extensions can add stanza filters and/or new XML element types.

type Features

type Features struct {
	Starttls   *starttls `xml:"urn:ietf:params:xml:ns:xmpp-tls starttls"`
	Mechanisms mechs     `xml:"urn:ietf:params:xml:ns:xmpp-sasl mechanisms"`
	Bind       *bindIq
	Session    *Generic
	Any        *Generic
}

type Filter

type Filter func(in <-chan Stanza, out chan<- Stanza)

A filter can modify the XMPP traffic to or from the remote server. It's part of an Extension. The filter function will be called in a new goroutine, so it doesn't need to return. The filter should close its output when its input is closed.

type Generic

type Generic struct {
	XMLName  xml.Name
	Any      *Generic `xml:",any"`
	Chardata string   `xml:",chardata"`
}

Holds an XML element not described by the more specific types.

func (*Generic) String

func (u *Generic) String() string

type Header

type Header struct {
	To       JID    `xml:"to,attr,omitempty"`
	From     JID    `xml:"from,attr,omitempty"`
	Id       string `xml:"id,attr,omitempty"`
	Type     string `xml:"type,attr,omitempty"`
	Lang     string `xml:"http://www.w3.org/XML/1998/namespace lang,attr,omitempty"`
	Innerxml string `xml:",innerxml"`
	Error    *Error
	Nested   []interface{}
}

One of the three core XMPP stanza types: iq, message, presence. See RFC3920, section 9.

type Iq

type Iq struct {
	XMLName xml.Name `xml:"iq"`
	Header
}

iq stanza

func (*Iq) GetHeader

func (iq *Iq) GetHeader() *Header

type JID

type JID string

JID represents an entity that can communicate with other entities. It looks like node@domain/resource. Node and resource are sometimes optional.

func (JID) Bare

func (j JID) Bare() JID

Returns the bare JID, which is the JID without the resource part.

func (JID) Domain

func (j JID) Domain() string

func (JID) Node

func (j JID) Node() string

func (JID) Resource

func (j JID) Resource() string

type Message

type Message struct {
	XMLName xml.Name `xml:"jabber:client message"`
	Header
	Subject []Text `xml:"jabber:client subject"`
	Body    []Text `xml:"jabber:client body"`
	Thread  *Data  `xml:"jabber:client thread"`
}

message stanza

func (*Message) GetHeader

func (m *Message) GetHeader() *Header

type Presence

type Presence struct {
	XMLName xml.Name `xml:"presence"`
	Header
	Show     *Data  `xml:"jabber:client show"`
	Status   []Text `xml:"jabber:client status"`
	Priority *Data  `xml:"jabber:client priority"`
}

presence stanza

func (*Presence) GetHeader

func (p *Presence) GetHeader() *Header

type Roster

type Roster struct {
	Extension
	// contains filtered or unexported fields
}

func (*Roster) Get

func (r *Roster) Get() []RosterItem

Return the most recent snapshot of the roster status. This is updated automatically as roster updates are received from the server. This function may block immediately after the XMPP connection has been established, until the first roster update is received from the server.

type RosterItem

type RosterItem struct {
	XMLName      xml.Name `xml:"jabber:iq:roster item"`
	Jid          JID      `xml:"jid,attr"`
	Subscription string   `xml:"subscription,attr"`
	Name         string   `xml:"name,attr"`
	Group        []string
}

See RFC 3921, Section 7.1.

type RosterQuery

type RosterQuery struct {
	XMLName xml.Name     `xml:"jabber:iq:roster query"`
	Item    []RosterItem `xml:"item"`
}

Roster query/result

type Stanza

type Stanza interface {
	GetHeader() *Header
}

type Status

type Status int

Status of the connection.

var (
	// The client has not yet connected, or it has been
	// disconnected from the server.
	StatusUnconnected Status = statusUnconnected
	// Initial connection established.
	StatusConnected Status = statusConnected
	// Like StatusConnected, but with TLS.
	StatusConnectedTls Status = statusConnectedTls
	// Authentication succeeded.
	StatusAuthenticated Status = statusAuthenticated
	// Resource binding complete.
	StatusBound Status = statusBound
	// Session has started and normal message traffic can be sent
	// and received.
	StatusRunning Status = statusRunning
	// The session has closed, or is in the process of closing.
	StatusShutdown Status = statusShutdown
	// The session has encountered an error. Otherwise identical
	// to StatusShutdown.
	StatusError Status = statusError
)

func (Status) Fatal

func (s Status) Fatal() bool

Does the status value indicate that the client is or has disconnected?

type Text

type Text struct {
	XMLName  xml.Name
	Lang     string `xml:"http://www.w3.org/XML/1998/namespace lang,attr,omitempty"`
	Chardata string `xml:",chardata"`
}

Holds human-readable text, with an optional language specification. Generally multiple instances of these can be found together, allowing the software to choose which language to present to the user.

Notes

Bugs

• Doesn't implement TLS/SASL EXTERNAL.

• This routine leaks one channel each time it's called. Listeners are never removed.

• Doesn't use stringprep. Could try the implementation at "code.google.com/p/go-idn/src/stringprep"