commands

Documentation

Overview

Package commands implements executable ad-hoc commands.

Index

• Constants
• Variables
• type Actions
  • func (a Actions) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (i Actions) String() string
  • func (a Actions) TokenReader() xml.TokenReader
  • func (a *Actions) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
  • func (a Actions) WriteXML(w xmlstream.TokenWriter) (n int, err error)
• type Command
  • func (c Command) Execute(ctx context.Context, payload xml.TokenReader, s *xmpp.Session) (Response, xmlstream.TokenReadCloser, error)
  • func (c Command) ExecuteIQ(ctx context.Context, iq stanza.IQ, payload xml.TokenReader, s *xmpp.Session) (resp Response, respPayload xmlstream.TokenReadCloser, err error)
  • func (c Command) ForEach(ctx context.Context, payload xml.TokenReader, s *xmpp.Session, ...) error
  • func (c Command) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (c Command) TokenReader() xml.TokenReader
  • func (c Command) WriteXML(w xmlstream.TokenWriter) (n int, err error)
• type Iter
  • func Fetch(ctx context.Context, to jid.JID, s *xmpp.Session) Iter
  • func FetchIQ(ctx context.Context, iq stanza.IQ, s *xmpp.Session) Iter
  • func (i Iter) Command() Command
• type Note
  • func (n Note) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (n Note) TokenReader() xml.TokenReader
  • func (n Note) WriteXML(w xmlstream.TokenWriter) (int, error)
• type NoteType
  • func (n NoteType) MarshalXMLAttr(name xml.Name) (xml.Attr, error)
  • func (i NoteType) String() string
  • func (n *NoteType) UnmarshalXMLAttr(attr xml.Attr) error
• type Response
  • func (r Response) Cancel() Command
  • func (r Response) Complete() Command
  • func (r Response) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (r Response) Next() Command
  • func (r Response) Prev() Command
  • func (r Response) TokenReader() xml.TokenReader
  • func (r Response) WriteXML(w xmlstream.TokenWriter) (n int, err error)

Constants

const NS = `http://jabber.org/protocol/commands`

NS is the namespace used by commands, provided as a convenience.

Variables

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

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

Types

type Actions

type Actions uint8

Actions represent the next steps that can be performed in multi-stage commands.

const (
	Prev     Actions = 1 << iota // prev
	Next                         // next
	Complete                     // complete

	// Execute is a bitmask that can be used to extract the default action.
	Execute = 0x38
)

A list of possible actions.

func (Actions) MarshalXML

func (a Actions) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML satisfies xml.Marshaler.

func (Actions) String

func (i Actions) String() string

func (Actions) TokenReader

func (a Actions) TokenReader() xml.TokenReader

TokenReader satisfies the xmlstream.Marshaler interface.

func (*Actions) UnmarshalXML

func (a *Actions) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML satisfies xml.Unmarshaler.

func (Actions) WriteXML

func (a Actions) 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 Command

type Command struct {
	JID    jid.JID `xml:"jid,attr"`
	Action string  `xml:"action,attr"`
	Name   string  `xml:"name,attr"`
	Node   string  `xml:"node,attr"`
	SID    string  `xml:"sessionid,attr"`
}

Command is an ad-hoc command that can be executed by a client.

func (Command) Execute

func (c Command) Execute(ctx context.Context, payload xml.TokenReader, s *xmpp.Session) (Response, xmlstream.TokenReadCloser, error)

Execute runs the given command and returns the next command or any errors encountered during processing. The returned tokens are the commands payload(s).

If the response is not nil it must be closed before stream processing will continue.

func (Command) ExecuteIQ

func (c Command) ExecuteIQ(ctx context.Context, iq stanza.IQ, payload xml.TokenReader, s *xmpp.Session) (resp Response, respPayload xmlstream.TokenReadCloser, err error)

ExecuteIQ is like Execute except that it allows you to customize the IQ. Changing the type has no effect.

If the response is not nil it must be closed before stream processing will continue.

func (Command) ForEach

func (c Command) ForEach(ctx context.Context, payload xml.TokenReader, s *xmpp.Session, f func(Response, xml.TokenReader) (Command, xml.TokenReader, error)) error

ForEach executes each command in a multi-command chain, returning when the final command is marked as completed.

func (Command) MarshalXML

func (c Command) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML implements xml.Marshaler.

func (Command) TokenReader

func (c Command) TokenReader() xml.TokenReader

TokenReader satisfies the xmlstream.Marshaler interface.

func (Command) WriteXML

func (c Command) 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 {
	*disco.ItemIter
}

Iter is an iterator over Command's.

func Fetch

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

Fetch requests a list of commands.

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 stanza.IQ, s *xmpp.Session) Iter

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

func (Iter) Command

func (i Iter) Command() Command

Command returns the last command parsed by the iterator.

type Note

type Note struct {
	XMLName xml.Name `xml:"note"`
	Type    NoteType `xml:"type,attr"`
	Value   string   `xml:",cdata"`
}

Note provides information about the status of a command and may be returned as part of the response payload.

func (Note) MarshalXML

func (n Note) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML implements xml.Marshaler.

func (Note) TokenReader

func (n Note) TokenReader() xml.TokenReader

TokenReader satisfies the xmlstream.Marshaler interface.

func (Note) WriteXML

func (n Note) WriteXML(w xmlstream.TokenWriter) (int, error)

WriteXML satisfies the xmlstream.WriterTo interface.

type NoteType

type NoteType int8

NoteType indicates the severity of a note. It should always be one of the pre-defined constants.

const (
	NoteInfo  NoteType = iota // info
	NoteWarn                  // warn
	NoteError                 // error
)

A list of possible NoteType's.

func (NoteType) MarshalXMLAttr

func (n NoteType) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

MarshalXMLAttr satisfies xml.MarshalerAttr.

func (NoteType) String

func (i NoteType) String() string

func (*NoteType) UnmarshalXMLAttr

func (n *NoteType) UnmarshalXMLAttr(attr xml.Attr) error

UnmarshalXMLAttr satisfies xml.UnmarshalerAttr.

type Response

type Response struct {
	stanza.IQ

	Node   string `xml:"node,attr"`
	SID    string `xml:"sessionid,attr"`
	Status string `xml:"status,attr"`
}

Response is the response to a command. It may contain other commands that can be execute in sequence.

func (Response) Cancel

func (r Response) Cancel() Command

Cancel ends the multi-stage command.

func (Response) Complete

func (r Response) Complete() Command

Complete ends the multi-stage command and optionally submits data.

func (Response) MarshalXML

func (r Response) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

MarshalXML implements xml.Marshaler.

func (Response) Next

func (r Response) Next() Command

Next requests the next step in a multi-stage command.

func (Response) Prev

func (r Response) Prev() Command

Prev requests the previous step in a multi-stage command.

func (Response) TokenReader

func (r Response) TokenReader() xml.TokenReader

TokenReader satisfies the xmlstream.Marshaler interface.

func (Response) WriteXML

func (r Response) WriteXML(w xmlstream.TokenWriter) (n int, err error)

WriteXML satisfies the xmlstream.WriterTo interface. It is like MarshalXML except it writes tokens to w.