go-xmpp2: comparison stream.go

equal deleted inserted replaced

-:b839e37b3f29
+:d269d9c0fc8e
 // license that can be found in the LICENSE file.
 // This file contains the three layers of processing for the
 // communication with the server: transport (where TLS happens), XML
 // (where strings are converted to go structures), and Stream (where
-// we respond to XMPP events on behalf of the library client).
+// we respond to XMPP events on behalf of the library client), or send
+// those events to the client.
 package xmpp
 import (
 	"big"
 	"strings"
 	"time"
 	"xml"
 )
+// Callback to handle a stanza with a particular id.
 type stanzaHandler struct {
 	id string
+	// Return true means pass this to the application
 	f func(Stanza) bool
 }
+// TODO Review all these *Client receiver methods. They should
+// probably either all be receivers, or none.
 func (cl *Client) readTransport(w io.Writer) {
 	defer tryClose(cl.socket, w)
 	cl.socket.SetReadTimeout(1e8)
 	p := make([]byte, 1024)
 		if err != nil {
 			log.Printf("unmarshal: %v", err)
 			break
 		}
+		// TODO If it's a Stanza, use reflection to search for
+		// any Unrecognized elements and fill in their
+		// attributes.
 		// Put it on the channel.
 		ch <- obj
 	}
 }
 			break
 		}
 	}
 }
+// TODO This should go away. We shouldn't allow writing of
+// unstructured data.
 func writeText(w io.Writer, ch <-chan *string) {
 	if debug {
 		pr, pw := io.Pipe()
 		go tee(pr, w, "C: ")
 		w = pw
 			}
 		}
 	}
 }
+// TODO Disable this loop until resource binding is
+// complete. Otherwise the app might inject something weird into our
+// negotiation stream.
 func writeStream(srvOut chan<- interface{}, cliIn <-chan interface{}) {
 	defer tryClose(srvOut, cliIn)
 	for x := range cliIn {
 		srvOut <- x
 		return
 	}
 	if fe.Bind != nil {
 		cl.bind(fe.Bind)
+		return
 	}
 }
 // readTransport() is running concurrently. We need to stop it,
 // negotiate TLS, then start it again. It calls waitForSocket() in
 	// Signal that we're going back to the read loop.
 	cl.socketSync.Done()
 }
+// TODO Implement TLS/SASL EXTERNAL.
 func (cl *Client) chooseSasl(fe *Features) {
 	var digestMd5 bool
 	for _, m := range(fe.Mechanisms.Mechanism) {
 		switch strings.ToLower(m) {
 		case "digest-md5":
 		m[key] = value
 	}
 	return m
 }
+// Inverse of parseSasl().
 func packSasl(m map[string]string) string {
 	var terms []string
 	for key, value := range(m) {
 		if key == "" || value == "" || value == `""` {
 			continue
 		terms = append(terms, key + "=" + value)
 	}
 	return strings.Join(terms, ",")
 }
+// Computes the response string for digest authentication.
 func saslDigestResponse(username, realm, passwd, nonce, cnonceStr,
 	authenticate, digestUri, nonceCountStr string) string {
 	h := func(text string) []byte {
 		h := md5.New()
 		h.Write([]byte(text))
 		nonceCountStr + ":" + cnonceStr + ":auth:" +
 		hex(h(a2))))
 	return response
 }
+// Send a request to bind a resource. RFC 3920, section 7.
 func (cl *Client) bind(bind *Unrecognized) {
 	res := cl.Jid.Resource
 	msg := &Iq{Type: "set", Id: cl.NextId(), Any:
 		&Unrecognized{XMLName: xml.Name{Space: nsBind, Local:
 					"bind"}}}
 	}
 	cl.HandleStanza(msg.Id, f)
 	cl.xmlOut <- msg
 }
+// 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.In channel.
 func (cl *Client) HandleStanza(id string, f func(Stanza) bool) {
 	h := &stanzaHandler{id: id, f: f}
 	cl.handlers <- h
 }

changeset 17	d269d9c0fc8e
parent 16	b839e37b3f29
child 19	e923f28d65aa