documentation updates

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 637365e4108e7754045aae9a06c668fa58b82dfb..a00ded33fbdb6dd5f1db45b2a4190740ea8c861e 100644 (file)
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -137,10 +137,12 @@ current session using @funcref{gnutls_credentials_set} (see @ref{Authentication
 
 The next step is to setup the underlying transport layer details. The
 Berkeley sockets for TCP are implicitly used by default in GnuTLS, thus a
-call to @funcref{gnutls_transport_set_ptr} would be sufficient to
+call to @funcref{gnutls_transport_set_ptr2} would be sufficient to
 specify the socket descriptor.
 
-@showfuncdesc{gnutls_transport_set_ptr}
+@showfuncdesc{gnutls_transport_set_ptr2}
+
+@showfuncA{gnutls_transport_set_ptr}
 
 If however another transport layer than TCP is selected, then
 the following functions have to be specified.
@@ -174,7 +176,31 @@ has been used. In both cases the following function can be
 used to verify the peer's certificate (see @ref{Certificate authentication}
 for more information).
 
-@showfuncA{gnutls_certificate_verify_peers2} 
+@showfuncA{gnutls_certificate_verify_peers2}
+
+
+@subsection Data transfer and termination
+Once the handshake is complete and peer's identity
+has been verified data can be exchanged. The available
+functions resemble the POSIX @code{recv} and @code{send}
+functions.
+
+@showfuncdesc{gnutls_record_send}
+@showfuncdesc{gnutls_record_recv}
+
+In DTLS it is adviceable to use the extended receive
+function shown below, because it allows the extraction
+of the sequence number. This is required in DTLS because
+messages may arrive out of order.
+
+@showfuncdesc{gnutls_record_recv_seq}
+
+A helper function is available to check whether data
+to be read are pending in a @acronym{GnuTLS} session.
+This is the equivalent in POSIX systems to using @code{select} 
+for data waiting to be read by @code{recv}.
+
+@showfuncdesc{gnutls_record_check_pending}
 
 Once a TLS or DTLS session is no longer needed, it is
 recommended to use @funcref{gnutls_bye} to terminate the
@@ -209,8 +235,8 @@ and proceed to a proper handshake.
 @showfuncdesc{gnutls_dtls_prestate_set}
 
 
-All the above apply to server side only. The client side cookie handling
-is done in @funcref{gnutls_handshake}. However both client and server
+Note that the above apply to server side only. The client side cookie handling
+is part of @funcref{gnutls_handshake}. However both client and server
 side should set the correct maximum transfer unit for
 the layer underneath @acronym{GnuTLS}. This would allow proper fragmentation
 of DTLS messages.

diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 7ab0361cb0395fab7478af18db045d8b7e5d4d21..7575ab719cee13dc01a507240c89f7d8fe14f9fa 100644 (file)
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -111,7 +111,7 @@ will use the Berkeley sockets.
 The record protocol is the secure communications provider. Its purpose
 is to encrypt, authenticate and ---optionally--- compress packets.
 
-@showfuncdesc{gnutls_record_send}
+@showfuncA{gnutls_record_send}
 
 The record layer functions can be called at any time after
 the handshake process is finished, when there is need to receive
@@ -132,10 +132,7 @@ The record protocol initially starts with NULL parameters, which means
 no encryption, and no MAC is used. Encryption and authentication begin
 just after the handshake protocol has finished.
 
-@showfuncdesc{gnutls_record_recv}
-@showfuncdesc{gnutls_record_recv_seq}
-@showfuncdesc{gnutls_record_check_pending}
-@c @showfuncdesc{gnutls_record_get_direction}
+@showfuncD{gnutls_record_recv,gnutls_record_recv_seq,gnutls_record_check_pending,gnutls_record_get_direction}
 
 @menu
 * Encryption algorithms used in the record layer::

diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index 134746084703d72bade69b58d1acfbc529ff2979..23020c4538e762f37fb42af0eb4ee7a5b1281aab 100644 (file)
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -195,7 +195,7 @@ int main()
 @section Callback functions
 @cindex Callback functions
 
-There are several cases where @acronym{GnuTLS} may need some out of
+There are several cases where @acronym{GnuTLS} may need out of
 band input from your program. This is now implemented using some
 callback functions, which your program is expected to register.
 

diff --git a/lib/gnutls_buffers.c b/lib/gnutls_buffers.c
index d7a5d638645cffb0e239999436cfc1eff33519a4..5478b3ffa4bc43ad318e612f2d61d3348049b757 100644 (file)
--- a/lib/gnutls_buffers.c
+++ b/lib/gnutls_buffers.c
@@ -87,7 +87,7 @@ _gnutls_record_buffer_put (gnutls_session_t session,
  * This function checks if there are any data to receive in the gnutls
  * buffers.
  *
- * Returns: the size of that data or 0.
+ * Returns: The size of that data or 0.
  **/
 size_t
 gnutls_record_check_pending (gnutls_session_t session)

diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c
index 46c42bfd7e96d7b97113019ce2910cb74248a026..6c1f72e4ea4c23d746babc8c0f7201b605880178 100644 (file)
--- a/lib/gnutls_record.c
+++ b/lib/gnutls_record.c
@@ -65,7 +65,7 @@ struct tls_record_st {
  *
  * Get TLS version, a #gnutls_protocol_t value.
  *
- * Returns: the version of the currently used protocol.
+ * Returns: The version of the currently used protocol.
  **/
 gnutls_protocol_t
 gnutls_protocol_get_version (gnutls_session_t session)
@@ -143,7 +143,7 @@ gnutls_transport_set_ptr2 (gnutls_session_t session,
  * PUSH and PULL).  This must have been set using
  * gnutls_transport_set_ptr().
  *
- * Returns: first argument of the transport function.
+ * Returns: The first argument of the transport function.
  **/
 gnutls_transport_ptr_t
 gnutls_transport_get_ptr (gnutls_session_t session)
@@ -1200,7 +1200,7 @@ _gnutls_recv_int (gnutls_session_t session, content_type_t type,
  * you could provide a %NULL pointer for data, and 0 for
  * size. cf. gnutls_record_get_direction().
  *
- * Returns: the number of bytes sent, or a negative error code.  The
+ * Returns: The number of bytes sent, or a negative error code.  The
  *   number of bytes sent might be less than @data_size.  The maximum
  *   number of bytes this function can send in a single call depends
  *   on the negotiated maximum record size.
@@ -1237,7 +1237,7 @@ gnutls_record_send (gnutls_session_t session, const void *data,
  * initiated a handshake. In that case the server can only initiate a
  * handshake or terminate the connection.
  *
- * Returns: the number of bytes received and zero on EOF (for stream
+ * Returns: The number of bytes received and zero on EOF (for stream
  * connections).  A negative error code is returned in case of an error.  
  * The number of bytes received might be less than the requested @data_size.
  **/
@@ -1258,12 +1258,10 @@ gnutls_record_recv (gnutls_session_t session, void *data, size_t data_size)
  * This function is the same as gnutls_record_recv(), except that
  * it returns in addition to data, the sequence number of the data.
  * This is useful in DTLS where record packets might be received
- * out-of-order.
- * In DTLS the least significant 48-bits are a unique sequence
- * number, per handshake. If your application is using TLS re-handshakes
- * then the full 64-bits should be used as a unique sequence.
+ * out-of-order. The returned 8-byte sequence number should be
+ * treated as a unique message identification.
  *
- * Returns: the number of bytes received and zero on EOF.  A negative
+ * Returns: The number of bytes received and zero on EOF.  A negative
  *   error code is returned in case of an error.  The number of bytes
  *   received might be less than @data_size.
  *