Update sip.lua NSEdoc

https://secwiki.org/w/Nmap/Code_Standards#NSEdoc_best-practices

nselib/sip.lua

@@ -1,35 +1,30 @@
 --- A SIP library supporting a limited subset of SIP commands and methods
 --
 -- The library currently supports the following methods:
---  * REGISTER, INVITE & OPTIONS
+--  * REGISTER
+--  * INVITE
+--  * OPTIONS
 --
 -- Overview
 -- --------
 -- The library consists of the following classes:
 --
--- o SessionData
+-- * SessionData
 --    - Holds session data for the SIP session
---
--- o Session
+-- * Session
 --    - Contains application functionality related to the implemented
 --       SIP methods.
---
--- o Connection
+-- * Connection
 --    - A class containing code related to socket communication.
---
--- o Response
+-- * Response
 --    - A class containing code for handling SIP responses
---
--- o Request
+-- * Request
 --    - A class containing code for handling SIP requests
---
--- o Util
+-- * Util
 --    - A class containing static utility functions
---
--- o SIPAuth
+-- * SIPAuth
 --    - A class containing code related to SIP Authentication
---
--- o Helper
+-- * Helper
 --    - A class containing code used as a primary interface by scripts
 --
 --
@@ -76,7 +71,8 @@ Error = {
 -- The SessionData class
 SessionData = {
 
-  --- Creates a new instance of sessiondata
+  --- Creates a new instance of SessionData
+  -- @name SessionData.new
   -- @return o an instance of SessionData
   new = function(self, o)
     local o = o or {}
@@ -87,54 +83,66 @@ SessionData = {
   end,
 
   --- Sets the session username
+  -- @name SessionData.setUsername
   -- @param user string containing the username
   setUsername = function(self, user) self.user = user end,
 
   --- Sets the session password
+  -- @name SessionData.setPassword
   -- @param pass string containing the password
   setPassword = function(self, pass) self.pass = pass end,
 
   --- Sets the SIP domain
+  -- @name SessionData.setDomain
   -- @param domain string containing the SIP domain
   setDomain = function(self, domain) self.domain = domain end,
 
   --- Sets the ip and port of the remote server
+  -- @name SessionData.setServer
   -- @param host string containing the ip of the remote server
   -- @param port number containing the port of the remote server
   setServer = function(self, host, port) self.server = { host = host, port = port } end,
 
   --- Sets the ip and port of the client
+  -- @name SessionData.setClient
   -- @param host string containing the ip of the client
   -- @param port number containing the port of the client
   setClient = function(self, host, port) self.client = { host = host, port = port } end,
 
   --- Sets the SIP users Full Name
+  -- @name SessionData.setName
   -- @param name string containing the full name of the user
   setName = function(self, name) self.name = name end,
 
   --- Retrieves the username
+  -- @name SessionData.getUsername
   -- @return user string containing the sessions username
   getUsername = function(self) return self.user end,
 
   --- Retrieves the session password
+  -- @name SessionData.getPassword
   -- @return pass string containing the session password
   getPassword = function(self) return self.pass end,
 
   --- Retrieves the SIP domain
+  -- @name SessionData.getDomain
   -- @return domain string containing the SIP domain
   getDomain = function(self) return self.domain end,
 
   --- Retrieves the client IP and port
+  -- @name SessionData.getClient
   -- @return host string containing the client IP
   -- @return port number containing the client port
   getClient = function(self) return self.client.host, self.client.port end,
 
   --- Retrieves the server IP and port
+  -- @name SessionData.getServer
   -- @return host string containing the server IP
   -- @return port number containing the server port
   getServer = function(self) return self.server.host, self.server.port end,
 
   --- Retrieves the SIP users full name
+  -- @name SessionData.getName
   -- @return name string containing the users full name
   getName = function(self) return self.name or "Nmap NSE" end,
 }
@@ -143,13 +151,14 @@ SessionData = {
 Session = {
 
   --- Creates a new session instance
+  -- @name Session.new
   -- @param host table containing the remote host to connect to
   -- @param port table containing the remote port to connect to
   -- @param sessdata instance of SessionData
   -- @param options table containing zero or more of the following options
   --                <code>expires</code> - the expire value in seconds
   --                <code>timeout</code> - the socket timeout in seconds
-  -- @return o containing a new instance of the Session class
+  -- @return a new instance of the Session class
   new = function(self, host, port, sessdata, options)
     local o = {}
     setmetatable(o, self)
@@ -166,6 +175,7 @@ Session = {
   end,
 
   --- Connect the session
+  -- @name Session.connect
   -- @return true on success, false on failure
   -- @return err string containing error message
   connect = function(self)
@@ -184,11 +194,15 @@ Session = {
 
   --- Closes the session
   -- TODO: We should probably send some "closing" packets here
+  -- @name Session.close
   -- @return true on success, false on failure
   close = function(self) return self.conn:close() end,
 
-  --- Sends and SIP invite
-  -- @param uri
+  --- Sends a SIP invite
+  -- @name Session.invite
+  -- @param uri The address to invite
+  -- @return status true on success false on failure
+  -- @return err string containing an error message if status is false
   invite = function(self, uri)
     local request = Request:new(Method.INVITE, self.protocol)
 
@@ -246,6 +260,7 @@ Session = {
   end,
 
   --- Prepares and sends the challenge response authentication to the server
+  -- @name Session.authenticate
   -- @param request instance of the request object requiring authentication
   -- @param authdata string containing authentication data
   -- @return status true on success false on failure
@@ -278,10 +293,10 @@ Session = {
   end,
 
   --- Sends a SIP Request and receives the Response
+  -- @name Session.exch
   -- @param request instance of Request
   -- @return status true on success, false on failure
-  -- @return resp containing a new Response instance
-  --         err containing error message if status is false
+  -- @return a new Response instance or error message if status is false
   exch = function(self, request)
     request:setCseq(self.cseq)
 
@@ -295,6 +310,7 @@ Session = {
   end,
 
   --- Sends a register request to the server
+  -- @name Session.register
   -- @return status true on success, false on failure
   -- @return msg string containing the error message (if status is false)
   register = function(self)
@@ -329,8 +345,10 @@ Session = {
   end,
 
   --- Sends an option request to the server and handles the response
+  -- @name Session.options
   -- @return status true on success, false on failure
-  -- @return response if status is true, nil else.
+  -- @return Response if status is true, nil else.
+  -- @see Response
   options = function(self)
     local req = Request:new(Method.OPTIONS, self.protocol)
     req:setUri("sip:" .. self.sessdata:getServer())
@@ -350,9 +368,10 @@ Session = {
 Connection = {
 
   --- Creates a new SIP Connection
+  -- @name Connection.new
   -- @param host table containing the host to connect to
   -- @param port table containing the port to connect to
-  -- @return o containing a new Connection instance
+  -- @return a new Connection instance
   new = function(self, host, port)
     local o = {}
     setmetatable(o, self)
@@ -364,6 +383,7 @@ Connection = {
   end,
 
   --- Connects to the server
+  -- @name Connection.connect
   -- @return status containing true on success and false on failure
   -- @return err containing the error message (if status is false)
   connect = function(self)
@@ -379,29 +399,37 @@ Connection = {
   end,
 
   --- Sends the data over the socket
+  -- @name Connection.send
   -- @return status true on success, false on failure
+  -- @return error message if status is false
   send = function(self, data)
     return self.socket:send(data)
   end,
 
   --- Receives data from the socket
+  -- @name Connection.recv
   -- @return status true on success, false on failure
+  -- @return error message if status is false
   recv = function(self)
     return self.socket:receive()
   end,
 
   --- Closes the communication channel (socket)
+  -- @name Connection.close
   -- @return true on success false on failure
+  -- @return error message if status is false
   close = function(self)
     return self.socket:close()
   end,
 
   --- Retrieves the client ip and port
+  -- @name Connection.getClient
   -- @return lhost string containing the local ip
   -- @return lport number containing the local port
   getClient = function(self) return self.lhost, self.lport end,
 
   --- Retrieves the server ip and port
+  -- @name Connection.getServer
   -- @return rhost string containing the server ip
   -- @return rport number containing the server port
   getServer = function(self) return ( self.host.ip or self.host ), ( self.port.number or self.port ) end,
@@ -413,8 +441,9 @@ Connection = {
 Response = {
 
   --- Creates a new Response instance
+  -- @name Response.new
   -- @param str containing the data as received over the socket
-  -- @return o table containing a new Response instance
+  -- @return a new Response instance
   new = function(self, str)
     local o = {}
     setmetatable(o, self)
@@ -424,6 +453,7 @@ Response = {
   end,
 
   --- Retrieves a given header value from the response
+  -- @name Response.getHeader
   -- @param name string containing the name of the header
   -- @return value string containing the header value
   getHeader = function(self,name)
@@ -436,24 +466,28 @@ Response = {
   end,
 
   --- Returns the error code from the SIP response
+  -- @name Response.getErrorCode
   -- @return err number containing the error code
   getErrorCode = function(self)
     return tonumber(self.tbl[1]:match("SIP/%d%.%d (%d+)"))
   end,
 
   --- Returns the error message returned by the server
+  -- @name Response.getErrorMessage
   -- @return errmsg string containing the error message
   getErrorMessage = function(self)
     return self.tbl[1]:match("^SIP/%d%.%d %d+ (.+)$")
   end,
 
   --- Returns the message method
+  -- @name Response.getMethod
   -- @return method string containing the method
   getMethod = function(self)
     return self.tbl[1]:match("^(.-)%s.*SIP/2%.0$")
   end,
 
   --- Returns the authentication data from the SIP response
+  -- @name Response.getAuthData
   -- @return auth string containing the raw authentication data
   getAuthData = function(self)
     local auth = self:getHeader("WWW-Authenticate") or self:getHeader("Proxy-Authenticate")
@@ -465,6 +499,7 @@ Response = {
   end,
 
   --- Retrieves the current sequence number
+  -- @name Response.getCSeq
   -- @return cseq number containing the current sequence number
   getCSeq = function(self)
     local cseq = self:getHeader("CSeq")
@@ -478,9 +513,10 @@ Response = {
 Request = {
 
   --- Creates a new Request instance
+  -- @name Request.new
   -- @param method string containing the request method to use
   -- @param proto Used protocol, could be "UDP" or "TCP"
-  -- @return o containing a new Request instance
+  -- @return a new Request instance
   new = function(self, method, proto)
     local o = {}
     setmetatable(o, self)
@@ -500,10 +536,12 @@ Request = {
   end,
 
   --- Sets the sessiondata so that session information may be fetched
+  -- @name Request.setSessionData
   -- @param data instance of SessionData
   setSessionData = function(self, data) self.sessdata = data end,
 
   --- Adds a custom header to the request
+  -- @name Request.addHeader
   -- @param name string containing the header name
   -- @param value string containing the header value
   addHeader = function(self, name, value)
@@ -512,67 +550,83 @@ Request = {
   end,
 
   --- Sets the SIP uri
+  -- @name Request.setUri
   -- @param uri string containing the SIP uri
   setUri = function(self, uri) self.uri = uri end,
 
   --- Sets an error
+  -- @name Request.setError
   -- @param code number containing the error code
   -- @param msg string containing the error message
   setError = function(self, code, msg) self.error = { code = code, msg = msg } end,
 
   --- Sets the request method
-  -- @param method string containing a valid SIP method (@see Method constant)
+  -- @name Request.setMethod
+  -- @param method string containing a valid SIP method
   setMethod = function(self, method) self.method = method end,
 
   --- Sets the sequence number
+  -- @name Request.setCseq
   -- @param seq number containing the sequence number to set
   setCseq = function(self, seq) self.cseq = seq end,
 
   --- Sets the allow header
+  -- @name Request.setAllow
   -- @param allow table containing all of the allowed SIP methods
   setAllow = function(self, allow) self.allow = stdnse.strjoin(", ", allow) end,
 
   --- Sets the request content data
+  -- @name Request.setContent
   -- @param string containing the content data
   setContent = function(self, content) self.content = content end,
 
   --- Sets the requests' content type
+  -- @name Request.setContentType
   -- @param t string containing the content type
   setContentType = function(self, t) self.content_type = t end,
 
   --- Sets the supported SIP methods
+  -- @name Request.setSupported
   -- @param supported string containing the supported methods
   setSupported = function(self, supported) self.supported = supported end,
 
   --- Sets the content-length of the SIP request
+  -- @name Request.setContentLength
   -- @param len number containing the length of the actual request
   setContentLength = function(self, len) self.length = len end,
 
   --- Sets the expires header of the SIP request
+  -- @name Request.setExpires
   -- @param expires number containing the expire value
   setExpires = function(self, expires) self.expires = expires end,
 
   --- Sets the User Agent being used to connect to the SIP server
+  -- @name Request.setUA
   -- @param ua string containing the User-Agent name (defaults to Nmap NSE)
   setUA = function(self, ua) self.ua = ua end,
 
   --- Sets the caller ID information of the SIP request
+  -- @name Request.setCallId
   -- @param cid string containing the callers id
   setCallId = function(self, cid) self.cid = cid end,
 
   --- Sets the maximum forwards allowed of this request
+  -- @name Request.setForwards
   -- @param maxfwd number containing the maximum allowed forwards
   setForwards = function(self, maxfwd) self.maxfwd = maxfwd end,
 
   --- Sets the proxy authentication data
+  -- @name Request.setProxyAuth
   -- @param auth string containing properly formatted proxy authentication data
   setProxyAuth = function(self, auth) self.proxyauth = auth end,
 
   --- Sets the www authentication data
+  -- @name Request.setWWWAuth
   -- @param auth string containing properly formatted proxy authentication data
   setWWWAuth = function(self, auth) self.wwwauth = auth end,
 
   --- Specifies the network protocol being used
+  -- @name Request.setProtocol
   -- @param proto should be either "UDP" or "TCP"
   setProtocol = function(self, proto)
     assert( proto == "UDP" or proto == "TCP", ("Unsupported protocol %s"):format(proto))
@@ -581,6 +635,8 @@ Request = {
 
 
   --- Converts the request to a String suitable to be sent over the socket
+  -- Called automatically by Lua's <code>tostring</code> function.
+  -- @name Request.__tostring
   -- @return ret string containing the complete request for sending over the socket
   __tostring = function(self)
     local data = {}
@@ -677,6 +733,7 @@ Request = {
 Util = {
 
   --- Generates a random string of the requested length.
+  -- @name Util.get_random_string
   -- @param length (optional) The length of the string to return. Default: 8.
   -- @param set    (optional) The set of letters to choose from. Default: upper, lower, numbers, and underscore.
   -- @return The random string.
@@ -705,7 +762,9 @@ Util = {
 SipAuth = {
 
   --- Creates a new SipAuth instance
+  -- @name SipAuth.new
   -- @param auth string containing the auth data as received from the server
+  -- @return a SipAuth instance
   new = function(self, auth)
     local o = {}
     setmetatable(o, self)
@@ -715,22 +774,27 @@ SipAuth = {
   end,
 
   --- Sets the username used for authentication
+  -- @name SipAuth.setUsername
   -- @param username string containing the name of the user
   setUsername = function(self, username) self.username = username end,
 
   --- Sets the password used for authentication
+  -- @name SipAuth.setPassword
   -- @param password string containing the password of the user
   setPassword = function(self, password) self.password = password end,
 
   --- Sets the method used for authentication
+  -- @name SipAuth.setMethod
   -- @param method string containing the method (Usually REGISTER)
   setMethod = function(self, method) self.method = method end,
 
   --- Sets the uri used for authentication
+  -- @name SipAuth.setUri
   -- @param uri string containing the uri (Usually sip:<ip>)
   setUri = function(self, uri) self.uri = uri end,
 
   --- Processes and parses a challenge as received from the server
+  -- @name SipAuth.parseChallenge
   parseChallenge = function(self)
     if ( not(self.auth) ) then return end
     self.nonce = self.auth:match("nonce=[\"]([^,]-)[\"]")
@@ -741,6 +805,7 @@ SipAuth = {
   end,
 
   --- Calculates the authentication response
+  -- @name SipAuth.calculateResponse
   -- @return response string containing the authentication response
   calculateResponse = function(self)
 
@@ -763,6 +828,7 @@ SipAuth = {
   end,
 
   --- Creates the complete authentication response
+  -- @name SipAuth.createResponse
   -- @return auth string containing the complete authentication digest
   createResponse = function(self)
     local response = self:calculateResponse()
@@ -777,11 +843,12 @@ SipAuth = {
 Helper = {
 
   --- Creates a new instance of the Helper class
+  -- @name Helper.new
   -- @param host table containing the remote host
   -- @param port table containing the remote port
-  -- @param options table containing any options to pass along to the
-  --                session (@see Session:new for more details)
-  -- @return o containing a new instance of the Helper class
+  -- @param options table containing any options to pass along to the session
+  -- @see Session.new
+  -- @return a new instance of the Helper class
   new = function(self, host, port, options)
     local o = {}
     setmetatable(o, self)
@@ -794,12 +861,19 @@ Helper = {
   end,
 
   --- Connects the helper instance
+  -- @name Helper.connect
+  -- @return true on success, false on failure
+  -- @return err string containing error message
   connect = function(self) return self.session:connect() end,
 
   --- Disconnects and closes the helper instance
+  -- @name Helper.close
+  -- @return true on success, false on failure
+  -- @return err string containing error message
   close = function(self) return self.session:close() end,
 
   --- Sets the credentials used when performing authentication
+  -- @name Helper.setCredentials
   -- @param username string containing the username to use for authentication
   -- @param password string containing the password to use for authentication
   setCredentials = function(self, username, password)
@@ -808,10 +882,12 @@ Helper = {
   end,
 
   --- Sets the SIP domain
+  -- @name Helper.setDomain
   -- @param domain string containing the domain name
   setDomain = function(self, domain) self.sessdata:setDomain(domain) end,
 
   --- Register the UAC with the server
+  -- @name Helper.register
   -- @param options table containing zero or more options
   --                (@see Session:register for more details)
   -- @return status true on success, false on failure
@@ -822,9 +898,15 @@ Helper = {
     return true
   end,
 
+  --- Sends an option request to the server and handles the response
+  -- @name Helper.register
+  -- @return status true on success, false on failure
+  -- @return Response if status is true, nil else.
+  -- @see Response
   options = function(self) return self.session:options() end,
 
   --- Attempts to INVITE the user at uri to a call
+  -- @name Helper.invite
   -- @param uri string containing the sip uri
   -- @return status true on success, false on failure
   invite = function(self, uri)