Grammatical, structural and idiomatic formulation edits to MSRP

module documentation.

modules/msrp/README

@@ -10,7 +10,13 @@ Daniel-Constantin Mierla
 
    <[email protected]>
 
-   Copyright © 2012 asipto.com
+Edited by
+
+Alex Balashov
+
+   <[email protected]>
+
+   Copyright © 2012 asipto.com
      __________________________________________________________________
 
    Table of Contents
@@ -84,33 +90,33 @@ Chapter 1. Admin Guide
 1. Overview
 
    This module provides a MSRP routing engine, a.k.a. MSRP relay. MSRP
-   (Message Session Relay Protocol) is defined by RFC4975, the extensions
-   for a MSRP Relay being covered in RFC4976.
-
-   A typical use of MSRP is to do Instant Messaging sessions initiated via
-   SIP. Unlike page-mode instant messaging, which is done via SIP request
-   MESSAGE, MSRP uses a different communication channel, which is
-   negotiated via INVITE-200OK-ACK.
-
-   However, MSRP is still a text based protocol, using several routing
-   mechanisms which are similar with what exists in SIP. Furthermore, MSRP
-   requres TCP (and recommends TLS for confidentiality and security).
-   Considering scalability and perormances of Kamailio for handling
-   TCP/TLS, this module reuses Kamailio's core framework to offer MSRP
-   routing capabilities. Along with embedded Presence and XCAP servers,
-   Kamailio offers now a complete solution for SIP beyond VoIP.
-
-   One of the main benefits with the new module, is the ability to reuse
-   all the other extensions that exist in the SIP server, from accounting,
+   (Message Session Relay Protocol) is defined by RFC4975, and the
+   extensions for an MSRP relay are covered in RFC4976.
+
+   A typical use of MSRP is instant messaging sessions initiated via SIP.
+   Unlike page-mode instant messaging, which is done via the SIP MESSAGE
+   request, MSRP uses a different communication channel which is
+   negotiated via INVITE-200 OK-ACK.
+
+   However, MSRP is still a text-based protocol. It uses several routing
+   mechanisms similar to what exists in SIP. Furthermore, MSRP requres
+   TCP, and recommends TLS for confidentiality and security. In light of
+   the scalability and performance of Kamailio in handling TCP/TLS, this
+   module reuses Kamailio's core framework to offer MSRP routing
+   capabilities. Along with embedded Presence and XCAP servers, Kamailio
+   offers now a complete solution for SIP beyond VoIP.
+
+   One of the main benefits of this module is the ability to reuse all the
+   other extensions that exist in the SIP server, including accounting,
    authentication, authorization to database connectors, security and DoS
-   attacks protections.
+   attack protections.
 
-   Kamailio can handle SIP and MSRP traffic received on the same port, the
+   Kamailio can handle SIP and MSRP traffic received on the same port; the
    appropriate configuration file block being executed based on the type
-   of message. Therefore you can use Kamailio as a stand-alone MSRP relay
-   or have an instance handling both SIP and MSRP. Another option is to
-   configure Kamailio to listen on multiple ports, some of them being used
-   for SIP and others for MSRP.
+   of message. Therefore, you can use Kamailio as a stand-alone MSRP relay
+   or you can have an instance handling both SIP and MSRP. Another option
+   is to configure Kamailio to listen on multiple ports, some of them for
+   SIP and others for MSRP.
 
 2. Dependencies
 
@@ -135,8 +141,8 @@ Chapter 1. Admin Guide
 3.1. sipmsg (int)
 
    If 1, the module will build a SIP message from MSRP frame headers,
-   providing it to event_route[msrp:frame-in]. The all the config file
-   functions (apart of SIP request relaying) that can be used in a request
+   providing it to event_route[msrp:frame-in]. All the config file
+   functions (apart from SIP request relay) that can be used in a request
    route block can be used in msrp event_route.
 
    Default value is '1'.
@@ -156,12 +162,12 @@ modparam("msrp", "sipmsg", 1)
    4.6. msrp_relay_flags(flags)
    4.7. msrp_reply_flags(flags)
 
-4.1. msrp_relay()
+4.1.  msrp_relay()
 
-   Relay MSRP frame according to To-Path. It has to be executed for each
-   MSRP request or reply that has to be forwarded. Note that due to nature
-   of MSRP transport layer which is reliable (TCP/TLS), there is no
-   retransmission of MSRP frames.
+   Relay MSRP frame according to the To-Path. This function has to be
+   executed for each MSRP request or reply that has to be forwarded. Note
+   that due to nature of MSRP transport layer, which is reliable
+   (TCP/TLS), there is no retransmission of MSRP frames.
 
    This function can be used in ANY_ROUTE.
 
@@ -172,11 +178,11 @@ event_route[msrp:frame-in] {
 }
 ...
 
-4.2. msrp_reply(code, text [, hdrs])
+4.2.  msrp_reply(code, text [, hdrs])
 
-   Send a reply for current MSRP request, adding optional headers.
+   Send a reply for the current MSRP request, adding optional headers.
 
-   The parameter can be pseudo-variable.
+   The parameter can be a pseudo-variable.
 
    This function can be used in ANY_ROUTE.
 
@@ -187,7 +193,7 @@ event_route[msrp:frame-in] {
 }
 ...
 
-4.3. msrp_is_request()
+4.3.  msrp_is_request()
 
    Return true if the MSRP frame is a request.
 
@@ -204,7 +210,7 @@ event_route[msrp:frame-in] {
 }
 ...
 
-4.4. msrp_is_reply()
+4.4.  msrp_is_reply()
 
    Return true if the MSRP frame is a reply.
 
@@ -221,12 +227,12 @@ event_route[msrp:frame-in] {
 }
 ...
 
-4.5. msrp_set_dst(addr, sock)
+4.5.  msrp_set_dst(addr, sock)
 
    Set destination attributes: addr - target address as MSRP URI; sock -
    local socket to be used (format 'proto:ip:port').
 
-   The parameter can be pseudo-variable.
+   The parameter can be a pseudo-variable.
 
    This function can be used in ANY_ROUTE.
 
@@ -239,13 +245,13 @@ event_route[msrp:frame-in] {
 }
 ...
 
-4.6. msrp_relay_flags(flags)
+4.6.  msrp_relay_flags(flags)
 
    Set transport layer sending flags for forwarding current MSRP frame;
    flags - a bitmask of flags - 1 (don't create a new connection), 2
    (close connection after send).
 
-   The parameter can be pseudo-variable.
+   The parameter can be a pseudo-variable.
 
    This function can be used in ANY_ROUTE.
 
@@ -258,13 +264,13 @@ event_route[msrp:frame-in] {
 }
 ...
 
-4.7. msrp_reply_flags(flags)
+4.7.  msrp_reply_flags(flags)
 
-   Set transport layer sending flags for replies to current MSRP frame;
-   flags - a bitmask of flags - 1 (don't create a new connection), 2
-   (close connection after send).
+   Set transport layer sending flags for replies to the current MSRP
+   frame; flags - a bitmask of flags - 1 (don't create a new connection),
+   2 (close connection after send).
 
-   The parameter can be pseudo-variable.
+   The parameter can be a pseudo-variable.
 
    This function can be used in ANY_ROUTE.
 
@@ -279,14 +285,14 @@ event_route[msrp:frame-in] {
 
 5. Pseudo Variables
 
-   The module exports a pseudo-variables class $msrp(key) to access the
-   MSRP frame (e.g., first line attributes, body, all frame content).
+   The module exports a pseudo-variable class, $msrp(key), to access the
+   MSRP frame (e.g. first line attributes, body, all frame content).
 
-   The module exports a transformations class 'msrpuri' to be able to
-   access attributes of a MSRP URI.
+   The module exports a transformations class, 'msrpuri', to allow access
+   attributes of a MSRP URI.
 
-   These are documented in the appropriate Wiki pages hosted by the
-   project's web site.
+   These are documented in the appropriate Wiki pages hosted on the
+   project web site.
 
 6. Event Routes
 
@@ -296,13 +302,13 @@ event_route[msrp:frame-in] {
 7. Usage
 
    When 'sipmsg' parameter is set to 1 (which is default), the module
-   builds internally a SIP request from the MSRP frame and gives it to the
-   config file interpreter, in this way all the functions that are valid
-   for SIP requests can be used safe in event_route[msrp:frame-in].
+   internally builds a SIP request from the MSRP frame and exposes it to
+   the config file interpreter. This way, all the functions that are valid
+   for SIP requests can be used safely in event_route[msrp:frame-in].
 
-   To build the SIP request, msrp module takes the first line and the
-   headers from a MSRP message and appends to a static buffer. Next two
-   examples show a MSRP frame and the resulted SIP request.
+   To build the SIP request, the module takes the first line and the
+   headers from an MSRP message and appends them to a static buffer. The
+   next two examples show an MSRP frame and the resulting SIP request.
 ...
 MSRP 6aef SEND
 To-Path: msrps://a.example.org:9000/kjfjan;tcp \
@@ -338,20 +344,20 @@ Content-Type: text/plain
 ...
 
    Note that MSRP does not permit line folding. A "\" in the examples
-   shows a line continuation due to limitations in line length of this
+   shows a line continuation due to the limitations of line length of this
    document. Neither the backslash nor the extra CRLF is included in the
    actual request or response.
 
-   As it can be observed, the MSRP frame content starts with the body of
-   header 'MSRP-First-Line:'. Using a static content to get to a valid SIP
-   request is a perfect trade off for performances.
+   As can be observed, the MSRP frame content starts with the body of the
+   'MSRP-First-Line:' header. Using static content to get to a valid SIP
+   request is a perfect trade-off for performance.
 
-   Besides the option to access parts of MSRP frame via internally build
-   SIP message, msrp module exports a new pseudo-variable class $msrp(key)
-   which returns attributes from the MSRP frame. There is also a new
-   transformation, {msrpuri.key}, to get access to parts of a MSRP URI.
-   See the appropriate Wiki pages on the project's web site for full
-   details about new pseudo-variable and transformation classes.
+   Besides the option to access parts of MSRP frame via an
+   internally-built SIP message, the module exports a new pseudo-variable
+   class $msrp(key) which returns attributes from the MSRP frame. There is
+   also a new transformation, {msrpuri.key}, to get access to parts of an
+   MSRP URI. See the appropriate Wiki pages on the project's web site for
+   full details about new pseudo-variable and transformation classes.
 
    Next is an example of configuration file with the routing block for
    MSRP frames. In this config, the SIP traffic is rejected.

modules/msrp/doc/msrp.xml

@@ -23,6 +23,11 @@
 		<surname>Mierla</surname>
 		<email>[email protected]</email>
 	    </editor>
+	    <editor>
+	      <firstname>Alex</firstname>
+	      <surname>Balashov</surname>
+	      <email>[email protected]</email>
+	    </editor>
 	</authorgroup>
 	<copyright>
 	    <year>2012</year>

modules/msrp/doc/msrp_admin.xml

@@ -18,36 +18,36 @@
 	<para>
 		This module provides a MSRP routing engine, a.k.a. MSRP relay.
 		MSRP (Message Session Relay Protocol) is defined by RFC4975,
-		the extensions for a MSRP Relay being covered in RFC4976.
+		and the extensions for an MSRP relay are covered in RFC4976.
 	</para>
 	<para>
-		A typical use of MSRP is to do Instant Messaging sessions initiated
-		via SIP. Unlike page-mode instant messaging, which is done via SIP
-		request MESSAGE, MSRP uses a different communication channel, which
-		is negotiated via INVITE-200OK-ACK.
+		A typical use of MSRP is instant messaging sessions initiated
+		via SIP. Unlike page-mode instant messaging, which is done via the SIP
+		MESSAGE request, MSRP uses a different communication channel which
+		is negotiated via INVITE-200 OK-ACK.
 	</para>
 	<para>
-		However, MSRP is still a text based protocol, using several routing
-		mechanisms which are similar with what exists in SIP. Furthermore,
-		MSRP requres TCP (and recommends TLS for confidentiality and security).
-		Considering scalability and perormances of &kamailio; for handling
+		However, MSRP is still a text-based protocol.  It uses several routing
+		mechanisms similar to what exists in SIP. Furthermore,
+		MSRP requres TCP, and recommends TLS for confidentiality and security.
+		In light of the scalability and performance of &kamailio; in handling
 		TCP/TLS, this module reuses &kamailio;'s core framework to
 		offer MSRP routing capabilities. Along with embedded Presence and XCAP
 		servers, &kamailio; offers now a complete solution for SIP beyond VoIP.
 	</para>
 	<para>
-		One of the main benefits with the new module, is the ability to reuse
-		all the other extensions that exist in the SIP server, from accounting,
-		authentication, authorization to database connectors, security and
-		DoS attacks protections.
+		One of the main benefits of this module is the ability to reuse
+		all the other extensions that exist in the SIP server, including 
+	        accounting, authentication, authorization to database connectors, 
+		security and DoS attack protections.
 	</para>
 	<para>
-		&kamailio; can handle SIP and MSRP traffic received on the same port,
+		&kamailio; can handle SIP and MSRP traffic received on the same port;
 		the appropriate configuration file block being executed based on the
-		type of message. Therefore you can use &kamailio; as a stand-alone
-		MSRP relay or have an instance handling both SIP and MSRP. Another
+		type of message. Therefore, you can use &kamailio; as a stand-alone
+		MSRP relay or you can have an instance handling both SIP and MSRP. Another
 		option is to configure &kamailio; to listen on multiple ports, some
-		of them being used for SIP and others for MSRP.
+		of them for SIP and others for MSRP.
 	</para>
 	</section>
 
@@ -87,8 +87,8 @@
 		<title><varname>sipmsg</varname> (int)</title>
 		<para>
 			If 1, the module will build a SIP message from MSRP frame headers,
-			providing it to event_route[msrp:frame-in]. The all the config
-			file functions (apart of SIP request relaying) that can be used
+			providing it to event_route[msrp:frame-in].  All the config
+			file functions (apart from SIP request relay) that can be used
 			in a request route block can be used in msrp event_route.
 		</para>
 		<para>
@@ -114,9 +114,9 @@ modparam("msrp", "sipmsg", 1)
 		<function moreinfo="none">msrp_relay()</function>
 	    </title>
 	    <para>
-			Relay MSRP frame according to To-Path. It has to be executed
-			for each MSRP request or reply that has to be forwarded. Note
-			that due to nature of MSRP transport layer which is reliable
+			Relay MSRP frame according to the To-Path. This function has to be 
+			executed for each MSRP request or reply that has to be forwarded. Note
+			that due to nature of MSRP transport layer, which is reliable
 			(TCP/TLS), there is no retransmission of MSRP frames.
 		</para>
 
@@ -140,10 +140,10 @@ event_route[msrp:frame-in] {
 		<function moreinfo="none">msrp_reply(code, text [, hdrs])</function>
 	    </title>
 	    <para>
-		Send a reply for current MSRP request, adding optional headers.
+		Send a reply for the current MSRP request, adding optional headers.
 		</para>
 		<para>
-		The parameter can be pseudo-variable.
+		The parameter can be a pseudo-variable.
 		</para>
 		<para>
 		This function can be used in ANY_ROUTE.
@@ -222,7 +222,7 @@ event_route[msrp:frame-in] {
 		sock - local socket to be used (format 'proto:ip:port').
 		</para>
 		<para>
-		The parameter can be pseudo-variable.
+		The parameter can be a pseudo-variable.
 		</para>
 		<para>
 		This function can be used in ANY_ROUTE.
@@ -251,7 +251,7 @@ event_route[msrp:frame-in] {
 		(close connection after send).
 		</para>
 		<para>
-		The parameter can be pseudo-variable.
+		The parameter can be a pseudo-variable.
 		</para>
 		<para>
 		This function can be used in ANY_ROUTE.
@@ -275,12 +275,12 @@ event_route[msrp:frame-in] {
 		<function moreinfo="none">msrp_reply_flags(flags)</function>
 	    </title>
 	    <para>
-		Set transport layer sending flags for replies to current MSRP frame;
+		Set transport layer sending flags for replies to the current MSRP frame;
 		flags - a bitmask of flags - 1 (don't create a new connection),
 		2 (close connection after send).
 		</para>
 		<para>
-		The parameter can be pseudo-variable.
+		The parameter can be a pseudo-variable.
 		</para>
 		<para>
 		This function can be used in ANY_ROUTE.
@@ -304,17 +304,17 @@ event_route[msrp:frame-in] {
 	<section>
 		<title>Pseudo Variables</title>
 		<para>
-			The module exports a pseudo-variables class $msrp(key) to access
-			the MSRP frame (e.g., first line attributes, body, all frame
+			The module exports a pseudo-variable class, $msrp(key), to access
+			the MSRP frame (e.g. first line attributes, body, all frame
 			content).
 		</para>
 		<para>
-			The module exports a transformations class 'msrpuri' to be able
-			to access attributes of a MSRP URI.
+			The module exports a transformations class, 'msrpuri', to allow
+			access attributes of a MSRP URI.
 		</para>
 		<para>
-			These are documented in the appropriate Wiki pages hosted by the
-			project's web site.
+			These are documented in the appropriate Wiki pages hosted on the
+			project web site.
 		</para>
 	</section>
 
@@ -330,15 +330,14 @@ event_route[msrp:frame-in] {
 		<title>Usage</title>
 		<para>
 			When 'sipmsg' parameter is set to 1 (which is default), the module
-			builds internally a SIP request from the MSRP frame and gives it to
-			the config file interpreter, in this way all the functions that are
-			valid for SIP requests can be used safe in
-			event_route[msrp:frame-in].
+			internally builds a SIP request from the MSRP frame and exposes it to
+			the config file interpreter.  This way, all the functions that are
+			valid for SIP requests can be used safely in event_route[msrp:frame-in].
 		</para>
 		<para>
-			To build the SIP request, msrp module takes the first line and the
-			headers from a MSRP message and appends to a static buffer. Next
-			two examples show a MSRP frame and the resulted SIP request.
+			To build the SIP request, the module takes the first line and the
+			headers from an MSRP message and appends them to a static buffer. The 
+			next two examples show an MSRP frame and the resulting SIP request.
 		</para>
 		<programlisting format="linespecific">
 <![CDATA[
@@ -384,21 +383,21 @@ Content-Type: text/plain
 </programlisting>
 		<para>
 			Note that MSRP does not permit line folding.  A "\" in the examples
-			shows a line continuation due to limitations in line length of this
+			shows a line continuation due to the limitations of line length of this
 			document.  Neither the backslash nor the extra CRLF is included in
 			the actual request or response.
 		</para>
 		<para>
-			As it can be observed, the MSRP frame content starts with the body
-			of header 'MSRP-First-Line:'. Using a static content to get to a
-			valid SIP request is a perfect trade off for performances.
+			As can be observed, the MSRP frame content starts with the body
+			of the 'MSRP-First-Line:' header. Using static content to get to a
+			valid SIP request is a perfect trade-off for performance.
 		</para>
 		<para>
-			Besides the option to access parts of MSRP frame via internally
-			build SIP message, msrp module exports a new pseudo-variable class
-			$msrp(key) which returns attributes from the MSRP frame. There is
+			Besides the option to access parts of MSRP frame via an 
+			internally-built SIP message, the module exports a new pseudo-variable 
+			class $msrp(key) which returns attributes from the MSRP frame. There is
 			also a new transformation, {msrpuri.key}, to get access to parts
-			of a MSRP URI. See the appropriate Wiki pages on the project's
+			of an MSRP URI. See the appropriate Wiki pages on the project's
 			web site for full details about new pseudo-variable and 
 			transformation classes.
 		</para>