protocol/rtsp/rtsp.go: commenting and general clean up.

protocol/rtsp/rtsp.go

@@ -1,3 +1,58 @@
+/*
+NAME
+  rtsp.go
+
+DESCRIPTION
+  rtsp.go provides functionality for forming and sending RTSP requests for
+	methods, DESCRIBE, OPTIONS, SETUP and PLAY.
+
+AUTHORS
+  Saxon A. Nelson-Milton <saxon@ausocean.org>
+
+LICENSE
+ 	This is Copyright (C) 2019 the Australian Ocean Lab (AusOcean).
+
+  It is free software: you can redistribute it and/or modify them
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation, either version 3 of the License, or (at your
+  option) any later version.
+
+  It is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ 	for more details.
+
+  You should have received a copy of the GNU General Public License
+  in gpl.txt.  If not, see http://www.gnu.org/licenses.
+
+	Copyright (c) 2015, T. Jameson Little <t.jameson.little@gmail.com>
+	All rights reserved.
+
+	Redistribution and use in source and binary forms, with or without modification,
+	are permitted provided that the following conditions are met:
+
+	1. Redistributions of source code must retain the above copyright notice, this
+	list of conditions and the following disclaimer.
+
+	2. Redistributions in binary form must reproduce the above copyright notice,
+	this list of conditions and the following disclaimer in the documentation
+	and/or other materials provided with the distribution.
+
+	3. Neither the name of the copyright holder nor the names of its contributors
+	may be used to endorse or promote products derived from this software without
+	specific prior written permission.
+
+	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+	ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+	WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+	DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+	FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+	DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+	SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+	CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+	OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+	OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
 package rtsp
 
 import (
@@ -23,6 +78,7 @@ const (
 	setup    = "SETUP"
 )
 
+// session describes an RTSP session.
 type session struct {
 	cSeq    int
 	url     *url.URL
@@ -30,6 +86,8 @@ type session struct {
 	session string
 }
 
+// NewSession returns a pointer to a new session. The URL u will be parsed and
+// a connection to the RTSP server will be made.
 func NewSession(u string) (*session, error) {
 	s := &session{}
 	var err error
@@ -44,14 +102,17 @@ func NewSession(u string) (*session, error) {
 	return s, nil
 }
 
+// Describe forms and sends an RTSP request of method DESCRIBE to the RTSP server.
 func (s *session) Describe() (*Response, error) {
 	return s.writeRequest(describe, func(req *Request) { req.Header.Add("Accept", "application/sdp") }, nil)
 }
 
+// Options forms and sends an RTSP request of method OPTIONS to the RTSP server.
 func (s *session) Options(urlStr string) (*Response, error) {
 	return s.writeRequest(options, nil, nil)
 }
 
+// Setup forms and sends an RTSP request of method SETUP to the RTSP server.
 func (s *session) Setup(transport string) (*Response, error) {
 	return s.writeRequest(
 		setup,
@@ -64,10 +125,16 @@ func (s *session) Setup(transport string) (*Response, error) {
 	)
 }
 
+// Play forms and sends an RTSP request of method PLAY to the RTSP server
 func (s *session) Play() (*Response, error) {
 	return s.writeRequest(play, func(req *Request) { req.Header.Add("session", s.session) }, nil)
 }
 
+// writeRequest creates an RTSP request of the method given and writes it to the
+// the session connection.
+//
+//headerOp and respOp define any operation that needs
+// to occur to the request or response for the given method.
 func (s *session) writeRequest(method string, headerOp func(*Request), respOp func(*Response)) (*Response, error) {
 	req, err := NewRequest(method, s.nextCSeq(), s.url, nil)
 	if err != nil {
@@ -83,7 +150,7 @@ func (s *session) writeRequest(method string, headerOp func(*Request), respOp fu
 		return nil, err
 	}
 
-	res, err := ReadResponse(s.conn)
+	res, err := ReadResponse(bufio.NewReader(s.conn))
 	if err != nil {
 		return nil, err
 	}
@@ -99,6 +166,7 @@ func (s *session) nextCSeq() string {
 	return strconv.Itoa(s.cSeq)
 }
 
+// Request describes an RTSP request.
 type Request struct {
 	Method        string
 	URL           *url.URL
@@ -110,6 +178,7 @@ type Request struct {
 	Body          io.ReadCloser
 }
 
+// String returns a formatted string of the Request.
 func (r Request) String() string {
 	s := fmt.Sprintf("%s %s %s/%d.%d\r\n", r.Method, r.URL, r.Proto, r.ProtoMajor, r.ProtoMinor)
 	for k, v := range r.Header {
@@ -125,6 +194,7 @@ func (r Request) String() string {
 	return s
 }
 
+// NewRequest returns a pointer to a new Request.
 func NewRequest(method, cSeq string, u *url.URL, body io.ReadCloser) (*Request, error) {
 	req := &Request{
 		Method:     method,
@@ -138,23 +208,22 @@ func NewRequest(method, cSeq string, u *url.URL, body io.ReadCloser) (*Request,
 	return req, nil
 }
 
+// Response describes an RTSP response.
 type Response struct {
 	Proto         string
 	ProtoMajor    int
 	ProtoMinor    int
-
 	StatusCode    int
 	Status        string
-
 	ContentLength int64
-
 	Header        http.Header
 	Body          io.ReadCloser
 }
 
-func (res Response) String() string {
+// String returns a formatted string of the Response.
-	s := fmt.Sprintf("%s/%d.%d %d %s\n", res.Proto, res.ProtoMajor, res.ProtoMinor, res.StatusCode, res.Status)
+func (r Response) String() string {
-	for k, v := range res.Header {
+	s := fmt.Sprintf("%s/%d.%d %d %s\n", r.Proto, r.ProtoMajor, r.ProtoMinor, r.StatusCode, r.Status)
+	for k, v := range r.Header {
 		for _, v := range v {
 			s += fmt.Sprintf("%s: %s\n", k, v)
 		}
@@ -162,75 +231,80 @@ func (res Response) String() string {
 	return s
 }
 
-func ReadResponse(r io.Reader) (res *Response, err error) {
+// ReadResponse will read the response of the RTSP request from the connection,
-	res = new(Response)
+// and return a pointer to a new Response.
+func ReadResponse(b *bufio.Reader) (*Response, error) {
+	res := &Response{}
 	res.Header = make(map[string][]string)
 
-	b := bufio.NewReader(r)
-	var s string
-
 	// TODO: allow CR, LF, or CRLF
-	if s, err = b.ReadString('\n'); err != nil {
+	s, err := b.ReadString('\n')
-		return
+	if err != nil {
+		return nil, err
 	}
 
 	parts := strings.SplitN(s, " ", 3)
-	res.Proto, res.ProtoMajor, res.ProtoMinor, err = ParseRTSPVersion(parts[0])
+	res.Proto, res.ProtoMajor, res.ProtoMinor, err = parseVersion(parts[0])
 	if err != nil {
-		return
+		return nil, err
 	}
 
-	if res.StatusCode, err = strconv.Atoi(parts[1]); err != nil {
+	res.StatusCode, err = strconv.Atoi(parts[1])
-		return
+	if err != nil {
+		return nil, err
 	}
 
 	res.Status = strings.TrimSpace(parts[2])
 
-	// read headers
 	for {
-		if s, err = b.ReadString('\n'); err != nil {
+		s, err = b.ReadString('\n')
-			return
+		if err != nil {
-		} else if s = strings.TrimRight(s, "\r\n"); s == "" {
+			return nil, err
+		}
+
+		s = strings.TrimRight(s, "\r\n")
+		if s == "" {
 			break
 		}
 
-		parts := strings.SplitN(s, ":", 2)
+		parts = strings.SplitN(s, ":", 2)
 		res.Header.Add(strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1]))
 	}
 
-	res.ContentLength, _ = strconv.ParseInt(res.Header.Get("Content-Length"), 10, 64)
+	res.ContentLength, err = strconv.ParseInt(res.Header.Get("Content-Length"), 10, 64)
+	if err != nil {
+		return nil, err
+	}
 
-	res.Body = closer{b, r}
+	res.Body = closer{b}
-	return
+	return res, nil
 }
 
 type closer struct {
 	*bufio.Reader
-	r io.Reader
 }
 
 func (c closer) Close() error {
 	if c.Reader == nil {
 		return nil
 	}
-	defer func() {
 	c.Reader = nil
-		c.r = nil
-	}()
-	if r, ok := c.r.(io.ReadCloser); ok {
-		return r.Close()
-	}
 	return nil
 }
 
-func ParseRTSPVersion(s string) (proto string, major int, minor int, err error) {
+// parseVersion returns the protocol type, major version and minor version.
+func parseVersion(s string) (proto string, maj, min int, err error) {
 	parts := strings.SplitN(s, "/", 2)
 	proto = parts[0]
 	parts = strings.SplitN(parts[1], ".", 2)
-	if major, err = strconv.Atoi(parts[0]); err != nil {
+
+	maj, err = strconv.Atoi(parts[0])
+	if err != nil {
 		return
 	}
-	if minor, err = strconv.Atoi(parts[0]); err != nil {
+
+	min, err = strconv.Atoi(parts[0])
+	if err != nil {
 		return
 	}
 	return