authenticate_user 连接事件

实现自定义用户验证。

参数

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

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

SQL 脚本的参数名称	说明	顺序
s.authentication_status	INTEGER。这是一个 INOUT 参数。	1
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

缺省操作

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

注释

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

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

authenticate_user 事件使用如下参数：

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

返回值	authentication_status	说明
V <= 1999	1000	验证成功。
1999 < V <= 2999	2000	验证成功：口令即将失效。
2999 < V <= 3999	3000	验证失败：口令已失效。
3999 < V <= 4999	4000	验证失败。
4999 < V <= 5999	5000	验证失败，因为用户已经在进行同步。
5999 < V	4000	如果返回值大于 5999，则 MobiLink 将其解释为返回值 4000。

username 此可选参数为 MobiLink 用户名。
请参见在脚本中使用远程 ID 和 MobiLink 用户名。
remote_id MobiLink 远程 ID。只有在使用已命名的参数时才能引用远程 ID。
password 可选参数，指示用于进行验证的口令。如果用户不提供口令，则为空。
new_password 此可选参数指示新口令。如果用户不更改口令，则为空。

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

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

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

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

请参见向外部服务器验证。

另请参见

SQL 示例

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

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

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

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

Java 示例

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

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

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

public String 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 ); 
  }
  return ( null );
}

.NET 示例

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

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

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

public string 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; 
  }
  return ( null );
}

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