Commit 535e4272 authored by Rob Pike's avatar Rob Pike

Regularize the comments for the websocket package and document all functions and methods.

R=rsc, ukai
CC=golang-dev
https://golang.org/cl/196044
parent 2d7c1304
......@@ -41,32 +41,32 @@ func newClient(resourceName, host, origin, location, protocol string, rwc io.Rea
return
}
// Dial opens new Web Socket client connection.
//
// A trivial example client is:
//
// package main
//
// import (
// "websocket"
// "strings"
// )
//
// func main() {
// ws, err := websocket.Dial("ws://localhost/ws", "", "http://localhost/");
// if err != nil {
// panic("Dial: ", err.String())
// }
// if _, err := ws.Write(strings.Bytes("hello, world!\n")); err != nil {
// panic("Write: ", err.String())
// }
// var msg = make([]byte, 512);
// if n, err := ws.Read(msg); err != nil {
// panic("Read: ", err.String())
// }
// // msg[0:n]
// }
/*
Dial opens a new client connection to a Web Socket.
A trivial example client is:
package main
import (
"websocket"
"strings"
)
func main() {
ws, err := websocket.Dial("ws://localhost/ws", "", "http://localhost/");
if err != nil {
panic("Dial: ", err.String())
}
if _, err := ws.Write(strings.Bytes("hello, world!\n")); err != nil {
panic("Write: ", err.String())
}
var msg = make([]byte, 512);
if n, err := ws.Read(msg); err != nil {
panic("Read: ", err.String())
}
// use msg[0:n]
}
*/
func Dial(url, protocol, origin string) (ws *Conn, err os.Error) {
parsedUrl, err := http.ParseURL(url)
if err != nil {
......
......@@ -9,32 +9,34 @@ import (
"io"
)
// Handler is a interface that use a WebSocket.
//
// A trivial example server is:
//
// package main
//
// import (
// "http"
// "io"
// "websocket"
// )
//
// // echo back the websocket.
// func EchoServer(ws *websocket.Conn) {
// io.Copy(ws, ws);
// }
//
// func main() {
// http.Handle("/echo", websocket.Handler(EchoServer));
// err := http.ListenAndServe(":12345", nil);
// if err != nil {
// panic("ListenAndServe: ", err.String())
// }
// }
/*
Handler is an interface to a WebSocket.
A trivial example server is:
package main
import (
"http"
"io"
"websocket"
)
// Echo the data received on the Web Socket.
func EchoServer(ws *websocket.Conn) {
io.Copy(ws, ws);
}
func main() {
http.Handle("/echo", websocket.Handler(EchoServer));
err := http.ListenAndServe(":12345", nil);
if err != nil {
panic("ListenAndServe: ", err.String())
}
}
*/
type Handler func(*Conn)
// ServeHTTP implements the http.Handler interface for a Web Socket.
func (f Handler) ServeHTTP(c *http.Conn, req *http.Request) {
if req.Method != "GET" || req.Proto != "HTTP/1.1" ||
req.Header["Upgrade"] != "WebSocket" ||
......
......@@ -2,12 +2,10 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// The websocket package implements Web Socket protocol server.
// The websocket package implements a client and server for the Web Socket protocol.
// The protocol is defined at http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol
package websocket
// References:
// The Web Socket protocol: http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol
// TODO(ukai):
// better logging.
......@@ -18,19 +16,23 @@ import (
"os"
)
// WebSocketAddr is an implementation of net.Addr for Web Sockets.
type WebSocketAddr string
// Network returns the network type for a Web Socket, "websocket".
func (addr WebSocketAddr) Network() string { return "websocket" }
// String returns the network address for a Web Socket.
func (addr WebSocketAddr) String() string { return string(addr) }
// Conn is an channels to communicate over Web Socket.
// Conn is a channel to communicate to a Web Socket.
// It implements the net.Conn interface.
type Conn struct {
// An origin URI of the Web Socket.
// The origin URI for the Web Socket.
Origin string
// A location URI of the Web Socket.
// The location URI for the Web Socket.
Location string
// A subprotocol of the Web Socket.
// The subprotocol for the Web Socket.
Protocol string
buf *bufio.ReadWriter
......@@ -48,6 +50,7 @@ func newConn(origin, location, protocol string, buf *bufio.ReadWriter, rwc io.Re
return ws
}
// Read implements the io.Reader interface for a Conn.
func (ws *Conn) Read(msg []byte) (n int, err os.Error) {
for {
frameByte, err := ws.buf.ReadByte()
......@@ -100,6 +103,7 @@ func (ws *Conn) Read(msg []byte) (n int, err os.Error) {
panic("unreachable")
}
// Write implements the io.Writer interface for a Conn.
func (ws *Conn) Write(msg []byte) (n int, err os.Error) {
ws.buf.WriteByte(0)
ws.buf.Write(msg)
......@@ -108,12 +112,16 @@ func (ws *Conn) Write(msg []byte) (n int, err os.Error) {
return len(msg), err
}
// Close implements the io.Closer interface for a Conn.
func (ws *Conn) Close() os.Error { return ws.rwc.Close() }
// LocalAddr returns the WebSocket Origin for the connection.
func (ws *Conn) LocalAddr() net.Addr { return WebSocketAddr(ws.Origin) }
// RemoteAddr returns the WebSocket locations for the connection.
func (ws *Conn) RemoteAddr() net.Addr { return WebSocketAddr(ws.Location) }
// SetTimeout sets the connection's network timeout in nanoseconds.
func (ws *Conn) SetTimeout(nsec int64) os.Error {
if conn, ok := ws.rwc.(net.Conn); ok {
return conn.SetTimeout(nsec)
......@@ -121,6 +129,7 @@ func (ws *Conn) SetTimeout(nsec int64) os.Error {
return os.EINVAL
}
// SetReadTimeout sets the connection's network read timeout in nanoseconds.
func (ws *Conn) SetReadTimeout(nsec int64) os.Error {
if conn, ok := ws.rwc.(net.Conn); ok {
return conn.SetReadTimeout(nsec)
......@@ -128,6 +137,7 @@ func (ws *Conn) SetReadTimeout(nsec int64) os.Error {
return os.EINVAL
}
// SeWritetTimeout sets the connection's network write timeout in nanoseconds.
func (ws *Conn) SetWriteTimeout(nsec int64) os.Error {
if conn, ok := ws.rwc.(net.Conn); ok {
return conn.SetWriteTimeout(nsec)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment