Documentation

Overview

Package disco implements service discovery.

Index

Constants

View Source
const (
	NSInfo  = `http://jabber.org/protocol/disco#info`
	NSItems = `http://jabber.org/protocol/disco#items`
)

Namespaces used by this package.

Variables

View Source
var (
	// Category: The "account" category is to be used by a server when responding to a disco request sent to the bare JID (user@host addresss) of an account hosted by the server.
	// Type: The user@host is an administrative account
	AccountAdmin = Identity{Category: "account", Type: "admin"}

	// Category: The "account" category is to be used by a server when responding to a disco request sent to the bare JID (user@host addresss) of an account hosted by the server.
	// Type: The user@host is a "guest" account that allows anonymous login by any user
	AccountAnonymous = Identity{Category: "account", Type: "anonymous"}

	// Category: The "account" category is to be used by a server when responding to a disco request sent to the bare JID (user@host addresss) of an account hosted by the server.
	// Type: The user@host is a registered or provisioned account associated with a particular non-administrative user
	AccountRegistered = Identity{Category: "account", Type: "registered"}

	// Category: The "auth" category consists of server components that provide authentication services within a server implementation.
	// Type: A server component that authenticates based on external certificates
	AuthCert = Identity{Category: "auth", Type: "cert"}

	// Category: The "auth" category consists of server components that provide authentication services within a server implementation.
	// Type: A server authentication component other than one of the registered types
	AuthGeneric = Identity{Category: "auth", Type: "generic"}

	// Category: The "auth" category consists of server components that provide authentication services within a server implementation.
	// Type: A server component that authenticates against an LDAP database
	AuthLDAP = Identity{Category: "auth", Type: "ldap"}

	// Category: The "auth" category consists of server components that provide authentication services within a server implementation.
	// Type: A server component that authenticates against an NT domain
	AuthNTLM = Identity{Category: "auth", Type: "ntlm"}

	// Category: The "auth" category consists of server components that provide authentication services within a server implementation.
	// Type: A server component that authenticates against a PAM system
	AuthPAM = Identity{Category: "auth", Type: "pam"}

	// Category: The "auth" category consists of server components that provide authentication services within a server implementation.
	// Type: A server component that authenticates against a Radius system
	AuthRadius = Identity{Category: "auth", Type: "radius"}

	// Category: The "automation" category consists of entities and nodes that provide automated or programmed interaction.
	// Type: The node for a list of commands; valid only for the node "http://jabber.org/protocol/commands"
	AutomationCommandList = Identity{Category: "automation", Type: "command-list"}

	// Category: The "automation" category consists of entities and nodes that provide automated or programmed interaction.
	// Type: A node for a specific command; the "node" attribute uniquely identifies the command
	AutomationCommandNode = Identity{Category: "automation", Type: "command-node"}

	// Category: The "automation" category consists of entities and nodes that provide automated or programmed interaction.
	// Type: An entity that supports Jabber-RPC.
	AutomationRpc = Identity{Category: "automation", Type: "rpc"}

	// Category: The "automation" category consists of entities and nodes that provide automated or programmed interaction.
	// Type: An entity that supports the SOAP XMPP Binding.
	AutomationSOAP = Identity{Category: "automation", Type: "soap"}

	// Category: The "automation" category consists of entities and nodes that provide automated or programmed interaction.
	// Type: An entity that provides automated translation services.
	AutomationTranslation = Identity{Category: "automation", Type: "translation"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: An automated client that is not controlled by a human user
	ClientBot = Identity{Category: "client", Type: "bot"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: Minimal non-GUI client used on dumb terminals or text-only screens
	ClientConsole = Identity{Category: "client", Type: "console"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: A client running on a gaming console
	ClientGame = Identity{Category: "client", Type: "game"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: A client running on a PDA, RIM device, or other handheld
	ClientHandheld = Identity{Category: "client", Type: "handheld"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: Standard full-GUI client used on desktops and laptops
	ClientPC = Identity{Category: "client", Type: "pc"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: A client running on a mobile phone or other telephony device
	ClientPhone = Identity{Category: "client", Type: "phone"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: A client that is not actually using an instant messaging client; however, messages sent to this contact will be delivered as Short Message Service (SMS) messages
	ClientSMS = Identity{Category: "client", Type: "sms"}

	// Category: The "client" category consists of different types of clients, mostly for instant messaging.
	// Type: A client operated from within a web browser
	ClientWeb = Identity{Category: "client", Type: "web"}

	// Category: The "collaboration" category consists of services that enable multiple individuals to work together in real time.
	// Type: Multi-user whiteboarding service
	CollaborationWhiteboard = Identity{Category: "collaboration", Type: "whiteboard"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that archives traffic
	ComponentArchive = Identity{Category: "component", Type: "archive"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that handles client connections
	ComponentC2S = Identity{Category: "component", Type: "c2s"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component other than one of the registered types
	ComponentGeneric = Identity{Category: "component", Type: "generic"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that handles load balancing
	ComponentLoad = Identity{Category: "component", Type: "load"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that logs server information
	ComponentLog = Identity{Category: "component", Type: "log"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that provides presence information
	ComponentPresence = Identity{Category: "component", Type: "presence"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that handles core routing logic
	ComponentRouter = Identity{Category: "component", Type: "router"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that handles server connections
	ComponentS2S = Identity{Category: "component", Type: "s2s"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that manages user sessions
	ComponentSM = Identity{Category: "component", Type: "sm"}

	// Category: The "component" category consists of services that are internal to server implementations and not normally exposed outside a server.
	// Type: A server component that provides server statistics
	ComponentStats = Identity{Category: "component", Type: "stats"}

	// Category: The "conference" category consists of online conference services such as multi-user chatroom services.
	// Type: Internet Relay Chat service
	ConferenceIRC = Identity{Category: "conference", Type: "irc"}

	// Category: The "conference" category consists of online conference services such as multi-user chatroom services.
	// Type: Text conferencing service
	ConferenceText = Identity{Category: "conference", Type: "text"}

	// Category: The "directory" category consists of information retrieval services that enable users to search online directories or otherwise be informed about the existence of other XMPP entities.
	// Type: A directory of chatrooms
	DirectoryChatroom = Identity{Category: "directory", Type: "chatroom"}

	// Category: The "directory" category consists of information retrieval services that enable users to search online directories or otherwise be informed about the existence of other XMPP entities.
	// Type: A directory that provides shared roster groups
	DirectoryGroup = Identity{Category: "directory", Type: "group"}

	// Category: The "directory" category consists of information retrieval services that enable users to search online directories or otherwise be informed about the existence of other XMPP entities.
	// Type: A directory of end users (e.g., JUD)
	DirectoryUser = Identity{Category: "directory", Type: "user"}

	// Category: The "directory" category consists of information retrieval services that enable users to search online directories or otherwise be informed about the existence of other XMPP entities.
	// Type: A directory of waiting list entries
	DirectoryWaitinglist = Identity{Category: "directory", Type: "waitinglist"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to AOL Instant Messenger
	GatewayAIM = Identity{Category: "gateway", Type: "aim"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the Facebook IM service
	GatewayFacebook = Identity{Category: "gateway", Type: "facebook"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the Gadu-Gadu IM service
	GatewayGaduGadu = Identity{Category: "gateway", Type: "gadu-gadu"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway that provides HTTP Web Services access
	GatewayHTTPWS = Identity{Category: "gateway", Type: "http-ws"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to ICQ
	GatewayICQ = Identity{Category: "gateway", Type: "icq"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to IRC
	GatewayIRC = Identity{Category: "gateway", Type: "irc"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to Microsoft Live Communications Server
	GatewayLCS = Identity{Category: "gateway", Type: "lcs"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the mail.ru IM service
	GatewayMRIM = Identity{Category: "gateway", Type: "mrim"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to MSN Messenger
	GatewayMSN = Identity{Category: "gateway", Type: "msn"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the MySpace IM service
	GatewayMyspaceim = Identity{Category: "gateway", Type: "myspaceim"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to Microsoft Office Communications Server
	GatewayOCS = Identity{Category: "gateway", Type: "ocs"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the QQ IM service
	GatewayQQ = Identity{Category: "gateway", Type: "qq"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to IBM Lotus Sametime
	GatewaySametime = Identity{Category: "gateway", Type: "sametime"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to SIP for Instant Messaging and Presence Leveraging Extensions (SIMPLE)
	GatewaySimple = Identity{Category: "gateway", Type: "simple"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the Skype service
	GatewaySkype = Identity{Category: "gateway", Type: "skype"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to Short Message Service
	GatewaySMS = Identity{Category: "gateway", Type: "sms"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the SMTP (email) network
	GatewaySMTP = Identity{Category: "gateway", Type: "smtp"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the Tlen IM service
	GatewayTlen = Identity{Category: "gateway", Type: "tlen"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to the Xfire gaming and IM service
	GatewayXfire = Identity{Category: "gateway", Type: "xfire"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to another XMPP service (NOT via native server-to-server communication)
	GatewayXMPP = Identity{Category: "gateway", Type: "xmpp"}

	// Category: The "gateway" category consists of translators between Jabber/XMPP services and non-XMPP services.
	// Type: Gateway to Yahoo! Instant Messenger
	GatewayYahoo = Identity{Category: "gateway", Type: "yahoo"}

	// Category: The "headline" category consists of services that provide real-time news or information (often but not necessarily in a message of type "headline").
	// Type: Service that notifies a user of new email messages.
	HeadlineNewmail = Identity{Category: "headline", Type: "newmail"}

	// Category: The "headline" category consists of services that provide real-time news or information (often but not necessarily in a message of type "headline").
	// Type: RSS notification service.
	HeadlineRSS = Identity{Category: "headline", Type: "rss"}

	// Category: The "headline" category consists of services that provide real-time news or information (often but not necessarily in a message of type "headline").
	// Type: Service that provides weather alerts.
	HeadlineWeather = Identity{Category: "headline", Type: "weather"}

	// Category: The "hierarchy" category is used to describe nodes within a hierarchy of nodes; the "branch" and "leaf" types are exhaustive.
	// Type: A service discovery node that contains further nodes in the hierarchy.
	HierarchyBranch = Identity{Category: "hierarchy", Type: "branch"}

	// Category: The "hierarchy" category is used to describe nodes within a hierarchy of nodes; the "branch" and "leaf" types are exhaustive.
	// Type: A service discovery node that does not contain further nodes in the hierarchy.
	HierarchyLeaf = Identity{Category: "hierarchy", Type: "leaf"}

	// Category: The "proxy" category consists of servers or services that act as special-purpose proxies or intermediaries between two or more XMPP endpoints.
	// Type: SOCKS5 bytestreams proxy service
	ProxyBytestreams = Identity{Category: "proxy", Type: "bytestreams"}

	// Category: Services and nodes that adhere to XEP-0060.
	// Type: A pubsub node of the "collection" type.
	PubsubCollection = Identity{Category: "pubsub", Type: "collection"}

	// Category: Services and nodes that adhere to XEP-0060.
	// Type: A pubsub node of the "leaf" type.
	PubsubLeaf = Identity{Category: "pubsub", Type: "leaf"}

	// Category: Services and nodes that adhere to XEP-0060.
	// Type: A personal eventing service that supports the publish-subscribe subset defined in XEP-0163.
	PubsubPEP = Identity{Category: "pubsub", Type: "pep"}

	// Category: Services and nodes that adhere to XEP-0060.
	// Type: A pubsub service that supports the functionality defined in XEP-0060.
	PubsubService = Identity{Category: "pubsub", Type: "service"}

	// Category: The "server" category consists of any Jabber/XMPP server.
	// Type: Standard Jabber/XMPP server used for instant messaging and presence
	ServerIM = Identity{Category: "server", Type: "im"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server component that stores data in a Berkeley database
	StoreBerkeley = Identity{Category: "store", Type: "berkeley"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server component that stores data on the file system
	StoreFile = Identity{Category: "store", Type: "file"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server data storage component other than one of the registered types
	StoreGeneric = Identity{Category: "store", Type: "generic"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server component that stores data in an LDAP database
	StoreLDAP = Identity{Category: "store", Type: "ldap"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server component that stores data in a MySQL database
	StoreMysql = Identity{Category: "store", Type: "mysql"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server component that stores data in an Oracle database
	StoreOracle = Identity{Category: "store", Type: "oracle"}

	// Category: The "store" category consists of internal server components that provide data storage and retrieval services.
	// Type: A server component that stores data in a PostgreSQL database
	StorePostgres = Identity{Category: "store", Type: "postgres"}
)

Predefined identities generated from the Service Discovery Identities Registry as registered with the XMPP Registrar.

View Source
var ErrSkipItem = errors.New("skip this item")

ErrSkipItem is used as a return value from WalkItemFuncs to indicate that the node named in the call is to be skipped. It is not returned as an error by any function.

Functions

func WalkItem

func WalkItem(ctx context.Context, item Item, s *xmpp.Session, fn WalkItemFunc) error

WalkItem walks the tree rooted at the JID, calling fn for each item in the tree, including root. To query the root, leave item.Node empty. The Name attribute of the query item is ignored.

All errors that arise visiting items are filtered by fn: see the WalkItemFunc documentation for details.

The items are walked in wire order which may make the output non-deterministic.

Types

type Feature

type Feature struct {
	XMLName xml.Name `xml:"http://jabber.org/protocol/disco#info feature"`
	Var     string   `xml:"var,attr"`
}

Feature represents a feature supported by an entity on the network.

func (Feature) TokenReader

func (f Feature) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler.

func (Feature) WriteXML

func (f Feature) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo.

type Identity

type Identity struct {
	XMLName  xml.Name `xml:"http://jabber.org/protocol/disco#info identity"`
	Category string   `xml:"category,attr"`
	Type     string   `xml:"type,attr"`
	Name     string   `xml:"name,attr,omitempty"`
	Lang     string   `xml:"http://www.w3.org/XML/1998/namespace lang,attr,omitempty"`
}

Identity is the type and category of a node on the network. Normally one of the pre-defined Identity types should be used.

func (Identity) TokenReader

func (i Identity) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler.

func (Identity) WriteXML

func (i Identity) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo.

type Info

type Info struct {
	InfoQuery
	Identity []Identity `xml:"identity"`
	Features []Feature  `xml:"feature"`
	Form     *form.Data `xml:"jabber:x:data x,omitempty"`
}

Info is a response to a disco info query.

func GetInfo

func GetInfo(ctx context.Context, node string, to jid.JID, s *xmpp.Session) (Info, error)

GetInfo discovers a set of features and identities associated with a JID and optional node. An empty Node means to query the root items for the JID. It blocks until a response is received.

func GetInfoIQ

func GetInfoIQ(ctx context.Context, node string, iq stanza.IQ, s *xmpp.Session) (Info, error)

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

func (Info) TokenReader

func (i Info) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler.

func (Info) WriteXML

func (i Info) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo.

type InfoQuery

type InfoQuery struct {
	XMLName xml.Name `xml:"http://jabber.org/protocol/disco#info query"`
	Node    string   `xml:"node,attr,omitempty"`
}

InfoQuery is the payload of a query for a node's identities and features.

func (InfoQuery) TokenReader

func (q InfoQuery) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler.

func (InfoQuery) WriteXML

func (q InfoQuery) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo.

type Item

type Item struct {
	XMLName xml.Name `xml:"http://jabber.org/protocol/disco#items item"`
	JID     jid.JID  `xml:"jid,attr"`
	Name    string   `xml:"name,attr,omitempty"`
	Node    string   `xml:"node,attr,omitempty"`
}

Item represents a discovered item.

func (Item) TokenReader

func (i Item) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler.

func (Item) WriteXML

func (i Item) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo.

type ItemIter

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

ItemIter is an iterator over discovered items. It supports paging

func FetchItems

func FetchItems(ctx context.Context, item Item, s *xmpp.Session) *ItemIter

FetchItems discovers a set of items associated with a JID and optional node of the provided item. The Name attribute of the query item is ignored. An empty Node means to query the root items for the JID. It blocks until a response is received.

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

func FetchItemsIQ

func FetchItemsIQ(ctx context.Context, node string, iq stanza.IQ, s *xmpp.Session) *ItemIter

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

func (*ItemIter) Close

func (i *ItemIter) 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 (*ItemIter) Err

func (i *ItemIter) Err() error

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

func (*ItemIter) Item

func (i *ItemIter) Item() Item

Item returns the last roster item parsed by the iterator.

func (*ItemIter) Next

func (i *ItemIter) Next() bool

Next returns true if there are more items to decode.

type ItemsQuery

type ItemsQuery struct {
	XMLName xml.Name `xml:"http://jabber.org/protocol/disco#items query"`
	Node    string   `xml:"node,attr,omitempty"`
}

ItemsQuery is the payload of a query for a node's items.

func (ItemsQuery) TokenReader

func (q ItemsQuery) TokenReader() xml.TokenReader

TokenReader implements xmlstream.Marshaler.

func (ItemsQuery) WriteXML

func (q ItemsQuery) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML implements xmlstream.WriterTo.

type WalkItemFunc

type WalkItemFunc func(level int, item Item, err error) error

WalkItemFunc is the type of function called by WalkItem to visit each item in an item hierarchy. Item nodes are unique and absolute (in particular they should not be treated like paths, even if a particular implementation uses paths for node names).

The error result returned by the function controls how WalkItem continues. If the function returns the special value ErrSkipItem, WalkItem skips the current item. Otherwise, if the function returns a non-nil error, WalkItem stops entirely and returns that error.

The error reports an error related to the item, signaling that WalkItem will not walk into that item. The function may decide how to handle that error, including returning it to stop walking the entire tree.

The function is called before querying for an item to allow SkipItem to bypass the query entirely. If an error occurs while making the query, the function will be called again with the same item to report the error.