How to Programmatically Create a GAL in Exchange 2000 Server (300121)

SUMMARY

This article includes Microsoft Visual Basic sample code that demonstrates how to programmatically create a global address list (GAL) in Exchange 2000 Server.

Background

An Exchange 2000 Server GAL is an Active Directory object that exists in the Configuration Namespace of the Active Directory. To create a GAL, you must create an addressBookContainer class object in the directory under the following object:

CN=All Global Address Lists,CN=Address Lists Container,CN=Organization,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=DomainName,DC=com

GALs, unlike address lists, cannot be nested and should be created in the All Global Address Lists container.

To enable Messaging Application Programming Interface (MAPI) clients to use a GAL, you must add the Distinguished Name of the newly created GAL to the globalAddressList attribute on the Microsoft Exchange container.

You must set the following attributes on a GAL object before your first call to SetInfo when you create the object:

displayName (mandatory): A single-valued directory string attribute that stores the display name for this GAL.
systemflags (optional): A single-valued integer attribute that stores system information regarding the directory object. To set this attribute, pass one or more logically OR'd values as defined by the ADS_SYSTEMFLAG_ENUM enumeration, documented at the following MSDN Web site:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/netdir/adsi/ads_systemflag_enum.asp
NOTE: Although the preceding attribute is marked optional, you must set it at object-creation time before the first SetInfo call.

You must also set the following optional attributes:

purportedSearch (optional): A single-valued directory string attribute that stores the search query filter for this GAL.
msExchPurportedSearchUI (optional): A multi-valued attribute that stores the parameters necessary to rebuild the Exchange System Manager's (ESM) Find Exchange Recipients dialog box. This attribute does not need to be set; however, without a value, the Modify button on the General tab of your GAL's Properties dialog box is not available (dimmed).NOTE: This attribute is not documented; therefore, when you set it programmatically, this action is not supported. The best way to set this attribute is to actually create an address list with a similar query filter from ESM. Then, copy the value of the msExchPurportedSearchUI attribute for this newly-created address list, and then paste it into the msExchPurportedSearchUI attribute for the GAL that you are creating programmatically.

MORE INFORMATION

This Visual Basic sample code creates a GAL. Note that this code does not demonstrate how to modify security on the new GAL. Refer to the "References" section of this article for references that demonstrate how to set permissions on Active Directory objects. This sample code requires that the "Active DS Type Library" topic be included in the Visual Basic references for this project.

The minimum requirements to run this code include the following:

A Windows 2000 client or a Microsoft Windows NT or Microsoft Windows 98 client with Active Directory Client Extensions installed.
Administrative privileges over the domain that the Exchange 2000 Server computer on which you plan to create the GAL resides.

To create this Visual Basic Project, follow these steps:

Start Visual Basic.
Select the Standard EXE new project.
Click Project, click References, and then add Active DS Type Library.
Insert the following code in the Code view of the form:

Private Sub Command1_Click()
Dim RootOUName
Dim sSystemFlags
Dim displayName
Dim purportedSearch

sSystemFlags = "1610612736"
displayName = "testGAL5"
purportedSearch = "(mailNickname=*)"

' Get Address list container
Set AddressListCont = GetObject("LDAP://Myserver/CN=All Global Address Lists,CN=Address Lists Container,CN=MyOrg,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=MyDomain,DC=com")
 
' Create the New Address List
Set NewAddressList = AddressListCont.Create("addressBookContainer", "CN=testGAL5")
 
NewAddressList.DisplayName = displayName

'this will have to be customized based on the query filter
NewAddressList.purportedSearch = purportedSearch

'This can only be set at creation time
'This attribute is set by passing a value that is defined by the ADS_SYSTEMFLAG_ENUM enumeration documented at -
'http://msdn.microsoft.com/library/default.asp?url=/library/en-us/netdir/adsi/ads_systemflag_enum.asp
'In this sample I am passing in the 1610612736 (0x60000000) which is
'0x60000000 = 0x40000000 or 0x20000000 (ADS_SYSTEMFLAG_CONFIG_ALLOW_RENAME + ADS_SYSTEMFLAG_CONFIG_ALLOW_MOVE)
NewAddressList.systemflags = sSystemFlags

'   Save New GAL
NewAddressList.SetInfo
Debug.Print "GAL Saved OK."

'Now that the GAL is created, we would need to add the distinguished
' name of this new GAL to the "globalAddressList" attribute on the
' CN=Microsoft Exchange object, so that Outlook clients would know
' the list of all the GALs
' If your not creating a GAL but creating a regular address list, you
' should not perform the following steps!
Set msExchService = GetObject("LDAP://MyServer/CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=MyDomain,DC=com")
msExchService.PutEx ADS_PROPERTY_APPEND, "globaladdresslist", Array("CN=testGAL5,CN=All Global Address Lists,CN=Address Lists Container,CN=MyOrg,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=MyDomain,DC=com")
msExchService.SetInfo
MsgBox "Done"

End Sub

REFERENCES

For more information about security on Active Directory objects, browse to the following Microsoft Web sites:

IADsSecurityDescriptor

IADsAccessControlList

IADsAccessControlEntry

IADsAccessControlEntry Property Methods

For additional information about Active Directory security issues, click the article number below to view the article in the Microsoft Knowledge Base:

269159 HOWTO: Use Visual Basic and ADsSecurity.dll to Properly Order ACEs in an ACL

For more information about Active Directory Client Extensions, browse to the following Microsoft Web site:

Active Directory Client Extensions for Windows 95, Windows 98 and Windows NT Workstation 4.0

For additional information about hosting with Exchange 2000 Server, click the article number below to view the article in the Microsoft Knowledge Base:

262183 XGEN: Hosting with Microsoft Exchange 2000 Server