Class SetupStore

Programmatic Identifier

MemAdmin.DSConfig.1

CLSID

40E9AD64-E2A1-11D0-920F-00C04FB954C7

COM Class Name

setupstr

Type Library Name

setupstr 1.0 Type Library

Type Library Location

c:\winnt\system32\inetsrv\setupstr.dll

Threading Model

“Both”

Administrators can use instances of the SetupStore (MemAdmin.DSConfig.1) COM class to create the necessary database objects required to host a Membership LDAP Directory Service instance.  The database can be either a Microsoft SQL Server database or an Access database.  Administrators must use the COM class ObjCreator (ObjCreator.ObjCreator.1) to enable an instance of this class as “read-write”.  Most methods will return E_ACCESSDENIED HRESULT values if the ObjCreator method CreateObjAuth is not used, and the calling process/thread does not have Windows NT administrative privileges.

Interfaces

The SetupStore COM class exposes the ISetupStore dual interface, providing both a custom COM interface as well as a dispinterface to the methods and properties.

Interface ISetupStore

CreateSQLDB

This method populates a database in a Microsoft SQL Server with the necessary tables to host a Membership LDAP service instance.

IDL Definition

HRESULT CreateSQLDB(
[in] BSTR bstrServerName, // server name hosting SQL
[in] BSTR bstrDatabaseName,  // empty database name
[in] BSTR bstrDirectoryName,  // the realm name of the directory
[in] BSTR bstrDBUserName,  // the login name for the database
[in] BSTR bstrDBPassword,  // the password
[in] BSTR bstrSuperDSPassword,  // the account password for SUPERBROKER
[in] BOOLEAN fUseMemSecurity  // Host Membership Authentication Service?
);

Parameters

bstrServerName

the name of the computer hosting the Microsoft SQL server.

bstrDatabaseName

the name of the empty database to house the LDAP tables, stored procedures,etc.

bstrDirectoryName

the realm name of the newly created directory.

bstrDBUserName

the name to use to authenticate to the SQL server when logging on.  This user usually is has administrative privilege in SQL server.

bstrDBPassword

the password to use to authenticate to the SQL server when logging on.

bstrSuperDSPassword

the password to set for the Directory (SUPERBROKER) administrator.  This password must be set when the database is created.  The username in the newly directory service is always "administrator".

fUseMemSecurity

a flag specifying whether the LDAP directory service using the database to persist information will be used with a Membership Authentication service instance to provide authentication services.  0=False, 1=True

Return Value

a standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
Server="dbsvr1"
Database="some-name"
DName="some-name"
DBUser="sa"
DBPass="password-here"
DSSuperPass="other-password"
fUseMemSec=TRUE
call DSConfig.CreateSQLDB(Server,DName,DBUSer,DBPass,DSSuperPass,fMemSec)
If Err.Number <> 0 Then
  WScript.Echo "Error creating database backend"
End If

CreateJetDB

This method creates an Access database and populates it with the necessary tables to host a Membership LDAP directory service.

IDL Definition

HRESULT CreateJetDB(
[in] BSTR bstrFileName, 
[in] BSTR bstrDirectoryName, 
[in] BSTR bstrDBUserName,
[in] BSTR bstrDBPassword, 
[in] BSTR bstrSuperDSPassword, 
[in] BOOLEAN fUseMemSecurity
);

Parameters

bstrFileName

the filesystem path to the access database.  All relative paths are from the c:\winnt\system32 directory.

bstrDirectoryName

the top level name of the directory.  (.eg. "MyCompany" names the directory and the distinguished name becomes "o=MyCompany" in the directory.)

bstrDBUserName

not used currently.

bstrDBPassword

not used currently.

bstrSuperDSPassword

the password to set for the Directory administrator.  This password must be set up in a special manner.  The username in the directory service is always "administrator". 

fUseMemSecurity

a flag specifying whether the LDAP service using this database as a backend will provide user authentication services to a Membership Authentication server.  0=false, 1=True

Return Value

a standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
Filename="inetsvr\myldapdb.mdb"
DirName="company1"
DBUserName=""
DBUserPass=" "
DBSuperPass="superpass"
fUseMembershipSecurity=1 ' true
call DSConfig.CreateJetDB(Filename, DirName, DBUserName, DBUserPass, DBSuperPass, fUseMembershipSecurity)
If Err.Number <> 0 Then
  WScript.Echo "Error creating access database: " & Err.Description
End If

CreatePartition

This method sets up a necessary tables and configuration information in a target server and database when partitioning a logical directory container across multiple SQL servers and databases.

IDL Definition

HRESULT CreatePartition(
[in] BSTR bstrServerName, 
[in] BSTR bstrDatabaseName, 
[in] BSTR bstrDBUserName, 
[in] BSTR bstrDBPassword
);

Parameters

bstrServerName

a name for the computer hosting the SQL server for this partition.

bstrDatabaseName

the name of the database to use for the partition.

bstrDBUserName

the username presented when authenticating to the SQL server.

bstrDBPassword

the password presented when authenticating to the SQL server.

Return Value

a standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
DBUser="sa"
DBPass="password-here"
Database="some-database"
Server="someserver"
call DSConfig.CreatePartition(Server,Database,DBUser,DBPass)
If Err.Number <> 0 Then
  WScript.Echo "Error creating partition: " & Err.Description
End If

SetDirectoryPropertiesPage

This method updates the meta-base information for a given LDAP server instance.  The realm and the optional DN Prefix are added.

HRESULT SetDirectoryPropertiesPage(
[in] long lInstanceId, 
[in] BSTR szRealm, 
[in] BSTR szDnPrefix
);

Parameters

lInstanceId

the LDAP server instance identifier.

szRealm

the Realm name of the directory service.

szDnPrefix

the prefix to use when constructing the full distinguished name.

Return Values

a standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
call DSConfig.SetDirectoryPropertiesPage(1,"somecompany","o=companies")

ValidateJetFileName

This method performs file existence verifications.  It checks to see if a file specified by name exists, and returns a TRUE/FALSE value depending on the value passed as the second argument.   

IDL Definition

HRESULT ValidateJetFileName(
[in] BSTR bstrFileName, 
[in] BOOL fWantNew, 
[out, retval] BOOL *pfValid
);

Parameters

bstrFileName

the full or relative path to the file.  All relative names are from the c:\winnt\system32 directory. (e.g. "mydb.mdb" -> "c:\winnt\system32\mydb.mdb"

fWantNew

a flag specifying the intent of the validation check.  If fWantNew is TRUE (1), then the returned BOOL will indicate FALSE if any file already exists by that name.  If fWantNew is FALSE, then the returned BOOL will return TRUE if a file by that name exits, and FALSE otherwise. 

pfValid

on return, the address of a BOOL variable. (TRUE/FALSE)

Return Values

a standard HRESULT.

Remarks

This method does not check to see whether the file specified is an access database or not.  It simply checks to see if the file exists. 

The matrix of possible BOOL values "returned"  (i.e. the address of the BOOL contained in the third argument on return) is listed below.

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
fWantNew=TRUE
Filename="c:\databases\db1.mdb"
if DSConfig.ValidateJetFilename(Filename,fWantNew) Then
  DSConfig.CreateJetDB(…)
Else 
  WScript.Echo "Name conflict encountered. DB not created"
End If

GenerateJetFileName

This method can be used to automatically generate a filename for an access database that does not conflict with others.  The names are all of the form "c:\winnt\system32\inetsvr\mpinstX.mdb" where "X" is a number.  The idea here is to correlate the instance number for the LDAP server using the access database with the name of the database itself.  Read mpinst3.mdb as "Membership and Personalization for LDAP instance 3."

IDL Definition

HRESULT GenerateJetFileName(
[in] DWORD dwID, 
[out, retval] BSTR *pbstrFileName
);

Parameters

dwID

the identifier to attempt to append to the "mpinst" prefix in the database name. If the number conflicts with another database name, the next possible value is added, and that filename is returned.

pbstrFileName

on return, the address of a BSTR variable containing the generated filename.

Return Values

a standard HRESULT value

Remarks

The argument to this method is the "suggested" id for the name.  If we are setting up LDAP instance number 3, we would send 3 as the argument.  Filename clashed permitting, we would receive "c:\winnt\system32\inetsvr\mpinst3.mdb" from the method.  However, if this file already exists, we would receive the next name available in the sequence.  That is, if all numbers up to 6 are used (mpinst1.mdb … mpinst6.mdb") are used, the method would return "c:\winnt\system32\inetsvr\mpinst7.mdb"

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
Filename = DSconfig.GenerateJetFilename(3) ' hope to use 3

DirName="company1"
DBUserName="ldapuser"
DBUserPass="passwordhere"
DBSuperPass="superpass"
fUseMembershipSecurity=1 ' true
call DSConfig.CreateJetDB(Filename, DirName, DBUserName, DBUserPass, DBSuperPass, fUseMembershipSecurity)
' go on to configure LDAP instance

LocalPathToFullPath

This method simply inserts "c:\winnt\system32\inetsvr\" at the beginning of the string passed as the first argument.  If "somedb" is passed, the BSTR at the address returned as the second argument would contain "c:\winnt\system32\inetsvr\somedb".

IDL Definition

HRESULT LocalPathToFullPath(
[in] BSTR bstrLocal, 
[out, retval] BSTR *pbstrFull
);

Parameters

bstrLocal

the string to insert the standard filesystem path "c:\winnt\system32\inetsvr" at the beginning of.

pbstrFull

on return, the address of a BSTR variable containing the standard full path.

Return Values

a standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSCfg = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
LName="mpinst5.mdb"
If DSCfg.ValidateJetFileName(DSCfg.localnametofullname(Lname),0) Then
  WScript.Echo "File " & Lname & " exists in standard location"
End If

GetDriveInformation

This method can be used to identify the type of drive a path refers to.

IDL Definition

HRESULT GetDriveInformation(
[in] BSTR bstrPath,
[out, retval] DWORD *pdwdt
);

Parameters

bstrPath

the path to interrogate information about.

pdwdt

on return, the address of a DWORD variable containing information about the drive.  The values are the same as the Win32 API GetDriveType function.

Return Values

a standard HRESULT value

Example

Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")
Set DSConfig = ObjCreator.CreateObjAuth("MemAdmin.DSConfig.1")
DriveType = DSConfig.GetDriveInformation("f:\somedir")