Class AuoConfig

Programmatic Identifier

MemAdmin.AuoConfig.1

CLSID

0b9ae1d6-b696-11d0-bbd7-00c04fb615e5

COM Class Name

AuoConfig

Type Library Name

AUO 1.0 Type Library

Type Library Location

C:\Microsoft Site Server\bin\P&M\auo.dll

Threading Model

"Both"

This COM class defines an object that programmers and administrators can use to configure the Active User Objects (AUO) provider entries for a given Membership service instance.

Administrators must use the special COM class ObjCreator.ObjCreator.1 to create instances of the AuoConfig COM class to allow write access to the configuration. If the object is created directly, attempting to use methods that alter the configuration of the entries will return E_ACCESSDENIED HRESULT values. The current AUO entry information, minus the respective BindAsPassword value can still be retrieved and viewed in this case.

When an instance of the AuoConfig class is created, it is registered with the context CLSCTX_LOCAL_SERVER, and therefore can only be created as an out-of-process COM object.

Interfaces

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

Security Issues

Most methods exposed by the IAuoConfig interface require the process or thread invoking them to have Windows NT administrator credentials. The exceptions are listed below

The GetInfo method does not require this credential.
The GetEntries method does not require this credential.
The GetEntry method will not return the AUO entry's BindAsPassword if the account invoking the method does not have Windows NT administrator credentials. If it does, all the entry data will be returned.

Interface IAuoConfig

DeleteInstance

This method clears all entries defined for the specified Membership server instance.

IDL Definition

HRESULT DeleteInstance();

Return Value

A standard HRESULT value

Remarks

You must have previously called GetInfo and specified a Membership server instance. If GetInfo has not been called, an error is returned.

This method only clears the entries within the AuoConfig object. Call SetInfo to commit the changes.

The process or thread invoking this method must have Windows NT administrative credentials associated with it for the method to succeed.

Example

' Using Windows Scripting Host and VBScript
Option Explicit

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")

' get the entries for Membership Instance ID = 1
AuoConfig.GetInfo(1)

'  Say we wish to redefine all the entries for this ID
'  We call DeleteInstance to remove all the current entries

AuoConfig.DeleteInstance()

GetEntries

GetEntries retrieves AUO entry names and their associated ADSI namespaces (also called Providers). The namespace is determined from the ADsPathPrefix value defined for each entry.

IDL Definition

HRESULT GetEntries(
[in,out] VARIANT* pNames,
[in,out] VARIANT* pNamespaces
) ;

Parameters

pNames

upon return, the VARIANT subtype SAFEARRAY contains VARIANT subtype BSTR variables that are the AUO entry names defined for the current Membership server instance. (VT_ARRAY|VT_VARIANT)

pNamespaces

upon return, the VARIANT subtype SAFEARRAY contains VARIANT subtype BSTR variables each of which contains the namespace portion of the ADsPathPrefix for the associated AUO entry. (VT_ARRAY|VT_VARIANT)

Return Value

A standard HRESULT value

Remarks

The names and namespaces are associated by index in the arrays. For example, the array elements Names(1) and Namespaces(1) (using VB syntax) represent an AUO name/namespace association.

You must have previously called GetInfo and specified a Membership server instance. If GetInfo has not been called, this method will return an error.

The returned variant type discriminator is of type VT_ARRAY|VT_VARIANT. Each VARIANT variable in the array has the discriminator type VT_BSTR.

Example

' Using Windows Scripting Host and VBScript
Option Explicit

'  Here we wish to fetch all the entry names and their
'  associated providers  for Membership Instance 1

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")

'  Call Getinfo for ID = 1
call AuoConfigObjRef.GetInfo ( 1 )

'  Now get a list of the defined entries
Dim Names
Dim ADSProv
call AuoconfigObj.GetEntries( Names, NameSpaces )

'  We'd now have an array of names and providers for ID = 1
Dim i
For i = LBound(Names) to UBound(Names)
  wscript.echo "Name: " & Names(i)
  wscript.echo "Namespace: " & NameSpaces(i)
Next

GetEntry

The GetEntry method gets the configuration information for the specified AUO provider entry.

IDL Definition

HRESULT GetEntry(
[in]        BSTR  bszName,        /* the entry to get elements for */
[in,out] VARIANT* pbszADsPathPrefix, //VT_BSTR
[in,out] VARIANT* pbszSchema,        //VT_BSTR
[in,out] VARIANT* pbszClass,         //VT_BSTR
[in,out] VARIANT* plSuffix,          //VT_LONG
[in,out] VARIANT* pbszDepObject,     //VT_BSTR
[in,out] VARIANT* pbszDepProp,       //VT_BSTR
[in,out] VARIANT* pbszBindAsName,    //VT_BSTR
[in,out] VARIANT* pbszBindAsPassword //VT_BSTR
) ;

Parameters

bszName

specifies the name of the entry to get configuration information for.

pbszADsPathPrefix

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current ADsPathPrefix value for the specified entry.

pbszSchema

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current Schema value for the specified entry.

pbszClass

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current Class value for the specified entry.

plSuffix

upon return, the VARIANT subtype LONG (VT_I4) variable contains the current Suffix value for the specified entry.

pbszDepObject

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current DepObject value for the specified entry.

pbszDepProp

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current DepProp value for the specified entry.

pbszBindAsName

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current BindAsName value for the specified entry.

pbszBindAsPassword

upon return, the VARIANT subtype BSTR (VT_BSTR) variable contains the current BindAsPassword value for the specified entry.

Return Value

a standard HRESULT value

Remarks

Set bszName to NULL to retrieve information about the default entry.

You must have previously called GetInfo and specified a Membership server instance. If GetInfo has not been called, this method will return an error.

The pbszBindAsPassword is only populated with the AUO entry's BindAsPassword value if a process with Windows NT administrative privileges used the ObjCreator COM class to create the instance of the AuoConfig COM class.

Example

' Using Windows Scripting Host and VBScript
'
Option Explicit

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")

' Call GetInfo
AuoConfigObjRef.GetInfo(1)
' We want the list of currently defined entries and their providers

Dim Name, Path, Schema, Class, Suffix,DepObj,DepProp,BindAsName,BindAsPassword

Name = ""  ' default entry
AuoConfigObjRef.GetEntry(Name,Path,Schema,Class,Suffix,
DepObj,DepProp,BindAsName,BindAsPassword)

GetInfo

The GetInfo method loads the AUO provider entries defined for a specified Membership server instance.

IDL Definition

HRESULT GetInfo( [in] LONG lVirtServId  );

Parameters

lVirtServId

a Membership server instance identifier (id).

Return Value

a standard HRESULT value

Remarks

The GetInfo method is the first method you call when you want to view and/or update the AUO provider entries for a specified Membership server instance. GetInfo will "succeed" even if the integer "ID" has not been defined. In this case, one may proceed to define the entries for this new Membership server instance.

Example

' Using Windows Scripting Host and VBscript
Option Explicit

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")

' now we want to work with Membership Instance 7, which has previously
'  been defined

call AuoConfig.GetInfo(7)
' here we view, update the entries.
AuoConfig.SetInfo   ' commits the changes for ID=7

' Now we wish to define a new Membership Instance #8
call AuoConfig.GetInfo(8)
' here we define the new entries  (code omitted)
AuoConfig.SetInfo     ' commits the entries for ID=8
                      ‘ Setinfo succeeds if we have Admin privilege

RemoveEntry

The RemoveEntry method deletes a specified AUO provider entry from the configuration present in the object.

IDL Definition

HRESULT RemoveEntry( [in] BSTR  bszName ) ;

Parameter

bszName

the name of the AUO provider entry to remove

Return Value

a standard HRESULT value

Remarks

You must have previously called GetInfo and specified a Membership server instance. If GetInfo has not been called, this method will return an error.

This method only deletes the entry in the object. To permanently commit the changes for the Membership server instance, invoke the SetInfo method.

The process or thread invoking this method must have Windows NT administrative credentials associated with it for the method invocation to succeed, and the caller must have created the instance using the ObjCreator COM class. If not, the HRESULT value E_ACCESSDENIED will be returned.

Example

' Using Windows Scripting Host and VBScript
Option Explicit

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")
'  Work with Membership Instance 3
AuoConfigObjRef.GetInfo(3)

' now we want to remove an entry in the AuoConfig object
' Say the entry with friendly name "ThisOne"
AuoConfigObjRef.RemoveEntry("ThisOne")

SetEntry

The SetEntry method creates or updates the specified AUO provider entry.

IDL Definition

HRESULT SetEntry(
[in] BSTR bszName,
[in] BSTR bszADsPathPrefix,
[in] BSTR bszSchema,
[in] BSTR bszClass,
[in] LONG lSuffix,
[in] BSTR bszDepObject,
[in] BSTR bszDepProp,
[in] BSTR bszBindAsName,
[in] BSTR bszBindAsPassword
);

Parameter

bszName

the name of the entry.

pbszADsPathPrefix

the ADsPathPrefix value for the entry.

pbszSchema

the Schema value for the entry.

pbszClass

the Class value for the entry.

plSuffix

the Suffix value for the entry. (1=username;2=dependent property;3=cookie)

pbszDepObject

the DepObject value for the entry. (an AUO entry name)

pbszDepProp

the DepProp value for the entry.

pbszBindAsName

the BindAsName value for the entry.

pbszBindAsPassword

the BindAsPassword value for the entry.

Return Value

a standard HRESULT value

Remarks

SetEntry updates an entry in the AuoConfig object’s entry list under the specified name. If an entry with the specified name does not already exist in the object, one is created.

You must have previously called GetInfo and specified a Membership server instance. If GetInfo has not been called, this method will return an error.

The process or thread invoking this method must have Windows NT administrative credentials associated with it, and the caller must have created the instance of the object using the ObjCreator COM class. If not, the HRESULT value E_ACCESSDENIED is returned.

Example

' Using Windows Scripting Host Runtime Env  (cscript.exe)
Option Explicit

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")

' We want to work with Membership Instance 1
AuoConfig.GetInfo(1)

Dim Name, Path, Schema, Class, Suffix
Name = ""   ' default entry
Path = "LDAP://ldapsvr1:389/o=somecompany/ou=members"
Schema = "LDAP://ldapsvr1:389/o=somecompany/cn=schema/cn=member"
Class = "member"
Suffix = "1"
AuoConfig.SetEntry(Name,Path,Schema,Class,Suffix, "","","","")

SetInfo

The Setinfo method commits (saves) the current AUO provider configuration as it is currently defined in the running object.

IDL Definition

HRESULT SetInfo() ;

Return Value

a standard HRESULT value

Remarks

You must have previously called GetInfo and specified a Membership server instance. If GetInfo has not been called, this method will return an error.

This method must be used with care. When SetInfo is invoked, all changes, deletions and additions to AUO provider entries that have occurs during the lifetime of this object will be committed. This method essentially "saves" the entries as they appear in the AuoConfig object.

The process or thread invoking this method must have Windows NT administrative credentials associated with it for the method to succeed, and the caller must have created the instance of the object using the ObjCreator COM class. If not, the HRESULT value E_ACCESSDENIED is returned.

Example

' Using Windows Scripting Host and VBScript
Option Explicit

' First the AuoConfig object gets instantiated
' using the special creator object
Dim ObjCreator
Set ObjCreator = CreateObject("ObjCreator.ObjCreator.1")

Dim AuoConfig
set AuoConfig = Obj.Creator.CreateObjAuth("MemAdmin.AuoConfig.1")

AuoConfig.Getinfo(1)

' change or define some entries here
'  < code ommited >
'  Now we commit these changes so they take effect
AuoConfig.SetInfo()

Errors

The table below lists the HRESULT return values that are returned by method invocations through the IAuoConfig object.

Value	Meaning
S_OK	Success
E_OUTOFMEMORY	Insufficient memory for allocation
E_FAIL	A critical operation failed
E_EXCEPTION	An exception has occurred
DISP_E_EXCEPTION	An exception has occurred. Check the ErrorInfo object for more detailed information
E_ACCESSDENIED	An attempt was made to invoke a method that requires administratvie privileges. See the security note in the overview section.

The AuoConfig COM class implements the COM exception handling IErrorInfo interface. For extended error information about exceptions generated while using the object, one can call the GetErrorInfo method to retrieve extended error information in the standard way.