SetAuthenticationOptions Method (IPISDKOptions interface)

                    

 

This method takes an ordered NamedValues collection of authentication option names and sets the corresponding in-memory structures controlling the connection process. The method returns a PIErrors collection.  During connection, the currently set authentication options are tried in order until a successful connection is achieved or all options have been tried unsuccessfully. 

Syntax

object.SetAuthenticationOptions pnvsAuthenticationOptions, bPersist

The object placeholder is an object expression that evaluates to a IPISDKOptions interface, obtained from a PISDK object.

The SetAuthenticationOptions method syntax has these parts:

 

Part

Description

object

An object expression that evaluates to an IPISDKOptions interface.

pnvsAuthenticationOptions

Passed NamedValues collection containing the names of the desired authentication options in order. The contained NamedValue objects should have their Name property set to one of the supported options below. If the NamedValues collection is empty (count is 0) the method sets the options to the defaults respecting the bPersist flag. 

bPersist

Passed boolean that indicates whether the changes should be persisted to the registry where they affect all applications.  See "Remarks" below.

 

Settings

Some of the supported settings for authentication options are:

Setting Description
SSPI Windows Security Support Provider Interface (Single Sign On)
Trust PI Server trust mechanism
DefaultUser Default PI user name with a blank password

 

The default authentication options, in-order, are:

  1. SSPI
  2. Trust
  3. DefaultUser

Remarks

To build an in-order, NamedValues collection, set the Sorted property to false before adding individual members. 

 The "set" method allows the caller to optionally persist the behavior. Persisted behaviors, whether turning them on or off, will affect all subsequently run PI-SDK applications unless they explicitly set behaviors for themselves.  Setting these behaviors in a persistent manner is an administrative behavior, typically performed once.  Reading and setting these behaviors without persisting is a typical application behavior. 

This method does not support partial success.  The method returns pseUNSUPPORTEDOPTION if any of the input option is invalid. An input Authentication option is not valid if it is not one of the entries returned from the GetAvailableAuthenticationOption method.  However, the SetAuthenticationOptions method goes through checking all the input options before returning. The returned PIErrors collection will contain one PIError object for each invalid input option where the Cause property is set to the name of the invalid authentication option. 

 

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:

Error

Description

E_INVALIDARG, E_POINTER Some of the function arguments are not valid.
psePIERRORSCREATE Fail to create the return PIErrors collection
pseUNSUPPORTEDOPTION Some of the input Authentication Options are not valid.
pseOPENINGREGKEY Error opening/writing registry key.
Enabling Operational Intelligence