ISSONotification.InitializeAdapter Method

Article
02/02/2021

Initializes the password sync adapter to the ENTSSO system.

Syntax

  
HRESULT InitializeAdapter(  
BSTR strAdapterName,  
ULONG lFlags,  
ULONGLONG* hNotifyEvent,  
GUID* guidTrackingId);

Parameters

bstrAdapterName
[in] The unique adapter name.

ulFlags
[in] A bitwise combination of the SSO_NOTIFICATION_FLAG values.

phNotifyEvent
[out] When this method returns, contains an event handle created by PS Helper. You should cast the return value to a HANDLE on return, as MIDL does not support the HANDLE data type. This parameter can be NULL if the event handle is not required by the adapter.

pguidTrackingId
[out] When this method returns, contains the tracking ID generated by ENTSSO. The tracking ID is used for auditing purposes. This parameter can be NULL if the tracking ID is not required by the adapter.

Return Value

This method returns an HRESULT indicating whether it completed correctly. For more information, see the Error Values section.

Error Values

This method returns an HRESULT containing one of the values in the following table.

Value	Description
S_OK	The initialization was successful.
S_FALSE	The initialization was successful, but was a reconnect. For more information, see the Remarks section.
E_ACCESSDENIED	Access is denied.
ENTSSO_E_NO_SERVER	Could not contact the ENTSSO server. Check that the ENTSSO service is running.

Remarks

Before calling InitializeAdapter, you must have entered the relevant adapter name into ENTSSO.

InitializeAdapter should be the first method your adapter calls, because you cannot call any other ISSONotification methods before you call InitializeAdapter. You should not call InitializeAdapter again until after you call ShutdownAdapter. Once you shut down the adapter, however, you may call InitializeAdapter at any time to reconnect.

InitializeAdapter initiates communication between the PS Helper and the adapter. When your adapter calls InitializeAdapter, the PS Helper calls the Enterprise Single Sign-On (ENTSSO) service over encrypted LRPC. Using the adapter name, the ENTSSO service grants or denies access based on the access account that was defined for the current adapter.

You must have started the ENTSSO service before calling InitializeAdapter. PS Helper cannot automatically start ENTSSO because the adapter process might not be running with sufficient privileges to start a service. Therefore, your adapter must initiate all communication between the adapter and ENTSSO.

PS Helper first establishes a connection with the ENTSSO service, and then creates a named event. PS Helper then passes the named event to the ENTSSO service. ENTSSO uses the event signal to the PS Helper when a notification arrives for the adapter. ENTSSO returns the event to the adapter so that the adapter can wait on the event, or else ignore the event and allow PS Helper to wait instead. This gives more flexibility to the adapter for the adapter threading model. The event is valid for the adapter until ENTSSO completes the processing initiated by a call to ShutdownAdapter.

The ENTSSO service accepts the initial remote procedure call (RPC) call from the PS Helper if ENTSSO is running. ENTSSO then performs an access check. If ENTSSO is unable to access the database to obtain the adapter configuration information, then ENTSSO returns an E_ACCESSDENIED event. If ENTSSO has the adapter configuration information, but cannot currently contact the database, then ENTSSO continues to accept password change notifications and buffers the notifications locally and encrypt the notifications in a local temporary file.

InitializeAdapter also returns E_ACCESSDENIED if the adapter is deleted or disabled.

For all errors, more detailed information will be available in the Windows Event Log.

It is assumed that the adapter knows the appropriate name to use when communicating with ENTSSO.

InitializeAdapter is single-threaded. All other threads calling InitializeAdapter are blocked until InitializeAdapter has completed. It is also synchronized with the ShutdownAdapter method.

It is possible that the adapter process terminates before you can issue a ShutdownAdapter. In this case, and if ENTSSO receives another InitializeAdapter before ENTSSO receives a corresponding ShutdownAdapter, ENTSSO treats the second ShutdownAdapter call as a reconnect. In this case, ENTSSO cleans up and invalidates the existing event, and creates a new handle. ENTSSO also completes any pending ReceiveNotifications for the old event handle with a shutdown notification.

In the case of a reconnect, a new tracking ID is returned from the InitializeAdapter. ENTSSO returns a new tracking ID because the tracking ID returned from InitializeAdapter can be considered a session ID. Further, ENTSSO reissues any pending (but unconfirmed) notifications to the adapter.

Requirements

Platforms: Windows

Share via