authenticate_user 连接事件

在下表中，说明部分列出 SQL 数据类型。如果您使用 Java 或 .NET 编写脚本，则应该使用相应的数据类型。请参见SQL-Java 数据类型和SQL-.NET 数据类型。

在 SQL 脚本中，可以按名称或使用问号指定事件参数。不建议使用问号，建议您使用命名参数。不能在一个脚本中混合使用名称和问号。如果使用问号，则参数必须按照如下所示的顺序并且仅当没有指定任何后继参数时才是可选的（例如，如果您想使用参数 2，则必须使用参数 1）。如果使用命名参数，则可以按照任何顺序指定任意参数子集。

SQL 脚本的参数名称	说明	顺序（不建议用于 SQL）
s.authentication_status	INTEGER。这是一个 INOUT 参数。	1
s.authentication_message	VARCHAR(1024)。这是一个 INOUT 参数。提供验证消息。	不适用
s.remote_id	VARCHAR(128)。MobiLink 远程 ID。只有在使用命名参数时才能引用远程 ID。	不适用
s.username	VARCHAR(128)。MobiLink 用户名。	2
s.password	VARCHAR(128)。用于验证目的的口令。如果用户不提供口令，则值为空。	3
s.new_password	VARCHAR(128)。如果它正被用于重置口令，则为新口令。如果用户不更改口令，则此值为空。	4
s.new_remote_id	VARCHAR(128)。MobiLink 远程 ID（如果该远程 ID 在统一数据库中为新 ID）。如果远程 ID 不是新的，则值为空。
s.new_username	VARCHAR(128)。MobiLink 用户名（如果该用户名在统一数据库中为新用户名）。如果用户名不是新的，则值为空。
s.script_version	VARCHAR(128)。可选的 IN 参数，可指定 MobiLink 服务器将用于当前同步的脚本版本字符串传递到此参数。不能使用问号指定此参数。	不适用

使用 MobiLink 内置用户验证机制。

MobiLink 服务器在每个同步开始时执行此事件。该事件在 begin_synchronization 事务之前的事务中执行。

您可以使用此事件并用自定义机制代替内置的 MobiLink 验证机制。您可能希望调用 DBMS 的验证机制，或者实现 MobiLink 的内置机制中没有的功能，如口令失效日期或最小口令长度等。

authenticate_user 事件使用如下参数：

authentication_status authentication_status 参数是必需的。它指示验证是否完全成功，可设置为以下值之一：

返回值	authentication_status	说明
V <= 1999	1000	验证成功。
2000 <= V <= 2999	2000	验证成功：口令即将失效。
3000 <= V <= 3999	3000	验证失败：口令已失效。
4000 <= V <= 4999	4000	验证失败。
5000 <= V <= 5999	5000	无法验证，因为远程 ID 已在使用中。稍后再尝试同步。
6000 <= V	4000	如果返回值大于 5999，则 MobiLink 将其解释为返回值 4000。

该值被发送到客户端，以便用于在客户端上自定义验证行为。

请参见：

authentication_message 该可选参数提供验证消息。
该命名参数在首次用于用户验证脚本之前已经初始化为 NULL。如果脚本采用此命名参数，则随后其返回消息将传递到下一个用户验证脚本。最后一条消息将转换为远程数据库的字符集。

如果在执行用户验证脚本期间未发生错误，则无论用户验证状态如何，都会在处理上载流之前通过 MobiLink 服务器将此消息发送到客户端。

即使用户验证失败也会将此消息发送到客户端。
username 此可选参数为 MobiLink 用户名。
请参见脚本中的远程 ID 和 MobiLink 用户名。
remote_id MobiLink 远程 ID。只有在使用命名参数时才能引用远程 ID。
password 可选参数，指示用于进行验证的口令。如果用户不提供口令，则为空。
new_password 此可选参数指示新口令。如果用户不更改口令，则为空。
new_remote_id 此可选参数指示新远程 ID。如果远程 ID 不是新的，则其为空。
new_username 可选参数指示新用户名。如果用户名不是新的，则其为空。
script_version 此可选参数指定 MobiLink 服务器将用于当前同步的脚本版本字符串传递到此参数。不能使用问号指定此参数。

authenticate_user 事件的 SQL 脚本必须作为存储过程实现。

如果定义了两个验证脚本，并且两个脚本返回不同的 authentication_status 代码，则会使用其中较大的值。

authenticate_user 脚本在事务中与所有验证脚本一起执行。始终提交此事务。

可为 authenticate_user 事件使用一些预定义的脚本，以简化使用 LDAP、IMAP 和 POP3 服务器时的验证。

请参见对外部服务器的验证。

典型的 authenticate_user 脚本是对某一存储过程的调用。该调用中参数的顺序必须与上面的顺序匹配。以下示例使用 ml_add_connection_script 将事件指派给名为 my_auth 的存储过程。

CALL ml_add_connection_script(
'ver1', 'authenticate_user', 'call my_auth ( {ml s.authentication_status}, {ml s.username} )'
)

以下 SQL Anywhere 存储过程只使用用户名进行验证—不进行口令检查。该过程只检查所提供的用户名是否为 ULEmployee 表中列出的一个员工 ID。

CREATE PROCEDURE my_auth( inout @auth_status int, in @user_name varchar(128) )
BEGIN
  IF EXISTS
  ( SELECT * FROM ulemployee
    WHERE emp_id = @user_name )
  THEN
    MESSAGE 'OK' type info to client;
    SET @auth_status = 1000;
  ELSE
    MESSAGE 'Not OK' type info to client;
    SET @auth_status = 4000;
  END IF
END

以下对 MobiLink 系统过程的调用在同步脚本版本 ver1 时将名为 authenticateUser 的 Java 方法注册为 authenticate_user 事件的脚本。此语法用于 SQL Anywhere 统一数据库。

CALL ml_add_java_connection_script(
   'ver1', 'authenticate_user',
   'ExamplePackage.ExampleClass.authenticateUser'
)

以下是 Java 方法 authenticateUser 示例。它调用检查用户口令（并在需要时更改用户口令）的 Java 方法。

public void authenticateUser( 
  ianywhere.ml.script.InOutInteger authStatus,
  String user, 
  String pwd, 
  String newPwd )
  throws java.sql.SQLException {
  // A real authenticate_user handler would
  // handle more authentication code states.
  _curUser = user;
  if( checkPwd( user, pwd ) ) {  
    // Authentication successful.
    if( newPwd != null ) {  
      // Password is being changed.
      if( changePwd( user, pwd, newPwd ) ) {  
        // Authentication OK and password change OK.
        // Use custom code.
        authStatus.setValue( 1001 );
      } else {  
        // Authentication OK but password
        // change failed. Use custom code.
        java.lang.System.err.println( "user: "
         + user + " pwd change failed!" );
        authStatus.setValue( 1002 ); 
      } 
    } else {  
      authStatus.setValue( 1000 ); 
    } 
  } else {  
    // Authentication failed.
    authStatus.setValue( 4000 ); 
  }
  }

以下对 MobiLink 系统过程的调用在同步脚本版本 ver1 时将名为 AuthUser 的 .NET 方法注册为 authenticate_user 连接事件的脚本。此语法用于 SQL Anywhere 统一数据库。

CALL ml_add_dnet_connection_script(
   'ver1', 'authenticate_user',
   'TestScripts.Test.AuthUser'
)

以下是 .NET 方法 AuthUser 示例。它调用检查用户口令（并在需要时更改用户口令）的 .NET 方法。

namespace TestScripts {
public class Test {
    string _curUser = null;
public void AuthUser( 
  ref int authStatus, 
  string user, 
  string pwd, 
  string newPwd ) {
  // A real authenticate_user handler would
  // handle more authentication code states.
  _curUser = user;
  if( CheckPwd( user, pwd ) ) {  
    // Authentication successful.
    if( newPwd != null ) {  
      // Password is being changed.
      if( ChangePwd( user, pwd, newPwd ) ) {  
        // Authentication OK and password change OK.
        // Use custom code.
        authStatus = 1001;
      } else {  
        // Authentication OK but password
        // change failed. Use custom code.
        System.Console.WriteLine( "user: "
         + user + " pwd change failed!" );
        authStatus = 1002; 
      } 
    } else {  
      authStatus = 1000 ; 
    } 
  } else {  
    // Authentication failed.
    authStatus = 4000; 
  }
  }}}

有关使用 .NET 中 C# 编写的 authenticate_user 脚本的更详细示例，请参见.NET 同步示例。

authenticate_user 连接事件

参数

缺省操作

注释

另请参见

SQL 示例

Java 示例

.NET 示例