mirror of https://github.com/gorilla/websocket.git
104 lines
3.9 KiB
Go
104 lines
3.9 KiB
Go
// Copyright 2013 Gary Burd. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
// Package websocket implements the WebSocket protocol defined in RFC 6455.
|
|
//
|
|
// Overview
|
|
//
|
|
// The Conn type represents a WebSocket connection. A server application calls
|
|
// the Upgrade function from an HTTP request handler to get a pointer to a
|
|
// Conn:
|
|
//
|
|
// func handler(w http.ResponseWriter, r *http.Request) {
|
|
// conn, err := websocket.Upgrade(w, r, nil, 1024, 1024)
|
|
// if _, ok := err.(websocket.HandshakeError); ok {
|
|
// http.Error(w, "Not a websocket handshake", 400)
|
|
// return
|
|
// } else if err != nil {
|
|
// log.Println(err)
|
|
// return
|
|
// }
|
|
// ... Use conn to send and receive messages.
|
|
// }
|
|
//
|
|
// Call the connection WriteMessage and ReadMessages methods to send and
|
|
// receive messages as a slice of bytes. This snippet of code shows how to echo
|
|
// messages using these methods:
|
|
//
|
|
// for {
|
|
// messageType, p, err := conn.ReadMessage()
|
|
// if err != nil {
|
|
// return
|
|
// }
|
|
// if err = conn.WriteMessage(messageType, p); err != nil {
|
|
// return err
|
|
// }
|
|
// }
|
|
//
|
|
// In above snippet of code, p is a []byte and messageType is an int with value
|
|
// websocket.BinaryMessage or websocket.TextMessage.
|
|
//
|
|
// An application can also send and receive messages using the io.WriteCloser
|
|
// and io.Reader interfaces. To send a message, call the connection NextWriter
|
|
// method to get an io.WriteCloser, write the message to the writer and close
|
|
// the writer when done. To receive a message, call the connection NextReader
|
|
// method to get an io.Reader and read until io.EOF is returned. This snippet
|
|
// snippet shows how to echo messages using the NextWriter and NextReader
|
|
// methods:
|
|
//
|
|
// for {
|
|
// messageType, r, err := conn.NextReader()
|
|
// if err != nil {
|
|
// return
|
|
// }
|
|
// w, err := conn.NextWriter(messageType)
|
|
// if err != nil {
|
|
// return err
|
|
// }
|
|
// if _, err := io.Copy(w, r); err != nil {
|
|
// return err
|
|
// }
|
|
// if err := w.Close(); err != nil {
|
|
// return err
|
|
// }
|
|
// }
|
|
//
|
|
// Data Messages
|
|
//
|
|
// The WebSocket protocol distinguishes between text and binary data messages.
|
|
// Text messages are interpreted as UTF-8 encoded text. The interpretation of
|
|
// binary messages is left to the application.
|
|
//
|
|
// This package uses the TextMessage and BinaryMessage integer constants to
|
|
// identify the two data message types. The ReadMessage and NextReader methods
|
|
// return the type of the received message. The messageType argument to the
|
|
// WriteMessage and NextWriter methods specifies the type of a sent message.
|
|
//
|
|
// It is the application's responsibility to ensure that text messages are
|
|
// valid UTF-8 encoded text.
|
|
//
|
|
// Control Messages
|
|
//
|
|
// The WebSocket protocol defines three types of control messages: close, ping
|
|
// and pong. Call the connection WriteControl, WriteMessage or NextWriter
|
|
// methods to send a control message to the peer.
|
|
//
|
|
// Connections handle received ping and pong messages by invoking a callback
|
|
// function set with SetPingHandler and SetPongHandler methods. These callback
|
|
// functions can be invoked from the ReadMessage method, the NextReader method
|
|
// or from a call to the data message reader returned from NextReader.
|
|
//
|
|
// Connections handle received close messages by returning an error from the
|
|
// ReadMessage method, the NextReader method or from a call to the data message
|
|
// reader returned from NextReader.
|
|
//
|
|
// Concurrency
|
|
//
|
|
// A Conn supports a single concurrent caller to the write methods (NextWriter,
|
|
// SetWriteDeadline, WriteMessage) and a single concurrent caller to the read
|
|
// methods (NextReader, SetReadDeadline, ReadMessage). The Close and
|
|
// WriteControl methods can be called concurrently with all other methods.
|
|
//
|
|
package websocket
|