From 28ef6e1429313e7416fa20f4cac289e9eb3cc9d0 Mon Sep 17 00:00:00 2001
From: Alexander Vdolainen <vdo@askele.com>
Date: Tue, 4 Aug 2015 19:05:14 +0300
Subject: [PATCH] man: added connections_set_authcheck.3;

---
 man/Makefile.am                 |  3 +-
 man/connections_set_authcheck.3 | 74 +++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 man/connections_set_authcheck.3

diff --git a/man/Makefile.am b/man/Makefile.am
index b892a53..ac24965 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,3 +1,4 @@
 man_MANS = sxmsg_rreply.3 connections_create.3 connections_init.3 connections_destroy.3 connections_free.3 \
 	sntl_init.3 connections_setsslserts.3 connections_set_priv.3 connections_get_priv.3 \
-	connections_set_ondestroy.3 connections_set_onpulse.3 connections_set_sslvalidate.3
+	connections_set_ondestroy.3 connections_set_onpulse.3 connections_set_sslvalidate.3 \
+	connections_set_authcheck.3
diff --git a/man/connections_set_authcheck.3 b/man/connections_set_authcheck.3
new file mode 100644
index 0000000..34b612f
--- /dev/null
+++ b/man/connections_set_authcheck.3
@@ -0,0 +1,74 @@
+.TH CONNECTIONS_SET_AUTHCHECK 3 "20 July 2015" "SNTLLv2" "SNTL Library Manual"
+.SH NAME
+connections_set_authcheck \- Set callback for the connection links based on the connections set, called to validate user name and password of the peer.
+.br
+.SH SYNOPSIS
+.B #include <sntl/sntllv2.h>
+.sp
+#define connections_set_authcheck(c, f)
+
+.br
+.sp
+.SH DESCRIPTION
+This macro should be used if you want to setup callback function fired while connection link initiating, and depending on returning value will establish link or destroy it.
+.br
+This macro will set on
+.B c
+connections link set callback
+.B f 
+which is a function pointer of the type:
+.br
+.sp
+.B typedef int (*authcheck_t)(conn_t *);
+.br
+.sp
+It will pass a pointer to the connection link initiating now. Link isn't set fully at this moment and doesn't pass any messages and don't works with channel's operations. To pass initiation to the next stage this function should return 
+.B SNE_SUCCESS.
+In fail case other code error should be returned. It's a good practice to return 
+.B SNE_EPERM
+if username and password mismatch.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.SH BUGS
+None known yet.
+.SH EXAMPLE
+This example shows the code prototype for the simple username and password check:
+.RS
+.nf
+.if t .ft CW
+int logincheck(conn_t *co)
+{
+  perm_ctx_t *ctx = connection_getpctx(co);
+  char *login = ctx->login;
+  char *password = ctx->password;
+
+  /* do checks ... */
+  /* your fail case */return SNE_EPERM;
+  return SNE_SUCCESS; /* all is fine */
+}
+.SH APPLICATION USAGE
+This function should be used on the master service, it will not be called on the client application anyway.
+.SH RATIONALE
+None.
+.SH SEE ALSO
+.BI connections_set_priv(3)
+,
+.BI connections_get_priv(3)
+,
+.BI connections_set_ondestroy(3)
+,
+.BI connections_set_sslvalidate(3)
+,
+.BI connection_getpctx(3)
+,
+.BI connection_getpriv(3)
+,
+.BI connection_setpriv(3)
+.SH COPYRIGHT
+This is a proprietary software. See COPYING for further details.
+.br
+(c) Askele Group 2013-2015 <http://askele.com>
+.SH AUTHOR
+Alexander Vdolainen (vdo@askele.com)