~samwhited/xmpp

21211ec4092412877b0895a8234ac4254df17660 — Sam Whited 1 year, 11 months ago ff49aa4
xmpp: tweak docs about SendElement and IQs
2 files changed, 9 insertions(+), 8 deletions(-)

M doc.go
M session.go
M doc.go => doc.go +3 -2
@@ 83,8 83,8 @@
//
// However, writing individual XML tokens can be tedious and error prone.
// The mellium.im/xmpp/stanza package contains functions and structs that aid in
// the construction of message, presence and IQ elements which have special
// semantics in XMPP and are known as "stanzas".
// the construction of message, presence and info/query (IQ) elements which have
// special semantics in XMPP and are known as "stanzas".
// These can be sent with the Send and SendElement methods.
//
//     // Send initial presence to let the server know we want to receive messages.


@@ 94,6 94,7 @@
// polling for incoming XML on the input stream—and possibly writing to the
// output stream in response—easier, we need a long running goroutine.
// Session includes the Serve method for starting this processing.
//
// Serve provides a Handler with access to the stream but prevents it from
// advancing the stream beyond the current element and always advances the
// stream to the end of the element when the handler returns (even if the

M session.go => session.go +6 -6
@@ 588,17 588,17 @@ func getID(start xml.StartElement) string {
// SendElement transmits the first element read from the provided token reader
// using start as the outermost tag in the encoding.
//
// If the element is an IQ stanza, Send blocks until a response is received and
// then returns a reader from which it can be read.
// If the element is an info/query (IQ) stanza, Send blocks until a response is
// received and then returns a reader from which the response can be read.
// If the input stream is not being processed (a call to Serve is not running),
// SendElement may block forever.
// If the provided context is closed before the response is received SendElement
// immediately returns an error and any response received at a later time must
// be handled separately.
// immediately returns an error and any response received at a later time will
// not be associated with the original request.
// The response does not need to be consumed in its entirety, but it must be
// closed before stream processing will resume.
// If an error is returned, xml.TokenReader will be nil; the converse is not
// necessarily true.
// If the input stream is not being processed (a call to Serve is not running),
// SendElement may block forever.
//
// SendElement is safe for concurrent use by multiple goroutines.
func (s *Session) SendElement(ctx context.Context, r xml.TokenReader, start xml.StartElement) (xmlstream.TokenReadCloser, error) {