Source file src/pkg/net/textproto/textproto.go
1 // Copyright 2010 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package textproto implements generic support for text-based request/response 6 // protocols in the style of HTTP, NNTP, and SMTP. 7 // 8 // The package provides: 9 // 10 // Error, which represents a numeric error response from 11 // a server. 12 // 13 // Pipeline, to manage pipelined requests and responses 14 // in a client. 15 // 16 // Reader, to read numeric response code lines, 17 // key: value headers, lines wrapped with leading spaces 18 // on continuation lines, and whole text blocks ending 19 // with a dot on a line by itself. 20 // 21 // Writer, to write dot-encoded text blocks. 22 // 23 // Conn, a convenient packaging of Reader, Writer, and Pipeline for use 24 // with a single network connection. 25 // 26 package textproto 27 28 import ( 29 "bufio" 30 "fmt" 31 "io" 32 "net" 33 ) 34 35 // An Error represents a numeric error response from a server. 36 type Error struct { 37 Code int 38 Msg string 39 } 40 41 func (e *Error) Error() string { 42 return fmt.Sprintf("%03d %s", e.Code, e.Msg) 43 } 44 45 // A ProtocolError describes a protocol violation such 46 // as an invalid response or a hung-up connection. 47 type ProtocolError string 48 49 func (p ProtocolError) Error() string { 50 return string(p) 51 } 52 53 // A Conn represents a textual network protocol connection. 54 // It consists of a Reader and Writer to manage I/O 55 // and a Pipeline to sequence concurrent requests on the connection. 56 // These embedded types carry methods with them; 57 // see the documentation of those types for details. 58 type Conn struct { 59 Reader 60 Writer 61 Pipeline 62 conn io.ReadWriteCloser 63 } 64 65 // NewConn returns a new Conn using conn for I/O. 66 func NewConn(conn io.ReadWriteCloser) *Conn { 67 return &Conn{ 68 Reader: Reader{R: bufio.NewReader(conn)}, 69 Writer: Writer{W: bufio.NewWriter(conn)}, 70 conn: conn, 71 } 72 } 73 74 // Close closes the connection. 75 func (c *Conn) Close() error { 76 return c.conn.Close() 77 } 78 79 // Dial connects to the given address on the given network using net.Dial 80 // and then returns a new Conn for the connection. 81 func Dial(network, addr string) (*Conn, error) { 82 c, err := net.Dial(network, addr) 83 if err != nil { 84 return nil, err 85 } 86 return NewConn(c), nil 87 } 88 89 // Cmd is a convenience method that sends a command after 90 // waiting its turn in the pipeline. The command text is the 91 // result of formatting format with args and appending \r\n. 92 // Cmd returns the id of the command, for use with StartResponse and EndResponse. 93 // 94 // For example, a client might run a HELP command that returns a dot-body 95 // by using: 96 // 97 // id, err := c.Cmd("HELP") 98 // if err != nil { 99 // return nil, err 100 // } 101 // 102 // c.StartResponse(id) 103 // defer c.EndResponse(id) 104 // 105 // if _, _, err = c.ReadCodeLine(110); err != nil { 106 // return nil, err 107 // } 108 // text, err := c.ReadDotAll() 109 // if err != nil { 110 // return nil, err 111 // } 112 // return c.ReadCodeLine(250) 113 // 114 func (c *Conn) Cmd(format string, args ...interface{}) (id uint, err error) { 115 id = c.Next() 116 c.StartRequest(id) 117 err = c.PrintfLine(format, args...) 118 c.EndRequest(id) 119 if err != nil { 120 return 0, err 121 } 122 return id, nil 123 }