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