Connection authentication functionality in a Windows environment

After the application has obtained the information about the connection (from either the registry or the InetLogin structure), the ESQL client-interface DLL performs the following steps:
  1. It copies connection information from the InetLogin structure (or from the registry for undefined InetLogin fields) into a HostInfoStruct structure (see Fields of the HostInfoStruct structure).
  2. It passes a pointer to the HostInfoStruct to the sqlauth() function in the esqlauth.dll to verify connection authentication.

If sqlauth() returns TRUE, the connection is verified and the user can access the server computer. However, if sqlauth() returns FALSE, the connection is refused and access denied. By default, the sqlauth() function returns a value of TRUE.

The parameter passed to sqlauth() is a pointer to a HostInfoStruct structure, which the login.h header file defines. This structure contains the subset of the InetLogin fields that the following table shows.
Table 1. Fields of the HostInfoStruct structure
HostInfoStruct field Data type Purpose
InfxServer char[19] Specifies the value for the INFORMIXSERVER network parameter
Host char[19] Specifies the value for the HOST network parameter
User char[19] Specifies the value for the USER network parameter passed into the sqlauth() function
Pass char[19] Specifies the value for the PASSWORD network parameter passed into the sqlauth() function
AskPassAtConnect char[2] Indicates whether sqlauth() requests a password at connection time passed into the sqlauth() function
Service char[19] Specifies the value for the SERVICE network parameter passed into the sqlauth() function
Protocol char[19] Specifies the value for the PROTOCOL network parameter passed into the sqlauth() function
Options char[20] Reserved for future use
Within sqlauth(), you can access the fields of HostInfoStruct with the pHostInfo pointer, as follows:
if (pHostInfo->AskPassAtConnect)

You can edit all the HostInfoStruct field values. ESQL/C, however, checks only the User and Pass fields of HostInfoStruct.

The following code fragment shows the default sqlauth() function, which the esqlauth.c file contains.
BOOL __declspec( dllexport ) sqlauth ( HostInfoStruct *pHostInfo )
{
   return TRUE;
}
This default action of sqlauth() means that performs no authentication verification when it establishes a connection. To provide verification, you can customize the sqlauth() function. You might want to customize sqlauth() to perform one of the following verification tasks:
  • Validation of the user name

    The function can compare the current user name against a list of valid or invalid user names.

  • Prompt for a password

    The function can check the value of the AskPassAtConnect field in the HostInfoStruct structure when this field is set to Y or y. You can code sqlauth() to display a window that prompts the user to enter a password.

The following steps describe how to create a customized sqlauth() function:
  1. Open the esqlauth.c source file in your system editor. This file is located in the %INFORMIXDIR%\demo\esqlauth directory.
  2. Add to the body of the sqlauth() function the code that performs the desired connection verification. Of the fields in Fields of the HostInfoStruct structure, the sqlauth() function can modify only the User and Pass fields. Make sure that sqlauth() returns TRUE or FALSE to indicate whether to continue with the connection request. Do not modify other code in this file.

Create a version of the esqlauth.dll by compiling the esqlauth.c file and specifying the -target:dll (or -wd) command-line option of the esql command processor. For an example of how to define the sqlauth() function, see the esqlauth.c file in the %INFORMIXDIR%\demo\esqlauth directory.