The Novell Controls for ActiveX and Visual Basic: Logging In

Articles and Tips: article

MORGAN B. ADAIR
Software Engineer
DeveloperNet University

01 Jul 1999

Second in a series of lessons that show how to develop programs that use NDS using Microsoft Visual Basic and the Novell Controls for ActiveX. Illustrates how to use the Session control to log in to an NDS directory from your Visual Basic program.

Introduction
Using the Session Control
Am I Already Logged In?
NDS Context
Nomenclature
Other Login Options
Logging Out
Example Program: Login
Other Session Control Features
Coming Next

Introduction

This article is the second lesson of a series that shows how to develop programs that use Novell Directory Services (NDS) using Microsoft Visual Basic and the Novell Controls for ActiveX. The first article in the series was "Programming with the Novell Controls for ActiveX and Visual Basic: Getting Started," in the June 1999 issue of Novell Developer Notes. These lessons and others on NDS development will appear on the DeveloperNet University Web page at http://developer.novell.com/education/.

This article illustrates how to use the Session control to log in to an NDS directory from your Visual Basic program.

Objective	Using this lesson as a guide, a Visual Basic programmer will be able to use the Session control to log in to an NDS directory.
Prerequisites	Entry-level Visual Basic programming skills, a DeveloperNet subscription (Electronic Level subscription available free at http://developer.novell.com).
Required Items	See "Required Setup."
Optional Items	None.
Required Setup	A NetWare 4 or 5 server, a Win32 workstation (Windows 95/98/NT) with installed software: the appropriate Novell Client for the operating system, Microsoft Visual Basic or Visual Studio, and the Novell Controls for ActiveX.
Development Environment	The procedures discussed in this article were tested using a 200 MHZ Pentium-based workstation with 64 MB RAM, running Windows NT 4.0, a NetWare 4.11 file server, the NetWare Client for NT 4.60, Microsoft Visual Studio 6.0, and the Novell Controls for ActiveX 1/25/99.

Using the Session Control

Before you can use the properties and methods of the Session control, you must add it to your project by selecting "Controls" from the Project menu (or by right-clicking on the Toolbox and selecting "Controls") and clicking on the box next to "Novell Session Control" (see Figure 1).

Figure 1: Adding the Session Control to your project.

After the Session control has been added to your project, its icon appears in Visual Basic's Toolbox. You can then create an instance of the Session control in your program by clicking on the Session control icon, then adding the control to one of your project's forms (see Figure 2).

Figure 2: The Session Control on a Visual Basic form.

Am I Already Logged In?

When your program starts running, the first thing you probably want to know is whether you are already logged in to an NDS directory. The Session control has properties that provide

A list of directories (trees) the workstation is connected to
A list of servers the workstation is connected to
A list of volumes the workstation is connected to (mapped drives)

The ConnectedTrees, ConnectedServers, and ConnectedVolumes properties of the Session control are collections of NWNetworkName objects. Each NWNetworkName has FullName and ShortName properties. The code to put the names of connected directories into a list box would look something like:

For Each Tree in NWSess1.ConnectedTrees

List1.AddItem Tree.ShortName

Next

If NWSess1.ConnectedTrees.Count equals 0, the workstation is not logged in to any NDS directories. The situation with ConnectedServers is not as simple. As part of the protocol used to log in to servers, the NetWare client issues a "Get Nearest Server" packet. The client forms a connection with the first server that responds, so that it can get information about NDS trees and NetWare servers on the network that the workstation can log in to. If the user browses the network, connections the client might make connections with other servers. So it is possible that the Session control's ConnectedServers.Count property could be non-zero, even though the workstation is not logged in to any servers.

NDS Context

You are probably already familiar with the concept of NDS context. Objects in a NDS directory reside in tree-structured container entries. You are probably familiar with Organization and Organizational Unit containers; every directory has a Top container; and some organizations use Country and Locality containers.

There can be multiple directories on a network, and within a directory there can be multiple users with the same user name. When logging in, you uniquely specify the user object you want to log in as by using the object's Full Name or Distinguished Name. The full name consists of:

The directory type
The directory name
Subcontainer(s)
The name of the user object

For example, in the full name:

NDS:\\Novell_Inc\novell\provo\ndi\MAdair

NDS is the directory type, Novell_Inc is the directory name, and \novell\provo\ndi is the subcontainer that contains the user object, MAdair.

The Session control's Login method takes 4 parameters:

FullName the Full Name of the server or directory to log in to
LoginName the Name of the user object to log in as
Password the user's password
ShowUI a boolean value: if True, Session.Login uses the NetWare client's login dialog to get the directory, user name and password; if False, Session.Login logs in using the values passed in the other parameters, without displaying the dialog.

If you don't use the NetWare client login dialog, there are two ways to specify the Full Name of the user object you are logging in as:

Specify the directory type, name, and subcontainer(s) in the FullName parameter, and the user name in the LoginName parameter. For example:
```
FullName:   NDS:\\Novell_Inc\novell\provo\ndi\
LoginName:  MAdair
```
Set the Session.DefaultFullName property to the directory type, name, and subcontainer(s), specify the full name of the directory of server to log in to in FullName, and set LoginName to the name of the user object.
```
DefaultFullName:    NDS:\\Novell_Inc\novell\provo\ndi\
FullName:   NDS:\\Novell_Inc\
LoginName:  MAdair
```

The Session.DefaultFullName is the "default context." If you do not specify directory objects with a full name, NDS will use the default context to resolve references to directory objects. For example, If the default context is set to "NDS:""Novell_Inc"novell"provo"ndi" a reference to a user object name "MAdair" is understood to refer to an object in the NDS:""Novell_Inc"novell"provo"ndi container.

Note a significant difference between NDS directory paths and other path specifications you are familiar with (like Internet URALS or file system paths). With file system paths, the final backslash is optional. For example:

C:\WINDOWS\SYSTEM

and

C:\WINDOWS\SYSTEM\

refer to the same directory. Network directory paths end with the name of the object or container being referenced. Adding a backslash to the end creates an invalid path.

Nomenclature

You may have notice that I've used both "tree" and "directory" to refer to the hierarchical database of network objects maintained by NDS. You will encounter two sets of terms for directory concepts, one from NDS and X.500 directory standard, and one from ActiveX. The table below compares some of these terms:

NDS Term	ActiveX Term	Definition
Tree	Directory	A hierarchical database of resources, such as network users, servers, printers, print queues, and applications.
Class	Layout	A type of network object, like a User or Organization. Each Class or Layout has a set of properties.
Attribute or Property	Field	The set of data fields associated with a directory object Class (Layout).
Syntax	Field Type	The data type of each Field or Attribute.
Object	Entry	A database record in a Directory that represents a network resource. For example, during installation of NDS, you create an Entry of Class User, named Admin.
Distinguished Name	Full Name	The complete name, or path, from an object to the [Root] of the Directory tree.

Other Login Options

Besides logging in to a directory tree, you can also log in to a specific server in a directory tree. You can do this by specifying the server name in the Login method's FullName parameter. For example, to log in to the server named Kathmandu in the \novell\provo\ndi container of the Novell_Inc tree, pass the following string in the FullName parameter:

NDS:\\Novell_Inc\novell\provo\ndi\Kathmandu

You can log in to an individual server in either Bindery or Directory mode. You control this by setting the Session control's Bindery property. The table below gives a brief description of the Session control's attributes.

Attribute	Description
AutoClose	Specifies if the login results window closes automatically.
Bindery	Specifies if the object performs a bindery or a directory login.
CapturedPorts	Returns a collection of captured printer ports.
ConnectedServers	Returns the connected servers.
ConnectedTrees	Returns all connected NDS directories.
ConnectedVolumes	Returns the connected volumes.
ConnectionTab	Specifies if the login dialog displays a connection tab.
DefaultFullName	Sets and returns the user's default NDS directory and context.
DisplayResults	Determines if login results are displayed.
DriveMappings	Returns the network drives mapped for this session.
RunScripts	Specifies if the login will execute the user's login script.
ScriptTab	Specifies if the login dialog shows the script dialog tab.
ServerNames	Returns all servers on the network.
TreeNames	Returns all directories on the network.
VariablesTab	Specifies if the login dialog shows the variables tab.

Logging Out

Logging out of a Directory or server is a simpler process than logging in. The Logout method takes one parameter, the full name of the Directory or server you want to log out of.

Example Program: Login

Login uses the Session control to give you login information about directories you are currently logged in to, allow you to log out of those directories, or log in to other directories on your network. Follow the steps below to create the Login program.

Create a new Standard EXE project.
Rename the project from Project1 to MyLogin.
Rename the project's main form from Form1 to LoginForm. Change LoginForm's Caption property to "Login to an NDS Tree."
Resize LoginForm and create the program's user interface by placing the controls as shown in Figure 3 and as described below.

Figure 3: Login's user interface.
Place a frame in the upper two-thirds of the form, name it LoginAsFrm, and change its Caption property to "Login As."
Place the controls shown in LoginAsFrm.
- Place a combo box control and name it TreesCmb. Change TreesCmb's Sorted property to True and delete the value in its Text property.
- Place 3 text controls, name them ContextTxt, UserNameTxt, and PasswordTxt, and change their Text properties to an empty string.
- Change the PasswordChar property of the PasswordTxt control to an asterisk (*).
- Place a button control, name it LoginBtn, and change its Caption property to "Login."
- Place 4 text controls and change their caption properties to "Tree:," "Context:," "User Name:," and "Password:."
Place another frame in the lower third of the form, name it LoggedFrm and change its Caption property to "Logged NDS Trees."
Place the controls shown in LogoutFrm.
- Place a combo box control and name it LoggedTreeCmb. Change LoggedTreeCmb's Sorted property to True and delete the value in its Text property.
- Place a text control and change its Caption property to "Tree:."
- Place a button control, name it StatusBtn, and change its Caption property to "Get Login Info."
- Place another button control, name it LogoutBtn, and change its Caption property to "Logout."
Place a button control at the bottom of the form, change its name to ExitBtn, and change its Caption property to "Exit."
Add the Session control to the project by selecting "Components" from the Project menu and clicking on the check box next to "Novell Session Control." Place an instance of the Session control anywhere on the Login form (shown in the upper left corner of the form in Figure 3).

Associate code with the various program controls by doing the following:

Double-click on the form to open LoginForm's Form_Load procedure. Type in the code for the procedure as shown below:

Private Sub Form_Load()

    Dim Tree As NWNetworkName



    On Error GoTo Err_Handler

    Err.Clear



`Display list of available trees in TreesCmb box

    For Each Tree In NWSess1.TreeNames

        TreesCmb.AddItem Tree.FullName

    Next



`Select first item in list (as default)

    If (TreesCmb.ListCount > 0) Then

        TreesCmb.Text = TreesCmb.List(0)

    End If



`Display list of connected trees in LoggedTreeCmb box

    For Each Tree In NWSess1.ConnectedTrees

        LoggedTreeCmb.AddItem Tree.FullName

    Next



`Select first item in list (as default)

    If (LoggedTreeCmb.ListCount > 0) Then

        LoggedTreeCmb.Text = LoggedTreeCmb.List(0)

    End If

Exit Sub



Err_Handler:

    MsgBox "Error getting available trees:" + Chr(13) + Str(Err.Number) + " " + 

Err.Description

    Exit Sub

End Sub

Double-click on LoginBtn to open the button's Click procedure. Type in the code for the procedure as shown below:

Private Sub LoginBtn_Click()

    Dim LoggedIn As Boolean

    Dim NewFullName As String



    On Error GoTo Err_Handler

    Err.Clear



`change cursor to hourglass (login could take awhile)

    LoginForm.MousePointer = vbHourglass



`Set context (full name = tree name + context)

    NewFullName = TreesCmb.Text + ContextTxt.Text

    NWSess1.DefaultFullName = NewFullName



`Log in

    LoggedIn = NWSess1.Login(TreesCmb.Text, UserNameTxt.Text, PasswordTxt.Text, False)

    If Not LoggedIn Then

        MsgBox "Login failed"

    Else

        MsgBox "Successfully logged in"

    End If



    `change cursor back to default

    LoginForm.MousePointer = vbDefault



Exit Sub



Err_Handler:

`change cursor back to default

    LoginForm.MousePointer = vbDefault

    MsgBox "Error logging in:" + Chr(13) + Str(Err.Number) + " " + Err.Description

    Exit Sub

Exit Sub

Double-click on StatusBtn to open the button's Click procedure. Type in the code for the procedure as shown below:

Private Sub StatusCmd_Click()

    MsgBox "Logged in to" + Chr(13) + "  " + LoggedTreeCmb.Text + Chr(13) + "As" + 

Chr(13) + "  " + NWSess1.LoginName(LoggedTreeCmb.Text)

End Sub

Double-click on LogoutBtn to open the button's Click procedure. Type in the code for the procedure as shown below:

Private Sub LogoutBtn_Click()

    Dim loggedOut As Boolean



    On Error GoTo Err_Handler

    Err.Clear



    loggedOut = NWSess1.Logout(LoggedTreeCmb.Text)

    If Not loggedOut Then

        MsgBox "Logout failed"

    Else

        MsgBox "Successfully logged out"

    End If

Exit Sub



Err_Handler:

    MsgBox "Error logging out:" + Chr(13) + Str(Err.Number) + " " + Err.Description

    Exit Sub

End Sub

Double-click on ExitBtn to open the button's Click procedure. Type in the code for the procedure as shown below:
```
Private Sub ExitBtn_Click()

    End

End Sub
```
Select "Save Project As" from the File menu to save the program .

When you run the program, it assembles a list of Directories for each of the two combo boxes a list of all available Directories on the network, and a list of Directories you are logged in to. To log in to a Directory, select its name from the combo box containing the names of available directories, enter the context containing the user object you want to log in as, enter a user name and password, then click on the Login button. So to log in as the user object with the full name NDS: Novell_Inc novell provo ndi MAdair, you would enter the following strings in Login's controls:

Tree: Novell_Inc
Context: \novell\provo\ndi
User Name: MAdair

Other Session Control Features

For the sake of completeness, I'll mention the Session control's two events:

OnLogin Occurs after a successful login is established.

OnLogout Occurs when a logged connection to the network is terminated.

These events let you know when Directory or server login status changes, so your program can update any connection-oriented data it may bemaintaining.

Coming Next

Next, we'll be talking about Fields the place where data actually gets stored in the Directory. Watch the DeveloperNet University Web site (http://developer.novell.com/education) for our online courses and downloadable example programs.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.