Novell is now a part of Micro Focus

Overview of Novell's Net2000 ActiveX Controls, Part 1

Articles and Tips: article

CHRIS ANDREW
Net2000 Engineer Manager
Developer Services Division

01 Nov 1996


First in a series of articles describing a set of software components to be used by programmers on the Win32 desktop who want to interface with Novell services.

Introduction

This DevNote (the first in a two-part series) describes a set of software components intended to be used by programmers on the Win32 desktop platform who have a need to interface with Novell NetWare services. This is a working specification that is subject to change.

The most important component in the set is the Directory which wrappers the NDS service and allows Visual Basic, Delphi and PowerBuilder programmers an easy and efficient way to create directory-enabled network applications. Note that the Directory component is key to understanding how the other components function. For example, the RAD programmer will learn to use the NDS full name in order to refer to other services that are present in the network. The programming model for these and all subsequent components will attempt to create a directory-centric environment where the user will cease to view the network as a collection of hard-wired boxes that have been cabled together, but rather an organized hierarchy of users, services and information.

The NetworkSession component handles the task of establishing connectivity with the NetWare network. It also allows the RAD programmer to map and unmap network drives that might be needed during the execution of a distributed application.

VolumeAdministration, ServerAdministration and PrintQueueAdministration components (discussed in Part 2) are a simple interface that the RAD programmer can use in creating his own network admin application that manages such features as which users have access to a given disk volume and so on. Finally, the ServiceDatabase component (also discussed in Part 2) permits the RAD programmer to access information stored in the legacy Bindery database that has been superceded by the Directory Services tree. This may prove very useful in mixed networks where not all servers have yet been upgraded to NetWare 4.x

Note that each of the OCX components described below may have one or many different types of sub-objects contained in or enumerated by it. In other words, a well factored OCX component is not necessarily just a single level interface of methods and properties.

It is also important to note that while the previous versions of AppWare ALMs that addressed this same problem space were tightly coupled visual components, this specification instead clearly illustrates the principle of model-view separation. In other words, the actual interface with the network services are represented as non-visual software components. However they are also constructed in such a way as to easily interface with a wide variety of commonly available visual components such as the TreeView, ListView, IconView, and so on. In order to maintain the same ease-of-use characteristics as their AppWare counterparts, each non-visual OCX will come with complete instructions and sample code showing a variety of ways in which to hook it into commonly available viewer components.

The terminology used in this specification is mostly derived from the NDS Specification; however please note that a deliberate attempt has been made to reduce the number of alien concepts that a RAD programmer must learn before being able to use these controls. For that reason, NetWare and NDS terms such as Schema, Distinguished Name, Syntax, Attribute, DiskRestriction and so on should not appear in the online help documentation for these controls. Consider the following:


NetWareTerm
Substitution

NDS Tree

Directory

NDS Syntax

Field Type

NDS Attribute

Field

NDS Object

Entry

NDS Class

Layout

NDS Schema

Layouts in the Directory

Disk Restriction

User Space Limit

Distinguished Name

Full Name

In this specification, objects are described in terms of their Properties, Methods and Events. Note that properties are categorized as RW or RO to indicate whether they are read only, and properties that should appear on a components property page and property sheet at design time are also marked with an asterisk ( "*" ).

Changes from Previous Beta Level OCX Controls

General modifications to the current codebase:

  • Error codes should be defined constants in the Type Library

  • Toolbox bitmap designs need to be improved

  • Make method and property names more "VB-friendly"

  • Controls do not need to be licensed, we will be giving them away

  • Use OLE-style enumerations where possible

  • Methods must use optional and named arguments where appropriate

  • Make all controls non-visual, but easily capable of driving standard tree & list OCXs.

  • Don't use BeginBrowse/FillList methods--controls should fill themselves automatically at run time when the TreeName and ContextName properties have been set.

  • Each and every design time property must be accessible through a property page, since some visual builders do not appear to always support the "property sheet" metaphor seen in Microsoft Visual Basic.

  • All image and text resources must be in a resource file ready for internationalization if that ever becomes a requirement.

  • Place all the NetWare OCXs into a single OCXDLL to eliminate possibility of replicating the same code into multiple DLLS. Dynamically link to the MFC runtime library to minimize size of the binary DLLs.

  • Ensure that the OCX controls can load in both Win95 and WinNT environments even though the NetWare client code is completely different. This is probably best achieved by putting all NetWare functionality in an external DLL (thus one version of the DLL can be installed for Win95, and another for WinNT).

  • Properties that are not modifiable at design time should probably not be listed in the property sheet in most cases.

  • Ensure that all properties support the property-sheet editing metaphor correctly. For example, some properties may need to be edited in a popup dialog (eg: Context) whereas others might require a drop-down enumeration (eg: TreeName).

  • All design-time properties must be made to persist using the normal OCX property exchange mechanisms.

  • Use ActiveX dual interfaces wherever possible throughout the source code. The developer SDK will ship with the C++header files for all dual interfaces that are defined by the components to facilitate high performance access from compiled-- / C++ applications.

The following OCX Controls are no longer needed:Server/Tree List Control, NDS Object List & Tree Control, Volume List Control, NDS Class List Control, NDS Attribute List Control, and NDS Syntax List Control.

Network Session Control

Description: This non-visual control provides an abstraction layer to NW authentication methods. The primary purpose of this control will be to display the standard Novell Client32 login dialog in order to permit an application to perform network login for a particular user.

The network session is also capable of enumerating the NDS distinguished names of all the currently connected volumes and servers. This permits the VolumeAdministration and ServerAdministration controls to be used with the currently connected network resources, as well as with any other resource found through the directory. To the RAD programmer, each resource has only one nameCthe name given to it by NetWare Directory Services.

Methods:


longLogin( Resource, LoginName, Password, ShowUI)

Logon to the network, showing UI if necessary.Note that LoginName and Password are both optionalparameters that can be omitted.

booleanLogout( hdlLogin )

Logout of the network.

Events:


OnLogin(hdlLogin, LoginName, Resource )

Sentafter a successful login connection.

OnLogout(hdlLogin, LoginName, Resource )

Sentwhen a login connection to the network is terminated.

Properties:


RW*

DefaultContextName

NDS context name

RW*

DefaultTreeName

NDS tree name

RW*

AutoClose

Close dialog after login script has run

RW*

Bindery

TRUE for a bindery connection

RW*

ShowConnectionTab

TRUEto show the connection tab in the login dlg

RW*

ShowScriptTab

TRUEto show the login script tab in the login dlg

RW*

ShowUI

FALSEto perform a "silent" login

RO

DriveMappings

Mappeddrives in this session

RO

ConnectedServers

FullNamesof all servers that are connected to

RO

ConnectedVolumes

FullNamesof all volumes that are connected to

NWDriveMapping Object

Description: Used as a data structure that represents currently mapped drives in network session to Visual Basic programmer.

Properties:


RO

DriveLetter

Logicaldrive mapping (eg: Z:)

RO

NetworkPath

UNCname of network path (eg: \\svr1\dev\util)

RO

MappedAsRoot

Waspath mapped as the root ?

NWDriveMappings Enumerator

Description: This iterator enumerates the drive mappings for the current network session. It can also be used to dynamically add or remove drive mappings that may be required by the RAD application while it is executing

Non-standard methods:


NWDriveMapping*Add( DriveLetter, NetworkPath, MapAsRoot)

Mapthe given UNC network path as a logical network drive on the machine. If bMapRoot is TRUE,the given network directory will be mapped as the root of the logical drive-otherwisetheroot of the logical drive will be the root of the volume on which it is located.The MapAsRootparameter is optional, with a default value of FALSE.

booleanRemove( DriveLetter )

Removean existing drive mapping. Note that this may include the remapping of a network drive that was automatically mapped by a login script;hence this method must always be used with care.

Directory Control

Description: This non-visual control provides a simple abstraction of the NDS Directory Tree that can be used to extract information from any object within the directory. It should also be possible to enumerate the elements at a given level within the tree, add new elements, and remove existing elements (provided that the user has an appropriate authorization level).

Instead of being a separated set of independent controls, the available NDS schema within a given tree will be represented as an enumerated set of LayoutDescription objects. Each LayoutDescription object will be capable of enumerating its Attribute names and Syntaxes. Note that the terminology of NDS will not be surfaced to the Visual Basic programmer to avoid confusion between VB "Objects" and NDS "Objects", the meaning of a "Syntax", "Schema", and so on.

As an example, the fields of the Volume layout could be enumerated as follows where an instance of the Directory control has been created called Tree1:

REM Enumerate the fields of the Volume layout and 

REM place their names into a listbox.

REM 

for each Field in Tree1.Layouts("Volume").Fields

    Listbox1.AddItem Field.Name

next

Note that each entry in the tree will contain a property that points back at its corresponding LayoutDescription object, so it will be very easy to figure out the layout name and fields of any node in the tree:

REM Enumerate the fields of an arbitrary entry in the tree

REM for each Field in Entry.Layout.Fields

    Listbox1.AddItem Field.Name

next

New entries will be able to be inserted into the tree by using the Add method on any Entries enumerator:

REM Create a new user at the current level within the tree. Note

REM that Surname is a mandatory attribute, and is thus specified

REM as a named argument.

REM

NewUser = Tree1.Entries.Add("User","CANDREW", _ 

                Surname:="Andrew");

NewUser.SetField("Telephone Number","801 861 4059");

NewUser.SetField("Initials","C A H");

NewUser.SetField("Given Name", "Chris");

Note that the Get/SetField methods will accept a VARIANT parameterCthat is to say that NDS Syntaxes will map to standard ActiveX Automation data types (string, integer, currency, datetime, float, object). Complex syntaxes will be mapped to new ActiveX Automation object types (eg: the "Telephone Number" syntax might be an object with properties of "Prefix" "AreaCode", "Number", "Extension").

In order to assist in the creation of simple visual views of the directory tree, an ImageList property has been provided that provides a plug-compatible interface with the ImageList control found in the common controls OCX. All ImageIndex properties found within Entry objects will actually refer to elements of this standard image list; however, the programmer is free to adopt his or her own customized images to represent the entities within the directory tree.

Finally, note that because the directory object no longer has a visual viewer to accompany it, the help documentation MUST contain sample source code to show the VB programmer how to incorporate its content into the shipping tree view and list controls in both Visual Basic, Delphi, etc., thus allowing the user to merely cut and paste code in order to wire up the non-visual directory control to a visual viewer OCX.

Methods:


booleanEntryExists( FullName )

Testfor existence of an entry within the directory tree

Entries*Search( StartContext, Filters, Scope )

Providea simple search capability within the directorytree. Note that the Search methodimplicitlyuses the Filters criteria specified, andwill only search the child nodes of the specified StartContextby default. The Scope parameter is optional.

Events:


voidRefreshViews( void )
Theroot context location or tree name has beenmodified. At this time, any visual viewswouldnormally be refreshed with the new subtreestructure.

voidEntryAdded( Entry )

Anentry has been added to the tree. If a visualview is currently displaying the items atthis levelin the tree, the entry should be added.

voidEntryDeleted( Entry )

Anentry has been deleted from the tree

voidEntryMoved( Entry )

Anentry was moved from one context to another.

Properties:


RO
Entries [enumeration]
Hierarchicallist of entries in the directory tree

RO

Layouts [enumeration]

Listsdefined layouts in the schema for this tree

RW*

Filters [enumeration]

Filtersto control WHICH entries are included

RW*

ImageList

Listof images used to represent items in the tree

RW*

TreeName

Nameof the current tree

RW*

ContextName

Rootcontext name within the current tree

Entry Object

Description: Each Entry object is really just a placeholder within the directory tree which allows the programmer to deal with a given NDS objects in the tree rather than just having methods on a tree object that manipulate data in arbitrary hidden objects within it as was the case in the original NDSMethods control.

Note that most fields of a Entry object can be extracted to a variable using the SetField and GetField methods. However the API also supports extraction of binary data to a file in order to handle larger multimedia data types that might be stored into the tree. Alias objects will be distinguishable only by virtue of their Alias property. This property should be inspected before traversing any child entries to prevent unexpected infinite recursion.

Methods:


booleanSaveFieldValueToFile( FieldName, FileName )

Savea fields= value into a file. This techniqueis useful for large binary blobs of datasuch asmultimedia data types. Once savedinto a temporary file, the data can be accessedeasily by theRAD programmer.

booleanLoadFieldValueFromFile( FieldName, FileName)

Setthe value of a field using the binary datacontained within the given file.

booleanSetFieldValue( FieldName, Value )

Setthe value of the given field using the passedin variable. Note that the passed in variablewillbe coerced to the expected type if necessaryand may be any one of the standard VB types,or oneof the NDS ActiveX data types thatare declared later in this document in theNDS Attribute TypeMapping table.

booleanGetFieldValue( FieldName, Value* )

Returnthe value of one of the entries= fields afterperforming appropriate type conversions sothata VB programmer can deal with that data.

booleanChangePassword( NewPassword, OldPassword )

Changepassword on this entry.

booleanValidatePassword( Password )

Forentries that are protected by a password,this allows the VB programmer to authenticatethepassed in string against the entries=password.

Properties:


RO

Name

RelativeDistinguished Name of the object

RO

FullName

Distinguishedname of the object

RO

ImageIndex

Imagethat can be used to display this entry

RO

Layout

Layoutobject to describe entries= fields

RO

Parent

Parent Entry or NULL

RO

Children

Iteratorof child Entries (NULL for leaf node)

RO

Alias

TRUEif this entry is an ALIAS

RW

Tag

Forthe programmer to store his own data

LayoutDescription Object

Description: A layout description object describes the structure of a given class within the NDS schema. For simplicity, the VB programmer will be shielded from the complexities of superclassing and will just be able to see a single set of Fields for a given layout even if the corresponding NDS class really inherited most of its properties from one or more ancestor classes.

Under normal circumstances, the Layout Description is a set of read-only data describing an already existing NDS schema class. However in the case where the programmer wishes to extend the NDS schema, he may create his own set of layout descriptions in order to describe the class to be added.

Properties:


RW

Name

Nameof this layout in the NDS schema

RW

Icon

Iconthat should be used to represent instances RW

RW

FieldDescriptions[enumeration]

Anenumeration of the fields of this layout

FieldDescription Object

Description: Each and every attribute of an NDS layout must be described by a corresponding field description. Note that the field description contains both the NDS Attribute Type (e.g., "Boolean") and its corresponding ActiveX Automation Type (e.g., VT_BOOL). Note that the NDS Attribute Type is provided for informational purposes only and is currently not used when getting or setting fields on an Entry Object. As with the LayoutDescription, this object=s properties can only be modified when creating a brand new class with which to extend the NDS schema.

Properties:


RW

Name

Nameof this field (eg: "US Citizen")

RW

Type

ActiveXType for the field (eg: VT_BOOL)

RW

FieldType

NDSname for this type (eg: "Boolean")

RW

ValidComparisons

Comparisontypes allowed for this field

RW

IsOptional

Whetherthe field is required or optional

Filter Object

Description: Each filter structure describes one particular criteria that must be met for an object in the directory to be included in the Entries enumeration. Normally, the filter criteria will be set up using a visual property sheet at design time. However, it is also possible to add and remove filter criteria at runtime by using the Add and Remove methods of the Filters enumerator. The user interface for creating filter criteria at design time will be a very simple dialog box that lists the current filter criteria (e.g., "Pay Grade" < 23 AND "Service" > 60 months) and permits the design time coder to add or remove criteria.

Properties:


RW

LogicalOperand

Thiscriteria should be ANDed / Red .

RW

Layout name

Layoutname (can be "*" to apply to all classes)

RW

Field name

Nameof field to be compared

RW

Comparison type

CMP_EQUAL,CMP_LESSTHAN, etc...

RW

ComparisonValue

Value to be compared with

Entries Enumerator

Description: This iterator is used extensively within the Directory control wherever a group of NDS objects have to be available to the Visual Basic programmer. For example, any object that can act as a container of other NDS objects will have a Children iterator of this type.

Non-standard methods:


Entry*Add( Layout name, EntryName, ... )

Createa entry in the tree, which is initializedwith following variable list of named fieldvalues.Note that all required field valuesfor the given layout must be specified -otherwise this methodthrow an ActiveX Automation exception.

booleanRemove( EntryName )

Removean existing entry from the directory tree.

LayoutDescriptions Enumerator

Description: An iterator that is used to walk through the classes within the NDS schema. New layouts defined in Visual Basic will be added using the Add method; however, this is an operation that will only be valid for a user with appropriate network authorizations (e.g., the administrator) and does of course cause irreversible changes to the directory tree. Any RAD developer wishing to modify the schema must be aware that thorough testing must be performed in an isolated test network environment before allowing the application to run in the corporate network environment where schema changes will replicate to all connected servers. Under normal usage, the schema would only ever be extended by an application installation programCand even then only when installing the server-end component of a client-server solution product.

Non-standard methods:


boolean Add( LayoutDescription*,LocalOrGlobal )

Add a new layout definitionto the schema.

FieldDescriptions Enumerator

Description: Iterates the fields of an existing layout, or in the case of creating a new layout to be added into the schema, can actually be used to add new fields. Note that when browsing existing layouts within the schema, it is not possible to add additional fields; therefore, the Add method will always fail if used under those circumstances.

Non-standard methods:


boolean Add( FieldDescription* )

Add a brand new field definitioninto a read/writeable layout. This methodwill not work on anypre-existing (read only) layout objects.

Filters Enumerator

Description: Used to manage a list of Filter criteria that will be used to filter the contents of the Directory control.

Non-standard methods:


IndexAdd( Filter* )

Copiesa filled out filter criteria into this list of criteria.

booleanRemove( Index )

Removea filter criteria.

Properties::


RW

ExcludeOrInclude

Filter criteria to be inclusiveOR exclusive

Type Mapping between NDS and ActiveX Automation

It is important to ensure that the Directory and DirectoryBrowser controls introduce as few new concepts as possible for the Visual Basic programmer to learn. One way that this can be achieved is to map all 28 of the defined NDS attribute syntaxes into either native ActiveX Automation Types or express more complex types as custom ActiveX Automation classes that represent a data structure (i.e., the automation class has properties, but no methods). Note that in several instances, the ActiveX Automation type allowed for a given attribute will in fact be either an ActiveX Automation object representing a data structure or a delimited string. For example, either of the following assignments would be valid for a Holdtype field:

HoldVal.objectName = "John";

 --OR--  HoldVal = "John,10";"
HoldVal.level  = 10;

The following table illustrates the mapping between NDS Syntax Types and ActiveX Automation types that will be used when getting and setting fields and also when representing the field types to the RAD programmer within an NDSField structure. When fields are being set on Entry objects, the value passed in will be validated according to an explicit set of rules for the expected NDS Attribute Type(s). In other words, while the "Case Ignore String" and "Numeric String" types have both been mapped to VT_BSTR type in ActiveX Automation, an exception will be thrown if the programmer attempts to pass in a value for a "Numeric String" field that contains an alphabetic character. Similarly, the programmer can expect that any comparison operations on a field will be performed using the true NDS Attribute Type rather than the ActiveX Automation type. For example, a filtering operation that compares two "Case Ignore String" values will of course ignore the case of the strings in the process of doing the comparison.


NDSAttribute Type
ActiveXAutomation VARIANT Type

Boolean

VT_BOOL

Case Exact String

VT_BSTR

Case Ignore List

VT_BSTR | VT_ARRAY

Case Ignore String

VT_BSTR

Class Name

VT_BSTR

Counter

VT_I4

Distinguished Name

VT_BSTR

EMail Address

VT_DISPATCH(EmailAddress struct)

Facsimile Telephone Number

VT_DISPATCH(PhoneNumber struct)

Hold

VT_DISPATCH (Hold struct)

Integer

VT_I4

Interval

VT_I4

Net Address

VT_DISPATCH(NetAddress struct)

Numeric String

VT_BSTR

Object ACL

VT_DISPATCH (ACL struct)

Octet String

VT_BSTR

Path

VT_DISPATCH (Path struct)

Postal Address

VT_BSTR | VT_ARRAY

Printable String

VT_BSTR

Replica Pointer

VT_DISPATCH (Replica struct)

Stream

VT_BSTR (IStream)

Telephone Number

VT_DISPATCH(PhoneNumber struct)

Time

VT_DATE

Timestamp

VT_DISPATCH(TimeStamp struct)

Typed Name

VT_DISPATCH(TypedName struct)

Unknown

VT_UNKNOWN (IStream)

* 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.

© Copyright Micro Focus or one of its affiliates